Viz Arc provides a Web API that allows you to set DataMap variables, trigger specific actions or control the Playlist.

The samples below assume that Arc runs on "localhost" and the web server is configured to run on port 5004, which can be configured in general configuration. Please note that this Web API is only accessible when the Viz Arc application is running.

This section contains the following examples:

ActionExecuter
ActionCanvas
DataMap
Playlist
PlaylistExecuter
Playlist Filtering
Projects
Profiles
Sample Usage

Information: The samples below use curl command line tools to demonstrate usage and python to beautify the returned JSON output. Note that these tools are not required for the Web API to function correctly.

ActionExecuter

The ActionExecuter endpoint allows you to execute a specific action either by using its name or its ID.

api/ActionExecuter/{id or name}

curl -s -X GET http://localhost:5004/api/ActionExecuter/Opener
 
curl -s -X GET http://localhost:5004/api/ActionExecuter/27cc7a3b-6f90-4d88-9101-a356a1668d83

Using the ID variant is preferable as it uniquely identifies an action. Although the name might appear multiple times in your action collection, only the first action with the specified name will be triggered.

ActionCanvas

The ActionCanvas endpoint allows you to retrieve all actions of a project, including information about their position, color, id etc. An interactive demo page using this API can be found at http://localhost:5004/.

Get All Actions

api/ActionCanvas

this endpoints returns all actions of the currently loaded project. The property "actions" contains an array of all actions. The property "tabs" contains all the information about the action tabs.

curl -s -X GET http://localhost:5004/api/ActionCanvas | python -m json.tool
{
    "actions": [
        {
            "actionColor": "#65686B",
            "actionType": null,
            "delay": 0,
            "engineType": "VIZ",
            "heightSector": 1,
            "name": "AB",
            "tab": 0,
            "textColor": "#DBDCDD",
            "type": "Template",
            "uuid": "b78801bd-c802-42dd-ae11-9955c53dbfe3",
            "widthSector": 1,
            "xSector": 0,
            "ySector": 0
        },
        {
            "actionColor": "#65686B",
            "actionType": null,
            "delay": 0,
            "engineType": "VIZ",
            "heightSector": 1,
            "name": "CD",
            "tab": 0,
            "textColor": "#DBDCDD",
            "type": "Template",
            "uuid": "6dd3107a-9487-4f32-92a0-b7eb83a1328f",
            "widthSector": 1,
            "xSector": 1,
            "ySector": 0
        },
        {
            "actionColor": "#65686B",
            "actionType": null,
            "delay": 0,
            "engineType": "VIZ",
            "heightSector": 1,
            "name": "Opener",
            "tab": 1,
            "textColor": "#DBDCDD",
            "type": "Template",
            "uuid": "27cc7a3b-6f90-4d88-9101-a356a1668d83",
            "widthSector": 1,
            "xSector": 0,
            "ySector": 0
        },
        {
            "actionColor": "#65686B",
            "actionType": null,
            "delay": 0,
            "engineType": "VIZ",
            "heightSector": 1,
            "name": "Show Monitor",
            "tab": 1,
            "textColor": "#DBDCDD",
            "type": "Template",
            "uuid": "ae7d2e75-552f-40e7-8c3d-7a8ef716809a",
            "widthSector": 1,
            "xSector": 0,
            "ySector": 1
        }
    ],
    "tabs": [
        {
            "isEditorOnly": false,
            "name": "DATA"
        },
        {
            "isEditorOnly": false,
            "name": "INTERACTIVE"
        }
    ]
}

DataMap

You can set, read and delete DataMap variables through the Web API. The DataMap endpoint is accessible on http://localhost:5004/api/DataMap. An interactive demo page can be found at http://localhost:5004/DataMap.

Get the Entire DataMap

Use the endpoint http://localhost:5004/api/DataMap to get the entire DataMap

curl -s -X GET http://localhost:5004/api/DataMap | python -m json.tool
[
    {
        "key": "key2",
        "value": "value2"
    },
    {
        "key": "key1",
        "value": "Value1"
    },
    {
        "key": "WhiteListIPRanges",
        "value": "0.0.0.0/0"
    }
]

To Get a Single Value from the DataMap

Use the endpoint http://localhost:5004/api/DataMap/key to get the value of "key":

