Contents
Background Services Push API
Purpose
This article is written to provide support and understanding for the Background Services function which enables the following push notifications:
- Appointment Confirmation
- Appointment Cancellation
- Unavailabilities
What is the Background Service
The DRS Background Service provides an Outbound Push notification service for 3rd party API's to consume for various actions performed by both Users and Automated Services within DRS.
How does the Background Service work
The Background service is a timed function to deliver formatted XML data through the DRS WebService Gateway API. All output from the Background Service is logged within the DRS Database and managed by the Housekeeping service.
As actions are performed within the product, whether they be by User action or Automated Service, an entry is made into the Background Services activity table. When tasks are processed by the relative services, a log of the output is created within the database. The Background Services activity table is updated with the outcome and the entry is marked as Actioned.
A number of formatted outputs are available;
Booking Confirmations
When a job is created and scheduled, a row will be added to tblbackgroundTasks until the Appointment Confirmation Data Extract runs via Background or Utility Service.
When a confirmation is processed through the WebService or Flat File gateway, the entry is marked as actioned.
Booking Cancellations
When a user deletes a booking, DRS writes a notification row within logging tables that track object deletions. The Cancellelation service periodically extracts the data from logging tables and writes it into the two archiving tables to ensure that if the sync database needs to be re-built then booking cancellation details are not lost. The Service also writes a row into the Background Services activity table.
When a Cancellation is processed through the WebService or Flat File gateway, the entry is marked as actioned.
Booking Completions
A timed service runs which reviews all Job Objects which have been set to a status of 'Completed' since the last time the service was run. On each run, the service adds an entry into the Background Services activity table. Order and Job information is sent for each entry within the activity table for consumption by third party API's.
When a Completion is processed through the WebService or Flat File gateway, the entry is marked as processed.
Unavailabilities
DRS can send a formatted XML output for Unavailabilities each night. The output contains all Unavailabilities for the previous day for each resource. This service runs as a two part function. Data is intiially extrracted for processing in bulk, this is then transformed for output through the API. On completion of the output, the date of the logged last extract time is updated. This extract is then processed and trasformed for output through the API to the third party API.
Only Unavailabilities scheduled since the last known extraction are processed through this function.
Background Service API
The DRS background service uses a standard interface output for all third party API's. Each API function provides a fixed set of data points which are associated with the object in question. Some datapoints within this output can be supressed to limit the data transmission size.
Booking Confirmation
The Booking Confirmation output will, by default, include these fields;
Booking Information
Field Name | Data Type | Length | Description |
bookingId | Text |
| An integer containing the unique id for the Booking |
primaryOrderNumber | Text | 50 | Primary Order Number |
secondaryOrderNumber | Text | 50 | Secondary order number (optional) |
tertiaryOrderNumber | Text | 50 | Order number from third interfacing application (optional) |
tokenId | Text | 50 | The token Id originally assigned by Xmbrace for the booking |
planningWindowStart | DateTime |
| e.g. DD-MMM-YYYY 00:00:00 01-JUN-2005 13:30 |
planningWindowEnd | DateTime |
| e.g. DD-MMM-YYYY 00:00:00 03-JUN-2005 17:30 |
targetDate | DateTime |
| e.g. DD-MMM-YYYY 00:00:00 03-JUN-2005 17:30 |
bookingReason | Text | 50 | Reason the planning window was changed. The reasons are held on a table and can be defined for each implementation. The first time an appointment is created this is set to ‘FIRST’. |
bookingSequence | Text | 50 | Indicates if this was the first or a follow on booking. For multi-day jobs where several bookings are created, each booking has a value of FIRST. ‘FIRST’ or ‘FOLLOW ON’ |
originalBookingId | Text | 50 | Where this is a FOLLOW ON, this is the unique id of the original booking for which it is a follow on. |
numberOfOperatives | Integer |
| The no of non-supplementary operatives required by the template associated with the booking |
userId | Text | 50 | User Id of the person scheduling the job or changing the planning window |
changedDate | DateTime |
| e.g. DD-MMM-YYYY 00:00 01-JUN-2005 13:30 |
contract | Text | 50 | Contract to which the appointment relates. Note: This may be used to hold the ’Programme of Work’ (in Housing terms) to which the work belongs, which is the code for the contractual arrangement. |
Booking Codes
Field Name | Data Type | Length | Description |
orderId | Integer |
| The unique id of the order within Opti-Time |
bookingId | Integer |
| The unique id of the booking within Opti-Time |
bookingCode (SOR code) | Text | 50 | The code value |
primaryOrderNumber | Text | 50 | The primary order number of the order which must be unique. This is the reference from the first application interfacing with Opti-Time. |
Quantity | Text | 50 | How many booking codes |
standardMinuteValue | Text | 50 | The number of minutes it will take to complete the booking code. |
itemNumber (within booking) | Text | 50 | A way to sequence booking codes within a booking. |
itemValue | Text | 50 | The value in monetary terms of the booking code. |
Trade | Text | 50 | The trade the booking code belongs to. |
bookingCodeDescription | Text | 250 | A description to override the stored description for this booking code. |
Comments | Text | 250 | Any comments about the booking code |
Reference | Text | 50 | A reference value that can be used by other applications to identify the booking code. |
Unavailability Notification
The Unavailability Notification will, by default, include these fields;
Field Name | Data Type | Length | Description |
Action | Text | 50 | The action |
ResourceId | Text | 50 | The DRS resource Id |
OperativeId | Text | 50 | The resource Id in the application communicating with Opti-Time |
PeriodStart | DateTime |
| e.g. DD-MMM-YYYY 00:00:00 01-JUN-2005 13:30 |
PeriodEnd | DateTime |
| e.g. DD-MMM-YYYY 00:00:00 03-JUN-2005 17:30 |
Reason | Text | 50 | Reason for the unavailability, e.g. absence |
Comments | Text | 50 | Comments about the unavailability, e.g. dentist |
Booking Cancellation
The Booking Cancellation Notification will, by default, include these fields;
Booking Information
Field Name | Data Type | Length | Description |
bookingId | Text |
| An integer containing the unique id for the Booking |
primaryOrderNumber | Text | 50 | Primary Order Number |
secondaryOrderNumber | Text | 50 | Secondary order number (optional) |
tertiaryOrderNumber | Text | 50 | Order number from third interfacing application (optional) |
tokenId | Text | 50 | The token Id originally assigned by Xmbrace for the booking |
planningWindowStart | DateTime |
| e.g. DD-MMM-YYYY 00:00:00 01-JUN-2005 13:30 |
planningWindowEnd | DateTime |
| e.g. DD-MMM-YYYY 00:00:00 03-JUN-2005 17:30 |
targetDate | DateTime |
| e.g. DD-MMM-YYYY 00:00:00 03-JUN-2005 17:30 |
userId | Text | 50 | User Id of the person cancelling the booking |
changedDate | DateTime |
| e.g. DD-MMM-YYYY 00:00 01-JUN-2005 13:30 |
contract | Text | 50 | Contract to which the booking relates. Note: This may be used to hold the ’Programme of Work’ (in Housing terms) to which the work belongs, which is the code for the contractual arrangement. |
