Attachments

Those endpoints allow you to manipulate attachments for every type of object that can own some in Retail Operations (Document, Project, ...)

Definition

Attachments are every file that can be added in the solution: document picture, company logo, email attachment, ....

All the attachments are read only, you can change certain properties of an attachment but the file itself can never be changed.
If you want to change a file you have to upload a new attachment and then remove the one you wanted to replace.

Identifier

The attachment identifying key is composed of 5 informations:

Key component	Description
objectTypeID	The type of the object (cf.Object types) Ex: Project, Document, Client, ...
entityTypeID	The type of the entity, this value signification depends on the type of object
entityID	The ID of the entity
attachmentID	The ID of the physical file
attachmentIndex	The Index of the file, used in case you may have the same file attached multiple times to the same entity

The objectTypeID, entityTypeID and entityID identify the entity.
The attachmentID and attachmentIndex identify an attachment on the entity.

Object types

ID	Name	Comment
1	Contact
2	Project
3	Document
4	Task	Also called Event in the API
5	Email
6	Product
7	Promotion
8	Catalog
9	Employee
10	EmailSignature
11	Warehouse
12	Workflow
13	Payment
14	Style
15	StyleType	Also called Style Feature
16	StyleInfo	Also called Style Feature Option
17	EditionAnnexes

Link types

Attachment link types are used to define the global type of an attachment.

Each link type can be assigned a maximum number of attachments. This value will limit the number of attachments of this link type on a same given entity.
When the Max Number set on a Link type is 1, then adding a new Attachment of this link type on an entity that already owns one will automatically delete the already present attachment, in order to respect the limit.
Ex: "Logo" limit = 1,. If an attachment with "Logo" link type already exists on a product, and if you add a new attachment with "Logo" type to this product, then the new attachment is added and the old one is automatically removed.

* -> no auto remove
1 -> auto remove existing attachment on new attachment upload

ID	Name	Max Number	Comment
0	List	*	A general list of attachments
1	Logo	1	The logo Ex: Product, Contact main logos
2	Banner	1	Reserved
3	FrontPageJson	1	Reserved
4	HtmlBody	1	Reserved
5	Unique	1	Reserved
6	DataSource	1	Reserved

ID	Name	CategoryID	Comment
1	Conception	1
2	CoveringPanels	1
5	EDI		.edi and ORDER.zip edi files
6	EDIGraph		Edi graph files
7	EDILogistic		Logistics (INSDES) edi file
8	EDIOriginFile		Used to mark which file should be used to generate the EDIGraph file
10	Elevation	1
11	Excel		used for .xls and .xlsx files
16	Module	1
17	Other		Misc tag
18	Perspective	1
19	Picture		used to identify "jpeg", "jpg", "wmf", "emf", "bmp", "png", "gif" files
20	Plan	1
23	Room		Identify the project save file of the configurator
24	SignedDocument		For the pdf document that have been electronically signed
28	Thumbnail	1
31	WorkTop	1
32	ZIP		all zip files
34	HQRender	1

Upload process

To upload a new file, you need to follow a 3 steps process:

Start
Upload
Finish

This is necessary as we internal deduplicate files.

Start

First you need to compute the sha256 of the file and get its size.
Then you can call the AttachmentAddStart endpoint with all the details of the attachment you want to add.
Then there are 2 possibilities, depending on the response needUpload property value:

if needUpload is false, then the upload process stops here. As we already own this exact file, you do not need to upload it again.
You can find the detail of the linked attachment in the response attachment properties.
if needUpload is true, then continue to the Upload step.

Upload

The second step (if needUpload == true) allows you to upload the file.
You just need to process a PUT request call at the url provided in the uploadUrl properties, with the raw file content as the request body.

Finish

The third step after the Upload is to call the Finish endpoint, in order to tell the webservice that you have finished uploading the file. The webservice will check that the file upload corresponds with the information you have provided and then will link the file to the entity.
In response you will find the detail of the attachment.

Attachment Structure

