Using Whispir to Manage Events

Using the Whispir API to manage Events

Whispir’s Events API allows users to capture, create and manage Events (including Incidents, Issues, Places, and Assets). Link multichannel communications to each event to track report and disseminate information textually and geospatially.

This section describes the process of storing, retrieving, updating and deleting Event information using the Whispir API.

  1. Overview of the Whispir Events Module
  2. Structure of a Whispir Event
  3. How to retrieve a listing of created Events
  4. How to retrieve the details of a single Event
  5. How to create new Events using the API
  6. How to send messages using Event data
  7. How to retrieve a list of messages related to an Event

Overview of the Whispir Events Module

The Whispir Events module allows customers to easily input, invoke and track communications about current events that are taking place within their organisation.

Events can be created from within the Whispir Conversation Platform through the web interface, or via the REST or WSDL APIs.

This information is then available for the author to distribute templated messages, or (if location enabled) for other users to view on Whispir’s map interface.

Events within the Whispir Conversation Platform are generally active for a short period of time, most commonly defined by a Start Date and an End Date.  Once the end date of the event is reached the event is deemed closed.

Whispir Consultants work with each customer to design and build an events module that is specific to them, ensuring that the fields, applicable values, and captured information maps directly to the organisational process.

An example of an event could be an outage of an internal system or service, or an organisation wide event e.g. bushfires or a river flooding.

Structure of a Whispir Event

As Whispir works with each organisation to build out the requirements of the events module, the required fields are minimal.  The bulk of the event information is from fields that are generic, and only applicable to the customer that is using the module.

Required Fields

  • Event Label – The concatenated unique Event ID and Event Name e.g. (2701095 Outage of Local Systems in Sydney)
  • Event Status – The current status of the event e.g. 'Active' or 'Inactive'

All other fields on the event are defined through name/value pairs. E.g.

Optional Fields

  • Event Field Name – Start Date
  • Event Field Value – 11 July 2013

  • Event Field Name – End Date
  • Event Field Value – 12 July 2013

  • Event Field Name – Type
  • Event Field Value – Notification

The event structure can be described more simply with the following XSD.

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://schemas.api.whispir.com/dap" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="link">
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base="xs:string">
          <xs:attribute type="xs:string" name="method"/>
          <xs:attribute type="xs:string" name="rel"/>
          <xs:attribute type="xs:anyURI" name="uri"/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>
  <xs:element name="eventLabel" type="xs:string"/>
  <xs:element name="status" type="xs:string"/>
  <xs:element name="eventFormList">
    <xs:complexType>
      <xs:sequence>
        <xs:element type="xs:string" name="formName"/>
        <xs:element name="eventFieldList" maxOccurs="unbounded" minOccurs="0">
          <xs:complexType>
            <xs:sequence>
              <xs:element type="xs:string" name="name"/>
              <xs:element type="xs:string" name="value" minOccurs="0"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

How to retrieve a list of Events

Name

Value

Service URL (Company)

https://api.whispir.com/events?apikey=

Service URL (Workspaces) https://api.whispir.com/workspaces/<ID>/events?apikey=

Method

GET

Request Headers

Authorization

The Base 64 representation of the Whispir Username and Password.

Accept

application/vnd.whispir.event-v1+xml
application/vnd.whispir.event-v1+json

Query String

apikey=

The Mashery API key to authenticate the request.

Response

200 OK

The request was processed successfully

401 Unauthorized

The authorization details were incorrect

415 Unsupported Media Type

The MIME type requested is not supported for the requested resource

Request/Response Example

After performing this request, the response contains a list of URLs to each of the Events that the API user has access to. 

Each URL is stored within a 'Link' element.  Each 'Link' element that is returned contains the following information:

Element Name

Description

Method

The HTTP Method that is available on this particular URI
Rel

The searchable description about what this URI should be used for.

URI The URI in focus.  This can be used by the developer to perform some action on the resource.
Type (Optional) When the type is update or create, the applicable Content Type header and Accept header are supplied for the developer to use.

This information allows the application client to traverse the available resources easily:

