# 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).

```javascript
// 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 one specific title with new variable values and animate it on screen:

```javascript
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.

```javascript
let titlesByName = {};
ServiceHandler.scheduler.scheduleCommand('getTitlesControlInfo', {}, {}, (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 (the real object will have much more detail):
{
	"channel": "0",
	"id": "{adf82825-daea-4db4-a919-b1394d257f1e}",
	"inSwitcher": "0",
	"input": "API Tour: JSON Command Tester",
	"inputs": [
		{
			"name": "API Tour: JSON Command Tester",
			"url": "/API Tour/tour/JsonCommands.html"
		}
	],
	"name": "New Title",
	"playStatus": "Off",
	"renderProgress": "1",
	"status": "Done",
	"type": "title",
	"url": "/API Tour/tour/JsonCommands.html",
	"variables": [
		{
			"value": "Name",
			"variable": "Name"
		},
		{
			"value": "Subtitle",
			"variable": "Subtitle"
		}
	]
}
*/
```

Make sure you read [Recommendations for Efficient Title Updates](/captivate-api/javascript-api-reference/using-the-servicehandler/recommendations-for-efficient-title-updates.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.newbluefx.com/captivate-api/javascript-api-reference/using-the-servicehandler/scheduleaction-method.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.