{
  "objectTypeID": long,
  "entityTypeID": long,
  "entityID": long,
  "id": long,
  "index": int,
  "url": string,
  "date": string,
  "linkTypeID": long,
  "name": string,
  "extension": string,
  "size": long,
  "checksum": string,
  "externalApplicationID": long,
  "conceptionID": long,
  "isFavorite": bool,
  "tags": long[]
}

Name	Comment
objectTypeID	ID of the type of object on which this attachment is present
entityTypeID	ID of the type of entity on which this attachment is present
entityID	ID of the entity on which this attachment is present
id	ID of the file itself
index	Index of this attachment on the entity
url	URL to access this attachment
date
linkTypeID	Link type between the attachment and the entity
name	Name of the file without extension
extension	Extension of the file without the leading "." and lower case
size	Size in bytes of the file
checksum	String representation of the SHA256 of the file as a hexadecimal
externalApplicationID	ID of the application that generated this file
conceptionID	ID of the conception the file is extracted from. Only present and used for "Document" object type.
isFavorite	true if this is the favorite image of the entity. Only used on "list" link type and on certain object (project / document), to choose the thumbnail. Only 1 favorite attachment is allowed at the same time.
tags	List of tag IDs for this attachment

Attachment methods

List

Returns the list of attachments of a specified entity.

Method

GET	/api/externals/v1/attachments/{objectTypeID}/{entityTypeID}/{entityID}

Arguments

objectTypeID (long): (provided in the path): ID of the target object type
entityTypeID (long): (provided in the path): ID of the target entity type
entityID (long): (provided in the path): ID of the entity owning the attachments to List
winLangID (long): Windows Language Identifier of the resulting data

Body

(none)

Response

The list method returns a JSON message with the list of items:

{
  "attachments": [
    {
      "objectTypeID": long,
      "entityTypeID": long,
      "entityID": long,
      "id": long,
      "index": int,
      "url": string,
      "date": string,
      "linkTypeID": long,
      "name": string,
      "extension": string,
      "size": long,
      "checksum": string,
      "externalApplicationID": long,
      "conceptionID": long,
      "isFavorite": bool,
      "tags": long[] // List of tag IDs
    }
  ],
  "success": boolean,
  "message": string,
  "rowCount": long
}

See Attachment Structure

Add Start

Starts the 3 steps process to Add an attachment

Method

POST	/api/externals/v1/attachments/{objectTypeID}/{entityTypeID}/{entityID}

Arguments

objectTypeID (long): (provided in the path): ID of the target object type
entityTypeID (long): (provided in the path): ID of the target entity type
entityID (long): (provided in the path): ID of the entity that will own the attachment to be added

Body

The details of the attachment to be added:

{
  "linkTypeID": long,
  "name": string,
  "extension": string,
  "size": long,
  "checksum": string,
  "externalApplicationID": long,
  "conceptionID": long,
  "isFavorite": bool,
  "tags": long[] // List of tag IDs
}

For detail on the fields see: Attachment Structure.
Highlighted fields are mandatory.

Response

The Add Start method returns a JSON message with the information of the added attachment or the information needed in order to complete the Upload process:

{
  "success": boolean,
  "message": string,
  "rowCount": long,
  "needUpload": bool,
  "uploadUrl": string,
  "transactionID": string,
  "attachment": AttachmentDetail // same as List endpoint  
}

Name	Comment
needUpload	If `true`: you need to complete the full Upload process. Else if `false`: we already own this file and we have attached it. You can find the details of the attached file in the attachment property.
uploadUrl	If `needUpload == true`: the url where to upload the file (Step 2 Upload).
transactionID	If `needUpload == true`: ID of the Add attachment transaction to be passed to the Finish endpoint after the upload is completed.
attachment	Only present if `needUpload == false`: a single AttachmentDetail that has the same properties as those in the List method response.

Finish add attachment

Step 3: Finish step of the add an attachment process.
Links a temporary upload to the entity.

Method

POST	/api/externals/v1/attachments/{objectTypeID}/{entityTypeID}/{entityID}/finish/{transactionID}

Arguments

objectTypeID (long): (provided in the path): ID of the target object type
entityTypeID (long): (provided in the path): ID of the target entity type
entityID (long): (provided in the path): ID of the entity owning the attachment to be added
transactionID (long): (provided in the path): ID of the Add attachment transaction, given by the Add Start endpoint