curl -s -X GET http://localhost:5004/api/DataMap/key2 | python -m json.tool
{
    "key": "key2",
    "value": "value2"
}

Set a Key/Value Pair

Send a POST request to the DataMap endpoint using a json string in the body containing key and value pair of the new variable. If the key already exists the value will be updated.

curl -s -H "Content-Type: application/json" -d "{ \"Key\": \"Hello\", \"Value\": \"World!\" }" -X POST http://localhost:5004/api/DataMap

Delete a DataMap Entry

Delete a key/value pair using the key and a DELETE message, for example to delete "key2" use:

curl -s -X DELETE http://localhost:5004/api/DataMap/key2

Playlist

You can read, trigger, preview and iterate through the playlist through the Web API. The Playlist endpoint is accessible on http://localhost:5004/api/PlayList. An interactive demo page can be found at http://localhost:5004/PlayList.

Get the Entire Playlist(s)

The endpoint api/PlayList returns the entire playlist(s):

curl -s -X GET http://localhost:5004/api/PlayList | python -m json.tool
[
    {
        "duration": 10.0,
        "index": 0,
        "name": "Morning",
        "rows": [
            {
                "actionUUID": "b78801bd-c802-42dd-ae11-9955c53dbfe3",
                "duration": 5.0,
                "id": "aaf0b451-1bb6-4bae-b11d-3b0c5f552e36",
                "name": "AB"
            },
            {
                "actionUUID": "6dd3107a-9487-4f32-92a0-b7eb83a1328f",
                "duration": 5.0,
                "id": "58b51c71-a904-4c95-b5d8-f42184af025e",
                "name": "CD"
            }
        ]
    },
    {
        "duration": 15.0,
        "index": 1,
        "name": "Afternoon",
        "rows": [
            {
                "actionUUID": "27cc7a3b-6f90-4d88-9101-a356a1668d83",
                "duration": 5.0,
                "id": "7f284bd1-a727-4e26-aea8-f417010c5386",
                "name": "Opener"
            },
            {
                "actionUUID": "955a622a-862b-4206-9658-a48b0c9f9a7e",
                "duration": 5.0,
                "id": "f43b4470-d08c-4261-8fb2-58ef97c4db28",
                "name": "Closer"
            },
            {
                "duration": 5.0,
                "id": "483231c0-5484-478c-9bbc-74530dafa7cd",
                "loop": false,
                "name": "old",
                "rows": [
                    {
                        "actionUUID": "ae7d2e75-552f-40e7-8c3d-7a8ef716809a",
                        "duration": 5.0,
                        "id": "c542f3d4-53d3-4aa1-82d1-8e75ae86342b",
                        "name": "Show Monitor"
                    }
                ]
            }
        ]
    }
]
	

The GET method returns all Playlist tabs and their respective rows and folders.

images/download/attachments/105108793/image2021-2-8_23-45-55.png

The screenshot above shows the query result for the "Morning" Playlist tab.

images/download/attachments/105108793/image2021-2-8_23-47-3.png

The screenshot above shows the query result for the "Afternoon" Playlist tab.

Get a Playlist by Index

The endpoint api/PlayList/{index} returns a Playlist tab by index:

curl -s -X GET http://localhost:5004/api/PlayList/0 | python -m json.tool
{
    "duration": 10.0,
    "index": 0,
    "name": "Morning",
    "rows": [
        {
            "actionUUID": "b78801bd-c802-42dd-ae11-9955c53dbfe3",
            "duration": 5.0,
            "id": "17a6ee8d-8c82-4480-9bda-32e4b9447336",
            "name": "AB"
        },
        {
            "actionUUID": "6dd3107a-9487-4f32-92a0-b7eb83a1328f",
            "duration": 5.0,
            "id": "4580c837-69a9-41b4-95dc-29b05f1ae0d4",
            "name": "CD"
        }
    ]
}

Starting from index 0 this call returns a single playlist tab only.

PlaylistExecuter

The PlaylistExecuter endpoint allow you to execute and preview individual playlist elements identified by their id.

Execute

api/PlaylistExecuter/execute/{id}

Executes the playlist element identified by id.

curl -s -X GET http://localhost:5004/api/PlaylistExecuter/execute/2628b63d-e947-4ee6-9dd2-5c90525e2cf5

Continue

api/PlaylistExecuter/continue/{id}

Continues the playlist element identified by id.

