M2A Workflows API (v1)

Workflows handle the orchestration of live stream resources of a scheduled event.

Workflows use Templates to define how a workflow will be executed. A Template specifies the resources, configuration desired states and order that resources are to be utilized.

You can create many workflow instances from 1 workflow template. The macros in the workflow templates will allow you to have different configuration per workflow instance:

Currently, only programmatic access via the API endpoints is available. The API requests and responses use the JSON:API specification https://jsonapi.org/.

A workflow instance represents a collection of media processing resources and their configuration that needs to be managed to achieve the video processing objectives.

Workflow instance is enrolled to an M2A scheduled event, and the system will update a workflow instance when completing a workflow for an event.

M2A sends HTTP POST notifications to a URL of your choice as each sequence step executes. Configure a webhook on a Workflow Template by setting workflow-settings.webhook.

Internal use only

Defines the resources and the video flows between them to fulfil a customer’s live video workflow.

A Workflow Template is a reusable blueprint. You create many Workflow Instances from one Template. The Template declares nodes — each node represents a media resource (encoder, packager, connect source, etc.) — and event-handlers that describe what should happen at each point in the broadcast lifecycle (e.g. PRE-TX, ON-AIR, POST-TX).

Any string value in a Template can include a macro using double-brace syntax: {{ variable_name }}. Macros are resolved immediately at instance creation time, using the config dictionary supplied in the Instance POST payload. Once the instance is created, all macro values are fixed.

Example — parameterising the encoder region:

Template node:

{
  "name": "Primary-Encoder",
  "node-type": "encoder_v4",
  "input-values": {
    "region": "{{ region }}",
    "medialive-input-role-arn": "{{ medialive_arn }}"
  }
}

Instance POST payload:

{
  "data": {
    "attributes": {
      "config": {
        "region": "eu-west-1",
        "medialive_arn": "arn:aws:iam::123456789:role/MediaLiveRole"
      }
    }
  }
}

Every occurrence of {{ region }} is replaced with "eu-west-1" and {{ medialive_arn }} with the supplied ARN at the moment the instance is created. This lets a single Template serve many events across different regions or accounts.

Some fields require a JSON array rather than a plain string (for example subnet-ids and security-group-ids on private-network encoder inputs). The standard {{ variable }} macro always produces a string. When you need a macro to expand into a list, use m2a.expand:

{{m2a.expand(variable_name)}}

Like standard macros, m2a.expand is rendered immediately at instance creation time.

Example:

Template:

{
  "subnet-ids": "{{m2a.expand(subnet_ids)}}",
  "security-group-ids": "{{m2a.expand(security_group_ids)}}"
}

Instance config:

{
  "subnet_ids": ["subnet-aaa", "subnet-bbb"],
  "security_group_ids": ["sg-111", "sg-222"]
}

{{m2a.expand(subnet_ids)}} is replaced with the full list ["subnet-aaa", "subnet-bbb"] rather than a string representation of it, at the moment the instance is created.

Each node in a Template is identified by its name field, which must be unique within the Template. To wire one node’s output into another node’s input, use the nodes.<NodeName>.<field> macro syntax:

{{ nodes.NodeName.field }}

Unlike standard macros, node references are not resolved at instance creation time. They are resolved at event time, once the referenced node has actually run and produced its output. This means the encoder will always receive the live, real values from the packager — even though those values did not exist when the instance was created.

Example — encoder referencing a packager’s output:

{
  "nodes": [
    {
      "name": "MediaPackage1",
      "node-type": "packager",
      "input-values": { ... }
    },
    {
      "name": "Primary-Encoder",
      "node-type": "encoder_v4",
      "input-values": {
        "settings": {
          "destinations": [
            {
              "output-group-type": "MEDIA_PACKAGE",
              "packager-id": "{{ nodes.MediaPackage1.packager-id }}"
            }
          ]
        }
      }
    }
  ]
}

When the event fires, MediaPackage1 runs first. Once it is up, {{ nodes.MediaPackage1.packager-id }} resolves to the live packager ID and the encoder is started with the correct destination.

Event-handlers contain sequences that control the order in which nodes are started and stopped. Each step in a sequence references a node by its name using the node-name field. The name field on the sequence step itself is a human-readable label for the step. Neither name nor node-name may be a macro — both must be static strings.

Example — sequence step that starts the encoder on PRE-TX:

{
  "nodes": [
    {
      "name": "Primary-Encoder",
      "node-type": "encoder_v4",
      "input-values": { ... }
    }
  ],
  "event-handlers": [
    {
      "events": ["PRE-TX"],
      "sequence": [
        {
          "nodes": [
            {
              "name": "Start primary encoder",
              "node-name": "Primary-Encoder",
              "desired-state": "RUNNING"
            }
          ]
        }
      ]
    }
  ]
}

node-name must match the name of an existing node in the Template exactly. Because node names are the sole identifier within a Template, they must be unique — duplicate names are not permitted.