Contents

Background Services Push API

Andrew Dotto Updated by Andrew Dotto

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.

Was this article useful?

Password Security in DRS

Contact