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 the type and defaultValue. 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 or Leaf.
- The first element is always Node <name>root</name> <type>object</type>.
- Node type is always object or array.
- If Node is of the array 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 the metadataUri 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 and array 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 Documentation

Mapper Configurations

Options

Limitations

Sample Configuration

How to Write Transformer Function

Definition

Rules

Examples

Simple Transformer Function

Complex Transformer Function

Examples

Simple (Flat) Metadata Example

Complex Metadata