Working with object attachments
Introduced in 2022.2
Starting with version 2022.2, the API provides the ability to work with object attachments.
Access level
The level of access an API user has to Alloy Navigator Express is the same, whether the user accesses Alloy Navigator Express over the API or any other module. That's why adding or removing attachments from objects requires the Modify access permission on those objects.
Authorization HTTP header
When the API is configured for Access Token authentication, all API requests require the Authorization HTTP header.
Authorization: bearer <token>
Available API methods
These API methods are available for working with attachments:
- Listing object attachments
- Getting attachment contents
- Downloading attachments
- Adding attachments to objects
- Adding attachments while running workflow actions
- Removing attachments
- Updating attachment descriptions
Listing object attachments
The following requests retrieve a list of attachments of a particular object.
GET {{baseUrl}}/Object/{objectId}/Attachments
POST {{baseUrl}}/Object/{objectId}/Attachments
where:
baseUrl
- the API URL, such ashttp://www.example.com/api/v2/
objectId
- the object ID (GUID or OID)
You can use the same GET and POST parameters as in API requests for listing objects (sorting, filtering, object fields, etc.). For details, see Retrieving object activities (GET) and Retrieving object activities (POST).
Response
{
"success": true,
"errorCode": 0,
"errorText": "",
"responseObject": {
"Fields": [
{
"Name": "ID",
"DataType": "guid",
"Caption": "ID"
},
<...>
{
"Name": "Created_Date",
"DataType": "datetime",
"Caption": "Created Date"
}
],
"Data": [
[
"{6D978EE7-7B88-499F-89FB-3B73C4DFE801}",
"5",
"2022-10-12.log",
"File",
"2022-10-25T11:11:16-07:00"
],
<...>
[
"{7B5B7027-E73C-4003-8AD6-4A0478D3AAED}",
"",
"Lorem.docx",
"File",
"2022-09-13T10:40:51-07:00"
]
]
}
}
Getting attachment contents
The following request obtains the contents of a specific object attachment. The attachment contents are base64 encoded.
GET {{baseUrl}}/Object/{objectId}/Attachments/{attachmentId}/content
where:
baseUrl
- the API URL, such ashttp://www.example.com/api/v2/
objectId
- the object ID (GUID or OID)attachmentId
- the attachment ID (GUID)
Response:
{
"success": true,
"errorCode": 0,
"errorText": "",
"responseObject": {
"Data": "UEsDBBQABgAIAA<...>AAA==",,
"FileName": "Lorem.docx",
"Description": "Sample file",
"Size": 14161
}
}
Downloading attachments
The following request downloads a specific object attachment.
GET {{baseUrl}}/Object/{objectId}/Attachments/{attachmentId}/download
where:
baseUrl
- the API URL, such ashttp://www.example.com/api/v2/
objectId
- the object ID (GUID or OID)attachmentId
- the attachment ID (GUID)
Response
The response is just a stream of binary data.
In addition to standard response headers (Content-Type
, Content-Length
, Content-Disposition
), a special header is used: attachment-file-name: "file_name"
. Using that header allows you to immediately get the file name, without parsing the Content-Disposition
header string.
Error
{
"success": false,
"errorCode": 101,
"errorText": "You do not have enough permissions to access this item.",
"responseObject": null
}
Adding attachments to objects
The following request adds an attachment directly to a specific object.
PUT {{baseUrl}}/Object/{objectId}/Attachments
where:
baseUrl
- the API URL, such ashttp://www.example.com/api/v2/
objectId
- the object ID (GUID or OID)
The file name and the file contents (base64 encoded) must be specified in the request body, as follows:
{
"FileName": "Hello.txt",
"Description": "Sample file",
"Data": "SGVsbG8h"
}
You can add multiple attachments, as follows:
]
{
"FileName": "Hello.txt",
"Description": "Sample file",
"Data": "SGVsbG8h"
},
{
"FileName": "Hello2.txt",
"Data": "SGVsbG8h"
}
]
Response
{
"success":true,
"errorCode":0,
"errorText":"",
"responseObject":null
}
Adding attachments while running workflow actions
The API provides the ability to run workflow step actions on Alloy Navigator Express objects (see Running Step Actions on objects). The following request runs a workflow action on a specific object.
POST {{baseUrl}}/Object/{objectId}/action/{actionId}
where:
baseUrl
- the API URL, such ashttp://www.example.com/api/v2/
objectId
- the object ID (GUID or OID)actionId
- the action ID
To add attachments, include the Attachments array in the request body in addition to the other field value pairs, as follows:
{
"Comment": "New activity",
"Attachments": [
{
"FileName": "hello.txt",
"Description": "Sample file",
"Data": "SGVsbG8h",
"AttachmentArea": "Documents"
}
]
{
where:
-
AttachmentArea
- the attachment area name in the action form's definition. If the action form has only a single attachment area, you can omitAttachmentArea
.
Removing attachments
The following request removes a specific object attachment.
DELETE {{baseUrl}}/Object/{objectId}/Attachments/{attachmentId}
where:
baseUrl
- the API URL, such ashttp://www.example.com/api/v2/
objectId
- the object ID (GUID or OID)attachmentId
- the attachment ID (GUID)
Response
{
"success":true,
"errorCode":0,
"errorText":"",
"responseObject":null
}
Updating attachment descriptions
The following request updates an attachment description.
PATCH {{baseUrl}}/Object/{objectId}/Attachments/{attachmentId}
where:
baseUrl
- the API URL, such ashttp://www.example.com/api/v2/
objectId
- the object ID (GUID or OID)attachmentId
- the attachment ID (GUID)
The new description must be specified in the request body, as follows:
{
"Description": "New description"
}
The only available attachment modification is updating the attachment description.