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.

Tip: A two minute tutorial video on using the REST API is here.

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 (black row), right-click and select Enable > Generic REST Commands.

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

  5. A new command appears in the Commands list (left side) with its properties configurable on the right side.

  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 device is selected, the command will not be executed. Default: empty string.

    • Execute command on: Specifies when Mosart should execute the command in relation to the template lifecycle. Options include when the template is cued, taken on-air, or when the template is taken out. Default: Preview.

    • Relative Path: The resource path appended to the Base URL configured for the selected device. This path should not start with a scheme (e.g., http://) or a leading slash. It can optionally include query string parameters. For instance, if a parameter value does not require a newsroom tag, it can be added directly to the Relative Path. URL parameters contain a key and value, separated by an equal sign (=). A URL can contain multiple parameters, which are then each separated with an ampersand (&).



    • 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. Available 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, which indicates the 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. It 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 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.


      A newsroom tag can be added/removed/changed using the options in the menu opened by clicking on the three dots to the right of a parameter:


      If a parameter is included in both the Relative Path and the Parameters list, the one in the Parameters list will take precedence and overwrite the value provided in the Relative Path.

    • Header: Additional HTTP headers can be included in the request for setting authentication tokens, cache control, or other custom headers required by the REST server.
      Headers are added similarly to parameters, with the option of using newsroom tags for header values.

Command Management

 To remove a configured command

  • Click on the three dots to the right of an item 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 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.