Working with Generic REST Drivers

Viz Mosart offers an easy to create, generic driver that sends REST commands to an external device. Features for these drivers can be controlled from a standard Mosart template, as described in section Controlling a REST-based Driver.

Key features of Viz Mosart Generic REST drivers:

  • Device configuration: Ability to configure multiple devices that are providing REST API services.

  • Authentication support: Options for basic, digest, and API key authentication methods.

  • Connection status monitoring: Ability to monitor the connection status of the device.

  • Heartbeat: Integrated heartbeat mechanism for consistent device status checks.

  • Standby mode: Facility to set devices in standby mode.

  • Template-based command execution: Options to configure and execute commands on cue, take or take-out.

  • HTTP command requests: Support for GET, POST, and PUT HTTP request methods.

  • Integration with newsroom systems: Enables the use of newsroom tags in request commands. This allows journalists to overwrite with content from their newsroom system.

  • Directtakes functionality: Execute directtakes with REST commands for a configured device from templates or keyboard shortcuts in the Viz Mosart UI.

Out-of-the-box features available with a Generic REST driver:

This section presents the following topics:

Setting up and Connecting to a REST-based Device

Tip:

You construct your REST-based driver from the Settings menu in the combined Mosart Administrator utility.

  1. Open the Settings window. There are two methods:

    1. From the Manus Administrator console, type settings.

    2. From AV Automation menu bar, navigate to Devices > Settings (Ctrl +Shift +P).

  2. In the left-side of the Settings menu, select Generic REST drivers.

    image-20250113-090614.png

  3. Add a new device by either

    1. Clicking Add device or

    2. Clicking the plus (+) sign next to the header Devices.
      You can add up to 50 devices.

  4. A new device appears in the device list (below heading Generic REST drivers).
    You configure its properties in the right side panel.

    image-20250127-095502.png

    1. Device title: A name that uniquely identifies the generic REST device. Default: Untitled.

    2. Base URL: This mandatory field must include the minimum necessary components of the REST API's URL: the scheme (http:// or https://) and the hostname or IP address of the device.
      Additionally, it can include a common resource path that forms the base for all requests to the device. Essentially, the Base URL should represent the shared part of the URL used in all requests to the device.

    3. Status URL path: The resource path to be attached to the base URL for testing the connection to the device's REST API or checking the device's heartbeat.
      Provide this if the base URL alone is insufficient for testing the connection. Default: empty.

    4. Enable heartbeat: When enabled, Viz Mosart will periodically send a request to the combined URL (Base URL concatenated with the Status URL Path) to verify the device's endpoint.
      This check occurs at the interval specified in the setting Connection interval (below). Default: disabled.

    5. Connection interval: The interval, in seconds, for sending the heartbeat request. Default: 10 seconds. Minimum: 1 second.

    6. Request timeout: The maximum time Viz Mosart will wait for a response from the server when an HTTP request is sent to the device, before timing out. Default: 10 seconds.

    7. Authentication type: Authentication type required by the device. Options include:

      • None: No authentication required by the device. This is also the default.

      • Basic: A simple, un encrypted authentication scheme requiring Username and Password as configured on the device.

      • Digest: A more secure authentication scheme requiring Username and Password as configured on the device.

        image-20250127-100413.png

    8. ApiKey: An authentication scheme requiring the API Key name and value as configured on the device.
      For example, when configuring Mosart Remote Control REST API as a Generic Rest driver, add X-API-Key as the key header and the value of RestApi setting from the Remote Control Dispatcher Service (RCS) configuration file as the API key:

      image-20250127-095928.png

      • OAuth2: Authentication using the OAuth2 authentication scheme that requires authentication towards a separate Authentication server.

    9. Authentication Server Url: The URL of the server that you will be authenticating towards. Only Password grant type is supported.

      image-20250127-100221.png

  5. Test the connection by clicking Test Connection.
    If the connection fails, an error message is displayed. See Troubleshooting (below) for more details.

Note: A REST-based device might not require authentication for certain HTTP request commands, such as those used to check the API version. These commands are commonly utilized for testing the connection to the device's REST API.

However, a successful response from this type of test does not necessarily verify authentication. In scenarios where authentication is crucial, it is recommended to configure the Status URL path to a resource that demands authentication.
Successful testing with this path ensures proper authentication setup. Afterwards, you can change this path to the one intended for regular heartbeat checks.

For example, the Mosart REST API does not require authentication for the endpoint http://lbu-pc:55167/api/v1/build. Consequently, a connection test using this URL does not validate the validity of the stored API Key.

  1. Once connection is successfully established, enable or activate the device by toggling the Switch button next to the device's name.

    r2.png

    This action initiates an HTTP connection to the device, preparing it to receive commands from Viz Mosart.

Note: If the device is not enabled, Viz Mosart will not transmit any commands to it!

  1. As necessary, add, configure and enable more devices:

    image-20250127-100735.png

  1. After configuring the device(s), save all settings by clicking Save.

  2. In the AV Automation UI, check that the enabled device(s) are displayed in the Status panel.

    1. If no heartbeat is configured, Mosart only checks the connection once and shows the correct status (Green for OK, Red for not OK).

    2. If a heartbeat is configured, hovering over the device in the Status area displays last heartbeat check details.

    3. You can reconnect to the device in AV Automation, by pressing Ctrl+Shift+Z.

Management of REST-based Devices

 To remove a device

  • Select a device from the list of devices, right-click on the three dots to the right and select Remove device.

To enable, disable or remove all devices

  • Right-click on the three dots next to the right of Devices and select an operation from the context menu.

Controlling a REST-based Driver

Standard Viz Mosart templates can be used to control a REST-based driver.

These show-specific operations are described in section Controlling a REST-based Driver.

Troubleshooting

When testing, if the connection to the device fails:

  • Ensure the Base URL is correctly configured.

  • Consider adding a Status URL Path in addition to the Base URL, if needed, and ensure it is correctly formatted.

  • Check that the correct authentication is set up if the device requires it.

  • Confirm that AV Automation is operational.

  • Review the Mosart logs for further details.