Aprimo DAM REST API Documentation

Resource: OrderCollection

About this resource

Representation of collection of orders. Retrieving this collection is currently not exposed via the REST API. For details on the supported order types, see the documentation for DownloadOrder, EmailOrder, FtpResortOrder and PublicCdnOrder

Relations

Method Name Select-key Resource type Description
GET self Provides a link to this resource

Actions

Method Action Description Response codes
POST /orders add Create an order
201 Request completed successfully. The header parameter 'Location' contains the location of the new order resource.
400 Bad request (in general)
403 Insufficient permissions

Examples

Order targets and target actions
When you add a target action (e.g. resize image) to an order target which has target types that don't support it (e.g. resizing previews/thumbnails), the action will only be applied to the target types that do support the action.
The following table shows which order target actions are supported per target type.
Target TypeSupported Actions
DocumentResizeImage, ResizeImageWithClippingPath, CropImage, TranscodeVideo, CreatePackage, UpdateXmpMetadata
MasterThumbnail-
AllThumbnails-
MasterPreview-
AllPreviews-
AdditionalFilesResizeImage, ResizeImageWithClippingPath, UpdateXmpMetadata
DocumentsOfAllItems-
Creating a new download order 
POST /orders HTTP/1.1
{
  "type": "download",
  "creatorEmail": "frank.tremens@adamsoftware.net",
  "disableNotification": "true",
  "downloadsPageUrl": "http://localhost/Assets/Downloads",
  "notificationThresholdInSeconds": "0"
  "targets": [
        {
          "recordId": "15e1090e37a34428a5efa3cd007c7807",
          "targetTypes": ["MasterPreview", "MasterThumbnail"],
          "assetType": "AllVersionsOfAllFiles"
        },
        {
          "recordId": "0333844867764f819ea5a3cd006e67c5",
          "targetTypes": ["MasterPreview"],
          "assetType": "LatestVersionOfAllFiles"
        },
        {
          "targetTypes": ["Document"],
          "fileVersionId": "541DF508C2DF45B2BC69A782013CB6B8"
        },
        {
          "targetTypes": ["AdditionalFiles"],
          "additionalFileId": "ad0ff17667af406994b5a8d200e99106",
          "actions": [
            {
              "action": "resizeImage",
              "parameters": {
              "width": 120,
              "height": 110,
              "format": "KeepOriginal",
              "resolution": 300,
              "colorSpace": "GrayScale",
              "useAlphaTransparency": "true"
            }
        }
    ]
  },
  {
      "recordId": "15e1090e37a34428a5efa3cd007c7807",
      "targetTypes": ["Document"],
      "assetType": "AllVersionsOfAllFiles",
      "actions": [
          {
          "action": "resizeImage",
          "parameters": {
          "width": 120,
          "height": 150,
          "format": "KeepOriginal",
          "resolution": 300,
          "colorSpace": "KeepOriginal",
          "useAlphaTransparency": "true"
          }
        }
      ]
    },
    ...
  ]
}
Creating a download order to get a link to the original file
Setting the disableProcessing parameter to 'Yes' on a download order will disable all post-processing (eg. XMP writeback, watermarks being applied, order target actions) and allow to get a direct link to the original file. These download orders are processed much faster than download orders that require post-processing, making them better suited for integrations that don't require up-to-date XMP metadata or watermarks applied. The user permission "Disable file processing of download orders" is required for this order to work. Setting the parameter to 'YesIfPermissionGranted' will return a direct link if the user has the permission granted, and otherwise return the post-processed files. Be aware that depending on the permission, the same order can lead to an entirely different file. Make sure to only order a single file per download order for optimal results.
POST /orders HTTP/1.1
{
	"type": "download",
	"disableNotification": "true",
	"disableProcessing": "yes",
	"targets": [
		{
			"recordId": "15e1090e37a34428a5efa3cd007c7807",
			"targetTypes": ["Document"],
			"assetType": "LatestVersionOfMasterFile"
		}
	]
}
Creating a download order without preliminary checks If you need to quickly submit the download order without preloading the records when creating the order, you can specify the recordIds parameter instead of recordId. In that case, no records are loaded when creating the download order; they are loaded only when the order gets executed. Therefore, if incorrect record IDs are specified (for example, those that don’t exist in the system or those for which the user doesn’t have view rights), the download order is created, gets executed, and fails or partially fails. 
POST /orders HTTP/1.1
{
	"type": "download",
	"disableNotification": "true",
	"targets": [
		{
			"recordIds": [
				"bb7855d00e12435d8443b13800994999",
				"c8816c117ffd4cdf8ee9b13800994a1e",
				"d2c0f429360442b48b0bb138009947f5"
			],
			"targetTypes": [
				"Document"
			],
			"assetType": "LatestVersionOfMasterFile",
			"actions": [
				{
				"action": "resizeImage",
				"parameters": {
						"width": -1,
						"height": -1,
						"format": "png",
						"resolution": -1,
						"colorSpace": "RGB",
						"useAlphaTransparency": "true"
					}
				}
			],
			"filter":{
				"extensions":["png", "tif"]
			}
		}
	]
}
The recordIds parameter is an array of record IDs. Only Document and AdditionalFile can be specified as target types in this case.
Creating a new email order 
POST /orders HTTP/1.1
{
"type": "email",
"emailSubject": "ADAM generated email",
"emailBody": "see attached files",
"emailRecipients": [ "administrator@adamsoftware.net", "all@adamsoftware.net" ],
"creatorEmail": "frank.tremens@adamsoftware.net",
"priority": "Medium",
"earliestStartDate": "2015-08-20T22:00:00Z",
"disableNotification": "true",
"targets": [
{
"recordId": "15e1090e37a34428a5efa3cd007c7807",
"targetTypes": ["MasterPreview", "MasterThumbnail"],
"assetType": "AllVersionsOfAllFiles"
},
{
"recordId": "0333844867764f819ea5a3cd006e67c5",
"targetTypes": ["MasterPreview"],
"assetType": "LatestVersionOfAllFiles"
},
{
"recordId": "15e1090e37a34428a5efa3cd007c7807",
"targetTypes": ["Document"],
"assetType": "AllVersionsOfAllFiles",
"actions": [
{
"action": "resizeImage",
"parameters": {
"width": 120,
"height": 150,
"format": "KeepOriginal",
"resolution": 300,
"colorSpace": "KeepOriginal",
"useAlphaTransparency": "true"
}
}
]
},
...
]
}
Creating a new FTP resort order 
POST /orders HTTP/1.1
{
"type": "ftpResort",
"creatorEmail": "frank.tremens@adamsoftware.net",
"priority": "Medium",
"earliestStartDate": "2015-08-20T22:00:00Z",
"disableNotification": "true",
"targets": [
{
"recordId": "15e1090e37a34428a5efa3cd007c7807",
"targetTypes": ["MasterPreview", "MasterThumbnail"],
"assetType": "AllVersionsOfAllFiles"
},
{
"recordId": "0333844867764f819ea5a3cd006e67c5",
"targetTypes": ["MasterPreview"],
"assetType": "LatestVersionOfAllFiles"
},
{
"recordId": "15e1090e37a34428a5efa3cd007c7807",
"targetTypes": ["Document"],
"assetType": "AllVersionsOfAllFiles",
"actions": [
{
"action": "resizeImage",
"parameters": {
"width": 120,
"height": 150,
"format": "KeepOriginal",
"resolution": 300,
"colorSpace": "KeepOriginal",
"useAlphaTransparency": "true"
}
}
]
},
...
]
}
Creating a new public cdn order for the latest master file of the record (Original file) 
POST /orders HTTP/1.1
{
"type": "publicCdn",
"targets": [{
"recordId": "24bb7956-afff-44f1-aae7-b0ff00cf440a"
}]
}

