Waiting for engine...
Skip to main content

Environment Map Extension object

The Environment Map Extensions object represents the extensible data map configuration for a deployed process.

Data map extensions allow you to override or augment default field mappings and profile elements for a given pair of object definitions. Map extensions are typically used with integration packs. It is common for an integration pack developer to configure a default set of field mappings for a given integration, but then allow extension of the map. This enables each consumer of that integration pack to customize and augment the field mappings to meet their specific requirements. Additionally, in some cases, consumers can customize the source and destination profiles to incorporate custom fields that exist in their endpoint applications. For more information, refer to the topic Data map extensions.

Integration pack developers typically use the Environment Map Extension object to present the mapping configuration to their end users through a custom user interface. In some situations, developers can customize the source and destination profile fields to include the end user's own custom fields. See the Customizing profiles section later in this topic.

The Environment Map Extension object operates with a single map ID. Use the Environment Map Extensions Summary object to query the list of available map extensions for the given environment.

Structure​

<EnvironmentMapExtension name="" mapId="" processId="" id="" extensionGroupId="" environmentId="">
  <Map> {Optional}
    <SourceProfile componentId="" type="">
      ... 0 to n Node elements
      <Node name="" xpath=""/> {Optional}
    </SourceProfile>
    <DestinationProfile componentId="" type="">
      ... 0 to n Node elements
      <Node name="" xpath=""/> {Optional}
    </DestinationProfile>
    <ExtendedFunctions>
      ... 0 to n Function elements
      <Function cacheType="" id="" type=""> {Optional}
        <Inputs>
          ... 0 to n Input elements
          <Input default="" name="" key=""/> {Optional}
        </Inputs>
        <Outputs>
          ... 0 to n Output elements
          <Output name="" key=""/> {Optional}
        </Outputs>
        <Configuration>
          <Scripting language=""> {Optional, @language is either GROOVY (Groovy v1.5), GROOVY2 (Groovy v2.4), or Javascript}
            <Script/>
            <Inputs>
              ... 0 to n Input elements
              <Input dataType="" name="" index=""/> {Optional}
            </Inputs>
            <Outputs>
              ... 0 to n Output elements
              <Output dataType="" name="" index=""/> {Optional}
            </Outputs>
          </Scripting>
          <StringConcat delimiter="" fixedLength=""/> {Optional}
          <StringSplit delimiter="" splitLength=""/> {Optional}
          <SequentialValue keyName="" batchSize="" keyFixToLength=""/> {Optional}
          <SimpleLookup> {Optional}
            <Table>
              <Rows>
                ... 0 to n Row elements
                <Row> {Optional}
                  <ref1/> {Optional}
                  <ref2/> {Optional}
                </Row>
              </Rows>
            </Table>
          </SimpleLookup>
          <DocumentProperty defaultValue="" propertyId="" propertyName="" persist=""/> {Optional}
        </Configuration> 
      </Function>
    </ExtendedFunctions>
    <ExtendedMappings>
      ... 0 to n Mapping elements
      <Mapping toXPath="" fromXPath="" toFunction="" fromFunction=""/> {Optional}
    </ExtendedMappings>
 <BrowseSettings containerId="">
   <SourceBrowse sessionId="">
     <BrowseFields name="" value=""/>
      ... 0 to n BrowseFields elements
   </SourceBrowse>
   <DestinationBrowse sessionId="">
     <BrowseFields name="" value=""/>
      ... 0 to n BrowseFields elements
   </DestinationBrowse>
 </BrowseSettings>
    <SourceProfileExtensions>  
       <Node name="" mandatory="" enforceUnique="" fieldLengthValidation="" minLength="" maxLength=""> 
         ... 0 to n Node elements
         <Character/>
         <DateTime format=""/>
         <Number format="" signed="" impliedDecimal=""/>
       </Node>
    </SourceProfileExtensions>
    <DestinationProfileExtensions>  
       <Node name="" mandatory="" enforceUnique="" fieldLengthValidation="" minLength="" maxLength=""> 
         ... 0 to n Node elements
         <Character/>
         <DateTime format=""/>
         <Number format="" signed="" impliedDecimal=""/>
       </Node>
    </DestinationProfileExtensions>
  </Map>
