Skip to content

Plaid management API

Plaid exposes an HTTP endpoint to allow management and monitoring of the VEN.

The HTTP endpoint exposes a json API. These functions can be used to assist with compliance testing and for tight control by an external system.

Security

This endpoint is not secured so care should be taken to control access to this listener. This port should be protected inside your firewall and should not exposed outside your firewall.

The listener can be disabled in the config file by setting the listener -> enabled parameter to false. Under normal circumstances, the listener can be disabled. Alternatively, the listener can be configured to listen on localhost behind a secure proxy.

Available functions overview

The Plaid HTTP API supports the following commands:

  • Query Registration: Send a query registration message.
  • Create Party Registration: Initiate the registration process between Plaid and the VTN.
  • Cancel Party Registration: Initiate cancel registration phase between Plaid and the VTN.
  • Clear Registration: Clear Plaid’s tracking of its registration status - no message is sent to the VTN.
  • Clear Reports: Clear any pending report requests - no message is sent to the vtn.
  • Start Ven: Start the Ven communication loop in Plaid. Upon starting, if Plaid isn’t in a registered state, it will continually attempt to register with the VTN.
  • Stop Ven: Stop the communication loop.
  • Request Event: Issue a requestEvents command to the VTN.
  • Clear Events: Clear events stored in Plaid. No messages are issued to the VTN. This function is primarily for testing purposes and would not normally be used in production.
  • Set VenID: Set a preconfigured VenID.
  • Create Opt Schedule: Creates an opt schedule.
  • Cancel Opt Schedule: Cancels a previously created opt schedule.
  • Opt Event: OptIn or optOut of an event with the createOpt request.
  • Created Event: OptIn or optOut of an event with the createdEvent request.
  • Register Reports: Complete report registration.
  • VEN Status: Retrieve information regarding the current status of Plaid.
  • Registered Namespace: This function executes code in the custom plugin.

The plugin is responsible for parsing the parameters in this message.

API Request/Reply Format

Each API request has the following format:

{
    "namespace": "ven.functionName",
    "parameters": {
        "param1" : "param1 value",
        "param2" : 200,
        "param3" : true
    }
}

If Plaid successfully parses the request, the response will have the following:

{
    "status": "OK"
}

The OK status response only indicates plaid understood and processed the request. It does not indicate the success or failure of the execution of the command.

If there was an error parsing the request, the response will be as follows:

{
    "status": "ERROR processing request: key 'eventId' not found"
}

If an exception is thrown processing the request, the output is as follows:

{
    "status": "OK",
    "exception": "Exception message"
}

If the status is OK and no exception exists, further information will be available in the response body depending on the function that was executed. Functions that send a request to the VTN will report the OpenADR EiResponse status as follows:

{
    "response": {
        "code": 200,
        "message": "OK"
    },
    "status": "OK"
}

A response code of 200 indicates the VTN received and processed the message successfully. A 4xx error indicates an invalid ID was sent to the VTN and the message could not be processed. A 5xx error or any other response indicates the server could not process the message and the function call can be retried at some later time.

Here's are rules to use when processing a response:

  1. Check for status of OK. If the status is not OK, process the error and exit.
  2. Check for the existence of exception. If there's an exception object, process the exception message and exit.
  3. Process the response according to the function that was called.

Using Boomerang to send API requests