Creating a new public cdn order for the latest master file of the record converted to png and give it downloadResizedPng renditionName 
POST /orders HTTP/1.1
{
"type": "publicCdn",
"targets": [
{
"recordId": "24bb7956-afff-44f1-aae7-b0ff00cf440a",
"renditionName":"downloadResizedPng",
"actions": [{
"action": "resizeImage",
"parameters": {
"width": -1,
"height": -1,
"format": "png",
"resolution": -1,
"colorSpace": "RGB",
"useAlphaTransparency": "true"
}
}]
}
]
}

Creating a new public cdn order for specific additional file of the record 
POST /orders HTTP/1.1
{
"type": "publicCdn",
"targets": [{
"recordId": "9dbdcdd123c346a4a863aa5500ac42c9",
"additionalFileId": "7495552b-1e26-4473-b121-aa6b0085f880",
}]
}

Shared order request attributes:
Attribute Description
type The type of the order that needs to be created.
One of the following types needs to be provided:
  • download
  • email
  • ftp
  • ftpResort
priority The priority of the download order should always be "High" and is not mandatory.
earliestStartDate The earliest start date of this order.
creatorEmail The e-mail address for this order.
By default this is the e-mail address of the user who created this order.
downloadsPageUrl (optional) if you have a custom downloads page provide the URL here. This property will be used to build the download links in e-mail notifications. If you don't provide a URL the default Downloads page of Assets or the DAM UI will be used.
disableNotification A value indicating whether or not notification is enabled on this order.
targets An array of references to the records that need to be downloaded in specific formats.

Download order specific request attributes:
Attribute Description
singleFileZipMode Specify whether a single file must be zipped when it is downloaded.
Available values for singleFileZipMode are:
  • Never
  • WhenNeeded
  • Always