</EnvironmentMapExtension>
FieldTypeDescription
namestringThe name of the extensible map. This variable includes the source object definition name and the destination object definition name, separated by a hyphen.
mapIdstringThe ID of the extensible map.
processIdstringThe ID of the process.
idstringThe ID of the object. This is a conceptual ID synthesized from the IDs of the Map, Process, Multi-install integration pack (extensionGroupId), and, if applicable Environment. After obtaining this value with a QUERY operation on the Environment Map Extensions Summary object, you can retrieve or update the extensible map by specifying the ID in a GET or UPDATE operation on this object.
extensionGroupIdstringThe ID of the multi-install integration pack to which the extensible map applies, if applicable.
environmentIdstringThe ID of the environment.
SourceProfileRepresents the fields in a source profile of the given map, and specifies the section of the map in which to extend. Note: You cannot add or create new fields in the object's request body. You must add new fields in the user interface of the underlying Map component or from a dynamic reimport. See the Customizing profiles section later in this topic.
The following SourceProfile attributes define fields in the source profile:
- componentId - represents the object definition extension ID. A GET request returns this value.
- name - the user-defined field label(s) found in the source profile.
- xpath - represents the field location in the source profile hierarchy.
DestinationProfileRepresents the fields in a destination profile of the given map, and specifies the section of the map in which to extend. Note: You cannot add or create new fields in the object's request body. You must add new fields in the user interface of the underlying Map component or from a dynamic reimport. See the Customizing profiles section later in this topic.
The following DestinationProfile attributes define fields in the destination profile:
- componentId - represents the object definition extension ID. A GET request returns this value.
- name - the user-defined field label(s) found in the destination profile.
- xpath - represents the field location in the destination profile hierarchy.
ExtendedFunctionsThe definition of Map function steps used in the Map component. For detailed information about how to define Map functions in a request or response, refer to the topic Environment Map Extension functions. You can us the Extended Functions attribute to define the following extensible map functions (supports standard and user-defined function types):
- User Defined
- Connector
- Lookup
- Date
- Numeric
- String
- Custom Scripting
- Property
ExtendedMappingsRepresents the field mappings between profiles, functions or both. You can use the following attributes:
- fromXPath - represents the source profile's field path or the function's output key from which you are mapping.
- toXPath- represents the destination profile's field path or the function's input key to which you are mapping.
- toFunction - represents the function ID from which you are mapping.
- fromFunction - represents the function ID to which you are mapping.
To properly define each of these attributes, see the section How to configure ExtendedMappings later in this topic.
BrowseSettingsRepresents the Connection information and is used to re-import newly-appended profile fields. This attribute is only applicable for certain application Connectors. To perform a re-import, the client must use the EXECUTE operation. For more information, see the Customizing profiles section later in this topic. Note: 'containerId' is a required field when using BrowseSettings.
SourceProfileExtensionsContains the user-defined custom fields for the source profile. Applicable only to Flat File profiles. Represents the field and value configuration settings manually specified in the source profile's Data Element tab. For more information, see the Customizing profiles section later in this topic.
DestinationProfileExtensionsContains the user-defined custom fields for the destination profile. Applicable only to Flat File profiles. Represents the field and value configuration settings manually specified in the destination profile's Data Element tab. For more information, see the Customizing profiles section later in this topic.

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.

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 XML profiles by reimporting the object to retrieve the object's definition from an application endpoint, similar to configuring a connector operation component. This option only applies if you associate the XML profile with a connector that enables object browsing and importing.

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>

Supported operations​

GETQUERYCREATEUPDATEEXECUTEDELETE
SupportedNot supportedNot supportedSupportedSupportedNot supported

Using the GET operation​

The ordinary GET operation retrieves an extensible map by its Environment Map Extension object ID. The bulk GET operation retrieves extensible maps by their Environment Map Extension object IDs, to a maximum of 100.

note

Extending a source or destination profile by means of browsing an external account may require including credentials in the request. The GET operation uses the credentials from the original process for the browse connection. However, because credential reuse can be problematic when sharing processes in Integration Packs, use the EXECUTE operation instead.

Using the UPDATE operation​

The UPDATE operation updates the extended mapping configuration for the specified Environment Map Extension object ID. Mapping overrides specified in UPDATE operations are subject to the same limitations applicable to extending maps in the UI.

caution

When performing an update, you must include all extensible map fields and functions in the request, otherwise it removes any omitted field or function. To prevent the removal of mappings and functions, include in the request all mappings and functions as returned by a GET operation, including those you are not changing. This caution does not apply to profiles — updates do not includedsource, destination, and profile extensions.

