2.1 Queue settings
2.2 Compression
2.3 Message sequencing and ordering
2.4 Versioning
3.1 Message format
3.2 Supported messages
3.2.1 Part consumed
3.2.2 Billing event occurred
3.2.2.1 Billing event objects
3.2.3 Work Order created
3.2.3.1 Order created objects
3.2.4 Work Order updated
3.2.5 Account Created
3.2.6 Account Updated
3.2.7 Property Created
3.2.8 Property Updated
3.3 Common objects
3.3.1 Enumerations
The purpose of this document is to provide a concise description on how an external system can con-nect and consume messages sent by the Urbanise Service Delivery software.
This guide describes the endpoints for the message queues, how to connect to a queue, as well a description of the event types currently supported by Service Delivery, the action that triggers them, as well as the format of the messages being sent.
The name of the SQS queue external systems can connect to is derived from the tenant name in Urbanise Service Delivery:
For example if the tenant name in Service Delivery is “somecompany”, then the queue for this tenant would be named:
OutboundQueue_somecompany
Authentication against the queue is done using a designated company account. A user of this API can use the following credentials to access the queue:
awsSecretAccessKey: contact your Urbanise provider
awsAccessKeyId: contact your Urbanise provider
awsEndPoint: contact your Urbanise provider
awsQueueName: OutboundQueue_{tenantName}
Due to the limitations of the SQS service a message can be at most 256kb in size. However a lot of the business objects transferred through this API exceed this limit in their JSON representation. This enforces the use of compression. Every single message passing through is compressed using GZIP and then Base64 encoded so that SQS accepts it, as it only allows a limited set of characters.
Because of this consumers of this API must decode their messages. The following code snippet is used for decompressing the message in Java. Other consumers must provide their own decompression implementations.
public static String uncompressString(String zippedBase64Str) throws IOException {
String result = null;
byte[] bytes = Base64.decodeBase64(zippedBase64Str);
GZIPInputStream zi = null;
try {
zi = new GZIPInputStream(new ByteArrayInputStream(bytes));
result = IOUtils.toString(zi);
} finally {
IOUtils.closeQuietly(zi);
}
return result;
}
Since Amazon's SQS does not guarantee ordering of the messages it sends, nor does it guarantee only-once delivery a scenario like the one depicted below is very likely to occur:
To deal with this problem sequence numbers are introduced in the message attributes of some of the messages. This is a custom message attribute , provided by Urbanise. A brief explanation of the logic behind it is described below.
Each message type has it's own unique sequence key. The counter associated with this key does not necessarily start from 0 and the key is different for each stream of objects.
The available keys are:
An example message attribute map would look like this:
{
LogicalResourceId=plaza-async-api-outbound-staging-original,
ApproximateReceiveCount=1,
SentTimestamp=1493271596597,
ReceiptHandle=f595a95f-f04f-4f4e-954b-00a39cdec467#1221de16-8e74-4138-88f1-d2ae57881b4a,
SenderId=127.0.0.1,
SequenceNumberBillingEventOccurred=2871,
lookupDestination=plaza-async-api-outbound-staging-original,
ApproximateFirstReceiveTimestamp=1493271596599,
MessageId=f595a95f-f04f-4f4e-954b-00a39cdec467,
WorkOrderUpdatedModelVersion=1
}
The Asynchronous API supports versioning which is described in this document. Every field in the messages has a version number indicating the version where it first appeared in the model. Fields are not deleted as the versions increase, so only additions are expected.
To determine which model version the message you've received is using you can read the message attributes of the message. Each message has a version tag describing this. Additionally for some clients this information is also available in the body of the message. The list of message attribute keys is as follows:
If a consumer of the Asynchronous API wants to increase the version of the messages they receive, they must contact their Urbanise suppliers. If you're a new client by default you'll be working with the latest version of the model. A changelog providing a summary of what was added between versions can be found at
Plaza uses JSON to represent the event messages. The generic message template is as follows:
{
“data":{
"property1":"value",
"property2":value,
"property3":"value",
…..
},
“eventType":"EVENT_DESCRIPTION"
}
Field - Type - Description
This event is triggered when a part is assigned to a job.
After the part has successfully been consumed by the job, a message is published at the address of the aforementioned queue. A consumer subscribed to the queue can then read it.
Field - Nullable - Type - Description - Version
An example message produced by the PART_CONSUMED event is as follows:
{
"data":{
"vendorSku":"JBHiFi_SKU",
"quantity":1,
“manufacturerCode":"LG_CODE",
"jobInventoryDetails":{
"jobName":"Plumbing",
"jobReferenceNumber":"JOB-00000460",
“jobExternalReferenceNumber”:""
},
"supplyPointName":"Mountain view site",
"partNumber":"DBN091000",
"manufacturerName":"LG",
"partName":"Screw"
},
"eventType":"PART_CONSUMED"
}
Field - Nullable - Type - Description - Version
Sample JobInventoryDetails object JSON:
"jobInventoryDetails":{
"jobName":"Job Template",
"jobReferenceNumber":"JOB-00000963",
"jobExternalReferenceNumber":""
}
This event is triggered whenever a billing event occurs. The specific reason for the billing event to be triggered can be derived from the billingEventType field.
The billingEventType field can take one of the following values:
Billing Event Type - Description - Version
A sample Billing Event message looks as follows:
{
"eventType":"BILLING_EVENT_OCCURRED",
"data":{
"creatorCredentials":"30",
"description":"Charge added to job Job Template for My Wizard Plan",
"subdescription":null,
"appliedCreditReferences":null,
"creationTime":"2016-10-31T09:11:24.000",
"effectiveStartDate":"2016-10-31T09:11:24.000",
"effectiveEndDate":null,
"salesTaxPercentage":29.99,
"margin":null,
"billingEventType":"MANUAL_CHARGE",
“amountRemaining”:{…},
“salesTaxAmount”:{…},
“account”:{…},
“amount”:{…},
"credit":null,
"invoice":null,
“property”:{…},
"quotedItem":null,
"productBundle":null,
“productBundleOrder”:{…},
“job”:{…},
"selectedVariation":null
}
}
Below is a description of the fields contained in the BILLING_EVENT_OCCURRED message. For enum values please refer to the corresponding tables provided below.
Nested objects are denoted with their appropriate type in the Type column. For further infor-mation about the particular object, please refer to it’s description table in section
Field - Nullable - Type - Description - Version
This section describes all the nested objects in the main BILLING_EVENT_OCCURRED mes-sage. An example JSON of each object is provided after the tabular description.
Field - Nullable - Type - Description - Version
Sample Credit object JSON:
"credit":{
"referenceNumber":"PT-10000001",
"amount":{
"currencyCode":"AUD",
"value":555.00
},
"amountRemaining":{
"currencyCode":"AUD",
"value":0.00
}
}
Field - Nullable - Type - Description - Version
Sample Invoice object JSON:
“invoice":{
"referenceNumber":"I-00000005",
"issuedDateTime":"2013-01-28T14:42:07.000"
}
Field - Nullable - Type - Description - Version
An example Product Bundle Order with the Product Bundle part omitted:
"productBundleOrder":{
“productBundle”: {…},
"description":null,
"referenceNumber":"WO-00000138",
"productBundleOrderSummary":"My Wizard Plan",
"status":"NEW",
"subCategory":"WORK_ORDER",
"dueTime":"2016-11-02T18:00:00.000",
“externalReferenceNumber”:null
}
Field - Nullable - Type - Description - Version
Field - Nullable - Type - Description - Version
Sample SelectedVariation object as JSON:
"selectedVariation":{
"variationSpec":{
”key":"size",
"name":"Choose your size"
}
}
The work order created event is triggered whenever there is an order creation in the Plaza Ops portal. There are several types of orders raised, which are described below. To determine the concrete type of the work order refer to the field orderType.
Subcategory Type - Description - Version
Field - Nullable - Type - Description - Version
An overview of the order created object in JSON format:
“data":{
“productBundle”:{…},
“jobs”:[…],
"orderType":"PACKAGE_ORDER",
"cancellationTime":null,
"cancelled":false,
“schedules”:[…],
"description":null,
"activationTime":null,
"lastCompletedTime":null,
"dueTime":null,
"referenceNumber":"PO-00000403",
“requestCategory”:{…},
“topic”:{…},
"creationTime":"2016-11-09T10:24:36.000",
"completedTime":null,
“account”:{…},
“assignee”:{…},
"lastUpdateTime":"2016-11-09T10:24:36.000",
"status":"REVIEW",
"externalReferenceNumber":"PO-14009999",
“creator”:{…},
“raisedFor”:{…},
“property”:{…},
"areas":[…],
“assets”:[…],
"nextAction":null,
“quotation”:{…}.
“productBundleCallout”:{…},
"comments":[...],
"attachments":[...]
}
A description of the OrderJob object is provided below. It extends the Job base object described in Table 2.4. It should be noted that the productBundleOrder field from the base object is omitted here, as it doesn’t make sense in the current context.
Field - Nullable - Type - Description - Version
An element from the list of OrderJobs in it’s JSON representation:
{
"dueTime":"2017-11-15T09:00:00.000",
"activationTime":"2017-11-12T09:00:00.000",
"description":null,
"status":"NEW",
"subCategory":"PLANNED",
"summary":"SLA Template",
"externalReferenceNumber":null,
"referenceNumber":"JOB-00001001",
"contractSLAExpiration":"2017-11-15T21:00:00.000",
"slowSLAExpiration":"2017-11-16T01:00:00.000",
"assignee":null,
"creator":null,
“property”:{…},
“assets”:[…],
“areas”:[…],
“appointments”:[…],
"nextAction":null,
“quotation”:{…},
"jobTemplateName":"name",
"checkIn":{...},
"jobType":"PLANNED",
"priority":"ROUTINE",
“invoice”:{…},
"comments":[...],
"attachments":[...],
"jobFields":[...]
}
Field - Nullable - Type - Description - Version
An element from the list of Quotation in it’s JSON representation:
"quotation":{
“provider”:{…},
"expiryDate":"2016-11-08T10:23:47.000",
"comment":"Your expired quote",
"quotationStatus":"EXPIRED",
“quotedItems”:[…]
}
Subcategory Type - Description - Version
A description of the OrderJobQuotedItem object is provided below. It extends the Quoted item base object described in the Table.
Field - Nullable - Type - Description - Version
An element from the list of OrderJobQuotedItem in it’s JSON representation:
{
"identifier":"16",
"description":"quoted item",
“recurringCost”:{…},
“setupCost”:{…},
"salesTaxRate":"Standard Tax Rate",
“acceptedSalesTaxRate":4.33,
"quantity":1,
“rate”:{…}
}
Subcategory Type - Description - Version
A Rate in it’s JSON representation:
"rate":{
"salesTaxRate":null,
"cost":{
"currencyCode":"AUD",
"value":13.37
},
"salesCost":{
"currencyCode":"AUD",
"value":13.37
},
"description":"tax rate",
"code":"CODE"
}
Field - Nullable - Type - Description - Version
An example Schedule JSON element:
{
"dayOfWeek":"FRIDAY",
"estimate":"PT14400S",
"weekNumber":null
}
Field - Nullable - Type - Description - Version
An example Category JSON element:
"requestCategory":{
"label":"spiffy",
"externalCode":null
}
Field - Nullable - Type - Description - Version
An example Topic JSON element:
"topic":{
"label":"spiffy",
"externalCode":null
}
Field - Nullable - Type - Description - Version
An example Person JSON element:
"person":{
"globalIdentifier":"154",
"organization":null,
"givenName":"dews321412341",
"middleName":"w421312341",
"familyName":"w234f",
"gender":null,
"nationality":null,
"dateOfBirth":null,
"contactDetails":{ },
"title":null
}
Field - Nullable - Type - Description - Version
An example Area JSON element:
{
"name":"Area 52",
"referenceNumber":"RN_A_1001",
"externalReference":"extRef",
"identifier":"I-1111",
"description":"some description",
"latitude":"23.320321",
"longitude":"42.736334",
"size":"12sqm",
"deleted":"false",
"areaTags":[...]
}
Field - Nullable - Type - Description - Version
An example Asset JSON element:
{
"type":"null | LG | null",
"serialNumber":"SN_101001",
"name":"asset name",
"referenceNumber":"RN_1010",
"externalReference":"extRef"
}
Field - Nullable - Type - Description - Version
An example ProductBundleCallout JSON element:
"productBundleCallout":{
"remaining":-1,
"allocated":-1,
“callout”:{…}
}
Field - Nullable - Type - Description - Version
An example Callout JSON element:
"callout":{
"label":"Air Conditioning",
"externalCode":"5432",
"retired":false,
"assignee":null
}
Field - Nullable - Type - Description - Version
Type - Description - Version
An example Invoice JSON element:
"invoice": {
"referenceNumber": "INV-00000051",
"invoiceStatus": "APPROVED",
"creationTime": "2017-05-07T23:49:34.000",
"updateTime": "2017-05-07T23:51:50.000",
"submittedTime": "2017-05-07T23:51:50.000",
"approvedTime": "2017-05-07T23:52:03.000",
"paidTime": null,
"paymentFailedTime": null,
"approvedBy": {...},
"submittedBy": {...},
"comment": "",
"rejectionReason": null,
"invoiceItems": [...],
}
Field - Nullable - Type - Description - Version
Field - Nullable - Type - Description - Version
name - No - String - The name of the job field. - 1
value - No - String - The value of the job field. - 1
Field - Nullable - Type - Description - Version
identifier - No - String - The identifier of the appointment. - 4
localDate - YES - String - Local date of the appointment. - 4
startTime - YES - String - The start time of the appointment. - 4
state - YES - String - The state of the appointment. To view the allowed values of this field refer to the corresponding table at the bottom of this document. - 4
The work order updated message is triggered whenever there’s a change in a Work Order. The message generated by this event is structurally very similar to the one for ORDER_CREATED. Every single field we have there is also present in the ORDER_UPDATED one.
The only addition here is the changeSet node, which contains information about the exact fields that have changed values, allQuotesApproved, totalInternalQuotedAmount and totalExternalQuotedAmount.
Field - Nullable - Type - Description - Version
allQuotesApproved - NO - Boolean - True if all jobs in the work order that are quotable have been accepted. - 1
totalInternalQuotedAmount - YES - Money - The total amount of the quotes in the work order. - 1
totalExternalQuotedAmount - YES - Money - The total amount of the quote using the sales cost of any rates used in the quote or the cost otherwise. - 1
changeSet - NO - List - A list of JsonPaths pointing to the changed elements. - 1
orderUpdatedModelVersion - NO - Number - The model version of the order updated payload. Only available for some clients. - 2
orderUpdateSequenceNumber - NO - Number - The order updated sequence number for this message. Only available for some clients. - 2
The additional part of the ORDER_UPDATED payload:
"orderUpdatedChangeSet":{
"typeInfo":"jsonPathChangeSet",
"changePaths":[
"$.nextAction",
"$.lastUpdateTime",
"$.jobs[1]",
"$.jobs[0].nextAction",
"$.jobs[0].lastUpdateTime"
]
},
"allQuotesApproved":true,
"totalInternalQuotedAmount":null,
"totalExternalQuotedAmount":null,
"orderFields":null
}
Note about the orderUpdatedChangeSet element:
This element contains two fields.
typeInfo, which can safely be ignored in most cases as it is mainly used to hold metadata about the format of the paths.
changePaths - a List of Json paths pointing to the elements in the payload that have changed, $. indicating root. In the example above $.jobs[0].lastUpdateTime indicates that, in the list of jobs, the job at position 0, changed it's last update time.
In case the path is "empty" as is the case with $.jobs[1], that means that the whole element at that index has been inserted. Refer to Introduction to JsonPath by Baeldung for additional information.
This event is triggered when an account is created in Plaza.
Field - Nullable - Type - Description - Version
accountCreatedSequenceNumber - NO - Number - The sequence number related with the ACCOUNT_CREATED event. - 2
creationTime - NO - Date - The creation time of the account. - 2
closedTime - YES - Date - The closing time of the account. - 2
accountNumber - NO - List - The account number. - 2
billingAddress - YES - Address - The billing address associated with this account. For additional information about the address object refer to table 14A. - 2
accountStatus - NO - String - The account status. Valid values are described in the account status table. - 2
preferredLanguage - NO - String - The preferred language for this account.
communities - YES - List - A list of communities. In reality there can only be one community. - 2
corporate - YES - Boolean - Indicates whether an account is corporate or not.
owner - YES - Person - The owner of this account. For additional information about the person object refer to table 6.5. - 2
relatedProperties - YES - List - A list of related properties for this account. - 2
externalReference - YES - String - An external reference number for this account. - 2
accountCreatedModelVersion - YES - Number - The account created object model version. This field exists only for some consumers. - 2
{
"eventType":"ACCOUNT_CREATED",
"data":{
"accountCreatedSequenceNumber":76,
"creationTime":"2017-08-08T08:33:24.000",
"closedTime":null,
"accountNumber":"00001032",
"billingAddress":{...},
"accountStatus":"ACTIVE",
"preferredLanguage":"en",
"communities":[...],
"corporate":null,
"owner":{...},
"relatedProperties":[...],
"externalReference":null,
"accountCreatedModelVersion":2
}
}
The account updated message is triggered whenever there’s a change in an Account. The message generated by this event is structurally very similar to the one for ACCOUNT_CREATED. Every single field we have there is also present in the ACCOUNT_UPDATED one.
The only addition here is the changeSet node, accountUpdatedModelVersion and accountUpdatedSequenceNumber which contains information about the exact fields that have changed in the form of JsonPaths and the model version/sequence number.
Field - Nullable - Type - Description - Version
changeSet - NO - List - A list of JsonPaths pointing to the changed elements. - 2
accountUpdatedSequenceNumber - NO - Number - the sequence number for the account updated message. Note that for each account number there is a sequence attached, and thus they are correlated. Only available for some clients. - 2
accountUpdatedModelVersion - NO - Number - the model version for the account updated message. Only available for some clients. - 2
ACCOUNT_UPDATED example Json:
{
"eventType":"ACCOUNT_UPDATED",
"data":{
"creationTime":"2017-08-08T08:33:24.000",
"closedTime":null,
"accountNumber":"00001032",
"billingAddress":{
"line1":"",
"line2":"",
"buildingName":null,
"city":null,
"state":null,
"postcode":null,
"country":""
},
"accountStatus":"ACTIVE",
"preferredLanguage":"en",
"communities":[
{
"identifier":null,
"displayName":"Original",
"key":"original"
}
],
"corporate":false,
"owner":{
"globalIdentifier":"154",
"organization":null,
"givenName":"dews321412341",
"middleName":"w421312341",
"familyName":"w234f",
"gender":null,
"nationality":null,
"dateOfBirth":null,
"contactDetails":{
"email":"t1111est@abv.bg",
"primaryPhone":"1111111132413ffff",
"normalisedPrimaryPhone":"1111111132413ffff",
"otherPhone":"11111111f",
"normalisedOtherPhone":"11111111f",
"mobileNumber":null,
"mobileCountryCode":null,
"mobileCountryCallingCode":null,
"residentialAddress":{
"line1":"",
"line2":"",
"buildingName":null,
"city":null,
"state":null,
"postcode":null,
"country":""
}
},
"title":null
},
"relatedProperties":[ ],
"externalReference":null,
"accountUpdatedSequenceNumber":2,
"accountUpdatedChangeSet":{
"typeInfo":"jsonPathChangeSet",
"changePaths":[
"$.communities",
"$.corporate",
"$.owner.contactDetails",
"$.owner.familyName",
"$.owner.givenName",
"$.owner.middleName"
]
},
"accountUpdatedModelVersions":2
}
}
This event is triggered when a property is created in Plaza.
Field - Nullable - Type - Description - Version
propertyCreatedSequenceNumber - NO - Number - The sequence number related with the PROPERTY_CREATED event. - 3
externalReferenceNumber - YES - String - The external reference number associated with this property - 3
referenceNumber - NO - String - The reference number associated with this property - 3
name - YES - String - The name of the property. - 3
address1 - YES - String - The address of the property. - 3
address2 - YES - String - The secondary address of the property. - 3
state - YES - String - The state for the property. - 3
city - YES - String - The city for the property. - 3
country - NO - String - The country for the property. - 3
postcode - YES - String - The postcode for the property. - 3
creationTime - NO - String - The time when the property first appeared in Plaza. - 3
lastUpdateTime - NO - String - The time when the property was last updated. - 3
archiveTime - YES - String - The time when the property was archived. -3
communities - YES - List - The communities associated with this property. - 3
areas - YES - List<Area> - The areas associated with this property. For a detailed description of the Area object refer to table 6.6. - 3
roomCount - YES - Number - The room count of the property. - 3
buildingType - YES - String - The building type of the property, if it is a building. - 3
buildingName - YES - String - The building name of the property, if it is contained in a building. - 3
siteName - YES - String - The name of the site where the property is. - 3
deliveryRegion - YES - String - The delivery region for the property. - 3
latitude - YES - String - The latitude of the property. - 3
longitude - YES - String - The longitude of the property. - 3
propertyTags - YES - List - A list of tags associated with the property. For a detailed description of the Region object please refer to table 17. - 3
region - YES - Region - The region associated with the property. For a detailed description of the Region object please refer to table 16. - 3
site - YES - Boolean - A flag indicating whether the property is a site. - 3
propertyType - YES - String - The type of the property. - 3
parent - YES - Property_Created - A parent property object, if it has any. - 3
buildingNumber - Yes - String - The building number of the property, if it is contained within a building or is a building. - 3
unitNumber - Yes - String - The unit number of the property. - 3
propertyCreatedSequenceNumber - Yes - Number - The property created sequence number. Only available for some clients. - 3
propertyCreatedModelVersion - Yes - Number - The property created sequence number. Only available for some clients. - 3
PROPERTY_CREATED example Json:
{
"externalReferenceNumber":null,
"referenceNumber":"PP-00000051",
"name":null,
"address1":"190 NotSoGood St1",
"address2":"test",
"state":null,
"city":null,
"country":"AS",
"postcode":null,
"creationTime":"2017-09-04T10:37:42.000",
"lastUpdateTime":"2017-09-04T10:37:42.000",
"archiveTime":null,
"communities":[...],
"areas":[...],
"roomCount":null,
"buildingType":null,
"buildingName":"juhtgf",
"siteName":null,
"deliveryRegion":null,
"latitude":"6",
"longitude":"6",
"propertyTags":[...],
"region":{...},
"site":false,
"propertyType":"UNIT",
"parent":null,
"buildingNumber":null,
"unitNumber":null,
"propertyCreatedSequenceNumber":25,
"propertyCreatedModelVersion":3
}
This event is triggered when a property is updated in Plaza.
The property updated message is triggered whenever there’s a change in a Property. The message generated by this event is structurally very similar to the one for PROPERTY_CREATED. Every single field we have there is also present in the PROPERTY_UPDATED one.
The only addition here is the changeSet node, propertyUpdatedModelVersion and propertyUpdatedSequenceNumber which contains information about the exact fields that have changed in the form of JsonPaths and the model version/sequence number.
Note that due to technical difficulties it is not always possible to easily tell when particular types of changes happen in the Property and Area tags. It is advisable that you don't completely rely on the changeset for those particular objects if they're of critical importance for your systems , and simply update them by using the last received state of the collections.
Field - Nullable - Type - Description - Version
changeSet - NO - List - A list of JsonPaths pointing to the changed elements. - 3
propertyUpdatedSequenceNumber - NO - Number - the sequence number for the property updated message. Note that for each property number there is a sequence attached, and thus they are correlated. Only available for some clients. - 3
propertyUpdatedModelVersion - NO - Number - the model version for the property updated message. Only available for some clients. - 3
PRPERTY_UPDATED example Json:
{
"externalReferenceNumber":"PP-10000015",
"referenceNumber":"PP-00000015",
"name":"7|11 Pipe St London",
"address1":"7|11 Pipe St33",
"address2":null,
"state":"London",
"city":"London",
"country":"GB",
"postcode":null,
"creationTime":"2017-09-04T06:55:16.000",
"lastUpdateTime":"2017-09-04T11:13:45.000",
"archiveTime":null,
"communities":[
{
"identifier":null,
"displayName":"Original",
"key":"original"
}
],
"areas":[
],
"roomCount":null,
"buildingType":null,
"buildingName":null,
"siteName":null,
"deliveryRegion":null,
"latitude":"123",
"longitude":"123",
"propertyTags":[ ],
"region":{
"name":"east",
"deleted":false
},
"site":false,
"propertyType":"UNIT",
"parent":null,
"buildingNumber":null,
"unitNumber":null,
"propertyUpdatedSequenceNumber":1,
"propertyUpdatedModelVersion":3,
"propertyUpdatedChangeSet":{
"typeInfo":"jsonPathChangeSet",
"changePaths":[
"$.address1",
"$.communities",
"$.lastUpdateTime",
"$.latitude",
"$.longitude",
"$.region"
]
}
}
Most of the messages produced by this API contain complex nested objects. Some of the messages share common objects which might seem redundant but are actually necessary. In this section all the common/shared objects are listed and described.
Field - Nullable - Type - Description - Version
Field - Nullable - Type - Description - Version
Field - Nullable - Type - Description - Version
Field - Nullable - Type - Description - Version
Sample ProductBundle object and all of it’s nested objects as JSON:
"productBundle":{
"startDate":"2008-12-19",
"endDate":"2008-12-19",
"referenceNumber":"CPR-00000017",
"communityProductBundleSpec":{
"community":{
"displayName":"Original",
"key":"original"
},
"productBundleSpec":{
"displayName":"We plumb for you ONCE!",
"referenceNumber":"P-0000050"
}
}
}
Field - Nullable - Type - Description - Version
*NOTE: The fields described in Table 2.4 are the base object representation of a Job. Certain messages extend this further, by providing additional information, or in some cases ignore fields which are redundant. For example the ORDER_CREATED message uses this a basis for it’s job descriptions, but ignores the field productBundleOrder.
Such details are described in the concrete message sections.
Sample Job object as JSON:
"job":{
"dueTime":"2016-11-02T18:00:00.000",
"activationTime":"2016-10-30T18:00:00.000",
"description":null,
"status":"NEW",
"subCategory":"PLANNED",
"summary":"Job Template",
"externalReferenceNumber":null,
"referenceNumber":"JOB-00000144",
“productBundleOrder”:{…}
}
Field - Nullable - Type - Description
Sample Account object, with the nested Communities list as JSON:
“account":{
"communities":[
{
"displayName":"Original",
"key":"original"
}
],
"accountNumber":"00000026",
"externalAccountIdentifier":"01234574",
"accountName":"Philip Fry"
}
Field - Nullable - Type - Description - Version
A sample Property object JSON:
"property":{
"propertyType":"BUILDING",
"referenceNumber":"PP-00000017",
"externalReferenceNumber":"PP-10000019",
"displayName":"Zoidbergia Property",
"latitude":"10.019191",
"longitude":"11.290292",
"region":"auckland"
}
Field - Nullable - Type - Description - Version
A sample QuotedItem object JSON:
"quotedItem":{
"identifier":"17",
"description":"quoted item"
}
Field - Nullable - Type - Description - Version
Sample Money object JSON:
“amountRemaining”: {
"currencyCode":"AUD",
“value":232.00
}
Field - Nullable - Type - Description - Version
Sample Comment object JSON:
“comment”: {
"updateTime":"2016-11-02T18:00:00.000",
“updater":{...},
"comment":"Here is a comment"
}
Field - Nullable - Type - Description - Version
Sample Attachment object JSON:
“attachment”: {
"reference":"00000001",
“type":"QUOTATION
}
Field - Nullable - Type - Description - Version
An example Address JSON:
"billingAddress":{
"line1":"",
"line2":"",
"buildingName":null,
"city":null,
"state":null,
"postcode":null,
"country":""
}
Field - Nullable - Type - Description - Version
"contactDetails":{
"email":"t1111est@abv.bg",
"primaryPhone":"1111111132413ffff",
"normalisedPrimaryPhone":"1111111132413ffff",
"otherPhone":"11111111f",
"normalisedOtherPhone":"11111111f",
"mobileNumber":null,
"mobileCountryCode":null,
"mobileCountryCallingCode":null,
"residentialAddress":{...}
}
Field - Nullable - Type - Description - Version
"region":{
"name":"AU-WEST",
"deleted":"false"
}
Field - Nullable - Type - Description - Version
"tag":{
"identifier":"1",
"tag":"PROP-1"
}
This section describes the various enumerations shared by the messages in the above sections.
Property Type - Description - Version
Status Type - Description - Version
Subcategory Type - Description - Version
Account Status - Description - Version
Property Type - Description - Version
Appointment State - Description - Version