Toggle menu

Echo Veolia Integration

Common Data Patterns

The Echo Veolia API defines a number of common data structures that are utilised within both requests and responses. These are documented within the Endpoint schemas but it is recommended that these are understood to help write and consume these patterns as needed.

Object Ref

An "Object Ref" is a basic data structure defined with the WSDL document of the Echo API. It looks like the following:

{
    "ref": {
        "type": "PointAddress",
        "value": [5582537],
        "key": "Id"
    }
}

In the above example "ref" is an instance of an Object Ref and these always contain the following properties:

"type" <string> - The Type is used to denote what this object reference is referencing. In the above example I am asking for a "PointAddress" type which is an internal data type to the Echo Veolia API.

"key" <string> - The Key is used to specify what the value property is referencing. These can differ based on the type property, the above example shows I am asking for a Point Address with a specific Id.

"value" <array> - The Value array is used to tell the API what identifier you want to retrieve. The above example shows I'm asking for a number which is the Id of a PointAddress object. Other examples could be a single string value within the array with the key of "Guid". There are multi-part identifiers as well, such as "Handle" for Tasks .

Extensible Datum Type

An "Extensible Datum type" is a data pattern that allows for recursive common objects to be defined which match Extensible Data types which are denoted within the Echo API document. Here is a snippet from the PostEvent Endpoint document which shows the pattern.

 "data": [{
            "childData": [],
            "datatypeId": "41810",
            "value": "Luke"
        }, {
            "childData": [],
            "datatypeId": "41811",
            "value": "Taylor"
        }, {
            "childData": [{
                "childData": [],
                "datatypeId": "41828",
                "value": "24"
            }, {
                "childData": [],
                "datatypeId": "41831",
                "value": "An abandoned microwave"
            }, {
                "childData": [],
                "datatypeId": "41829",
                "value": "1"
            }],
            "datatypeId": "41827",
            "value": "Microwave"
        }, {
            "childData": [],
            "datatypeId": "41813",
            "value": "luke.taylor@email.com"
        }, {
            "childData": [],
            "datatypeId": "41839",
            "value": "50.00"
        }],
"data" is an array of extensible datums which follow the following pattern:

"datattypeId" <string> - This is the identifier telling the Echo system what this abstract data actually matches. These are dictated by the environment setup, but an example above is the id "41810" which is the "Forename" data type id. This lets the system know what the values context is.

"value" <string> - This is the actual value that you wish to map to the datatypeId into the system. The pattern of this entirely depends on the data type this is being mapped to which is setup within the system per service.

"childData" <array> - This is an array of extensible datums which lets you set sub-category data where applicable. The above example shows a Bulky Waste request where I've asked for a Microwave to be picked up, there is only 1 of them, it has the description of "An abandoned microwave" and the identifier of that item type within the system is "24".

Last modified on February 24, 2021

Share this page

Facebook icon Twitter icon email icon

Print

print icon