API User's Guide

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 is the same, whether the user accesses Alloy Navigator 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

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 as http://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"
			]
		]
	}
}

 

INFO: For sample PowerShell scripts, see PowerShell: Listing attachments (GET) and PowerShell: Listing attachments (POST).

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 as http://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 as http://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
}

 

INFO: For a sample PowerShell script, see PowerShell: Downloading attachments.

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 as http://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
}

 

INFO: For a sample PowerShell script, see PowerShell: Adding attachments.

Adding attachments while running workflow actions

The API provides the ability to run workflow step actions on Alloy Navigator 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 as http://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 omit AttachmentArea.

Removing attachments

The following request removes a specific object attachment.

DELETE {{baseUrl}}/Object/{objectId}/Attachments/{attachmentId}

where:

  • baseUrl - the API URL, such as http://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 as http://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.

INFO: For a sample PowerShell script, see PowerShell: Updating attachment descriptions.