You must have the Runtime Management privilege to perform the UPDATE operation. If you have the Runtime Management Read Access privilege, you cannot update extensible maps.

For information about using these operations to retrieve or update map functions, refer to the topic Environment Map Extension functions.

Using the EXECUTE operation​

Use the EXECUTE operation when you want to customize XML profiles by reimporting them from endpoint applications. The EXECUTE operation returns the current Environment Map Extension configuration similar to the GET operation. It also accepts connection credentials and automatically connects to the external application to retrieve additional custom fields for that profile.

You must have the Runtime Management privilege to perform the EXECUTE operation. If you have the Runtime Management Read Access privilege, you cannot post connection credentials.

For information about using these operations to retrieve or update map functions, refer to the topic Environment Map Extension functions.

SOAP implementation​

GET operation

Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.platform.boomi.com/">
   <soapenv:Header>
      <wsse:Security
       xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
        <wsse:UsernameToken wsu:Id="UsernameToken" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
          <wsse:Username>ATOMSPHERE_USER_NAME</wsse:Username>
          <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">ATOMSPHERE_PASSWORD</wsse:Password>
        </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <api:get>
         <api:objectType>EnvironmentMapExtension</api:objectType>
         <api:objectId>Ab0Cd1Ef1Gh3Ij4Kl5Mn6Op7Qr8St9Uv0Wx9Yz8Zy7Xw6Vu5Ts4Rq3Po2Nm1Lk0Ji1Hg</api:objectId>
      </api:get>
   </soapenv:Body>
</soapenv:Envelope>

