Background

Whenever an external system needs to be integrated with ServiceOptimizer, there are two general types of workflow.

Firstly, there is the workflow where the external system is the originating source of the workflow. For example, consider the case where an external system is being used (perhaps by someone in a call center), and the external system needs to search for (and then book) an appointment.

In this case, the external system is the system that is originating the workflow, and it makes sense for the external system to initiate the integration communications by making a call to the appropriate ServiceOptimizer SOAP API(s).

However, the second type of workflow is where the ServiceOptimizer is the originating source of the workflow. For example, consider the case where a new appointment has been booked directly in ServiceOptimizer, and it is desirable to send a notification of the new appointment to the customer, via an external system.

In this case, while it is possible (and perfectly acceptable) for the external system to "poll" ServiceOptimizer, by periodically calling the appropriate ServiceOptimizer SOAP API(s), customers may instead prefer for ServiceOptimizer to automatically initiate communications, and make an API call from ServiceOptimizer to their external system.

This type of integration is referred to as a push notification - because ServiceOptimizer pushes the notification to the external system (rather than the external system having to pull the information needed).

This section and sub-pages document how to configure ServiceOptimizer for push notifications.

Configuring Push Notifications

Each type of push notification can be enabled/disabled by setting the appropriate flag value in the sp213_scheduler_parameters database table for the relevant FRU (or, enabled/disabled globally by setting the value in the sp083_system_parameters database table). See the sub-pages for the details of the flag for each type of push notification.

However, before enabling specific push notifications for an FRU (or globally) the following values must be set globally via the sp083_system_parameters database table. (Setting of general push notification flags below for a specific FRU via the sp213_scheduler_parameters database table is not permitted).

Column Name Type Description

notification_server_url

string

The URL which ServiceOptimizer will call when sending push notifications.

For example:

https://localhost:443/myapp/somepath/jobNotification
http://my.host/notificationApi

notification_jwt string The JSON Web Token required to authenticate calls to the URL above. Leave blank if not required.

notification_days_before int Number of days for which undelivered push notifications will be stored for; after this time, any undelivered notification are deleted.

Notification API Interface

In order to ensure that ServiceOptimizer can communicate with the external system when sending push notifications, it is a requirement that the URL that ServiceOptimizer is configured to send push notifications implement the following API Interface.

API Inputs

The URL that ServiceOptimizer is configured to send push notifications to is required to accept the following API inputs:

API Type

The API must accept a POST HTTP method.

Headers

The API must accept the following HTTP headers:

User-Agent: "DataNotifier"
Authorization: ${notification_jwt}
Content-Type: application/json

The ${notification_jwt} value in the header will be from the value configured via the database (above).

Body

The API must accept a JSON object in the body of the API call. The details of the JSON object that will be sent are documented in the sub-pages for each type of push notification.

API Response

In addition to ensuring that the URL that ServiceOptimizer is configured to send push notifications to implements the above API inputs, it is also a requirement that the API respond with the following format:

Response Object Format

{
	"Success": true,
	"Code": "0",
	"Message": "OK"
}

Response Object Properties

Property	Type	Required?	Description
`Success`	`boolean`	Yes	Must be `true` if the external system handled the push notification from ServiceOptimizer; `false` otherwise.
`Code`	`integer`	Yes	Must be 0 (zero) on success; non-zero otherwise, with the non-zero value indicating the type of error encountered.
`Message`	`string`	Yes	A string (required, but empty permitted), describing the response in further detail (usually, describing the reason for an error).

Browser not supported