External Control Configuration

To make a job controllable via external elements like mixing control faders or buttons, it must contain a specification to be controllable.

This applies to directly created jobs as well as to jobs, which were created by the ROAD scheduling. In that case the schedule's job description or the job template, which is referred to by a schedule, needs to contain a external control configuration.

External Control Specification

When a job is created, which contains an external control configuration, the ROAD Service will care for instantiating the needed control module (e.g. for Ember+) and listen to events received from this module while the job is active.

In case the external control module cannot be initialized, job creation will be stopped with an error.

Breaking change

Note this specification was changed while development of version 1.4.469.0 with a breaking change, so older configurations need to be adapted. The former specification is still available in v1.3 of this documentation.

This external control configuration defines the type of module (e.g. Ember+), the module's config XML and a list of input and output control items:

"externalControl": {
	"controlModule": "EmberPlus",
    "controlModuleConfig": "<xml ...>",
    "inputs": [
          { input definition },
          { input definition },
          ...
     ],
    "outputs": [
          { output definition },
          { output definition },
          ...
      ]
  }

List of all configuration parameters

This list is provided here for completeness. Everything except the two first basic parameters is described again in its context in the paragraphs below.

The keys "inputs" and "outputs" each contains an array of definitions. By this it is possible to add as many definitions as required for a ROAD job.

Input Definitions

This paragraph describes the configuration parameters inside an input definition. There's two general variants depending on usage of a GenericEvent (supported by any Ember+ device) or DHD-specific line specifications. See column "Used by" in table above.

The basic parameters are described above; they differ depending on definition for a DHD console or a generic event.

The following actionType values are supported:

• "ToggleRunning": When the specified event is received, the job is switched between Running and a defined non-running state
  • ActionCommand can be set to define the non-running state (e.g. for Pause, PauseOutputSwitch, Finish or Cancel). Note a stopped job won't be there any more for a subsequent start command.
    A toggle always refers to the current state of the job in the moment the command is received. So two toggle commands received in a very short frequency might lead into only one actual toggle action.
• "JobState": When the specified event is received, the job is controlled to a new state.
  • ActionCommand is mandatory and defines the requested new job state. "PauseOutputSwitch" is a special value here as it's not an actual job state, but leads into a pause in combination with a switch of job's output.
    See above for more details.
• "Marker": When the specified event is received, the job's output will receive a marker at the current time position.
  • Options.MarkerGraphName is optional: Here a comma-separated list of output graph names can be provided to specify which output graphs' entries are to set the marker.
    If this is not defined, for all existing output graphs of the job a marker will be set by default.
  • Options.MarkerLabel is optional to define a descriptive text for the markers.

Output Definitions

The basic parameters for an output definition with GenericEvent (DHD lines are not supported for output):

• eventType: must be "GenericEvent"
• eventName: mandatory
• eventParameter: optional, but used almost always
• actionType: mandatory

For actionType "JobState" there is one mandatory additional field, to be provided inside "options":

• options.applyJobState: can be one of
  
  • the ROAD current job states Waiting, Paused, Running, Finished, Cancelled, Updating, Error, Terminated
  • a list of ROAD current job states, separated by commas
  • "default": This means everything not addressed for the jobState in other event definitions for the same eventName (all output events with a common eventName build a group). It is recommended to always define a default to assure every job state is covered.

Examples

{
  // Here is a job definition
  ...
  "jobDescription": {
    "pipeSpec": {
      ...
    },

  "externalControl": { // already existing config inside job
    "controlModule": "EmberPlus",
    "controlModuleConfig": "<?xml ...>...</Settings>",

    "inputs": [
      {
        "eventType": "StartStop", // DHD event
        "eventLine": 2,
        "actionCommand": "Finish" // stop action
      },
      {
        "eventType": "FaderMoved", // DHD event
        "eventLine": 2,
        "actionCommand": "PauseOutputSwitch" // stop action (this is default)
      },
      {
        "eventType": "GenericEvent", // generic event
        "eventName": "Recording", // (this is named "Unique Id" in the config tool, but eventName in the API)
        "eventParameter": "Start", // (all case-insensitive) optional, considered if defined
        "actionType": "JobState",
        "actionCommand": "Start"
      },
      {
        "eventType": "GenericEvent",
        "eventName": "Recording", // (this is named "Unique Id" in the config tool, but eventName in the API)
        "eventParameter": "Finish", // (all case-insensitive) optional, considered if defined
        "actionType": "JobState",
        "actionCommand": "PauseOutputSwitch"
      },        {
        "eventType": "GenericEvent",
        "eventName": "StartStop",
        // intentionally no "eventParameter"
        "actionType": "ToggleRunning",
        "actionCommand": "PauseOutputSwitch" // stop action (this is default) 
      },
       {
        "eventType": "GenericEvent",
        "eventName": "Set_Marker",
        // in this example we omit the eventParameter, but it could be used here optionally
        "actionType": "Marker",
        "options": {
          "markerGraphName": "Output1"
        }
      },
      {
        "eventType": "GenericEvent",
        "eventName": "Set_Marker_All",
        "actionType": "Marker",
        "options": {
          "markerGraphName": "Output1, Output2", // allow a comma separated list in a string (restricts graph names to not use commas)
          "markerLabel": "At this timecode the speaker changed"
        }
      }
    ],

    "outputs": [
      {
        "eventType": "GenericEvent",
        "eventName": "Light_Recording",
        "eventParameter": "ON",
        "actionType": "JobState",
        "options": {
          "applyJobState": "Running"
        }
      },        {
        "eventType": "GenericEvent",
        "eventName": "Light_Recording",
        "eventParameter": "YELLOW",
        "actionType": "JobState",
        "options": {
          "applyJobState": "Waiting"
        }
      },
       {
        "eventType": "GenericEvent",
        "eventName": "Light_Recording",
        "eventParameter": "OFF",
        "actionType": "JobState",
        "options": {
          "applyJobState": "default" // everything not addressed for the JobState in other event definitions for this group
        }
      }
    ]
  }
}

Providing a Standby Job by Scheduling

If there is no specific client application being responsible for creating a job, which is controllable via external sources, the ROAD scheduling can be used to care for having a "standby job" active, which is there to wait for a control event. See also Understanding ROAD Schedules

This means to create a schedule containing a JobDescription with field ExternalControl or referring to a template containing it. The TimePlan of this schedule can be defined to run always or at specific times. The stop command should then not be configured to close the job (via "actionCommand"), because the scheduler won't restart it immediately and then there is no more standby job.

Note one exception applies to scheduling of jobs with ExternalControl configuration: By default they start in state waiting (other jobs start in running) or in another state, if specified in the JobDescription.