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 is running on localhost and the In-App Web API is configured to run on port 5004. The In-App Web API port can be configured in the General Settings, under the Communication section. Please note that this In-App Web API is only accessible when the Viz Arc application is running.

A Swagger webapp that describes every API can be found at http://localhost:5004/swagger/.

This section contains the following examples:

Error rendering macro 'toc'

[com.ctc.wstx.exc.WstxLazyException] com.ctc.wstx.exc.WstxUnexpectedCharException: Unexpected character '=' (code 61) (expected a name start character) at [row,col {unknown-source}]: [88,371]

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.

Status

The Status endpoint allows you to get basic information of the running Viz Arc instance, such as version and uptime.

GET api/v1/status

curl -s -X GET http://localhost:5004/api/v1/Status | python -m json.tool

{
	"version": "Viz Arc 1.8.0.2116",
	"license": "CORE",
	"uptime": "00:59:14.8406020"
}

ActionCanvas

The ActionCanvas endpoint allows you to retrieve all actions of a project, including information about their position, color, id etc.. It also allows you to select an action specified by the id or name. An interactive demo page using this API can be found at http://localhost:5004/.

GET /api/v1/actioncanvas

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

curl -s -X GET http://localhost:5004/api/v1/ActionCanvas | python -m json.tool

{
	"tabs": [
		{
			"name": "show",
			"isEditorOnly": false
		},
		{
			"name": "Startlist",
			"isEditorOnly": false
		}
	],
	"selectedTabIndex": 0,
	"actions": [
		{
			"uuid": "a090e1c9-28ad-4c4f-976d-2727befe182d",
			"name": "Title Day 1",
			"type": "TEMPLATE",
			"actionType": null,
			"engineType": "VIZ",
			"xSector": 1,
			"ySector": 0,
			"widthSector": 1,
			"heightSector": 1,
			"tab": 0,
			"delay": 0,
			"actionColor": "#65686B",
			"textColor": "#DBDCDD"
		},
		{
			"uuid": "95c0bc26-fb63-4ffe-becf-bd42db7ae5f8",
			"name": "Startlist",
			"type": "TEMPLATE",
			"actionType": null,
			"engineType": "VIZ",
			"xSector": 0,
			"ySector": 1,
			"widthSector": 1,
			"heightSector": 1,
			"tab": 1,
			"delay": 0,
			"actionColor": "#65686B",
			"textColor": "#DBDCDD"
		}
	],
	"project": "Skating"
}

POST /api/v1/actioncanvas/select/{id | name}

Selects an action specified by the id or name.

curl -s -X POST http://localhost:5004/api/v1/ActionCanvas/select/13ddcaa8-e52a-4357-85d6-5731f3b45ebd

200 OK

ActionExecuter

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

GET /api/v1/actionexecuter/{id | name}

Executes the action specified by the id or name.

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

200 OK

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 is triggered.

GET /api/v1/actionexecuter/{id | name}/continue

Executes a "Continue" on a template action specified by the name.

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

200 OK

GET /api/v1/actionexecuter/{id | name}/out

Executes a "Out" on a template action specified by the name.

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

200 OK

GET /api/v1/actionexecuter/{id | name}/update

Executes a "Update" on a template action specified by the name.

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

200 OK

Arena

The Arena APIs allow you to control the Viz Arena integration.

GET /api/v1/arena/detectArenaCalibration

Detects the calibration.

curl -s -X GET http://localhost:5004/api/v1/arena/detectArenaCalibration | python -m json.tool

200 OK

GET /api/v1/arena/clearArenaCalibration

Clears the current calibration.

curl -s -X GET http://localhost:5004/api/v1/arena/clearArenaCalibration | python -m json.tool

200 OK

GET /api/v1/arena/clearArenaKeyer

Clears the Viz Arena keyer.

curl -s -X GET http://localhost:5004/api/v1/arena/clearArenaKeyer | python -m json.tool

200 OK

GET /api/v1/arena/setArenaCamera/{id}

Sets the active arena camera.

curl -s -X GET http://localhost:5004/api/v1/arena/setArenaCamera/1 | python -m json.tool

200 OK

DataMap

You can set, read and delete DataMap variables through the Web API. An interactive web application can be found at http://localhost:5004/DataMap.

GET /api/v1/DataMap

Gets the list of all the key-value pairs.

curl -s -X GET http://localhost:5004/api/v1/DataMap | python -m json.tool

