Most of the calls in the CTMS API are synchronous calls in the sense that you send a request and get a response with the result of the request. However, there are some operations in the CTMS API that may need a longer time to execute. For such long-running commands, we use the pattern that is explained in this page.
Long-running commands are defined with a link relation with the suffix "-command". Example, aa:set-thumb-command.
For bulk versions of long-running commands, the order of suffixes is always "-bulk-command".
Starting a long-running command
A client starts the execution of a long-running command in the same way as it calls any other link relation. As for other link relations, the details regarding the HTTP verb, the request body, and the headers are defined in the documentation of the link relation.
The response of the call is a command:command resource.
Example: Command information
{
"version": "1.0",
"command": {
"type": "aa:set-thumb-command",
"id": "c296fcd5-b0a8-4750-b80b-1d06c5a2ca8a",
"lifecycle": "running",
"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:53.9138053+01:00"
},
"_links": {
"curies": [
{
"href": "http://services.avid.com/apis/command/{rel}",
"name": "command",
"templated": true
}
],
"self": {
"href": "https://host/…"
},
"command:cancel": {
"href": "https://host/…"
}
}
}
Depending on the operation, the resource may contain additional properties or additional links. The self link can be used to get the status of the command. The status is available for a certain amount of time but will be discarded after a few hours.
A client can optionally use the query parameter commandid to define an ID for the command. The ID must be a unique identifier, e.g. a UUID. If the client doesn’t provide a commandid query parameter, the service will generate an ID.
Monitoring the command
The client should query the self link of the command response to get (poll) the current status of the command.
Polling
The client starts the command. For polling, it doesn’t have to use the commandid parameter. The service will create a command ID. The response is the first status information.
As long as the lifecycle property is not "finished" or "error", the client calls the self link of the command information. The result is an updated command:command resource. If the lifecycle is "finished", the command was executed successfully. If the lifecycle is "error", the command failed, and the property error contains error information.
Notifications
Note: As of Media Central | Cloud UX 2023.7 the use of notifications for command processing is deprecated and may be removed in a future version of the API.
To avoid race conditions, the client must register for notifications before sending the command. To do so, it opens a WebSocket connection to "wss://clouduxhost/broadcastNotifications" with a valid Authorization header. Then it registers to the channel "avid.ctms.command.bridge" and the subject pattern "command....", by sending a JSON body like this to the WebSocket connection:
{
"jsonrpc": "2.0",
"method": "updateBindings",
"id": "<access-token or open-id-token>",
"params": {
"channel": "avid.ctms.command.bridge",
"add": [
"command.*.*.*.*"
]
}
}
Then, the client must generate a command ID. The command ID must be a unique identifier, e.g. a UUID.
The client then starts the command with the generated command ID in the commandid URL query parameter.
The response is the first status information. If the lifecycle property in the response is already "finished", the command has already been executed successfully. If the lifecycle is "error", the command failed already.
If the command didn’t succeed or fail immediately, the client can wait for notifications on the WebSocket connection. The body of the notification is a command:command resource with the current information about the command. Notifications are sent when the lifecycle changes, but also to indicate progress, or to indicate that the current execution step of phase (state property) changed.
If the lifecycle is "finished", the command was executed successfully. If the lifecycle is "error", the command failed, and the property error contains error information.