Version Control#
Version control applied so that the latest calls available are visible along with any Whitespace version that they would apply to.| Version | Date | Description | WS Version |
|---|
| 0.1 | Jun 2025 | Draft REST | TBC |
Understanding Whitespace#
Since it is important to understand some fundamental principles of the operation of Whitespace to make best use of the system the following few paragraphs will introduce the main features (emboldened in the text below).The Whitespace API is ID-centric. Therefore, Create-type requests will revolve around ID numbers instead of naming conventions. This gives Whitespace front end users the flexibility to rename items without the risk that it will impact API development.You will be provided with an API Matrix by your Implementation Consultant shortly after the initial data load. This API Matrix will contain all of the relevant ID’s required for API Development. There are also mechanisms to retrieve ID’s built into the API after Implementation has been completed which will be covered later in this document.The primary operations of the Whitespace system revolve around the carrying out of work at Sites.Sites are predominantly properties and roads (these being loaded from the council’s BS7666 gazetteer), although other geographical features such as parks and playgrounds are often also included. Typically, this will be a UPRN value (Unique Property Reference Number) in a Municipal system. Commercial systems will be more reliant on Site ID or Account Site ID values.Rounds are collections of Sites logically or geographically grouped together and typically serviced by a particular vehicle or crew.Round Areas are portions of Rounds that are serviced on a given Schedule. As an example, to help elaborate on this a typical setup might be a refuse collection Round called “Refuse-1” that collects from various Sites – the Sites that it collects refuse from on a Monday being grouped into Round Area “Refuse-1 Monday”.Services are mostly the type or works that are undertaken at Sites. Services can be either scheduled or ad-hoc with scheduled work normally being processed to Schedules on Round Areas; ad-hoc work is normally arranged by means of a Worksheet.Schedules are timings that Services are carried out to (e.g. Monday, Tuesday Week-1, Friday Week-2, Annual etc.) Scheduled work is mostly expected to be done as a matter of routine with reporting of problems by exception. Scheduled work most commonly involves routine work being carried out on Service Items.Service Items are features or items that have work carried out on them such as a bin (that gets emptied) or a gulley (that gets cleaned) etc.Service Properties are features that relate particularly to a given type of service. These are user definable fields and are very commonly related to service-related fields in the 3rd party system. All Worksheets carry a standard set of fields, but often additional information is required for clarification or further processing elsewhere. These fields are shown in the back office as “Extra Information” on a worksheet.Combinations of the above features are often referred to such as Site Service Items (occurrences of a specific Service Item at an individual Site – a bin at a property or a tree on a road, that sort of thing). More complex combinations are usually built up by stringing together the component features in a logical fashion – for instance a Round – Round Area –Site – Service – Schedule being information related to the Schedule governing the performance of a particular Service at a Site within a Round Area which in turn is part of a Round.Fair Usage - TBC#
Whitespace will support a maximum of 10,000 API calls per day.Any retry function for a failed call is limited to one instance only.Whitespace will also require that an API Specification relevant to your integration into Whitespace is provided to your Implementation consultant. The Live API connection will not be switched on until this specification is in place.Connecting to your Whitespace instance - TBC#
INSTRUCTIONS on what to do... TBCError Handling - TBC#
No idea if SOAP error messages are relevant / will be returned - TBCService End Point - VERY TBC#
Whitespace can “Poke” a service end point when a worksheet workflow event has taken place. We commonly call this the “Waste Listener” anticipating that your CRM system will have endpoints for multiple systems and Whitespace is typically used to manage Waste.The Waste Listener is not designed to return full information, it returns a summary and further API calls can then be used to retrieve customised fields such as “feedback from the crew” which are held as service properties and seen in Whitespace as extra info. Hence the term “poke”.SOAP instructions are not appropriate - need words from Olavo / Andy / Rob to accurately define the REST Listener. In main doc there is loads of bumpff about SOAP formats - do we need something similar or not? And are there any restirctions to note
Completed Worksheet Listener Functionality#
Notifies your system when a Worksheet Status changes to either Closed or Cancelled.Workflow Event Listener#
Is activated whenever the Worksheet Event Changes. i.e. “Worksheet Created”, or “Worksheet Updated” or “moved to next step” notifications.The Worksheet Status field is updated before the Workflow Event field and can be found here: Worksheet StatusesFor this reason, if you use both the Workflow Event Listener and the Completed Worksheet Listener you will receive the notification that a worksheet has been closed or cancelled a fraction of a second before you receive details about the workflow event which will probably detail the previous step.Sample Poke#
TBC!!! - What is REST listener formatWhitespace Standard Code / ID Tables#
The following tables are non-variable and form part of the system build. They can be used to understand API call responses, as well as to lookup a specific result by API developers.Account Site Status IDs#
| AS Status ID | AS Status Name | AS Status Description |
|---|
| 1 | Active | Active |
| 2 | Stop | Stop – commonly used in Commercial |
| 3 | Closed | Closed – Account site no longer in use |
| 4 | Prospect | Prospect – commonly used in Commercial |
| 5 | Excluded | Excluded from LLPG (Local Land Property Gazetteer) – no further updates will be accepted from COU (Change Only Update) files for LLPG |
Contract Status Codes#
| AS Status ID | AS Status Name |
|---|
| C | Cancelled |
| E | Expired |
| L | Live |
| N | No Contract |
| Q | Quotation |
| S | Stopped |
Log Types#
| Log Type ID | Log Type Name | Log Type Description |
|---|
| 0 | Round | Logs (exclusive to GetInCabLogs) specific to ROUND or WORKSHEET |
| 1 | System | Those logs that are generated by the system |
| 2 | Worksheet | Those logs that are generated by the worksheet module |
| 3 | Worksheet Changes | The logs that record changes to data associated with worksheets |
| 6 | Contact | The logs that record changes to data associated Contacts |
| 7 | Workflow | The logs that generated from Workflow Web Service |
| 8 | Users | The logs that record changes to data to Users |
| 9 | Custom Log | The logs that are entered manually by the users |
| 15 | Workflows | The logs that record changes to Workflows |
| 99 | System Error | Those logs that are generated by a system/server error |
Service Item Properties#
| SIP ID | SIP Name | Service Property Type |
|---|
| 1 | Blocked from | Date |
| 2 | Service item serial number | String |
| 3 | Service item chip number | String |
| 4 | Service item unique number | String |
| 5 | Site service notes | String |
| 6 | EWC code | String |
Worksheet Statuses#
| SIP ID | SIP Name |
|---|
| Open | Indicates that the worksheet is open, ready to be processed |
| Complete | Indicates that the worksheet has been completed successfully |
| Cancelled | Indicates that a worksheet has been cancelled |