[
	{
		"key": "Hello",
		"value": "World!"
	},
	{
		"key": "WhiteListIPRanges",
		"value": "0.0.0.0/0"
	}
]

GET /api/v1/DataMap/{key}

Gets the key-value pair identified by the specified key.

curl -s -X GET http://localhost:5004/api/v1/DataMap/key | python -m json.tool

{
    "key": "Hello",
    "value": "World!"
}

POST /api/v1/DataMap

Adds a new key-value pair or an array of them to the DataMap. The payload must be sent as JSON body. If the key already exists the value is updated.

curl -s -H 'Content-Type: application/json' -d

{ 
	"Key": "key", 
	"Value": "hello"
}

DELETE /api/v1/DataMap/{key}

Deletes a key/value pair by sending a DELETE message, for example to delete "key2" use:

curl -s -X DELETE http://localhost:5004/api/v1/DataMap/key2 | python -m json.tool

200 OK

Object Tracker

The Object Tracker APIs allow you to control the Object Tracker integration.

GET /api/v1/objectTracker/takeTracker

Takes all active trackers On Air.

curl -s -X GET http://localhost:5004/api/v1/objectTracker/takeTracker | python -m json.tool

200 OK

GET /api/v1/objectTracker/takeOutTracker

Takes all active trackers Off Air.

curl -s -X GET http://localhost:5004/api/v1/objectTracker/takeOutTracker | python -m json.tool

200 OK

GET /api/v1/objectTracker/previewTracker

Previews all active trackers on the preview channel.

curl -s -X GET http://localhost:5004/api/v1/objectTracker/PreviewTracker | python -m json.tool

200 OK

GET /api/v1/objectTracker/previewOutTracker

Previews out all active trackers on the preview channel.

curl -s -X GET http://localhost:5004/api/v1/objectTracker/PreviewOutTracker | python -m json.tool

200 OK

GET /api/v1/objectTracker/stopTracker/{id}

Stops the tracker with index {id}, starting from index 1.

curl -s -X GET http://localhost:5004/api/v1/objectTracker/stopTracker/1 | python -m json.tool

200 OK

GET /api/v1/objectTracker/setActiveTracker/{id}

Sets the active tracker with index {id}, starting from index 1.

curl -s -X GET http://localhost:5004/api/v1/objectTracker/setActiveTracker/1 | python -m json.tool

200 OK

GET /api/v1/objectTracker/resetPointerOffset/{id}

Resets the pointer offset of the tracker with index {id}, starting from index 1.

curl -s -X GET http://localhost:5004/api/v1/objectTracker/resetPointerOffset/1 | python -m json.tool

200 OK

Playlist

You can read, trigger, preview and iterate through the playlist through the Web API. An interactive web application can be found at http://localhost:5004/PlayList.

GET /api/v1/playlist

Gets all the tabs.

curl -s -X GET http://localhost:5004/api/v1/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/140811494/image2021-2-8_23-45-55.png

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

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

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

GET /api/v1/playlist/{index}

Gets the content of the playlist tab, by specifying its index.

curl -s -X GET http://localhost:5004/api/v1/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.

GET api/v1/PlaylistExecuter/execute/{id}

Executes the playlist element identified by id.

curl -s -X GET http://localhost:5004/api/v1/PlaylistExecuter/execute/2628b63d-e947-4ee6-9dd2-5c90525e2cf5 | python -m json.tool

200 OK

GET api/v1/PlaylistExecuter/continue/{id}

Continues the playlist element identified by id.

curl -s -X GET http://localhost:5004/api/v1/PlaylistExecuter/continue/2628b63d-e947-4ee6-9dd2-5c90525e2cf5 | python -m json.tool

200 OK

GET api/v1/PlaylistExecuter/preview/{id}

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

curl -s -X GET http://localhost:5004/api/v1/PlaylistExecuter/preview/2628b63d-e947-4ee6-9dd2-5c90525e2cf5 | python -m json.tool

200 OK

GET api/v1/PlaylistExecuter/previewContinue/{id}

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

curl -s -X GET http://localhost:5004/api/v1/PlaylistExecuter/previewContinue/2628b63d-e947-4ee6-9dd2-5c90525e2cf5 | python -m json.tool

200 OK

GET api/v1/PlaylistExecuter/playPlaylistByName/{name}

Plays every item in the playlist identified by name.

curl -s -X GET http://localhost:5004/api/v1/PlaylistExecuter/playPlaylistByName/myPlaylist | python -m json.tool