Body

The attachment detail to add.
Should be the same as the one given in the Add Start endpoint.

See Add start Body

Response

The Add Finish method returns a JSON message with the information of the added attachment:

{
  "success": boolean,
  "message": string,
  "rowCount": long,
  "attachment": AttachmentDetail // same as List endpoint  
}

Name	Comment
attachment	A single AttachmentDetail that has same properties as those in the List Response.

Delete attachment

Deletes the attachment on an entity.

Method

DELETE	/api/externals/v1/attachments/{objectTypeID}/{entityTypeID}/{entityID}/{attachmentID}/{attachmentIndex}

Arguments

objectTypeID (long): (provided in the path): ID of the target object type
entityTypeID (long): (provided in the path): ID of the target entity type
entityID (long): (provided in the path): ID of the entity owning the attachment to be removed
attachmentID (long): (provided in the path): ID of the attachment to be removed
attachmentIndex (long): (provided in the path): Index of the attachment to be removed on the specified entity

Body

(none)

Response

{
  "success": boolean,
  "message": string,
  "rowCount": long,
}

Update attachment info

Allows you to update certain editable properties on an existing attachment.

Method

PUT	/api/externals/v1/attachments/{objectTypeID}/{entityTypeID}/{entityID}/{attachmentID}/{attachmentIndex}

Arguments

objectTypeID (long): (provided in the path): ID of the target object type
entityTypeID (long): (provided in the path): ID of the target entity type
entityID (long): (provided in the path): ID of the entity owning the attachment to be updated
attachmentID (long): (provided in the path): ID of the attachment to be updated
attachmentIndex (long): (provided in the path): Index of the attachment to be updated on the specified entity

Body

{
  "name": string,
  "isFavorite": bool,
  "tags": long[]
}

Response

{
  "success": boolean,
  "message": string,
  "rowCount": long,
}

Attachment enum methods

Here are the endpoints that give you the possible values for the different enums:

Object types
Link types
Tags

Object types

Returns the list of all available object types that can own attachments.

Method

GET	/api/externals/v1/attachments/objectTypes

Arguments

winLangID (long): Windows Language Identifier of the resulting data

Body

(none)

Response

{
  "success": boolean,
  "message": string,
  "rowCount": long,
  "types": [
    {
      "id": long, // ID of the object type
      "name": string, // Name of the object type
      "description": string  // Additional description of the object type, if set
    }
  ]
}

Link types

Returns the list of all available link types.

Method

GET	/api/externals/v1/attachments/types

Arguments

winLangID (long): Windows Language Identifier of the resulting data

Body

(none)

Response

{
  "success": boolean,
  "message": string,
  "rowCount": long,
  "types": [
    {
      "id": long, // ID of the link type
      "name": string, // Name of the link type
      "description": string  // Additional description of the link type, if set
    }
  ]
}

Definition​

Identifier​

Object types​

Link types​

Tags​

Upload process​

Start​

Upload​

Finish​

Attachment Structure​

Attachment methods​

List​

Method​

Arguments​

Body​

Response​

Add Start​

Method​

Arguments​

Body​

Response​

Finish add attachment​

Method​

Arguments​

Body​

Response​

Delete attachment​

Method​

Arguments​

Body​

Response​

Update attachment info​

Method​

Arguments​

Body​

Response​

Attachment enum methods​

Object types​

Method​

Arguments​

Body​

Response​

Link types​

Method​

Arguments​

Body​

Response​

Tags​

Method​

Arguments​

Body​

Response​

Definition

Identifier

Object types

Link types

Tags

Upload process

Start

Upload

Finish

Attachment Structure

Attachment methods

List

Method

Arguments

Body

Response

Add Start

Method

Arguments

Body

Response

Finish add attachment

Method

Arguments

Body

Response

Delete attachment

Method

Arguments

Body

Response

Update attachment info

Method

Arguments

Body

Response

Attachment enum methods

Object types

Method

Arguments

Body

Response

Link types

Method

Arguments

Body

Response

Tags

Method

Arguments

Body

Response