curl -s -X GET http://localhost:5004/api/PlaylistExecuter/continue/2628b63d-e947-4ee6-9dd2-5c90525e2cf5

Preview

api/PlaylistExecuter/preview/{id}

Executes the playlist element identified by id on the preview channel.

curl -s -X GET http://localhost:5004/api/PlaylistExecuter/preview/2628b63d-e947-4ee6-9dd2-5c90525e2cf5

Preview Continue

api/PlaylistExecuter/previewContinue/{id}

Continues the playlist element identified by id on the preview channel.

curl -s -X GET http://localhost:5004/api/PlaylistExecuter/previewContinue/2628b63d-e947-4ee6-9dd2-5c90525e2cf5

Playlist Controls on the Currently Selected Playlist

The following commands are applied to the currently selected Playlist in Viz Arc:

Execute Current

api/PlayList/executeCurrent

Executes the currently selected playlist element:

curl -s -X GET http://localhost:5004/api/PlaylistExecuter/executeCurrent

Continue Current

api/PlayList/continueCurrent

Continues the currently selected playlist element:

curl -s -X GET http://localhost:5004/api/PlaylistExecuter/continueCurrent

Out Current

api/PlayList/outCurrent

Takes out the currently selected playlist element (only for template actions):

curl -s -X GET http://localhost:5004/api/PlaylistExecuter/outCurrent

Preview Current

api/PlayList/previewCurrent

Executes the currently selected playlist element on the preview channel:

curl -s -X GET http://localhost:5004/api/PlaylistExecuter/previewCurrent

Preview Continue Current

api/PlayList/previewContinueCurrent

Continues the currently selected playlist element on the preview channel:

curl -s -X GET http://localhost:5004/api/PlaylistExecuter/previewContinueCurrent

Preview Out Current

api/PlayList/previewOutCurrent

Takes out the currently selected playlist element on the preview channel (only for template actions):

curl -s -X GET http://localhost:5004/api/PlaylistExecuter/previewOutCurrent

Execute And Next

api/PlayList/executeAndNext

Executes the currently selected playlist element and moves to the next playlist item:

curl -s -X GET http://localhost:5004/api/PlaylistExecuter/executeAndNext

Goto First

api/PlayList/gotoFirst

Selects the first playlist item:

curl -s -X GET http://localhost:5004/api/PlaylistExecuter/gotoFirst

Playlist Filtering

It is possible to inhibit calls to the playlist API using two mechanisms, by IP whitelists or URL query parameters. Both methods are described below.

IP Whitelists

You can configure a IP addresses/ranges using a semi-colon (;) separated list of IP ranges (in CIDR notation) that are allowed to use the Playlist API. By default, the rage is 0.0.0.0/0 which means all external hosts can use the API. To allow only specific IP addresses to use the Playlist API, you can specify, for example, 192.168.1.12;192.168.1.23 as your Whitelist IP Range, thus allowing only those two machines to use the API.

The IP Whiltelist can can be configured manually in the general configuration or it can be set via scripting using a DataMap key WhiteListIPRanges.

images/download/attachments/105108793/datamapwhitelist.png

set Whitelist IP's through scripting

SetData("WhiteListIPRanges", "192.168.1.12;192.168.1.23")

In this example, only hosts 192.168.1.12 and 192.168.1.23 can trigger Playlist actions from the web API.

Filter by URL Query Parameters

Another way to filter requests is to use query parameters in the URL of a request and specify key and value values in the DataMap to use as comparison.

For example, a query:

http://localhost:5004/api/playlistExecuter/executeCurrent?Source=B20&Hello=World

contains two query parameters Source with a value of B20 and Hello with a value of World. Let's assume we want to let execute only calls that have as Source parameter the value B21.

To do so, set the two DataMap variables PlaylistExecuterConditionKey and PlaylistExecuterConditionValue to the two respective values:

images/download/attachments/105108793/conditionkeys.png

set comparison values script

SetData("PlaylistExecuterConditionKey", "Source")
SetData("PlaylistExecuterConditionValue", "B21")

When those values are not empty, the Playlist API checks whether the URL contains a Key/Value pair matching the DataMap values.

In this example, calling:

http://localhost:5004/api/playlistExecuter/executeCurrent?Source=B21&Hello=World

executes the currently selected Playlist element, while calls to:

