Resource command:command

Overview

The command:command resource contains the information about a long-running command. The most important properties are:

command.id: The ID of the command.
command.lifecycle: The current lifecycle status, one of pending, running, finished, error, and suspended.
command.progress: The progress in percent.
command.state: The current state or execution step.

Properties

The command:command resource has the following properties:

version

The version of the command structure. Currently always "1.0".

command

Information about the current command status. See below for details.

payload

Additional information about the command (optional).

Depending on the type of command, it may have a number of command-specific sub properties. See the documentation of the link relation that starts a specific command for details.

Frequently used sub properties:

Property

Description

command-parameters

May contain the parameters used to start the command.

result

For commands that operate on a given list of entities (bulk commands), the result property contains the same JSON structure that a non-command version of the bulk call would return. See chapter Response in Bulk Calls in CTMS for details, and see below for an example.

Link Relations

command:cancel	Cancel the command.
additional link relations	Depending on the type of the command, there may be additional links to affected resources. Some of them may be returned as embedded sub resources. See the documentation of the link relation that starts a specific command for details.

command:cancel

Cancel the command.

additional link relations

Depending on the type of the command, there may be additional links to affected resources. Some of them may be returned as embedded sub resources.

See the documentation of the link relation that starts a specific command for details.

Property "command"

The property command has the following sub properties:

created	date/time, optional	Creation time of the command.
creator	string, optional	Account name of the user who started the command.
error	struct, optional	Error description. The error struct may contain the following sub properties: cause (string, optional): the cause for the error. The value is one of: runtimeError: a general error that occurred while executing the command timeout: a timeout occurred canceled: the command was canceled either by the caller or by the service after a restart rejected: the command was directly rejected by the service httpCode (int, optional): the HTTP status code that a synchronous call would return. E.g. 404 if an item was not found. text (string, mandatory): human-readable error text. code (string, mandatory): message code, identifies the error. This can be used to generate localized messages and to react on specific errors on the client-side. params (map, optional): map with additional parameters that can be used to generate a localized text.
finished	date/time, optional	Finish time of the command. The value is set when the lifecycle is "finished" or "error"
host	string, optional	Host name of the server where the service that is handling the command is running.
id	string	ID of the command
lifecycle	string	The lifecycle of the command. One of: pending: the command was accepted and is ready to run but execution has not started. running: the command is running. finished: the command completed successfully. error: the command failed. suspended: the command is paused, it can be resumed at a later point in time
modified	date/time, optional	Last modification time of the command.
progress	integer, optional	Progress in percent (0-100)
serviceName	string, optional	Name of the service that is handling the command.
serviceVersion	string, optional	Version of the service that is handling the command.
serviceInstance	string, optional	Instance ID of the service that is handling the command.
state	struct, optional	Localizable text describing the current execution step. The value is a JSON object with the following sub properties: text: human-readable text in English code: message code, identifies the state. This can be used to generate localized messages. param: Map with additional parameters that can be used to generate a localized text.

created

date/time, optional

Creation time of the command.

creator

string, optional

Account name of the user who started the command.

error

struct, optional

Error description. The error struct may contain the following sub properties:

cause (string, optional): the cause for the error. The value is one of:
- runtimeError: a general error that occurred while executing the command
- timeout: a timeout occurred
- canceled: the command was canceled either by the caller or by the service after a restart
- rejected: the command was directly rejected by the service
httpCode (int, optional): the HTTP status code that a synchronous call would return. E.g. 404 if an item was not found.
text (string, mandatory): human-readable error text.
code (string, mandatory): message code, identifies the error. This can be used to generate localized messages and to react on specific errors on the client-side.
params (map, optional): map with additional parameters that can be used to generate a localized text.

finished

date/time, optional

Finish time of the command. The value is set when the lifecycle is "finished" or "error"

host

string, optional

Host name of the server where the service that is handling the command is running.

string

ID of the command

lifecycle

string

The lifecycle of the command. One of:

pending: the command was accepted and is ready to run but execution has not started.
running: the command is running.
finished: the command completed successfully.
error: the command failed.
suspended: the command is paused, it can be resumed at a later point in time

modified

date/time, optional

Last modification time of the command.

progress

integer, optional

Progress in percent (0-100)

serviceName

string, optional

Name of the service that is handling the command.

serviceVersion

string, optional

Version of the service that is handling the command.

serviceInstance

string, optional

Instance ID of the service that is handling the command.

state

struct, optional

Localizable text describing the current execution step. The value is a JSON object with the following sub properties:

text: human-readable text in English
code: message code, identifies the state. This can be used to generate localized messages.
param: Map with additional parameters that can be used to generate a localized text.

