Web API Parameter
Handle
“Handle” is the general term for something which is stored. There are handles for every item: for playbacks, palettes, workspaces, groups, fixtures and more. To get an impression what handles are in your show you might use Titan IDs.
With regards to the Web API there are three ways to identify a handle:
- by usernumber - this is the number you set using
Set Legend
in Titan. In order to use this method denote the handle as
handle_userNumber=2
- by location - this is the 'place' where you find this item in the Titan UI, e.g. the 6th button on page 1 in the Fixtures and Playbackswindow. In order to use this method identify the handle as
handle_location=Presets_1_6
- 'Presets' is the handle group i.e. the workspace window “Fixtures and Playbacks”. See Location for the available groups
- 1 is the page number (1-based)
- 6 is the button number on that page (1-based)
- all three parts are concatenated wih underscores
_
. Titan IDs already gives the correct location string.
- by Titan ID. Everything in the show has a unique ID which is set by the system and cannot be changed by the user. You can get the Titan IDs of your show with Titan IDs. There are some useful reserved IDs for masters, see titanId. In order to use this method to identify a handle the notation is
handle_titanId=2335
.
Example
Let's assume we want to kill a particular cuelist using Playbacks/KillPlayback. The prototype for this is
http://[ip]:4430/titan/script/2/Playbacks/KillPlayback?handle={handle}
Given a show where a cuelist is recorded in the Fixtures and Playbacks window (group: Presets), page 1, button 6, and this cuelist (here: Cue List 2) has the user number 2:
Luckily Titan IDs already shows the Titan ID and the correct location (it's the “Computed Web API Location string”).
We can kill this cuelist by one of the following ways:
http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle_userNumber=2
- by user number
http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle_location=Presets_1_6
- by location
http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle_titanId=2335
- by titan Id
It appears that Titan applies some guessing and interprets the handle as userNumber if no other type is defined. Hence,
http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle=2
does also work.
Errors
Various errors may result from wrong or incomplete parameters:
http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle=Presets_1_6
does not work and throws the error
“Error: Failed to parse value to AcwUserNumber”
Reason: the part _location
is missing, thus Titan tries to parse this as usernumber (default), and fails.
http://localhost:4430/titan/script/2/Playbacks/KillPlayback?2
does not work and results in
“Error: Der Objektverweis wurde nicht auf eine Objektinstanz festgelegt.”
(no object referenced)
Reason: the parameter name and parsing (handle_userNumber) and the equal sign is missing.
http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle_titanId=23350
leads to
“Error: Unable not find handle in group 'playbackHandle' with index '23350'.\r\nParametername: handle”
Reason: the specified handle could not be found (there doesn't exist a handle in that location/with that titanId)
http://localhost:4430/titan/script/2/Playbacks/KillPlayback?
throws
“Error: Die Sequenz enthält kein übereinstimmendes Element.”
(no matching element in sequence)
Reason: the handle wasn't correctly specified or not specified at all
http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle_titanId=
gives
“Error: Die Eingabezeichenfolge hat das falsche Format.”
(wrong format)
Reason: the parameter name and parsing was correctly set but no value given.