HTTP1.1 GET https://api.whispir.com/events?apikey=DFD0FD90u809SDF90832FDS
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
Accept: application/vnd.whispir.event-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <status>1 to 20 of 38</status>
    <ns2:events>
        <ns2:event>
            <ns2:link method="GET" rel="self" uri="http://api.whispir.com/events/2EE7FEA3343662BE?apikey=DFD0FD90u809SDF90832FDS"/>
            <eventLabel>378563 Outage of local systems in Melbourne</eventLabel>
            <status>Active</status>
        </ns2:event>
        . . .
    </ns2:events>
    <ns2:link method="GET" rel="next" uri="http://api.whispir.com/events/?limit=20&amp;offset=20&amp;apikey=DFD0FD90u809SDF90832FDS"/>
</ns2:return>

The same response can be interpreted in JSON as follows:

HTTP1.1 GET https://api.whispir.com/events?apikey=DFD0FD90u809SDF90832FDS
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
Accept: application/vnd.whispir.event-v1+json

{
  "events" : [ {
    "eventLabel" : "378563 Outage of local systems in Melbourne",
    "status" : "Active",
    "eventFormList" : [ ],
    "link" : [ {
      "uri" : "http://api.whispir.com/events/2EE7FEA3343662BE?apikey=DFD0FD90u809SDF90832FDS",
      "rel" : "self",
      "method" : "GET"
    } ]
  }, 
  "status" : "1 to 20 of 38",
  "link" : [ {
    "uri" : "http://api.whispir.com/events/?limit=20&offset=20&apikey=DFD0FD90u809SDF90832FDS",
    "rel" : "next",
    "method" : "GET"
  } ]
}

The elements returned in the response are described as follows:

Element Name Description
eventLabel The unique Event ID and textual summary of the event
status The current status of the returned event. This denotes whether the event is still in an 'open' or 'active' state as opposed to 'closed'. The specific values can be configured on a customer basis.
eventFormList The eventFormList has been inserted as part of a roadmap development to allow multiple events forms within each organisation. At present this array will always have zero elements.
link The URL for the user/application to access this specific contact record

How to retrieve a single event using the API

Name

Value

Service URL (Company)

https://api.whispir.com/events/<ID>?apikey=

Service URL (Workspaces) https://api.whispir.com/workspaces/<ID>/events/<ID>?apikey=

Method

GET

Request Headers

Authorization

The Base 64 representation of the Whispir Username and Password.

Accept

application/vnd.whispir.event-v1+xml 
application/vnd.whispir.event-v1+json

Query String

apikey=

The Mashery API key to authenticate the request.

Response

200 OK

The request was processed successfully

401 Unauthorized

The authorization details were incorrect

415 Unsupported Media Type

The MIME type requested is not supported for the requested resource

Request/Response Example

After performing this request, the response contains the Event object specified in the request URL.

HTTP1.1 GET https://api.whispir.com/events/2EE7FEA3343662BE?apikey=DFD0FD90u809SDF90832FDS
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
Accept: application/vnd.whispir.event-v1+json

{
    "eventLabel" : "378563 Outage of local systems in Melbourne",
    "status" : "Active",
    "eventFormList" : [ {
        "formName" : "MetroEvent",
        "eventFieldList" : [ {
              "name" : "summary",
              "value" : "Outage of local systems in Melbourne"
            }, {
              "name" : "description",
              "value" : "ATMs are non responsive, teams to be sent to investigate."
            }, {
              "name" : "category",
              "value" : "Internal"
            }, {
              "name" : "startDate",
              "value" : "21/05/2013 15:41:00"
            }, {
              "name" : "actionOwner1",
              "value" : "Jordan Walsh"
            }, {
              "name" : "actionDate1",
              "value" : "21/05/2013 15:42:00"
            }, {
              "name" : "severity",
              "value" : "Severity 3 - Minor Outage (Some Service Degradation)"
            } ]
    } ],
    "link" : [ {
        "uri" : "http://api.whispir.com/events/2EE7FEA3343662BE?apikey=DFD0FD90u809SDF90832FDS",
        "rel" : "self",
        "method" : "GET"
    }, {
        "type" : "application/vnd.whispir.event-v1+json,application/vnd.whispir.event-v1+xml",
        "uri" : "http://api.whispir.com/events/2EE7FEA3343662BE?apikey=DFD0FD90u809SDF90832FDS",
        "rel" : "updateEvent",
        "method" : "PUT"
    } ]
}

The elements returned in the response are described as follows:

Element Name Description
eventLabel The unique Event ID and textual summary of the event
status The current status of the returned event. This denotes whether the event is still in an 'open' or 'active' state as opposed to 'closed'. The specific values can be configured on a customer basis.
eventFormList The eventFormList has been inserted as part of a roadmap development to allow multiple events forms within each organisation. At present this array will always have zero elements.
eventFormList – FormName The internal name of the event form being used by Whispir. It is envisaged that users will be able to create their own event forms in future.
eventFormList – EventFieldList The EventFieldList contains the listing of event field data that has been input from the user interface or the external system that created the event.
eventFormList – EventFieldList – name/value The name/value pairs make up the data on the specific event. Whispir will work with each organisation to understand the specific names that need to be supported, and any validations (if any) on the values associated to each name. This information can then be represented graphically in the Whispir UI.

How to create new Events using the API

Name

Value

Service URL (Company)

https://api.whispir.com/events?apikey=

Service URL (Workspaces) https://api.whispir.com/workspaces/<ID>/events?apikey=

Method

POST

Request Headers

Authorization

The Base 64 representation of the Whispir Username and Password.

Accept

application/vnd.whispir.event-v1+xml 
application/vnd.whispir.event-v1+json

Query String

apikey=

The Mashery API key to authenticate the request.

Response

201 Created

The request was accepted and the event was created.

400 Bad Request

The request was formatted incorrectly.

401 Unauthorized

The authorization details were incorrect.

415 Unsupported Media Type

The MIME type requested is not supported for the requested resource.

422 Unprocessable Entity

The request was formatted correctly but could not be processed due to a validation error.

Request/Response Example

After performing this request, the response contains the Event object specified in the request URL.

HTTP1.1 POST https://api.whispir.com/events?apikey=DFD0FD90u809SDF90832FDS
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
Accept: application/vnd.whispir.event-v1+json

{
    "eventLabel" : "1234567896 Outage of systems in Sydney",
    "status" : "Active",
    "eventFormList" : [ {
        "formName" : "MetroEvent",
        "eventFieldList" : [ 
            {
              "name" : "summary",
              "value" : "Outage of systems in Sydney"
            }, {
              "name" : "status",
              "value" : "Open"
            }, {
              "name" : "description",
              "value" : "ATMs are non responsive, teams to be sent to investigate."
            }, {
              "name" : "category",
              "value" : "Internal"
            }, {
              "name" : "startDate",
              "value" : "11/06/2013 17:41:00"
            }, {
              "name" : "actionOwner1",
              "value" : "Jordan Walsh"
            }, {
              "name" : "actionDate1",
              "value" : "11/06/2013 17:41:00"
            }, {
              "name" : "actionDetails1",
              "value" : "investigation to take place asap."
            }, {
              "name" : "severity",
              "value" : "Severity 3 - Minor Outage (Some Service Degradation)"
            } 
        ]
    } ]
}

 

The elements returned in the response are described as follows:

Element Name Description
eventLabel The unique Event ID and textual summary of the event
status The current status of the returned event. This denotes whether the event is still in an 'open' or 'active' state as opposed to 'closed'. The specific values can be configured on a customer basis.
eventFormList The eventFormList contains the name of the Event Form configured for your organisation, as well as the listing of event fields that should be set on the newly created event.
eventFormList – FormName The internal name of the event form being used by Whispir. It is envisaged that users will be able to create their own event forms in future.
eventFormList – EventFieldList The EventFieldList contains the listing of event field data that has been input from the user interface or the external system that created the event.
eventFormList – EventFieldList – name/value The name/value pairs make up the data on the specific event. Whispir will work with each organisation to understand the specific names that need to be supported, and any validations (if any) on the values associated to each name. This information can then be represented graphically in the Whispir UI.

How to send Messages using Event Data

Once you have completed creating your event data into the Whispir Platform, the next logical step is to be able to deliver a notification about the event.

This action can be performed using the existing Messages endpoint, with the Event ID as an attribute of the message.

Including this Event ID will link the message to the event, and allow you to use any attribute of the Event within your message payload.

This is described further below;

Name

Value

Service URL (Company)

https://api.whispir.com/messages?apikey=

Service URL (Workspaces) https://api.whispir.com/workspaces/<ID>/messages?apikey=

Method

POST

Request Headers

Authorization

The Base 64 representation of the Whispir Username and Password.

Content-Type

application/vnd.whispir.message-v1+xml 
application/vnd.whispir.message-v1+json

Query String

apikey=

The Mashery API key to authenticate the request.

Response

202 Accepted

The request was accepted and the message has been queued for delivery

400 Bad Request

The request was formatted incorrectly.

401 Unauthorized

The authorization details were incorrect.

415 Unsupported Media Type

The MIME type requested is not supported for the requested resource.

422 Unprocessable Entity

The request was formatted correctly but could not be processed due to a validation error.

Request/Response Example

Once you have the Event ID, you can include it in a message request as follows:

HTTP1.1 POST https://api.whispir.com/messages?apikey=DFD0FD90u809SDF90832FDS
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
Content-Type: application/vnd.whispir.message-v1+json

{
    "to" : "61XXXXXXXXX",
    "subject" : "Event Notification",
    "eventId" : "2EE7FEA3343662BE",
    "body" : "An event has occurred: @@summary@@.  A resolution is required by @@actionDate1@@."
}

The response to this request would look as follows:

HTTP1.1 202 Accepted
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
Location: http://api.whispir.com/messages/47707420BAE1288B?apikey=DFD0FD90u809SDF90832FDS 

This would result in an SMS message being sent out with the following content:

Event Notification. An event has occurred: Outage of systems in Sydney.  A resolution is required by 11/06/2013 17:41:00."

How to retrieve a listing of sent messages for an Event

You can easily retrieve all of the messages that are associated with an Event by using the unique label that is created for each event.

The label that should be used for searching is provided to users in both the /events and /events/<ID> requests as a link element.  The 'rel' field for this element is: retrieveEventMessages

A sample of the URL that is provided in this field is:

<ns2:link uri="http://api.whispir.com/messages?label=657126%20Outage%20of%20systems%20in%20Sydney" rel="retrieveEventMessages" method="GET" /> 

Name

Value

Service URL (Company)

https://api.whispir.com/messages?label=<event label>&apikey=

Service URL (Workspaces) https://api.whispir.com/workspaces/<ID>/messages?label=<event label>&apikey=

Method

GET

Request Headers

Authorization

The Base 64 representation of the Whispir Username and Password.

Content-Type

application/vnd.whispir.message-v1+xml 
application/vnd.whispir.message-v1+json

Query String

apikey=

The Mashery API key to authenticate the request.

Response

200 OK

The request was accepted and the messages will be returned in the response

400 Bad Request

The request was formatted incorrectly.

401 Unauthorized

The authorization details were incorrect.

415 Unsupported Media Type

The MIME type requested is not supported for the requested resource.

422 Unprocessable Entity

The request was formatted correctly but could not be processed due to a validation error.

Request/Response Example

Once you have the Event ID, you can include it in a message request as follows:

HTTP1.1 GET https://api.whispir.com/messages?label=657126%20Outage%20of%20systems%20in%20Sydney?apikey=DFD0FD90u809SDF90832FDS
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
Content-Type: application/vnd.whispir.message-v1+json

The response to this request would look as follows:

HTTP1.1 200 OK

{
   "messages" : [{
     "subject" : "Event Notification",
     "repetitionCount" : 0,
     "repeatDays" : 0,
     "repeatHrs" : 0,
     "repeatMin" : 0,
     "from" : "Jordan Walsh",
     "direction" : "OUTGOING",
     "responseCount" : "0",
     "createdTime" : 1424062773000,
     "link" : [ {
       "uri" : "http://api.whispir.com/messages/47707420BAE1288B?apikey=DFD0FD90u809SDF90832FDS ",
       "rel" : "self",
       "method" : "GET"
     } ]
   } ],
   "status" : "",
   "link" : [ ]
} 

Users can then use this listing to query the different messages for status or any other purpose.

Any of the features available in Sending Messages, or Advanced Messages, are also available to be used within the Events Messages.  For further information, please send an email through to apisupport@whispir.com.