http://localhost:5004/api/playlistExecuter/executeCurrent?Source=B20&Hello=World

or

http://localhost:5004/api/playlistExecuter/executeCurrent

do nothing as the condition Source = B21 is false.

When calling any Playlist API method, a JSON string is stored in the DataMap containing useful information like the origin of the caller, the list of query parameters passed and the command being used.

The call http://localhost:5004/api/playlistExecuter/executeCurrent?Source=B21&Hello=World causes the DataMap variable PlaylistExecuterInfo to be set to:

{
   "Origin":"127.0.0.1",
   "EndPoint":"executeCurrent",
   "Source":"B21",
   "Hello":"World"
}

This JSON can be easily utilized with a script:

 var js = JSON.parse(GetData("PlaylistExecuterInfo"))
 Console.WriteLine("json of playlist request " + js.Source + " " + js.Hello)
// prints "json of playlist request B21 World"

Projects

The Projects endpoint allows you to get a list of all available projects and to load a project.

Get Projects

api/Projects

Returns a list of all available Projects, first the projects residing on Graphic Hub and then the projects residing on the local file system.

curl -s -X GET http://localhost:5004/api/Projects | python -m json.tool
[
    {
        "checked": false,
        "fullpath": null,
        "lastModified": "2021-02-07T23:03:58",
        "location": 1,
        "name": "AB",
        "newName": null
    },
    {
        "checked": false,
        "fullpath": null,
        "lastModified": "2021-02-07T18:36:58",
        "location": 0,
        "name": "test",
        "newName": null
    }
]

In the sample above, two projects were found, the "location" property indicates whether the project resides on Graphic Hub (value "1") or on the local filesystem (value "0").

Load Project

api/Projects/load/{name}

Loads the project name. It first tries to load the project from Graphic Hub, if it is not found there it searches for the project on the local file system.

curl -s -X GET http://localhost:5004/api/Projects/load/test

Load Project from Graphic Hub

api/Projects/loadGH/{name}

Loads the project name from Graphic Hub.

curl -s -X GET http://localhost:5004/api/Projects/loadGH/AB

Load Project from Local File System

api/Projects/loadLocal/{name}

Loads the project name from the local file system.

curl -s -X GET http://localhost:5004/api/Projects/loadLocal/test

Get Currently Loaded Project

api/Projects/current

Gets the name and location (Local or GraphicHub) of the currently loaded project.

curl -s -X GET http://localhost:5004/api/Projects/current
{
  "Name": "elections2022",
  "Location": "Local"
}

Profiles

The Profiles endpoint allows you to retrieve information about the available Profiles, Channels and Engines.

Get Profiles

/api/Profiles

Returns the entire list of profiles available in Viz Arc.

curl -s -X GET http://localhost:5004/api/Profiles

Get Profiles by Index

/api/Profiles/{index}

Returns a specific profile only specified by index index (starting from 0).

curl -s -X GET http://localhost:5004/api/Profiles/0

Sample Usage

When Viz Arc starts up, an internal web server is launched where you can view a small web demo of the API. Navigate to http://localhost:5004/ (adapt the port to whatever you have configured) in any web browser and you see the currently loaded project in Viz Arc. For example:

images/download/attachments/105108793/image2021-3-2_16-32-40.png

You can click any of the tabs to see a simplified version of the actions. Click any action to execute it.

Click the PlayList tab to see and trigger all available playlists and their elements:

images/download/attachments/105108793/image2021-3-2_16-35-52.png

Click the DataMap tab to view the current DataMap. From here you can add, delete or modify any DataMap variable.

images/download/attachments/105108793/image2021-3-2_17-10-25.png

Triggering a Viz Arc Action from a Web Browser

You can easily trigger a Viz Arc action for the currently loaded project using its GUID or just its name. First, get the GUID and name from the action:

images/download/attachments/105108793/image2021-3-2_17-12-37.png

The GUID is now copied to the clipboard from where you can easily paste it anywhere else (for example, to notepad):

images/download/attachments/105108793/image2021-3-2_17-14-43.png

Typing http://localhost:5004/api/ActionExecuter/203e10df-8ba1-403c-a378-4d93186f4d06 or http://localhost:5004/api/ActionExecuter/default triggers the action.

Information: Be aware that triggering only works when Viz Arc is running and when the project that contains the requested Action is open.