200 OK

GET api/v1/PlaylistExecuter/playPlaylistByIndex/{id}

Plays every item in the playlist identified by Id.

curl -s -X GET http://localhost:5004/api/v1/PlaylistExecuter/playPlaylistByIndex/1 | python -m json.tool

200 OK

Playlist Controls on the Currently Selected Playlist

The following commands are invoked against the Playlist that is currently selected in Viz Arc:

GET api/v1/playlistexecuter/executeCurrent

Executes the currently selected playlist element.

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

200 OK

GET api/v1/playlistexecuter/continueCurrent

Continues the currently selected playlist element.

curl -s -X GET http://localhost:5004/api/v1/playlistexecuter/continueCurrent | python -m json.tool

200 OK

GET api/v1/playlistexecuter/outCurrent

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

curl -s -X GET http://localhost:5004/api/v1/playlistexecuter/outCurrent | python -m json.tool

200 OK

GET api/v1/playlistexecuter/previewCurrent

Executes the currently selected playlist element on the preview channel.

curl -s -X GET http://localhost:5004/api/v1/playlistexecuter/previewCurrent | python -m json.tool

200 OK

GET api/v1/playlistexecuter/previewContinueCurrent

Continues the currently selected playlist element on the preview channel.

curl -s -X GET http://localhost:5004/api/v1/playlistexecuter/previewContinueCurrent | python -m json.tool

200 OK

GET api/v1/playlistexecuter/previewOutCurrent

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

curl -s -X GET http://localhost:5004/api/v1/playlistexecuter/previewOutCurrent | python -m json.tool

200 OK

GET api/v1/playlistexecuter/executeAndNext

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

curl -s -X GET http://localhost:5004/api/v1/playlistexecuter/executeAndNext | python -m json.tool

200 OK

GET api/v1/playlistexecuter/gotoFirst

Selects the first playlist item.

curl -s -X GET http://localhost:5004/api/v1/playlistexecuter/gotoFirst | python -m json.tool

200 OK

GET api/v1/playlistexecuter/playCurrentPlaylist

Plays every item in the currently selected playlist.

curl -s -X GET http://localhost:5004/api/v1/playlistexecuter/playCurrentPlaylist | python -m json.tool

200 OK

GET api/v1/playlistexecuter/stopCurrentPlaylist

Stops the execution of the currently selected playlist.

curl -s -X GET http://localhost:5004/api/v1/playlistexecuter/stopCurrentPlaylist | python -m json.tool

200 OK

Projects

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

Information: Viz Arc can store and read projects from two different locations, Graphic Hub or the local file system. In order to distinguish the source of the project, the project's name is prefixed by the keywords "gh:" or "local:" (for example, "gh:sunday_elections" or "local:sunday_elections").

Also, the "location" property in the responses, indicates whether the project resides on Graphic Hub (value "1") or the file system (value "0").

GET api/v1/projects

Returns a list of all available Projects, first the projects located on the Graphic Hub, then the ones on the file system.

curl -s -X GET http://localhost:5004/api/v1/Projects | python -m json.tool

[
	{
		"name": "gh:Animations",
		"lastModified": "2023-05-09T13:53:32.4633996+00:00",
		"location": 1,
		"profileIndex": 0,
		"tabs": []
	},
	{
		"name": "local:Skating",
		"lastModified": "2023-05-11T07:53:51.80198+00:00",
		"location": 0,
		"profileIndex": 0,
		"tabs": []
	}
]

In the example above, two projects were found.

The name of the project is prefixed by the keywords "gh:" or "local:"; this prefix indicates whether the project is stored in the Graphic Hub or on the file system.

GET api/v1/projects/{id}

Returns the project with the specified id, if it exists. If two projects with the same name exist in Graphic Hub and the local disk, the one of the local disk is returned first.

curl -s -X GET http://localhost:5004/api/v1/Projects/Animations | python -m json.tool

{
	"name": "gh:Animations",
	"lastModified": "2023-05-09T13:53:32.4633996+00:00",
	"location": 1,
	"profileIndex": 0,
	"tabs": []
}

GET api/v1/projects/load/{id}

Loads the project with the specified id in Viz Arc. If the id does not contain the location prefix, then Viz Arc tries to retrieve the project with a given name by looking in the Graphic Hub first, then the file system.

curl -s -X GET http://localhost:5004/api/v1/Projects/load/local:Skating | python -m json.tool

200 OK

