Incidents Action

Incident actions extend the monitoring capabilities of Broadsign Core.

They allow third-party applications to open and close incidents on Broadsign Player.

Some Broadsign 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

With these Incident actions, you can call the Player API using one of the following methods:

    • remote_action: Exposes the open_incident, close_incident or query_incidents actions via the command-line remote_action tool.
    • XML: Exposes the open_incident, close_incident or query_incidents actions through simple XML commands sent to port 2324.
    • JSON: Exposes the open_incident, close_incident or query_incidents actions by sending JSON messages to the WebSocket server (port 2326).
    • Flash: Flash applications can call the Player API via ActionScript and the open_incident, close_incident or query_incidents actions.

Add external incident types

You can add up to twenty-five user-defined incident types to the supported list. These incidents types are hidden by default in the 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.

For example, 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 the Broadsign 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:

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 /close the incident:

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:

<?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).

Incident Actions

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:

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

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:

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

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

The return document will appear as follows:

<?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>
Incident – XML Parameters
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 Configuration Profiles – Players – 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:

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

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:

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

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:

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

The return document will appear as follows:

{
    "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 – JSON Parameters
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.