The Urgent platform also communicates outbound to send details of four operations that occur within it, these are:

• Task Created
• Task Status Changed
• task Note Added
• Task Chased
• Task Changed

Endpoint Configuration

The endpoint for each method is configured in the user's profile in the API tab.

Authentication

The outbound process uses the same HMAC digest format as the inbound process (guide) where tokens and secrets will be used when sending API requests to the end users. If you are not using the HMAC system to secure your endpoint the system currently requires something added to the token and secret fields.

SSL Certificates

All endpoints must be SSL secured. They must be a valid, trusted certificate. The following items will be checked:

• The certificate chains to a trusted root
• The certificate is not expired (and other such things)
• The request hostname matches

Recipients

The following logic is used to determine which users receive API notifications. All require that the relevant API Endpoint configuration method in the user profile is not blank

User Type	Recipients
Supplier	Any users of the supplier or its parent that are assigned to the task and have access to the site, either explicitly or through geographic areas and site channels, and the user that created the task.
Site	Any site users that have access to that site or any of its parents, either explicitly or through geographic areas and site channels.
Management	Any users that have access to the site or any of its parents, either explicitly or through geographic areas and site channels.

Acknowledgement

The receiving service should reply with an HTTP 200 status code with a blank (not null) body. Any other responses will be treated as an error.

Error Handling

Should a response be returned that does not meet the above criteria the request will be made repeatedly at regular intervals until a threshold is reached. after which the message is deemed a terminal failure and will be not retried. Instead, if the relevant user has the Email Failures flag set in their user profile and they have an email address set, the JSON will be emailed to the user along with the message returned by their server. It will not be possible to re-queue the notifications, the user must use the JSON provided to manually update the receiving system.

Methods

Task Created

Purpose: Notify a user when a new task is created and dispatched to a supplier. Note, notifications for tasks in a NEW status are not sent via the API.

Method: POST Request The JSON response from the Read Task API will be sent.

Task Status Changed

Purpose: Notify a user when a task's status has been changed.

Please note: If you have both a Task Create and a Task Status Changed endpoint set then you will receive the details through both endpoints for a new task or one that the Urgent system has determined it has not sent to your system before. This can cause multiple versions of the data (one containing the full data set of the Task for the Create and one smaller update for the Status Update) being sent to your system.

Method: PUT

Request

Property	Type	Max Length	Mandatory	Note
TaskIdentifier	GUID		Y
TaskReference	int		Y
Tenant	string	100	Y
StatusChangeIdentifier	GUID		Y
Status	string	100	Y	Name of status in user’s language
StatusChangeDateTimeUtc	DateTime		Y
Note	string	2000	N	Mandatory by status
TaskCompliance[]	array		N
TaskCompliance[]/Name	string	250	Y	Task Compliance question name
TaskCompliance[]/Answer	string	depends on data type	Y	String representation of the appropriate data type. List options are text in user’s language
AssetDowntime/Reason	string	255	N	Asset Downtime Reason in text
AssetDowntime/IsAssetBackUp	boolean?		N	Only if the task’s Asset Available To Make Sales is false.

Example

{
  "TaskIdentifier": "f5e99171-db8a-42f5-9822-1385f055f42c",
  "TaskReference": 80027,
  "Tenant" : "Test Tenant",
  "StatusChangeIdentifier": "fd899952-a146-4739-bc1c-f422d5201ec6",
  "StatusChangeDateTimeUtc": "2020-05-29T10:47:34.915632Z",
  "Status": "Attended",
  "Note": "Technician John Doe now on site",
  "TaskCompliance": [{
    "Name": "TC_TrainedAndCompetent",
    "Answer": true
  }, {
    "Name": "TC_SafetyBadgeNumber",
    "Answer": "ABC-112"
  }],
  "AssetDowntime": null
}

Task Note Added

Purpose: Notify a user when a note has been added to a task Method: POST

Request

Property	Type	Max Length	Mandatory	Notes
Tenant	string	100	Y
TaskReference	string	100	Y
NoteIdentifier	GUID		Y
Note	string	2000	Y
NoteDateTimeUtc	Datetime		Y

Example

{
  "Tenant": "Test Tenant",
  "TaskReference": 80027,
  "NoteIdentifier": "b7e0d728-c96b-4bc4-b9f6-8c2f8f833c76",
  "Note": "Technician John Doe will be on site today",
  "NoteDateTimeUtc": "2020-05-29T10:54:18.388505Z",
  "TaskIdentifier": "21a2c19e-7317-4b64-bf4e-6bbf1f51c4e8"
}

Task Chased

Purpose: Notify a user when a task has been chased Method: PUT

Request

Property	Type	Max Length	Mandatory	Notes
Tenant	string	100	Y
TaskReference	int		Y
TaskIdentifier	GUID		Y
Note	string	2000	Y
ChasedDateTimeUtc	DateTime		Y
ChaseIdentifier	GUID		Y

Example

{
  "Tenant": "Test Tenant",
  "TaskReference": 80027,
  "TaskIdentifier": "058e9c0a-44fb-46ca-9510-35f38ff82dfd",
  "Note": "Technician is over two hours late, please update.",
  "ChasedDateTimeUtc": "2020-05-29T10:57:58.225195Z",
  "ChaseIdentifier": "f0dcb615-ee3f-4d38-aa74-8e82f7e60618"
}

Task Changed

Purpose: Notify a user when a new task is changed via the Change Task process.

Method: POST Request The JSON response from the Read Task API will be sent.