GET api/v1/projects/current

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

curl -s -X GET http://localhost:5004/api/v1/projects/current | python -m json.tool

{
	"name": "local:Skating",
	"lastModified": "2023-05-11T07:53:51.80198+00:00",
	"location": 0,
	"profileIndex": 2,
	"tabs": [
		{
			"name": "show",
			"index": 0,
			"isEditorOnly": false,
			"actions": [
				{
					"uuid": "ff1ae771-4c69-42e4-ba8a-ad98747a5477",
					"name": "Logo",
					"type": "Template",
					"actionType": "TEMPLATE",
					"engineType": "VIZ",
				...

Profiles

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

GET /api/v1/profiles

Returns the entire list of profiles available in Viz Arc.

curl -s -X GET http://localhost:5004/api/v1/profiles | python -m json.tool

[
	{
		"name": "Local",
		"channels": [
			{
				"name": "Local",
				"type": 1,
				"engines": [
					{
						"name": "localhost"
					}
				],
				"model": {
					"engineConfigTuple": [
						{
							"item1": {
								"name": "localhost",
								"ipAddress": "127.0.0.1",
								"port": 6100,
								"launcherPort": 5644,
								"webInterfacePort": 30010,
								"webSocketPort": 30020,
								...

GET api/v1/profiles/{id | name}

Returns the profile specified by the id or name.

curl -s -X GET http://localhost:5004/api/v1/profiles/0 | python -m json.tool

{
	"name": "Local",
	"channels": [
		{
			"name": "Local",
			"type": 1,
			"engines": [
				{
					"name": "localhost"
				}
			],
			"model": {
				"engineConfigTuple": [
					{
						"item1": {
							"name": "localhost",
							"ipAddress": "127.0.0.1",
							"port": 6100,
							"launcherPort": 5644,
							"webInterfacePort": 30010,
							"webSocketPort": 30020,
							...

GET api/v1/profiles/current

Returns the currently selected profile.

curl -s -X GET http://localhost:5004/api/v1/profiles/current | python -m json.tool

{
	"name": "Local",
	"channels": [
		{
			"name": "Local",
			"type": 1,
			"engines": [
				{
					"name": "localhost"
				}
			],
			"model": {
				"engineConfigTuple": [
					{
						"item1": {
							"name": "localhost",
							"ipAddress": "127.0.0.1",
							"port": 6100,
							"launcherPort": 5644,
							"webInterfacePort": 30010,
							"webSocketPort": 30020,
							...

POST api/v1/profiles

Sets the currently active profile.

curl -s -H 'Content-Type: application/json' -d

{ 
	"name": "productionA"
}

curl -s -H 'Content-Type: application/json' -d

{ 
	"index": 0 
}

Index starts at 0 for the first profile.

Web API Access Control

It is possible to inhibit calls to the PlayListExecuter and the ActionExecuter APIs with the IP whitelisting.

IP Whitelist

You can configure the IP addresses/ranges that are allowed to use the APIs. These have to be specified using a semi-colon (;) separated list of IP ranges (in CIDR notation). By default, the range is 0.0.0.0/0 which means all hosts can access the API.

The IP Whitelist can be configured in three different ways:

Manually in the General Settings(under the Communication section)
Web Application
Scripting

Web Application Whitelist configuration

If you want to allow only two machines with IP addresses (e.g. 192.168.1.100 and 192.168.1.142) you can specify them by reaching the page http://localhost:5004/DataMap and set the value of the WhiteListIPRanges key, as in the snapshot below.

images/download/attachments/140811494/datamap.png

Scripting Whitelist configuration

set Whitelist IP's through scripting

SetData("WhiteListIPRanges", "192.168.1.100;192.168.1.142")

Web Application Sample Usage

When Viz Arc starts up, it also launches an internal In-App Web Server which host a Web Application that makes use of some of the APIs described above.

Actions

Navigate to http://localhost:5004/ (the port can be configured in the General Settings, under the Communication section) to see the currently loaded project in Viz Arc. For example:

images/download/attachments/140811494/actions.png

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

PlayList

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

images/download/attachments/140811494/Playlist.png

Datamap

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

images/download/attachments/140811494/datamap.png

Triggering a Viz Arc Action from the 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/140811494/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/140811494/image2021-3-2_17-14-43.png

Typing http://localhost:5004/api/v1/ActionExecuter/203e10df-8ba1-403c-a378-4d93186f4d06 or http://localhost:5004/api/v1/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.