Incidents Action

Some Broadsign Control Players require extended monitoring capabilities. Incident actions allow third-party applications to open and close incidents within the Broadsign system.

Use one the following Incident actions:

• open_incident
• close_incident
• query_incidents

Call the open_incident, close_incident and query_incidents actions using one of the following:

WebSocket Server:

• JSON – You can pass parameters from within your HTML5 file using JSON.

  Note: Ensure that you select Enable Remote Control in the Remote Control tab of the configuration profile. See The Remote Control Tab.

  Note: If using JSON via the WebSocket server, any firewall present on Broadsign Control Player should be configured to access port 2326 directly for use.

Port 2324:

• remote_action – An application that ships with Broadsign Control Player, using command line.
• XML – If you want to develop your own applications, you can communicate directly with Broadsign Control Player API using XML.

Note: Ensure that you select Enable Remote Control in the Remote Control tab of the configuration profile. See The Remote Control Tab.

Note: Any firewall present on Broadsign Control Player should be configured to either allow bsp.exe to open ports, or configure port 2324 or port 2326 directly for use.

Note: The Triggers Action is the only exception to this rule. It uses port 2325. See Triggers Action.

You can call this action on Windows and Ubuntu Linux, and find it along the following paths:

• Windows (64-bit):

C:\Program Files\BroadSign\bsp\bin

• Ubuntu Linux:

  /opt/broadsign/suite/bsp/bin/

You can add up to twenty-five user-defined incident types to the supported list. These incidents types are hidden by default in Broadsign Control Administrator, but will appear when you check Show External Incidents in the incident report.

External incidents can serve any purpose, and you can standardize the user text via a translation file.

If you want to use “Type 1 External Incident” for Wi-Fi monitoring, create a translation file to replace “Type 1 External Incident” with “Wi-Fi Failure”. Each one of the 25 incident types can appear with user-defined incident thresholds.

To use the command-line remote_action tool, find the executable in Broadsign Control Player’s installation bin directory.

Incident Actions

• open_incident – Only one incident of each type can be open at once and duplicates will get suppressed. Note that -T (Incident Type) and -P (Incident problem description) are required when the action is open_incident.

For example, to open an incident type:

Copy

remote_action open_incident -T 10001 -P "This is an Incident"

• close_incident – Note that -T (Incident type) and -R (Incident resolution description) are required when the action is close_incident.

To resolve or close the incident:

Copy

remote_action close_incident -T 10001 -R "Incident Resolved"

A "Type 1 External Incident" would correspond to type code 10001, “Type 2 External Incident” to type code 10002, and so on.

• query_incidents – This action will return an XML document describing all the currently open incidents. That way, a third party can decide when and if they should be closed. The document will be formatted as follows:
Copy

<?xml version="1.0"?>
<incidents>
    <incident id='12345'
        type='10005'
        occurred_on_utc='2012-12-12T09:13:13'
        problem_description='Wifi hotspot not functional.'
        status='2'
        target_resource_id='0'
        resource_id='0'/>
    <incident id='123456'
        type='10007'
        occurred_on_utc='2012-12-21T09:13:13'
        problem_description='Panel door is open.'
        status='2'
        target_resource_id='0'
        resource_id='0'/>
</incidents>

Note: Broadsign automatically closes all open reported incidents that have been inactive for fourteen days. If the incident still persists after fourteen days, you should re-opened it as a new incident.

Your application can open or close incidents through, or query incidents from, the Player API. Send an XML message to the monitor_remote port (2324).

Incidents Action

• open_incident – You can open an incident, using an XML query to the Player API. Supply the incident type and problem_description. Only one incident of each type can be open at once and duplicates will get suppressed.

Enter the XML as follows:

Copy

<rc version="1" id="1" action="open_incident" type="10001" problem_description="This is an incident." />\r\n\r\n

Note: You must terminate the request with \r\n\r\n.

Note: Each command sent requires a unique identifier (id). The application can use a simple incrementing value here.

• close_incident – Supply the incident type and the resolution_description. A "Type 1 External Incident" would correspond to type code 10001, “Type 2 External Incident” to type code 10002, and so on.