Bulk commands

For commands that operate on a given list of entities (bulk commands), the payload property has a sub property result which contains the same JSON structure that a non-command version of the bulk call would return. See chapter Response in Bulk Calls in CTMS for details, and see below for an example.

Similar to non-command bulk calls, a bulk command usually succeeds (lifecycle "finished") even if the action fails for some or even all of the entities. The result property should be evaluated by the caller to learn for which entities the action succeeded and for which it failed.

The bulk command usually only fails if the caller requests something that the service doesn’t support at all.

Examples

Successful command

An example of a successfully finished aa:set-thumb-command command. This specific command returns an additional embedded resource aa:thumb with a link to the updated thumbnail.

Example: A successfully finished command

 
{
  "command": {
    "type": "aa:set-thumb-command",
    "id": "c296fcd5-b0a8-4750-b80b-1d06c5a2ca8a",
    "lifecycle": "finished",
    "state": {
      "text": "Thumbnail changed successfully",
      "code": "CTMS/THUMB_CHANGED"
    },
    "progress": 100,
    "serviceName": "MAMAssetsCTC_1",
    "serviceInstance": "MAMAssetsCTC_1",
    "serviceVersion": "7.4.0.102",
    "created": "2020-01-27T13:21:53.9138053+01:00",
    "modified": "2020-01-27T13:21:54.6448607+01:00",
    "finished": "2020-01-27T13:21:54.6448607+01:00"
  },
  "version": "1.0",
  "_links": {
    "curies": [
      {
        "href": "https://developer.avid.com/ctms/api/command/linkrels/{rel}.html",
        "name": "command",
        "templated": true
      }
    ],
    "self": {
      "href": "https://host/…"
    },
    "command:cancel": {
      "href": "https://host/…"
    },
    "aa:thumb": {
      "href": "https://host/…"
    }
  },
  "_embedded": {
    "aa:thumb": {
      "thumbnail": "https://host/…",
      "_links": {
        "self": {
          "href": "https://host/…"
        }
      }
    }
  }
}

Failed command

An example of a failed command with error information:

Example: A failed command

 
{
  "command": {
    "type": "aa:set-thumb",
    "id": "e9094d1d-5a28-46cd-91ac-0098076dd9d1",
    "lifecycle": "error",
    "error": {
      "text": "Failed to download image",
      "code": "CTMS/INTERNAL_SERVER_ERROR",
      "httpCode": 500,
      "cause": "runtimeError"
    },
    "serviceName": "MAMAssetsCTC_1",
    "serviceInstance": "MAMAssetsCTC_1",
    "serviceVersion": "7.4.0.102",
    "created": "2020-01-27T15:07:37.1875506+01:00",
    "modified": "2020-01-27T15:07:37.6025464+01:00",
    "finished": "2020-01-27T15:07:37.6025464+01:00"
  },
  "version": "1.0",
  "_links": {
    "curies": [
      {
        "href": "https://developer.avid.com/ctms/api/command/linkrels/{rel}.html",
        "name": "command",
        "templated": true
      }
    ],
    "self": {
      "href": "https://host/…"
    },
    "command:cancel": {
      "href": "https://host/…"
    }
  }
}

Bulk command

An example of a bulk command, where one item succeeded and one failed. Note the result property within the payload property.

Example: A bulk command

 
{
    "command": {
        "type": "loc:delete-item-by-id-bulk-command",
        "id": "ab1b0976-0025-4211-87fa-fda6c033f4c9",
        "lifecycle": "finished",
        "state": {
            "text": "Deleted 1 of 2 items",
            "code": "avid.mam.assets.access/DELETE_ITEMS_DONE",
            "params": {
                "totalCount": 2,
                "successCount": 1,
                "failureCount": 1
            }
        },
        "progress": 100,
        "serviceName": "MAMAssetsCTC_1",
        "serviceInstance": "MAMAssetsCTC_1",
        "serviceVersion": "7.5.0.91",
        "host": "hostname",
        "created": "2020-08-11T14:25:45.1426858+02:00",
        "modified": "2020-08-11T14:25:45.6270553+02:00",
        "finished": "2020-08-11T14:25:45.6270553+02:00"
    },
    "version": "1.0",
    "payload": {
	    "command-parameters": {
           "mode": "reference"
        },
        "result": [
            {
                "success": true,
                "data": "123330.1444213"
            },
            {
                "success": false,
                "data": "",
                "httpStatus": 400,
                "errorCode": "avid.mam.assets.access/BAD_ARGUMENT",
                "errorMessage": "Invalid item ID"
            }
        ]
    },
    "_links": {
        "self": {
            "href": "https://host/…"
        }
    }
}