scheduleAction Method

This method is used to control title playback and/or to update variables with new values. The callback will be passed as a JSON-encoded string with the results of the command (and error messages if applicable).

// callback version
ServiceHandler.scheduler?.scheduleAction(action, inputName, titleId, variables, callback);

// promise version
await ServiceHandler.scheduler?.scheduleAction(action, inputName, titleId, variables);

• action : See below for a description of some different possible actions.

• inputName: Schedule the action on all titles connected to the input with this name. Use the empty string ("") to schedule the action on all titles in the project or when specifying the titleId.

• titleId: Schedule the action on the one title identified by its internal id value. Use the empty string ("") when specifying the inputName. The titleId value can be retrieved by using API commands (the easiest way to get titleId is with the getTitlesPlayStatus or the getTitlesConnected command, see below).

• variables: Basic JavaScript object of variable names and values.

• callback: The callback will be passed a JSON-encoded string with the results of the command (and error messages if applicable).

• promise: If no callback function is given, the function will return a promise that will resolve to a JavaScript object.

  • NOTE: Promises will automatically parse the API response to an object, but callbacks return an unparsed string.

An action is usually one of the following presets (capitalization doesn’t matter):

Action	Description
animateIn	Start at the beginning and play up to the pause point.
animateOut	Start at the pause point and play out.
alert	Play the title in, hold for duration, then play out.
cutIn	Start playback in the middle and hold.
cutOut	Stop immediately.
render	Render the selected variable(s) so they are ready to play.
update	Update the selected variable(s) using animations.
still	Update the selected variable(s) instantly.
hide/show	Turns visibility on/off for any variable named in the variable map (ignoring values).
automatic	Animate In, Update, or Animate Out. See below.
smart	Similar to Automatic, See below.

How Automatic Works: If the specified title is currently not playing, automatic will do animateIn; if the title is playing but the variable values are changing, automatic will do update; but if the title is playing and the variable values have not changed, automatic will do animateOut.

How Smart Works: Does animateIn or update if new variable values are submitted. Does animateOut when all submitted variable values are empty or when an empty variable object {} is provided.

Example:

Full example to update a specific title with new variable values and animate it on screen:

ServiceHandler.scheduler?.scheduleAction(
  'animateIn',
  '',
  '{1234-5678-9011}',
  {
    Name: 'Wolverines',
    Logo: 'https://example.com/wolverines/logo.png',
    Background: '#ff00ff00',
    Progress: '0.45',
    Time: ' 4:56pm',
  },
  console.log
);
// `{
//     "command": "schedule",
//     "reply": "schedule",
//     "success": true
// }`

Easy Way to Get Title Ids

Wherever a title parameter is used, you can use either the internal title id, or the name of the title as it appears in the project panel. For the most precise control, we recommend using the title id wherever possible. To get title ids, use a function like this when you first connect to the scheduler.

let titlesByName = {};
ServiceHandler.scheduler?.scheduleCommand('getTitlesPlayStatus', {}, {}, (result) => {
  let data = JSON.parse(result);
  if (data.titles) {
    for (let title of data.titles) titlesByName[title.title] = title.id;
  }
});
/* each title will be an object like this:
{
  "id": "{4a04ecc7-5c46-4d5d-9a71-5dbc8b12804f}",
  "input": "Shared: Objects,Clocks: Custom Clock",
  "playStatus": "Off",
  "title": "GenericScoreboard"
}
*/

Recommendations for Efficient Title Updates

When you have a heavily animated graphic that takes multiple seconds to render, consider pre-rendering values in advance. As soon as you know the value of the variable you will want to display, send a render action for that specific variable to the specific title and then wait before sending the actual update or animateIn action.

You can determine the current render status for any title by using the renderStatus command described under the scheduleCommand section.

Additionally, whenever your graphic is heavily dependent on numerical data, consider setting up those numbers as pattern variables in your graphic, in your InputBehavior definition, or issuing a updateInputDefinition command to add a pattern to an existing variable. When you use a pattern for a text variable, all possible values of each digit are rendered separately in advance, so they can be used immediately when needed. As a side benefit, you also get your animation applied to each digit independently.

Summary:

• Set up your graphic to use pattern variables for every numeric value that needs to update immediately.

• Whenever you know some variable data in advance of when it needs to be displayed and using a pattern doesn't make sense (e.g. names in a baseball line-up, or a team’s jersey numbers), send a render action for each possible value of that variable.

By sending render as soon as you can, you ensure your title will be completely ready for any data you send to it.