Boomerang is a Chrome browser plugin that can send API requests and we have pre-configured a boomerang project with all of the Plaid API requests. Steps to use boomerang:

  • Download the example config file by right clicking and downloading from the following link: here.
  • Add boomerang to Chrome by following this link https://chrome.google.com/webstore/detail/boomerang-soap-rest-clien/eipdnjedkpcnlmmdfdkgfpljanehloah?hl=en
  • Once installed launch boomerang (it can be found on your apps page at chrome://apps)
  • In the top right corner, click on the hamburger menu and select "import". Upload the config file provided.
  • Your new project should look like the following screenshot. Make sure the url you are POSTing to matches where you are running Plaid. You are now ready to send requests to the Plaid API using Boomerang!

boomerang-screenshot

API Function Definitions

The request and response for each function is covered below.

Query Registration

Send a queryRegistration message.

Request

{
  "namespace": "ven.queryRegistration",
  "parameters": {}
}

Response

{
    "response": {
        "code": 200,
        "message": "OK"
    },
    "status": "OK"
}

Create Party Registration

Initiate the registration process between plaid and the VTN.

Request

{
    "namespace": "ven.createPartyRegistration",
    "parameters": {
        "includeIds" : false
    }
}
  • inlcudeIDs (bool): If true, include registrationId and venId in the registration request.

Response

{
    "response": {
        "code": 200,
        "message": "OK"
    },
    "status": "OK"
}

Cancel Party Registration

Initiate cancel registration phase between plaid and the VTN.

Request

{
    "namespace": "ven.cancelPartyRegistration",
    "parameters": {}
}

Response

{
    "response": {
        "code": 200,
        "message": "OK"
    },
    "status": "OK"
}

Clear Registration

Clear Plaid’s tracking of its registration status - no message is sent to the VTN. Plaid will detect this as being in an unregistered state and start the registration process.

Request

{
    "namespace": "ven.clearRegistration",
    "parameters": {}
}

Response

{
    "status": "OK"
}

Clear reports

Clear all pending report requests - no message is sent to the VTN.

Request

{
    "namespace": "ven.clearReports",
    "parameters": {}
}

Response

{
    "status": "OK"
}

Start Ven

Start the VEN communication loop in Plaid. On start, if Plaid isn’t in a registered state, it will continually attempt to register with the VTN. Once registration succeeds, Plaid enters the poll state.

Request

{
    "namespace": "ven.start",
    "parameters": {}
}

Response

{
    "status": "OK"
}

Stop Ven

Stop the communication loop.

Request

{
    "namespace": "ven.stop",
    "parameters": {}
}

Response

{
    "status": "OK"
}

Request Event

Issue a requestEvent command to the VTN

Request

{
    "namespace": "ven.requestEvent",
    "parameters": {}
}

Response

{
    "response": {
        "code": 200,
        "message": "OK"
    },
    "status": "OK"
}

Clear Events

Clear events stored in Plaid. No messages are issued to the VTN. This function is primarily for testing purposes and should not be used in production. This function does not send a message to the VTN.

Request

{
    "namespace": "ven.clearEvents",
    "parameters": {}
}

Response

{
    "status": "OK"
}

Set VenID

Set a preconfigured VenID. The VEN ID will be used in all future registration attempts. This function does not send a message to the VTN.

Request

{
    "namespace": "ven.setVenId",
    "parameters": {
        "venId" : "01234567890123456789012345678901234567890123456789"
    }
}
  • venId (string): OpenADR VEN ID. The VEN ID can be configured ahead of time in the Plaid config file, or the VTN will issue a VEN ID on registration.

Response

{
    "status": "OK"
}

Create Opt Schedule

Creates an opt schedule on. Opt schedules inform the VTN of periods of availability or unavailability for control.

Request

{
    "namespace": "ven.createOptSchedule",
    "parameters": {
        "optId" : "optIndentifaction",
        "optType" : "optOut",
        "optReason" : "economic",
        "marketContext" : "http://MarketContext1",
        "resourceId" : "resource1",
        "endDeviceAsset" : "Thermostat",
        "availability" : [
            { "dtstart": 1475696028, "duration" : 6},
            { "dtstart": 1475868828, "duration" : 8}
        ]
    }
}
  • optId (string): Opt message identifier
  • optType: (string): optIn, optOut
  • optReason: (string): economic, emergency, mustRun, notParticipating, outageRunStatus overrideStatus, participating, x_schedule
  • marketContext (string): Market context should match the list of market contexts the VEN is participating in. Plaid does not validate this field.
  • resourceId (string): ID of the resource the opt schedule pertains to. This is an optional field. If blank, the schedule pertains to the entire VEN and all of its resources.
  • availability (array): Array of dtstart/duration values.
  • dtstart (time_t): Unix epoch start time of the period
  • duration (integer): Duration of the period in hours

Response

{
    "response": {
        "code": 200,
        "message": "OK"
    },
    "status": "OK"
}

Cancel Opt Schedule

Cancels an existing opt schedule

Request

{
    "namespace": "ven.cancelOptSchedule",
    "parameters": {
        "optId" : "optIndentifaction"
    }
}
  • optId (string): ID of an existing opt schedule to cancel

Response

{
    "response": {
        "code": 200,
        "message": "OK"
    },
    "status": "OK"
}

Opt Event

OptIn or optOut of an event with the createOpt message. This function is similar to the createdEvent which is also use to opt in or out of an event. This function offers contains a reason field and a resource ID field. The resource ID field is useful if the VEN is controlling multiple devices but only a subset of devices will be participating in the event.

Request

{
    "namespace": "ven.eventOpt",
    "parameters": {
        "optId" : "optId",
        "eventId" : "465159917efa511ede0f",
        "optType" : "optOut",
        "optReason" : "economic",
        "resourceId": "resourceId",
        "requestId": "requestId"
    }
}
  • optId (string): Opt message identifier
  • eventId (string): ID of the event to opt in/out of
  • optType: (string): optIn, optOut
  • optReason: (string): economic, emergency, mustRun, notParticipating, outageRunStatus overrideStatus, participating, x_schedule
  • resourceId (string): ID of the resource the opt schedule pertains to. This is an optional field. If blank, the schedule pertains to the entire VEN and all of its resources.
  • requestId (string): OpenADR request ID

Response

{
    "response": {
        "code": 200,
        "message": "OK"
    },
    "status": "OK"
}

Created Event

OptIn or optOut of an event with the createdEvent request.

Request

{
    "namespace": "ven.createdEvent",
    "parameters": {
        "eventId" : "5cabbf1371f930c46af5",
        "optType" : "optOut",
        "scheduleEvent" : true
    }
}
  • eventId (string): ID of the event to opt in/out of
  • optType: (string): optIn, optOut
  • scheduleEvent (bool): Set to false if Plaid should NOT schedule the event. If the event isn't scheduled, no callbacks will occur on the plugin. Cloud systems or other installations where Plaid is controlling multiple resources, this parameter will likely always be set to true. If Plaid is controlling a single resource and there's no need to receive event callbacks in the plugin for an event that has been opted out of, set this value to FALSE on optOut but true on optIn.

Response

{
    "response": {
        "code": 200,
        "message": "OK"
    },
    "status": "OK"
}

Register Reports

Perform report registration.

Request

{
    "namespace": "ven.registerReports",
    "parameters": {}
}

Response

{
    "response": {
        "code": 200,
        "message": "OK"
    },
    "status": "OK"
}

VEN Status

Retrieve information regarding the current status of Plaid. This function does not send a message to the VTN.

Request

{
    "namespace": "ven.status",
    "parameters": {

    }
}

Response

{
    "endpointStatus": null,
    "events": {
        "31aef7bd0ad4cef12936": {
            "dtstart": "2019-02-25 17:11:00",
            "duration": "PT5M",
            "eventId": "31aef7bd0ad4cef12936",
            "optType": "optIn",
            "status": "completed"
        },
        "5cabbf1371f930c46af5": {
            "dtstart": "2019-02-25 17:29:00",
            "duration": "PT5M",
            "eventId": "5cabbf1371f930c46af5",
            "optType": "optIn",
            "status": "completed"
        }
    },
    "log": [
        "[ 2019-02-26 14:20:36 ] new event received: 5cabbf1371f930c46af5",
        "[ 2019-02-26 14:20:36 ] new event received: 31aef7bd0ad4cef12936",
    ],
    "polling": {
        "enabled": true
    },
    "registration": {
        "defaultRegistrationId": "",
        "defaultVenId": "",
        "isRegistered": true,
        "pollFreqquency": "PT10S",
        "registrationId": "b552b5225451f4a45191",
        "venId": "2423f6ed2d9599a8f6b5",
        "vtnId": "NEBLAND_VTN"
    },
    "status": "OK",
    "version": "1.2.0 SHA: HASH"
}

Registered Namespace

This is a custom function which is forwarded to the custom plugin. The namespace value that is forwarded to the plugin is set in the plugin initialize function. The sample plugin sets name to my.custom.namespace, doesn't take any parameters, and returns information regarding the events that have been received.

Request

{
    "namespace": "my.custom.namespace",
    "parameters": {
    }
}

Response

{
    "events": [
        {
            "dtstart": "2019-02-25 17:11:00",
            "eventID": "31aef7bd0ad4cef12936",
            "status": "completed"
        },
        {
            "dtstart": "2019-02-25 17:29:00",
            "eventID": "5cabbf1371f930c46af5",
            "status": "completed"
        },
        {
            "dtstart": "2019-02-25 16:53:00",
            "eventID": "88720fdaf57f768d08d9",
            "status": "completed"
        },
        {
            "dtstart": "2019-02-25 17:16:00",
            "eventID": "b9767e11626a20728b7d",
            "status": "completed"
        },
        {
            "dtstart": "2019-02-25 17:21:00",
            "eventID": "d6a993aee2aa3ea71d0d",
            "status": "completed"
        }
    ],
    "note": "This is an example of processing a message sent using a registered namespace"
}