To resolve/close the incident:

Copy

<rc version="1" id="1" action="close_incident" type="10001" resolution_description="Incident resolved."/>\r\n\r\n

• query_incidents – This action will return an XML document describing all the currently open incidents. That way, a third party can decide when and if they should be closed.

To query incidents:

Copy

<rc version="1" id="1" action="query_incidents"/>\r\n\r\n

The return document will appear as follows:

Copy

<?xml version="1.0"?>
<incidents>
    <incident id='12345'
        type='10005'
        occurred_on_utc='2012-12-12T09:13:13'
        problem_description='Wifi hotspot not functional.'
        status='2'
        target_resource_id='0'
        resource_id='0'/>
    <incident id='123456'
        type='10007'
        occurred_on_utc='2012-12-21T09:13:13'
        problem_description='Panel door is open.'
        status='2'
        target_resource_id='0'
        resource_id='0'/>
</incidents>

Incidents Action - XML Parameters

Note: Any firewall present on Broadsign Control Player should be configured to either allow bsp.exe to open ports, or configure port 2324 or port 2326 directly for use.

Parameter	Description
version	The version is always "1".
id	Contains the identifier of the request.
action	The kind of action to be taken: open_incident, close_incident or query_incidents.
type	A "Type 1 External Incident" would correspond to type code 10001, “Type 2 External Incident” to type code 10002, and so on. Required when action is open_incident or close_incident.
problem_description	A brief description of the problem or incident. Required when action is open_incident.
resolution_description	A brief description of the problem's resolution. Required when action is close_incident.

Your interactive application can submit JSON data to the player via the WebSocket server of monitor_remote (port 2326). You will need to enable the WebSocket server. For more information, see The Remote Control Tab.

Incident Actions

• open_incident – You can open an incident by sutmitting a JSON string to the Player API. Supply the incident type and problem_description. Only one incident of each type can be open at once and duplicates will get suppressed.

Enter the JSON as follows:

Copy

{
    "rc": {
        "version": "1",
        "id": "1",
        "action": "open_incident",
        "type": "10001",
        "problem_description": "This is an incident."
    }
}

Note: Each command sent requires a unique identifier (id). The application can use a simple incrementing value here.

• close_incident – Supply the incident type and the resolution_description. A "Type 1 External Incident" would correspond to type code 10001, “Type 2 External Incident” to type code 10002, and so on.

To resolve or close the incident:

Copy

{
    "rc": {
        "version": "1",
        "id": "1",
        "action": "close_incident",
        "type": "10001",
        "resolution_description": "Incident resolved."
    }
}

• query_incidents – This action will return a JSON document describing all the currently open incidents. That way, a third party can decide when and if they should be closed.

To query incidents:

Copy

{
    "rc": {
        "version": "1",
        "id": "1",
        "action": "query_incidents"
    }
}

The return document will appear as follows:

Copy

{
    "incidents": {
        "incident": [
            {
                "id": "12345",
                "type": "10005",
                "occurred_on_utc": "2012-12-12T09:13:13",
                "problem_description": "Wifi hotspot not functional.",
                "status": "2",
                "target_resource_id": "0",
                "resource_id": "0"
            },
            {
                "id": "123456",
                "type": "10007",
                "occurred_on_utc": "2012-12-21T09:13:13",
                "problem_description": "Panel door is open.",
                "status": "2",
                "target_resource_id": "0",
                "resource_id": "0"
            }
        ]
    }
}

Incident Action - JSON Parameters

Note: If using JSON via the WebSocket server, any firewall present on Broadsign Control Player should be configured to access port 2326 directly for use.

Parameter	Description
version	The version is always "1".
id	Contains the identifier of the request.
action	The kind of action to be taken: open_incident, close_incident or query_incidents.
type	A "Type 1 External Incident" would correspond to type code 10001, “Type 2 External Incident” to type code 10002, and so on. Required when action is open_incident or close_incident.
problem_description	A brief description of the problem or incident. Required when action is open_incident.
resolution_description	A brief description of the problem's resolution. Required when action is close_incident.