Mapper Configurations
These configurations are used for mapping system structures into another system structure.
Options
There are several types of configuration depending on the target system possibilities: Does the target system have metadata? Do the metadata change? Does the metadata definition contain nested objects?
Static configuration – You provide a fully defined system configuration within the
<metadata>
tag. All fields, types, defaultValues etc. are filled in statically. No metadata call is done by IntegrationManager. This method is useful when the system does not provide metadata, but you want to capture the definition.Semi-static configuration – You provide a fields structure within the
<metadata>
tag and<metadataUri>
definition followed by<typeJsonPath>
and<defaultValueJsonPath>
definitions. IntegrationManager will reach the defined URI, read the structure and parse thetype
anddefaultValue
. This is useful for systems with metadata where you want to have only a subset of elements in your configuration.Auto configuration – You do not provide the
<metadata>
tag. Instead, you provide the<metadataUri>
and<transformer>
definitions. To do that, please refer to the How to write transformer function chapter below. This is useful when you want to have full control over the metadata representation.
Limitations
Currently, only the
JSON
content type is supported.<metadata>
element must be well formatted while keeping certain rules:It represents a tree structure, each element is either
Node
orLeaf
.The first element is always
Node
<name>root</name>
<type>object</type>
.Node
type is alwaysobject
orarray
.If
Node
is of thearray
type, its<items>
must have only one<item>
(heterogenous arrays are not supported).
References are not followed in types (you must implement it in
transformer
).You must adhere to given schema:
Sample Configuration
The following excerpt defines a valid configuration. Please read the inline comments.
<mapper>
<name>opportunity-3-fields</name> <!-- Name of the configuration to appear in PM -->
<contentType>JSON</contentType> <!-- Content type of the response. Currently only JSON is supported -->
<uri>/api/v40/Opportunity</uri> <!-- URI with real data -->
<connections> <!-- List of usable connections for this configuration. Name of the connection must adhere to IM class -->
<connection>net.pricefx.integration.component.rest.domain.connection.OAuth2Connection</connection>
</connections>
<metadata> <!-- The definition how to parse the metadata statically -->
<className>net.pricefx.integration.api.ConnectionMetadataNode</className>
<name>root</name> <!-- First element must always be 'root' -->
<type>object</type> <!-- The type of first element must always be 'object' -->
<items> <!-- The representation of data in IM language. Must be acyclic graph -->
<item>
<className>net.pricefx.integration.api.ConnectionMetadataLeaf</className>
<name>Id</name>
<type>String</type>
</item>
<item>
<className>net.pricefx.integration.api.ConnectionMetadataLeaf</className>
<defaultValue>unnamed</defaultValue>
<name>Name</name>
<type>String</type>
</item>
<item>
<className>net.pricefx.integration.api.ConnectionMetadataLeaf</className>
<format>yyyy-MM-dd-HH-mm-ss</format>
<name>Created</name>
<type>Date</type>
</item>
<item>
<className>net.pricefx.integration.api.ConnectionMetadataNode</className>
<items>
<item>
<className>net.pricefx.integration.api.ConnectionMetadataLeaf</className>
<name>Id</name>
<type>String</type>
</item>
<item>
<className>net.pricefx.integration.api.ConnectionMetadataLeaf</className>
<defaultValue>unnamed</defaultValue>
<name>Name</name>
<type>String</type>
</item>
</items>
<name>items</name>
<type>object</type>
</item>
</items>
</metadata>
</mapper>
How to Write Transformer Function
The transformer function is a recipe how to extract metadata fields from an external system.
Definition
The Transformer function is part of configuration and resides in the <transformer>
element. The definition is:
<transformer>
<language>groovy</language>
<script> <!-- Here goes the script definition--> </script>
</transformer>
The language
tag resolves to one of known languages in Camel. Currently, supported languages are simple
, constant
, groovy
. You can read more about these languages in the official Camel languages documentation. The recommended language to use is groovy
.
In the script
tag, you must provide a valid script code. The script is subject to the Groovy Sandbox limitations.
Rules
These are the rules which are enforced in the script
tag:
Variable
body
is available. It bears the payload from the metadata call converted to a Java object (List or Tree, depending on themetadataUri
response).You must return a response.
The response structure must return a valid tree structure with limitations imposed by the
<metadata>
tag.
Examples
Simple Transformer Function
def res = [root: [:]]
body.fields.each { res['root'][it.name] = ['name': it.name, 'defaultValue': it.defaultValue, 'type': it.type] }
return res
Note:
Variable
body
is used.Valid tree structure is returned.
Example just maps a flat structure in metadata JSON.
Complex Transformer Function
Note:
There is a custom logic that iterates via elements to handle the
object
type andarray
type on 2nd/3rd levels.You might create your own methods to handle recursions (not covered in the example).
You might want to implement your own logic to follow the
reference
type.
Examples
Simple (Flat) Metadata Example
The following example shows how to handle a flat structure of fields (no references, arrays, lists, …).
Metadata:
This is an excerpt from Salesforce v48 sobject Opportunity. Note that all fields are 1st level citizens (no nested objects, arrays).
Transformer definition:
The definition utilizes an input property called body
which bears a read JSON response from REST fetch of metadata.
Result:
Complex Metadata
The following example is fabricated from the previous example by adding some complex structures (nested objects, arrays of objects) into the system metadata definition to provide better understanding how to write the transformer.
Metadata:
Note that the fields Tags
and Friend
are nested objects. 3rd and 4th field are nested – there is an object inside the array and vice versa.
Transformer:
This transformer is used solely for demonstration. It does not implement any real system.
Result:
IntegrationManager version 5.8.0