In case WhenNeeded is selected, the ordered files will be zipped whenever a directory structure is needed,
but the chosen delivery target doesn't support directories, for example when ordering a Publication-All Items package in a download order.
Download order specific request attributes:
Attribute Description
notificationThresholdInSeconds The number of seconds that must elapse when processing the job to trigger a notification. NOTE: this only applies to successful download orders.

FTP order specific request attributes:
Attribute Description
ftpHostname The FTP hostname.
ftpUsername The FTP username.
ftpPassword The FTP password.
ftpPort The FTP port. Defaults to 21.
ftpDirectory The FTP directory.
proxyHostname The FTP proxy hostname.
proxyUsername The FTP proxy username.
proxyPassword The FTP proxy password.
proxyPort The FTP proxy port. Defaults to 80.
passiveTransfer Indicates if passive transfer is enabled.
connectionType The FTP connection type. Can be one of the options listed below:
  • normal
  • implicitEncryption
  • explicitSSLEncryption
  • explicitTLSEncryption

Email order specific request attributes:
Attribute Description
recipients A list of recipients to send the mail to.
subject The subject of the mail.
body The body of the mail.

Download order, contact sheet specific request attributes:
Attribute Description
title Specify the title of the download that will appear on the Downloads page in Content Workspace.
Title usually is something that can identify download.
description Specify the description of the download that will appear on the Downloads page in Content Workspace.
Description is usually the type of download, e.g. Export contact sheet.
Downloads based on a Download or Contact sheet order are displayed on the Downloads page in DAM UI (Content Workspace).
Values for title and description could be:
  • text
  • JSON(used for translatable title or description)
If title and description are not specificed, default value will be used.
Default value for title is either file name or "X items"(if multiple files were ordered).
Default value for description is "Download".

To provide translations for the title and description for non-English users, refer to the Localization > Translations section of
the DAM Administrator Guide.
Values for title and description properties should be in the following format: 
{
...
"title":"{\"StudioName\":\"DAMUI\",\"ModuleName\":\"Orders\",\"TranslationKey\":\"DownloadImageForPublishing\"}",
"description":"{\"StudioName\":\"DAMUI\",\"ModuleName\":\"Orders\",\"TranslationKey\":\"DownloadImageForPublishingDescription\"}",
...
}
Where "DAMUI", "Orders", "DownloadImageForPublishing" are examples of a Studio, Module and Translation Key of a translation created earlier.

For each target, the following attributes need to be provided:
Attribute Description
recordId The id of the record that needs to be included in the order.
Alternatively, for the download order, the recordIds parameter can be used instead of recordId. Please note that only one of these parameters can be specified at a time - either recordId or recordIds.
recordIds (for orders with type:"download") The array of ids of the records that need to be included in the download order.
Use this feature if you need to quickly submit a download order without preloading the records. In this case, no records are preloaded during the creation of the download order; they are loaded only when the order is executed. Please note that you can specify only one of these parameters at a time: either recordId or recordIds. Also, be aware that if you specify recordIds, only Document and AdditionalFile can be specified as target types, and assetType can only be set to LatestVersionOfMasterFile.
fileVersionId The id of the file version that needs to be included in the download (optional).
The assetType is ignored if a fileVersionId is provided.
additionalFileId The id of the additional file that needs to be included in the download (optional).
The assetType is ignored if an additionalFileId is provided.
renditionName (for orders with type:"publicCdn") When you create a public link for a transformation of an original file, for example by using resizeImage action, you can specify renditionName.
Then a specific additional file of type external will be created for the public link and its name will be the value specified as renditionName.
The same renditionName value will be used in the public link uri if @RENDITIONNAME variable is used in .orderPublicLinkNamingConvention.
Please note that to create public link based on the specific additional file which is a rendition of the record generated based on the preset from .renditionPresets setting, the ID of that additional file should be passed along as additionalFileId.
Passing renditionName in that case has no effect.
targetTypes Array of one or more of the options listed below:
  • Document
  • MasterThumbnail
  • AllThumbnails
  • MasterPreview
  • AllPreviews
  • AdditionalFiles
  • DocumentsOfAllItems
assetTypes One of the following available options:
  • LatestVersionOfMasterFile
  • AllVersionsOfMasterFile
  • AllVersionsOfAllFiles
  • LatestVersionOfAllFiles
