API User's Guide

Working with object attachments

Introduced in 2022.2

Updated in 2023.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": "...",
				"DataType": "...",
				"Caption": "..."
			},
			{
				"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"
			]
			// Add more entries as needed
		]
	}
}

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 and links to objects

The following request adds an attachment or link 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"
	}
]

To attach a link to an object, use the IsLink property set to true in your JSON request:

[
	{
		"FileName": "Hello.txt",
		"Description": "Sample link",
		"Data": "",
		"IsLink": true		
	}
]

IMPORTANT: Ensure that the Data property is empty when IsLink is set to true to avoid an invalid combination error.

Response
{
	"success":true,
	"errorCode":0,
	"errorText":"",
	"responseObject":null
}

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

Adding attachments and links while running workflow actions

The API provides the ability to add attachments or links to specific object while running workflow actions.

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.

To attach a link while running a workflow action, use the IsLink property set to true in your JSON request:

{
	"Comment": "New activity",
	"Attachments": [
		{
			"FileName": "hello.txt",
			"Description": "Sample file",
			"Data": "",
			"IsLink": true,	
			"AttachmentArea": "Documents"
		}
	]
}

IMPORTANT: Ensure that the Data property is empty when IsLink is set to true to avoid an invalid combination error.

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.