Waiting for engine...
Skip to main content

Customizing profiles for an Environment Map Extension object

Customizing profiles​

In addition to augmenting the data map extension's default field mappings, it is possible in some situations to augment the source and destination profiles themselves to add custom fields. You can add additional fields to XML profiles by browsing the object definition from an endpoint application, or to Flat File profiles by manually appending fields to the default set of elements.

Customizing profiles is most applicable for integration pack use cases, in which the integration pack consumer wants to incorporate custom fields from their specific application instances or data files beyond the default fields defined by the integration pack publisher.

XML Profile Customization and Browsing​

You can add custom fields for Flat File profiles by manually appending them to the default set of elements. You define the custom fields for the source and destination profile in the <SourceProfileExtensions> or <DestinationProfileExtensions> sections of the object, respectively. Custom fields can be of type Character, Number, or Date/Time and the configuration options correspond to their respective Flat File profile Data Element.

note

More specifically, you can browse a profile only if you include it in one of the Object Definition Extensions in the Data Map Extension. Also, the reference must be in a Connector Operation of a browsable Connector within the process.

Reimporting the XML profiles typically involves connecting to an external service using a connection. That connection usually requires you to provide values for any encrypted fields, such as passwords or other tokens. To obtain the necessary field names and corresponding connection IDs associated with either the source and destination profiles, use the Environment Map Extensions Summary object.

To start reimporting, use the Environment Map Extension object's EXECUTE action instead of the GET action. In the EXECUTE request, you provide required details to perform browsing, including:

  • containerId (required) on which to perform the reimport. This container can be a local runtime or an attachment to a cloud runtime including the Runtime cloud but must have connectivity access to the target application instance.

  • Encrypted connection fields and values, such as a password, for the connection associated with the source and destination profile. You must provide encrypted values here because the does not store encrypted values. Review the specific connector for applicable encrypted fields and their API names. You can obtain these fields using the Environment Map Extensions Summary object.

After importing, any available custom fields are included automatically in the <SourceProfile> or <DestinationProfile> section of the EXECUTE action's response. You can reference these in the mapping.

tip

The EXECUTE response also includes a sessionId token for the source and destination browse. If you need to call the EXECUTE action repeatedly for the same map, you can alternatively use the sessionId to avoid having to supply the encrypted connection fields in subsequent calls. The platform caches the sessions for about 30 minutes.

Flat File Profile Customization​

You can add custom fields for Flat File profiles by manually appending them to the default set of elements. You define the custom fields for the source and destination profile in the <SourceProfileExtensions> or <DestinationProfileExtensions> sections of the object, respectively. Custom fields can be of type Character, Number, or Date/Time and the configuration options correspond to their respective Flat File profile Data Element.

<bns:SourceProfileExtensions>
    <bns:Node name="my character field" mandatory="true" enforceUnique="false" fieldLengthValidation="true" minLength="1" maxLength="10">
        <bns:Character/>
    </bns:Node>
    <bns:Node name="my date field" mandatory="false" enforceUnique="false" fieldLengthValidation="false">
        <bns:DateTime format="yyyyMMdd HHmmss.SSS"/>
    </bns:Node>
    <bns:Node name="my number field" mandatory="false" enforceUnique="false" fieldLengthValidation="true" minLength="1" maxLength="4">
        <bns:Number format="#" signed="false" impliedDecimal="0"/>
    </bns:Node>
</bns:SourceProfileExtensions>

How to configure ExtendedMappings​

The ExtendedMappings attribute defines how to map between a source and destination profile, or how to map through a function between two profiles.

  • To extend mappings between profiles using the Environment Map Extension object, you must identify the fields in both the source and destination profiles that you want to map to and from. You can retrieve xpath values, which represent the field's location in the profile hierarchy, by first performing a GET operation and noting the xpath value returned in the SourceProfile and DestinationProfile attributes for use in a new request.

    The following UPDATE request example shows how you can use the Environment Map Extensions object to create a direct, extended mapping between fields titled "Street Address 1" and "Street Address 2" in the source and destination profiles:

    <bns:ExtendedMappings>
      <bns:Mapping fromXPath="Account/StreetAddress1" toXPath="/CustomerAdd/ShipAddress/Addr1"/>
      <bns:Mapping fromXPath="Account/StreetAddress2" toXPath="/CustomerAdd/ShipAddress/Addr2"/>
    </bns:ExtendedMappings>

    In this request, the fromXPath attribute represents the xpath of the source profile field from which to map. The toXPath attribute represents the xpath of the destination profile field to which to map.

  • To extend mappings through a function using the Environment Map Extension object, you define the mappings from the source profile to the function's inputs, and then from the function's outputs to the destination profile.

    A function's fields are uniquely identified by the function's ID and the key for the given input or output. Each function input and output has a numeric key attribute. For a given function, the first input or output has a key attribute value of 1, the second a key attribute value of 2, and so on. For functions with variable numbers of user-defined inputs or outputs such as String Split and Custom Scripting, key assignments can vary.

    For detailed information and a corresponding example about how to perform updates to a map function, see the section Extending map functions with the UPDATE operation in the topic Environment Map Extension functions and the section Using the UPDATE operation later in this topic.

On this Page