API Protocol

Protocol

The OpenFin core exposes functionality and data via the protocol described below.

API Request Object:

Name	Type	Description
action	string	Specifies the action taken.
messageId	number	Is used by the Ack mechanism to correlate that API call.
payload	object	arguments passed to the remote function.

API Response Object:

Name	Type	Description
action	string	Specifies the action taken, in the case of a response it will be "ack".
correlationId	number	Corresponds to the messageId sent.
payload	object	Response package from the Runtime core.
payload.success	bool	Represents success/fail for the action taken.
payload.data	bool	If payload.success === true then this will contain the data response from the API.
payload.action	string	If payload.success === false then this will contain action name
payload.reason	string	If payload.success === false then this will contain the reason string for the failure
payload.error	Error Object	If payload.success === false then this will contain the Javascript Error object raised.

Sample successful exchange

Requesting entity:

OnOutgoingMessage
{
  "action": "get-window-bounds",
  "messageId": 3,
  "payload": {
    "uuid": "OpenFinHelloWorld",
    "name": "OpenFinHelloWorld"
  }
}

Response from OpenFin Core:

{
  "action": "ack",
  "correlationId": 3,
  "payload": {
    "success": true,
    "data": {
      "height": 525,
      "left": 10,
      "top": 50,
      "width": 395,
      "right": 405,
      "bottom": 575
    }
  }
}

Sample unsuccessful exchange

Response from OpenFin Core:

{
    "action": "ack",
    "correlationId": 3,
    "payload": {
        "success": false,
        "action": "get-window-bounds",
        "reason": "Error: Cannot read property 'mainWindow' of undefined",
        "error": {
            "message": "Cannot read property 'mainWindow' of undefined",
            "stack": "TypeError: Cannot read property 'mainWindow' of undefined\n at Object.Application.close ..."
        }
    }
}

Events

Below we will describe the protocol around consuming OpenFin core events.

Request to be notified on OpenFin core events by constructing a "subscribe-to-desktop-event" API request with the following payload:

Name	Type	Description
topic	string	Specifies the topic of the event
type	string	Specifies the event type

OpenFin core events will produce a "process-desktop-event" API message with the following payload:

Name	Type	Description
topic	string	Specifies the topic of the event
type	string	Specifies the event type
additional data *	any	additional data will be added to the payload

• additional data can be specific data relating to the event, as: uuid, name or a MonitorInfo object.

Sample exchange successful event.

API Request Object:

{
  "action": "subscribe-to-desktop-event",
  "messageId": 3,
  "payload": {
    "topic": "system",
    "type": "application-closed"
  }
}

API Response Object:

{
  "action": "ack",
  "correlationId": 3,
  "payload": {
    "success": true
  }
}

API Event Object:

{
  "action": "process-desktop-event",
  "payload": {
    "topic": "system",
    "type": "application-closed",
    "uuid": "closed-apps-uuid"
  }
}