Summary
The Echo Veolia API integration product provides a way to easily configure, and invoke, various API methods provided by the Echo Veolia API. These are predominantly focused on various waste based systems, with common calls into the API made to find details of a provided address, which services may be applicable to that address, and to create events for services against the address.
Both SOAP and JSON request types are supported and can be toggled on and off globally, or per request, to ensure older versions of the API remain supported without the need for manual modification of parameters.
Notification elements coming back from Echo are not currently supported but are in the pipeline for a future release.
Configuration
Setup
Configuration of the Echo Veolia Integration is handled via the getConfig pattern used across various products.
You should copy the provided example getConfig end point,
Settings
The return schema details what settings are supported/available:
"wsdlUrl" should map directly to the service's singleWsdl URL, for example "https://int.veolia.echoweb.co.uk/api/v1/service.svc?singleWsdl".
"apiUrl" should map to the general path to the v1 API such as: "https://int.veolia.echoweb.co.uk/api/v1/".
"useSoap" is a boolean denoting whether all requests should enforce the SOAP based mechanisms if an older version of the API is in use. If this isn't set then this can also be set per request, else it will default to JSON based requests.
"echoUsername" should contain the username that the service will authenticate requests with.
"echoPassword" should contain the password that the service will authenticate requests with.
"requestOptions" is a generic object that will be used as part of the requests made to the API via the request node library. It is highly recommended that you set the "timeout" property to something sensible.
Additionally, you can provide any other settings as required by any extensions you may make outside of the product, as additional properties are allowed, but we would advise caution as you could expose the username and password for the service if you are not careful.
Endpoint Overview
There are numerous End Points that make up the Echo Veolia integration:
These can be broken down into two categories:
1) Utilities
The sub-category you can see in the image above, is the utilities category. These are critical to the function of the Echo Veolia integration and should never be invoked directly by anything other than the Integration Points.
Here is a summary of what each internal utility End Point does:
requestHandler - The request handler is the shared endpoint that all integration endpoints call into. No single integration point endpoint makes their own request, they simply construct the relevant payload, and method parameter, for their purpose to help ensure a single point of maintenance if any outgoing changes are required in the future.
responseHandler - Similarly, the response handler deals with converting and shaping the resulting response from the API, or if a failure state is hit, so we can modify and maintain a single endpoint if the need arises without impacting other elements. The response handler mutates the resulting response from the API into a unified shape that each Integration Point endpoint will know how to handle.
soapConverter - If the useSOAP configuration property is set to true, or if the useSoap parameter has been specified to the Integration Point, then the soapConverter endpoint comes into play. This provides a number of utility methods to convert common JSON patterns into valid SOAP patterns for the service. This is required as a number of types have been defined within the Echo Veolia WSDL that need explicit mapping to avoid ambiguity, alongside the usual nested object types that interchange based on both the type, and number, of results found. What this helps the product achieve is the ability to support a more simple JSON based input and output schema regardless of the actual technology involved within the API itself.
soapRequestHandler - Similarly, the requestHandler would require a sizable amount of modification to also support the SOAP based request structure so these have been de-coupled. The soapRequestHandler takes the provided params from each integration point and constructs the required strong-soap action request to the Echo Veolia service using the converted data. This returns the raw SOAP response back to the caller ready for them to modify the data back into the JSON format using the SOAP to JSON methods within the soapConverter.
2) Integration Points
Each Integration Endpoint maps directly to a documented API method, with the same name, within Echo. These have request and response schemas, where feasible. There is a caveat that some areas have not been used as part of the initial development so no test data was made available. These will be highlighted within their corresponding article.
See Endpoints for an in depth look at some of the individual Endpoints.
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": [{"data" is an array of extensible datums which follow the following pattern:
"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"
}],
"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".
Additional Response data
As with many external services, there can be concerns regarding response times which is why a fixed max timeout is set. In Echo Veolia's case, we are also adding additional overhead by converting the request and response elements to and from SOAP/XML, when the appropriate setting or parameter is set. To help transparency, each integration Endpoint tracks the time taken to convert as well as the time taken for the service to respond. This data is returned as part of any request into the integration.
Note - This is a particularly large search query made by the GetEventsForObject Endpoint with unflattering parameters given and is not indicative of normal speeds but helps demonstrate the differing times being displayed.
Request:
{
"objectRef": {
"type": "PointAddress",
"value": [6599297],
"key": "Id"
},
"debug": false,
"query": {
"from": "1970-01-01T00:00:00.000+01:00"
}
}
Response - Data removed
{
"success": true,
"technology": "SOAP",
"apiTime": 4303,
"totalTime": 4460
}
"success" <boolean> - This is a standard boolean to notify the consumer as to whether we consider the request "successful", if not there will be an errors array with further details.
"technology" <string> - This will either be SOAP or JSON.
"apiTime" <number> - The time, in milliseconds, it took to query the service and receive its response.
"totalTime" <number> - The total time, in milliseconds, it took to complete all aspects of the query. This will include converting to and from a SOAP schema if set.
From the above example we can see that it took 4.3 seconds to retrieve a large data set from the service and ~150ms to convert the request and response data into the JSON schema we expect. This is one of the largest and most expensive of the available Integration Points, data wise, but these metrics can be useful when the service is under load to determine if the GOSS integration aspects are being ill-performant or if the service is struggling.
Share this page
