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 web server is configured to run on port 5004. The web server port can be configured in the General Settings, under the Communication section. Please note that this 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/.

Info: 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.

This section contains the following examples:

Status
ActionExecuter
ActionCanvas
DataMap
Playlist
PlaylistExecuter
Projects
Profiles
Web API Access Control
Web Application Sample Usage

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"
}

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/Opener | or | 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.

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 /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"
}

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 will be updated.

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

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

DELETE /api/v1/datamap/{key}

Delete 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

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/125451677/image2021-2-8_23-45-55.png

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

images/download/attachments/125451677/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

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

Projects

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

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 wheter the project is stored in the Graphic Hub or on the file system. Likewise, the "location" property indicates whether the project resides on Graphic Hub (value "1") or on the file system (value "0").

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

Loads the project with the specified name in Viz Arc. If the name does not contains the location prefix, then Viz Arc will try to retrieve the project by looking in the Graphic Hub, 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,
							...

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 3 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/125451677/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 web server which host a Web Application that makes use of most 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/125451677/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/125451677/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/125451677/datamap.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/125451677/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/125451677/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.

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