Locator

A Locator is a JSON object that is used to identify a Resource in an API request. In Designer API a Resource is typically an editable object in Designer such as Track, Transport, Prop or Screen.

Each Locator can be used to identify a Resource either by its uid (unique identifier) or its name. If the Locator object identifies a Resource by name, the API will use the first Resource that matches the given name.

Properties

Either uid or name must be provided. If both are provided, only uid will be checked.

Property	Type	Description
uid	string	The unique identifier of the Resource. (optional)
name	string	The name of the Resource. If the Locator object identifies a Resource by name, the API will use the first Resource that matches the given name. (optional)

Using Locators

Using a Locator with the uid field can be useful when you want to address a specific Resource programmatically in your show controller, lighting desk, or web application. If you want to enumerate Resources using other query APIs, you can use the uid field to be sure that you are addressing the correct Resource. The uid of a Resource will not change, even if the name of the Resource changes.

Using a Locator with the name field can be useful when you want to identify an object by its name but the name of the object may change in the future. For example, you may want to address a specific Track in your show controller, lighting desk, or web application, but you want to allow the operator to manage the Tracks independently of your implementation - such as replacing a Track later on without needing to reprogram the controller. In this case, you can use the name field in the Locator object to identify the Track by its name, without having to change your implementation if the name of the Track changes.

Example Usage

// Trigger show Track and set play mode using javascript

fetch('/api/v2/session/transport/gototrack', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ 
    transport: { uid: '123456789' }, // `Locator` using uid
    track: { name: 'act 1' }, // `Locator` using name
    playMode: 'playsection' })
});

In the above example, the Transport Resource is identified by its uid, while the Track Resource is identified by its name. The API will use the first Track Resource that it finds with the name ‘act 1’, the ordering of which will be found first is not guarunteed and may change.