Events

Creating an event

Because Whispir works with each organisation to build 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 using the module.

Events have sub-sections under them called as ‘actions’ (maximum of 10). When an event occurs, the related actions are performed. Each action has an owner, a set time, and details associated with it. The owner or person responsible for managing the event could be a /contacts in the system. This ensures that the proper communications are sent automatically to the individual based on their preferred channel (message, email, voice) without having to key in the phone, email, and other communication information again.

The Events module captures information specific to an event so the information can be used as part of messaging for the duration of the event. It can be customised to accept events and associated information from external systems or to capture more complex information around an event.

Events are created within a workspace. As they are custom-built the information to be captured depends on your organisation’s specific requirements. Generally at a minimum an event will have a label, start date and status.

Most importantly, to create an event, you must have the create access for Incident row in the Roles & Permission section of Whispir’s account settings.

Required fields:

  • Event Label: The concatenated unique Event ID and Event Name. For example, 2701095 - Outage of Local Systems in Sydney.
  • Event Status: The current status of the event. For example,‘Open’ or ‘Inactive’

and one set of actions for this event:

  • Action Date: The date and time of the action.
  • Action Owner: The contact who is responsible for this action execution.
  • Action Detail: The details of the action.

All other fields on the event are defined through name/value pairs. For example:

  • JSON
  • XML
<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>

 

Optional fields:

  • Event Field Name: Start Date
  • Event Field Value: 11 Sep 2019
  • Event Field Name: End Date
  • Event Field Value: 12 Sep 2019
  • Event Field Name: Type
  • Event Field Value: Notification
  • … and so on.

You can refer to the schema for the detailed object structure.

High-level request elements

eventLabel

String

Specifies the name of the label used for the messages sent under this event.

status

String

Specifies the status of the event. The status can be one of the following:

  • Active
  • Resolved

Note: The default status is Open.

summary

String

Specifies the summary of the event. A single line that can be the equivalent of the subject of an email.

description

String

Specifies the detailed description of the event.

location

String

Specifies the latitude and longitude values of the event location. This helps to show the event location on Whispir’s geo-map feature set and coordinated communication based on the geo-location of the event.

startDate

String

Specifies the start date of the event. This is a mandatory value.

The date and time should be in the format DD/MM/YYYY HH:MI:SS (24 hour format). For example, 23/09/2019 17:21:00 for 23 September 2019 5.21 PM.

endDate

String

Specifies the end date of the event.

The date and time should be in the format DD/MM/YYYY HH:MI:SS (24 hour format). For example, 23/09/2019 17:21:00 for 23 September 2019 5.21 PM.

severity

String

Specifies the severity of the event. While this can change from company to company, the standard value set to be chosen from is:

  • Severity 5 – Routine Maintenance Tasks
  • Severity 4 – Scheduled System Changes
  • Severity SL3 – Minor Outage (some service degradation)
  • Severity SL2 – Moderate Outage (service degradation)
  • Severity SL1 – Major Outage (significant service unavailability)

Priority

String

Specifies the priority of the event. While this can change from company to company, the standard value set to choose from is:

  • Priority 5 – No Set Resolution Period
  • Priority 4 – < 1 week Resolution
  • Priority 3 – < 3 day Resolution
  • Priority 2 – < 1 day Resolution
  • Priority 1 – < 2 hour Resolution

duration

String

The duration of the event in HH:MI:SS. For example, 02:05:00.

This can be substituted in the place of end date if required. Or a subset of the time between the start and end dates.

Event categorisation attributes:

category

String

Specifies the category of event. The default values to choose from are:

  • Internal Systems
  • External Systems
  • Infrastructure

subcategory

String

Specifies the subcategory in the category. The default values to choose from are:

  • Customer Impact
  • Cust & Staff Impact
  • Staff Impact
  • Impact Unknown

type

String

Specifies the type of event. The default values to choose from are:

  • Multiple Issues
  • NIL
  • Network
  • Applications
  • Mobile Apps

externalVendor

String

Specifies the name/contact who is the external vendor related to this event.

lineNumber

String

Specifies the line number (production lines).

externalCaseNumber

String

Specifies the number as tracked by an external party related to this event.

Services affected by this event:

platform

String

Specifies the platform in the company that this event is associated with.

services

String

Specifies the service in the company that this event is associated with

Impact of this event:

impactCondition

String

Specifies the impact condition of this event to the company. These values can be configured via custom lists as these can be very specific to the company. The default values to choose from are:

  • All services not available
  • All services degraded
  • Some services not available
  • Some services degraded
  • No Impact
  • Unknown

impactToOrg

String

Specifies the impact of this event to the organisation. These values can be configured via custom lists as these can be very specific to the company. The default values to choose from are:

  • Global
  • National
  • Local

locations

String

Specifies the impact location of this event to a company’s operational geographies. These values can be configured via custom lists as these can be very specific to the company.

Actions for this event:

multiple key value sets

String

Specifies the set of individual actions to be taken during this event.

Each action consists of the following:

  • actionDate: The start date of this action in dd/mm/yyyy HH:MI:SS 24 hour format
  • actionOwner: The individual (contact) responsible for this action’s execution
  • actionDetails: The detail description of this action

