Control Room
Try Relay free
All chapters
On this page

Actions / Action reference

CatDV actions

Manual / Actions

Read clips and update custom clip metadata.

Actions

Action Use it to
CatDV Get Clip Read one CatDV clip and make every field available to later steps.
CatDV Update Clip Write the picked custom metadata fields to one CatDV clip.

Read Shared action rules for disabling steps, outputs, error routing, and automatic recovery.

Connection and shared behavior

Two actions read and write clips in a CatDV Server: CatDV Get Clip and CatDV Update Clip. Both appear in the Add Action palette under CatDV, their own section.

The workflow CatDV connection. Every CatDV action in a workflow uses one CatDV connection, shown in the workflow header as soon as the workflow holds a CatDV step. The connection selects one CatDV credential (10.7) and nothing else. CatDV actions have no credential field of their own, so the credential is chosen once for the whole workflow. Open the control, pick the credential, and it reads Using credential <name>. With no credential it reads Choose the CatDV credential this workflow uses. A credential that was deleted reads Credential ID "…" is missing. Select an available credential., and the control itself reads CatDV: Needs attention. A workflow that has a CatDV step and no usable connection cannot be enabled, and a run of one fails the step with this workflow has no CatDV connection. Select a CatDV credential in the workflow's CatDV connection.

Relay never writes the credential into the step. The connection is applied while the job runs, so renaming or rotating the credential changes nothing in the saved workflow.

One sign-in per job. A CatDV license seat is held by a sign-in, not by a request, and only a sign-out returns it. Many sites license five seats for the whole facility, so Relay is careful with them:

  • The first CatDV step in a job signs in. Every later CatDV step in the same job reuses that sign-in, so one job holds one seat.
  • A job that never reaches a CatDV step never signs in and holds no seat at all.
  • Jobs never share a sign-in.
  • The end of the job signs out, whether it succeeded or failed. A sign-out CatDV refuses is kept and tried again rather than dropped, so one failed sign-out does not strand a seat.
  • A sign-in that reached CatDV and never got an answer back has still taken a seat. Relay signs out of it straight away, so that seat comes back too. The job then stops rather than sign in a second time, because a second sign-in could hold a second seat. A sign-in CatDV answered and refused took no seat, and Relay sends nothing for it.
  • A sign-in the server breaks off before it takes a seat, for example while CatDV is restarting, leaves nothing behind. Relay signs in again inside the step's retry window, so a server that comes back a second later does not fail the job.
  • A sign-in answered by something that is not CatDV also takes no seat, but signing in again cannot help: the same address gives the same answer. That is a wrong server address or API path in the credential. The job stops and names the credential to correct.

If the Relay service stops while a job holds a seat, that seat stays taken until CatDV times the session out. Relay cannot release it from outside the job.

What a CatDV step is allowed to do is what the CatDV user in the credential is allowed to do. Relay asks for nothing more. A refusal becomes a failure that names the permission, not a workaround.

Recovery. Both actions take a Retry window, 2m by default, accepting 1 second through 1 hour. The window covers the first send and every retry wait. What Relay may try again inside it differs by operation:

Situation Behavior
CatDV has no free seat The sign-in is tried again for the rest of the window. Freeing a seat inside the window lets the job continue normally.
CatDV refuses the user name or password The step fails at once. Relay never repeats a refused sign-in: it wastes the window and can lock the account out.
A read failed temporarily, or the server could not be reached The read is tried again inside the window.
An update was refused with an explicit temporary status, or provably never left Relay The update is sent again inside the window.
An update was sent and Relay could not read the answer The step fails with an unknown outcome and is never sent again. See How a CatDV step fails.

Named CatDV values

CatDV Get Clip publishes a browsable result rather than one JSON blob, the same way the Iconik read actions do (Named Iconik values). Reach the values from Available data: find the Get Clip step, expand its groups, then click or drag the value you need. The editor writes the reference for you; do not type these paths by hand.

Group Holds
Built-in fields The clip's own properties, as CatDV returned them, one entry each.
User-defined fields One entry per custom metadata field, under the name CatDV reports for it.

At run time a reference resolves against the current job. A value that is not there fails the receiving step with CatDV clip value "…" is missing, before the step does any work, and follows the normal error routing. A saved sample is never substituted.

What CatDV checks, and what it does not

Relay does not second-guess CatDV. It does not re-read field definitions during a job, and it forms no opinion about whether a value suits a field. CatDV owns both questions, and CatDV is more permissive than most operators expect:

  • A deleted field can come back. If the field definition was deleted in CatDV after you picked the field, CatDV usually accepts the identifier anyway and makes the metadata key again on the clip. The update succeeds. The clip ends up with a metadata key that has no field definition behind it.
  • A value that does not match the field's type can be stored. CatDV can accept text into a field shown as a date or a number, and store it. The update succeeds, and the clip looks wrong in CatDV afterwards.

Neither case is reported as an error, because CatDV did not report one. If a clip ends up with an unexpected key or an unusable value, correct the field definition in CatDV, or correct the picked fields and values in the workflow, then run the step again. Refresh in the field list is the fastest way to see which of your picked fields CatDV still reports.

How a CatDV step fails

An error handler can branch on ${error.catdv.kind}:

error.catdv.kind Means
configuration Something in the step is wrong: no CatDV connection, a clip ID that is not one whole positive number, picked fields that cannot be read, no picked field, or a request CatDV rejected as invalid.
permission The CatDV user in the stored credential does not have permission.
not_found CatDV has no clip with that ID. The message names the ID.
unavailable CatDV did not provide a usable response.
transport Relay could not complete contact with the CatDV server.
session The sign-in for this job could not be made, or is no longer usable. ${error.catdv.outcome} says which: catdv_no_seat, catdv_sign_in_refused, catdv_unreachable, catdv_sign_in_unconfirmed, catdv_sign_in_temporary, catdv_address_unusable, catdv_credential_unavailable, or catdv_credential_wrong_kind.
outcome_unknown Update Clip only. Relay sent the update and cannot tell whether CatDV applied it.

Outcome unknown is deliberate. CatDV offers no way to ask afterwards what happened to an update, so Relay never sends that update a second time. The step fails with Relay cannot tell whether CatDV applied this change to clip <ID>, so check that clip in CatDV before you run this step again. Route that case to a person: an error branch that tests ${error.catdv.kind} for outcome_unknown can raise a ticket or send a message instead of treating it as an ordinary failure.

Relay writes every CatDV message itself. CatDV's own error text, the server address, the password, and the sign-in are never repeated in a message, a job record, a log, or an export.