This value is ignored if a fileVersionId or additionalFileId is specified.
filter
(for orders with type:"download" and when recordIds attribute is used) 		The optional filter parameters let you further refine what is downloaded. You can, for example, only include the output if the file (original file, additional file) has one of the listed file extensions or when the file name matches a string. You can combine both parameters or use only one of them.
  • filename Specify a string (with or without wildcards).The output will only be generated for files whose file name matches the string, e.g.
    "filename": "Product*"
  • extensions Specify one or a list of file extensions. The output will only be generated for content items whose file extension matches one of the listed ones, e.g. 
    "extensions": ["jpg","jpeg"]
  • purposes Only when asset type is AdditionalFile. The additional file will only be included in the download if its purpose matches one of the listed ones, e.g. 
    "purposes": ["lowres"]
  • metadata Only when asset type is AdditionalFile. the additional file will only be included in the download if its metadata value matches this value, e.g. 
    "metadata": {
"isManual":"true"
}
actions The actions that need to be executed on this target.

Order target action attributes
Attribute Description
action The name of the action that needs to be executed on the target.
The following actions are supported:
  • ResizeImage
  • ResizeImageWithClippingPath
  • TranscodeVideo
  • CropImage
  • CreatePackage
  • UpdateXmpMetadata
parameters The parameters that need to be passed to the action.

Actions

  • ResizeImage

    Resizes an image.

    The following parameter attributes need to be provided:

    Attribute Description
    width The width to which the image needs to be resized.
    height The height to which the image needs to be resized.
    format The following formats are supported:
    • keepOriginal
    • jpg
    • png
    • tiff
    • bmp
    • eps
    • pdf
    • webp
    resolution The resolution in dpi.
    colorSpace The following colorSpaces are supported:
    • keepOriginal
    • rgb
    • cmyk
    • lab
    • indexedColor
    • grayscale
    • bitmap
    useAlphaTransparency The following values are supported:
    • true
    • false

  • ResizeImageWithClippingPath

    Resizes an image and makes modifications according to clipping path provided.

    The following parameter attributes need to be provided:

    Attribute Description
    width The width in pixel to which the image needs to be resized.
    height The height in pixel to which the image needs to be resized.
    mediaProfile The name of the media profile.
    clippingPath The name of the clipping path.

  • CropImage

    Crops an image.

    The following parameter attributes need to be provided:

    Attribute Description
    Crop
    • X
    • Y
    • Width
    • Height
    		 The coordinates of the crop in the original image. X and Y are the coordinates of the upper left corner of the crop, with X and Y starting from 0 in the upper left corner. The width and height are relative to these coordinates. Example: 
    "crop": {
    "x" : 200,
    "y" : 300,
    "width" : 150,
    "height" : 250
}
    ResizeWidth The width to which the cropped image needs to be resized.
    ResizeHeight The height to which the cropped image needs to be resized.
    format The following formats are supported:
    • keepOriginal
    • jpg
    • png
    • tiff
    • bmp
    • eps
    • pdf
    resolution The resolution in dpi.
    colorSpace The following colorSpaces are supported:
    • keepOriginal
    • rgb
    • cmyk
    • lab
    • indexedColor
    • grayscale
    • bitmap

  • TranscodeVideo

    Transcodes a video.

    The following parameter attributes need to be provided:

    Attribute Description
    maxHeight The maximum height to which the video needs to be transcoded.
    The following values are standard video heights:
    • 4320
    • 2160
    • 1080
    • 720
    • 576
    • 480
    • 288
    • 240
    quality The quality to which the video needs to be transcoded.
    The following values are supported:
    • Lowest
    • Low
    • Medium
    • High
    • Highest
    audioQuality The audio quality of the video that needs to be transcoded.
    The following values are supported:
    • KeepOriginalAudio
    • StereoAac
    • MonoAac
    outputFormat The format to which the video needs to be transcoded.
    The following output formats are supported:
    • mp4
    • webm

  • TrimVideo

    Trims a video.

    The following parameter attributes need to be provided:

    Attribute Description
    startTime The start time (format: "hh:mm:ss[.fffffff]") of the trimmed video.
    duration The duration (format: "hh:mm:ss[.fffffff]") of the trimmed video.

  • CreatePackage

    Downloads a package. It is required that the file is uploaded as a Package. This can be checked by the availability of a manifest. See "Package Download" in the Administrator Guide.

    No Parameters are accepted.


  • UpdateXmpMetadata

    Update xmp metadata for jpg images based on xmp metadata mapping on system setting.

    No Parameters are accepted.


Following up on an order
Once the order has been created, a resource is returned containing the id and the status of the order.
Orders will not always be processed immediately. They are processed by a service bus. The resource need be retrieved at a later time and a link to the delivered files will be available upon successfully processing the order. The user which will later retrieve the order must be assigned to the ViewMaintenanceJobs role in order to access this resource. 
{
	"_links": {
		"self": {
			"href": "/order/f0233034fd8441028977a4f000e0d35d"
		}
	},
	"id": "f0233034fd8441028977a4f000e0d35d",
	"status": "Executing",
	"deliveredFiles": []
}
A generated order can be retrieved directly in the following way: 
GET /order/94c217e4565f44d79beea4ba00a2fa97 HTTP/1.1