Response:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <bns:getResponse xmlns:bns="http://api.platform.boomi.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <bns:result xsi:type="bns:EnvironmentMapExtension" name="Account - Customer" 
           mapId="01234567890123456789012345" processId="789abcde-f012-3456-789a-bcdef0123456" 
           id="Ab0Cd1Ef1Gh3Ij4Kl5Mn6Op7Qr8St9Uv0Wx9Yz8Zy7Xw6Vu5Ts4Rq3Po2Nm1Lk0Ji1Hg" 
           extensionGroupId="" environmentId="456789ab-cdef-0123-4567-89abcdef0123">
            <bns:Map>
               <bns:SourceProfile componentId="ef012345-6789-abcd-ef01-23456789abcd">
                  <bns:Node xpath="" name="Account"/>
                  <bns:Node xpath="/CustomerNum" name="CustomerNum"/>
                  <bns:Node xpath="/CustomerName" name="CustomerName"/>
                  <bns:Node xpath="/Website" name="Website"/>
                  <bns:Node xpath="/StreetAddress1" name="StreetAddress1"/>
                  <bns:Node xpath="/StreetAddress2" name="StreetAddress2"/>
                  <bns:Node xpath="/City" name="City"/>
                  <bns:Node xpath="/State" name="State"/>
                  <bns:Node xpath="/Zip" name="Zip"/>
                  <bns:Node xpath="/Country" name="Country"/>
                  <bns:Node xpath="/Phone" name="Phone"/>
               </bns:SourceProfile>
               <bns:DestinationProfile componentId="dcba9876-5432-10fe-dcba-9876543210fe">
                  <bns:Node xpath="" name="CustomerAddRq"/>
                  <bns:Node xpath="/CustomerAdd" name="CustomerAdd"/>
                  <bns:Node xpath="/CustomerAdd/Name" name="Name"/>
                  <bns:Node xpath="/CustomerAdd/IsActive" name="IsActive"/>
                  <bns:Node xpath="/CustomerAdd/ParentRef" name="ParentRef"/>
                  <bns:Node xpath="/CustomerAdd/ParentRef/ListID" name="ListID"/>
                  <bns:Node xpath="/CustomerAdd/ParentRef/FullName" name="FullName"/>
                  <bns:Node xpath="/CustomerAdd/CompanyName" name="CompanyName"/>
                  <bns:Node xpath="/CustomerAdd/Salutation" name="Salutation"/>
                  <bns:Node xpath="/CustomerAdd/FirstName" name="FirstName"/>
                  <bns:Node xpath="/CustomerAdd/MiddleName" name="MiddleName"/>
                  <bns:Node xpath="/CustomerAdd/LastName" name="LastName"/>
                  <bns:Node xpath="/CustomerAdd/Suffix" name="Suffix"/>
                  <bns:Node xpath="/CustomerAdd/BillAddress" name="BillAddress"/>
                  <bns:Node xpath="/CustomerAdd/BillAddress/Addr1" name="Addr1"/>
                  <bns:Node xpath="/CustomerAdd/BillAddress/Addr2" name="Addr2"/>
                  <bns:Node xpath="/CustomerAdd/BillAddress/City"  name="City"/>
                  <bns:Node xpath="/CustomerAdd/BillAddress/State" name="State"/>
                  <bns:Node xpath="/CustomerAdd/BillAddress/PostalCode" name="PostalCode"/>
                  <bns:Node xpath="/CustomerAdd/BillAddress/Country" name="Country"/>
                  <bns:Node xpath="/CustomerAdd/BillAddress/Note" name="Note"/>
                  <bns:Node xpath="/CustomerAdd/ShipAddress" name="ShipAddress"/>
                  <bns:Node xpath="/CustomerAdd/ShipAddress/Addr1" name="Addr1"/>
                  <bns:Node xpath="/CustomerAdd/ShipAddress/Addr2" name="Addr2"/>
                  <bns:Node xpath="/CustomerAdd/ShipAddress/City"  name="City"/>
                  <bns:Node xpath="/CustomerAdd/ShipAddress/State" name="State"/>
                  <bns:Node xpath="/CustomerAdd/ShipAddress/PostalCode" name="PostalCode"/>
                  <bns:Node xpath="/CustomerAdd/ShipAddress/Country" name="Country"/>
                  <bns:Node xpath="/CustomerAdd/ShipAddress/Note" name="Note"/>
                  <bns:Node xpath="/CustomerAdd/Phone" name="Phone"/>
                  <bns:Node xpath="/CustomerAdd/Mobile" name="Mobile"/>
                  <bns:Node xpath="/CustomerAdd/Email" name="Email"/>
                  <bns:Node xpath="/CustomerAdd/Contact" name="Contact"/>
               </bns:DestinationProfile>
               <bns:ExtendedFunctions>
                  <bns:Function type="StringAppend" id="FUNCEXT--012345678" cacheType="ByDocument">
                     <bns:Inputs>
                        <bns:Input key="1" name="Original String" default=""/>
                        <bns:Input key="2" name="Fix to Length" default=""/>
                        <bns:Input key="3" name="Char to Append" default="-9999"/>
                     </bns:Inputs>
                     <bns:Outputs>
                        <bns:Output key="1" name="Result"/>
                     </bns:Outputs>
                     <bns:Configuration/>
                  </bns:Function>
               </bns:ExtendedFunctions>
               <bns:ExtendedMappings>
                  <bns:Mapping fromXPath="/StreetAddress1" toXPath="/CustomerAdd/ShipAddress/Addr1"/>
                  <bns:Mapping fromXPath="/StreetAddress2" toXPath="/CustomerAdd/ShipAddress/Addr2"/>
                  <bns:Mapping fromXPath="/Zip" toXPath="/CustomerAdd/ShipAddress/PostalCode"/>
                  <bns:Mapping toFunction="FUNCEXT--012345678" fromXPath="/Zip" toXPath="1"/>
                  <bns:Mapping fromFunction="FUNCEXT--012345678" fromXPath="1" toXPath="/CustomerAdd/ShipAddress/PostalCode"/>
               </bns:ExtendedMappings>
               <bns:SourceProfileExtensions>
                  <bns:Node xpath="" name="Account">
                    <bns:Character/>
                  </bns:Node> 
                  <bns:Node xpath="/CustomerNum" name="CustomerNum">
                    <bns:Character/>
                  </bns:Node> 
                  <bns:Node xpath="/CustomerName" name="CustomerName">
                    <bns:Character/>
                  </bns:Node> 
                  <bns:Node xpath="/StreetAddress1" name="StreetAddress1">
                    <bns:Character/>
                  </bns:Node> 
                  <bns:Node xpath="/StreetAddress2" name="StreetAddress2">
                    <bns:Character/>
                  </bns:Node> 
                  <bns:Node xpath="/City" name="City">
                    <bns:Character/>
                  </bns:Node> 
                  <bns:Node xpath="/State" name="State">
                    <bns:Character/>
                  </bns:Node> 
                  <bns:Node xpath="/Zip" name="Zip">
                    <bns:Character/>
                  </bns:Node> 
               </bns:SourceProfileExtensions>
               <bns:DestinationProfileExtensions/>
            </bns:Map>
         </bns:result>
      </bns:getResponse>
   </S:Body>
</S:Envelope>
On this Page