An event can have a maximum of 10 action. So the action values are numbered:

  • actionDate1, actionOwner1, actionDetails1
  • actionDate2, actionOwner2, actionDetails2
    … through to:
  • actionDate10, actionOwner10, actionDetails10

Alias Fields

String

The other (alias) name and title fields.

  • otherFirstName, otherLastName, otherTitle


  • JSON
  • XML

Creating an event

You can easily create an event using the following request structure:

 

{{codeStart}}

HTTP1.1 POST https://api.<region>.whispir.com/events?apikey=<your_api_key>

Authorization: Basic asdf98nf89asdvasd2r398h8sdf

x-api-key: your_api_key

Content-Type: application/vnd.whispir.event-v1+json

{

"eventLabel" : "2701095 - Outage of Local Systems in Sydney",

"status" : "Open",

"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/09/2019 17:41:00"

}, {

"name" : "actionOwner1",

"value" : "John Wick"

}, {

"name" : "actionDate1",

"value" : "11/09/2019 17:41:00"

}, {

"name" : "actionDetails1",

"value" : "investigation to take place asap."

}, {

"name" : "severity",

"value" : "Severity 3 - Minor Outage (Some Service Degradation)"

}

]

} ]

}

{{codeEnd}}

 

The request if successful shall return a 201 Created along with the complete event object.

 

{{codeStart}}

{

"id": "421FEEBA93GF53A2",

"eventLabel": "2701095 - Outage of Local Systems in Sydney",

"status": "Active",

"eventFormList": [

{

"formName": "MetroEvent",

"eventFieldList": [

{

"name": "summary",

"value": "Outage of systems in Sydney"

},

{

"name": "location",

"value": "0.0,0.0"

},

{

"name": "endDate"

},

{

"name": "type",

"value": ""

},

{

"name": "actionDetails2",

"value": ""

},

{

"name": "actionDetails3",

"value": ""

},

{

"name": "actionDetails1",

"value": "investigation to take place asap."

},

{

"name": "priority",

"value": ""

},

{

"name": "description",

"value": "ATMs are non responsive, teams to be sent to investigate."

},

{

"name": "actionDetails8",

"value": ""

},

{

"name": "actionDetails9",

"value": ""

},

{

"name": "actionDetails6",

"value": ""

},

{

"name": "actionDetails7",

"value": ""

},

{

"name": "actionDetails4",

"value": ""

},

{

"name": "actionOwner10",

"value": ""

},

{

"name": "actionDetails5",

"value": ""

},

{

"name": "platform",

"value": ""

},

{

"name": "services",

"value": ""

},

{

"name": "status",

"value": "Open"

},

{

"name": "openedBy",

"value": ""

},

{

"name": "category",

"value": "Internal"

},

{

"name": "externalVendor",

"value": ""

},

{

"name": "externalCaseNumber",

"value": ""

},

{

"name": "actionOwner6",

"value": ""

},

{

"name": "startDate",

"value": "11/09/2019 00:00:00"

},

{

"name": "actionOwner5",

"value": ""

},

{

"name": "actionOwner8",

"value": ""

},

{

"name": "actionOwner7",

"value": ""

},

{

"name": "actionOwner9",

"value": ""

},

{

"name": "actionDate8"

},

{

"name": "actionDate9"

},

{

"name": "actionDetails10",

"value": ""

},

{

"name": "actionDate4"

},

{

"name": "actionOwner2",

"value": ""

},

{

"name": "actionDate5"

},

{

"name": "actionOwner1",

"value": "John Wick"

},

{

"name": "actionDate6"

},

{

"name": "actionOwner4",

"value": ""

},

{

"name": "actionDate7"

},

{

"name": "actionOwner3",

"value": ""

},

{

"name": "actionDate1",

"value": "11/09/2019 00:00:00"

},

{

"name": "actionDate3"

},

{

"name": "actionDate2"

},

{

"name": "locations",

"value": ""

},

{

"name": "impactToOrg",

"value": ""

},

{

"name": "actionDate10"

},

{

"name": "locationDisplay",

"value": ""

},

{

"name": "subCategory",

"value": ""

},

{

"name": "severity",

"value": "Severity 3 - Minor Outage (Some Service Degradation)"

},

{

"name": "duration",

"value": ""

},

{

"name": "lineNumber",

"value": ""

},

{

"name": "impactCondition",

"value": ""

}

]

}

],

"link": [

{

"uri": "https://api..whispir.com/workspaces/26C20B1A09XS3RA2/events/421FEEBA93GF53A2?apikey=",

"rel": "self",

"method": "GET"

},

{

"uri": "https://api..whispir.com/workspaces/26C20B1A09XS3RA2/events/421FEEBA93GF53A2?apikey=",

"rel": "self",

"method": "PUT",

"type": "application/vnd.whispir.event-v1+xml,application/vnd.whispir.event-v1+json"

},

{

"uri": "https://api..whispir.com/workspaces/26C20B1A09XS3RA2/messages?label=2701095%20-%20Outage%20of%20Local%20Systems%20in%20Sydney",

"rel": "retrieveEventMessages",

"method": "GET"

}

]

}

{{codeEnd}}