Working with a REST-based Driver

Viz Mosart offers an easy to create, generic driver which can send REST commands to an external device. The initial driver construction is explained in section Generic REST Driver.

This section explains how to communicate with a REST-based driver from a template.

Template Commands

To configure REST commands

 Begin by globally enabling Generic Rest Commands:

1. Navigate to AV Automation menu > Devices > Template editor.

2. Select or create a new template.

3. In the device's Function area (grey/black to the left), right-click and select Enable > Generic REST Commands.

   

4. In the Generic REST Commands Properties menu that appears, click the Plus (+) sign or Add command to add a new REST command.
   You can add up to 50 commands.

   

5. A command placeholder appears in the Commands list (left side) with configurable properties to the right.

   

6. Configure the properties for a Generic REST command as follow:

• Command title: The name that identifies the generic REST command. Default: Command.

• Assign to device: Select the Generic REST device configured in Mosart Administrator Settings to execute the command.

  • If no devices are available, you must first define your REST driver.

  • If no device is selected, the command will not be executed. Default: empty string.

• Execute command on: Specifies when Viz Mosart should execute the command, relative to the template lifecycle.
  Options include when the template is cued (Preview), taken on-air (Program) or when the template is taken out (Out). Default: Preview.

  

• Relative Path: The resource path appended to the Base URL for the selected device.

• URL Preview: This field displays a preview of the complete URL, composed of the Base URL, Relative Path, and any extra parameters specified in the Parameters section.

• Request method: The HTTP method used for the request.
  Options are: GET, PUT, and POST. For PUT or POST methods, the Content Type and Body of the request can be configured.

• Content type: Specifies the value for the Content-Type HTTP header, indicating media type of the resource or data in the request body.
  Required for PUT and POST methods.
  Common Content-Type values include text/plain, text/xml, application/xml, application/json.
  The charset parameter can be used to set the character encoding for the text being sent. Default: text/plain; charset=utf-8.

• Body: The data sent in the request body. Required for PUT and POST methods. Body must be formatted according to the specified Content Type.

  

• Parameter: Additional parameters can be included in the command request by adding them in this list using the Plus (+) sign. This gives the possibility of providing newsroom tags for the parameters' values, enabling dynamic control from the newsroom control system (NRCS).
  In the following example, two parameters are added to the request command.
  - Parameter Name is attached to the Relative Path with a static value main_a_named_input.
  - Parameter Value is added in the Parameters section with static value INPUT6 and a newsroom tag attached. This enables the value to be overwritten from the NRCS when planning the show design.

  

  Newsroom tags
  You can add/remove/change a newsroom tag. Click the three dots to the right of the Name/Value row:

  

  If a parameter is included in both Relative Path and the Parameters listing, the value in Parameters will take precedence, overwriting the value in Relative Path.

• Header: To set authentication tokens, cache control, or other custom headers required by the REST server, additional HTTP headers can be included in the request.
  Headers get added in a similar way as Parameters, with an option of using a newsroom tag as a header value.

Placeholders

Placeholders let you insert dynamic data into the REST URL, headers or body. During show execution, these placeholders are replaced with current values just before the REST command is sent.
A placeholder can hold, for example:

- attributes and fields from a Mosart item
- an XPath extraction relative to the Mosart item
- the Current/Next story information.

Supported placeholders:

• [field:fieldName]
  A field from the NRCS (for example, an NRCS column mapped in Mosart Administrator’s Story External Metadata as an item_variable)
  or a template variable known as a newsroom tag, for example, [field:clip_hirespath].
  In the example below, the field clip_hirespath is defined as newsroom tag on the template, so that the clip ID defined in the NRCS is inserted in the Mosart item:

  

  In the next example below, the field sr_final_clip_name inserts data from an NRCS column into the Mosart item:

  

• [item:attributeName]
  An attribute from the <item> XML representing a Mosart item. For example, [item:type].
  In the screenshot below, the rundown ID found as an attribute in a Mosart item, is passed to the URL REST call as a sub-path:

  

• Predefined placeholders

  • [CurrentStoryId], [CurrentStoryName]: ID and name of the on-air story.

  • [NextStoryId], [NextStoryName]: ID and name of the Mosart story marked as Set as Next.

• $xpath:expression$
  With an XPath query, you can extract data from the <item> XML which is representing a Mosart rundown item.
  Example: $xpath:/item/fields/field[@name='graphics_id']/@value$.

In the example below, we send information about the overlay graphics found on a story item:

Examples

1. Sending the next story id to a teleprompter.
   On a camera template, configure a Generic REST command on Program to include the next story ID using the predefined placeholder NextStoryId, either in the request path or in the body as supported by the teleprompter REST endpoint.

   

2. Placeholders defined as a relative path, sub-path or parameter in either the Body or Headers:

   

3. Pass the data from the NRCS through a MOS object into a Generic REST command configured on a Mosart template.
   As an example, instructions on movement and duration of a selected robotic camera is provided from the NRCS.
   The NRCS instructions detailing the camera ID and movement duration is provided through a MOS object that Viz Mosart does not by default, support.
   If the device has support for REST API, these instructions can be executed with generic REST commands, as illustrated below.

   1. In the NRCS, build a story containing a Mosart Primary template and an empty Accessories template, followed by the MOS object that contains the robotic camera details.
      The MOS object is unknown to Viz Mosart, so we attach the MOS object data in an Accessories template.

      

   2. Use the Field Mapping in file newsroomsettings.xml (located on the Mosart server) to attach the MOS object data to the ACCESSORIES template.

      

   3. Load the rundown from the Mosart UI and verify that details from the NRCS are passed to the Mosart item:

      

   4. Open the ACCESSORIES template and add a Generic REST command with placeholders to resolve to the fields itemEdDur and objid added on the Accessory item.

      

Command Management

 To remove a configured command

• Click on the three dots to the right of a command row in the list of commands and select Remove command.

  

Troubleshooting

Here are some steps to take if results are not as expected.

To verify the execution of a REST command

1. To verify the execution of REST commands configured in a template, run the template using the Take button.

2. Check the lower-left Log area of AV Automation for execution confirmation from the Mosart server.

   

3. Confirm the expected outcome on the target device.

If the command failed to execute, verify the Mosart logs for more information.

To verify a REST command is correctly configured

• Copy the URL from the field URL Preview and execute the command using a browser or a REST client application like Postman.