Adding buttons (actions)

With actions, it is possible to tie in custom functionality in the user interface.

Three kind of actions exist:

  • productionActions - Actions on the production level

  • clipActions - Actions on an annotation (MediaObjectAnnotation, ClipAnnotation, …​)

  • eoActions - Actions on an EditorialObject (collection, collection group, story, …​)

This section documents properties which apply to all kind of actions. See the sections on productionActions, clipActions, eoActions for more details on how to use in a specific context.

A basic Action

{
  // Label when shown in a menu, tooltip when shown as an icon button
  "label": "Test command",
  // icon for the button / menu option
  "icon": "icon-magic",
  // see "checking rights" section
  "requiredRights": "LIBRARY_SHARE",
  // the actual action that will be performed when clicking the button or menu option.
  // The available clientCommand values are listed in the productionActions, clipActions and eoActions sections
  "clientCommand": "TheClientCommand",
  // These parameters will be passed on to the clientCommand. See "common params"
  "params": {
    "paramToClientCommand": "value",
    "oneWorkflowPerItem": true
  },
  // The action will only be visible when the object matches the filters. See "filters" section
  "filters": [
    {
      "key": "annotation.funnel",
      "values": [
        "MediaObjectAnnotation"
      ]
    }
  ]
}

Filters

The filters define on which object the action should be shown.

A basic filter

Here’s a simple filter example, which will only match Editorial Objects with an objectType of Draft, StoryPart or Scene:

{
  "key": "eo.objectType",
  "values": [
    "Draft",
    "StoryPart",
    "Scene"
  ]
}

A filter can contain a modifier, of which NOT is the most common. This filter will match Editorial Objects that are not a Scene:

{
  "key": "eo.objectType",
  "values": [
    "Scene"
  ],
  "modifiers": ["NOT"]
}

Combining filters

Filters are combined like this:

{
  "operator": "AND", // Can be "OR" or "AND" (default)
  "filters": [
    // array of basic or combined filters
    { "key": "eo.objectType", "values":  ["Draft"] },
    { "key":  "eo.title", "values": ["Example Title"] }
  ]
}

Note that the array of filters can contain both basic filters, but it can also contain combined filters again. This makes the filters very expressive.

Advanced modifiers

We already discussed the "NOT" modifier. Two more modifiers are available:

  • "ARRAY_CONTAINS_ALL" - assumes the checked value is an array. Will check if it contains all values specified in values

  • "ARRAY_CONTAINS_ANY" - Like ARRAY_CONTAINS_ALL, but one value appearing from values is enough for the filter to pass.

Checking rights

You can pass in a requiredRights string to only show the action in the UI for people with certain rights.

Some examples first:

{
    "requiredRights": "LIBRARY_SHARE+LIBRARY_UPLOAD"
}
{
    "requiredRights": "(!LIBRARY_SHARE+LIBRARY_UPLOAD)|(LIBRARY_DELETE)"
}

Three operators are supported

  • ! before a right means the user can’t have this right

  • + is a logical AND

  • | is a logical OR. It has lower precedence than AND.

The parentheses are simply stripped from the string and not interpreted! They can be used to keep things clearer.

The following rights exist (note that not each right can be set as is in the UI, some rights are combined)

Check the page about permissions to learn which rights exist.

In the context of actions, you can also use some special run-time interpreted rights:

  • EO_BUILDER_EDIT (evaluates to COLLECTION_BUILDER_EDIT, STORY_BUILDER_EDIT or SCREENPLAY_BUILDER_EDIT depending on the Editorial Object)

When requiredRights is omitted:

  • for eoActions, it will default to EO_BUILDER_EDIT

  • for clipActions (see below), it will default to no rights required (so always show)

Advanced rights checking

Rights can also be checked directly using filters. The key userRights can be used, it is a map from the right to either true or false.

{
  "filters": [
    {
      "key": "userRights.LIBRARY_DELETE",
      "values": [ true ]
    }
  ]
}

In most cases it is more concise to use the requiredRights property. However, the filters approach is more powerful as it can be combined with other filters.

the EO_BUILDER_EDIT right can not be used in filters.

Checking roles

It is possible to check roles by adding a filter on the productionRoles key. Both the role name or role id can be used.

when possible, prefer checking rights instead of roles. 
{
  "filters": [
    {
      "key": "productionRoles",  // action only visible for user having role with name 'Production Administrator' OR a role with name 'Freelancer' OR a role with id 3202
      "values": ["name[Production Administrator]", "name[Freelancer]", "id[3202]"]
    }
  ]
}

requiredRoles

Deprecated

Instead of using a filter on productionRoles key, one can also add a requiredRoles option. Internally, this is converted into a filter on productionRoles.

You can pass in a requiredRoles string to only show the action in the UI for people with a certain role.

The following examples illustrate how to use the requiredRoles option:

{
  "requiredRoles": "name[Production Administrator]" // action only visible for user having a role with name 'Production Administrator'
}
{
  "requiredRoles": "name[Production Administrator]|name[Freelancer]|id[3202]" // action only visible for user having role with name 'Production Administrator' OR a role with name 'Freelancer' OR a role with id 3202
}

Common params

The params strongly depend on the clientCommand which is executed. But some parameters are common for multiple commands.

param description example

userInputFields

An array of parameters to ask the user. See User Input Fields for more details on defining a userInputField.

infoMessage

Message to show at the top of the start page of the dialog

"Start the workflow"

alwaysShowNew

When true, always show the start screen of the dialog, allowing you to start the workflow. Even if another workflow is still running. Has preference over showProgressOnComplete.

true

showProgressOnComplete

true will show the progress of the busy workflow if one is busy. If no workflow is busy, it will show the start screen of the dialog. false will show the state of the previous workflow, even if it has completed already. In the latter case, a button is shown to start a new workflow which takes the user to the start screen of the dialog.

service

The service to launch

"test"

serviceArguments

Raw arguments to send to the call to the backend

{ "forceRedo": true }