Map Data

Use the mapper to drag fields from the source structure to the target structure to map elements between the two.

See Map Data of Using the Oracle Mapper.

Access the Mapper

To create mappings in an integration, you need to first access the mapper. The method for accessing the mapper is based on the integration pattern you are using.

To create mappings in App Driven Orchestration integrations and Scheduled Orchestration integrations:

As you add triggers and invokes to an App Driven Orchestration integrations, a map icon is automatically added. You can also add ad-hoc mappings to this type of integration, such as adding a mapper to a switch action.

  1. Click an existing mapper icon or drag a mapper into your integration from the Actions panel to the appropriate location in your integration.

  2. Click Edit.
    View, Edit, and More Actions icons

    If you click the View icon, note the following details:
    • You cannot add or edit mappings.

    • You cannot validate mappings.

    • You cannot save or erase the XPath expression in the Expression Builder.

    • You cannot create or delete elements or mappings in the target context menus.

    • You cannot drag source element nodes to target element nodes.

    • You can view XSLT code and test your mappings.

  3. See Creating Integrations.

To create mappings in Basic Routing integrations:
  1. In the middle of the integration, click the Mapper icon for the request, response, or fault map to edit.
  2. Click Edit.
    Edit, View, and Delete icons

Modify Mappings

Once you create a mapping in an integration, you can return to the mapping and make any necessary changes to how you mapped your data. The integration in which you want to edit the mappings cannot be active.

To modify a data mapping:
  1. In the middle of the integration, click the Mapper icon for the request, response, or fault map to edit.
  2. Click Edit to invoke the mapper.
  3. Make appropriate updates to the mappings.
  4. When complete, click Close, then click Apply to save your changes.

See Mapping Data of Using the Oracle Mapper.

Delete All Mappings

You can delete all mappings in the mapper. This action deletes all source-to-target mappings in the mapper and all mapper statements created in the Mapping Builder.

  1. Click the Mapper icon in the middle of the integration for the map to delete. For this example, the request mapper is selected, but you can also delete all mappings in another mapper, such as the response mapper, or any request or response enrichment mapping you created.
  2. Click Delete.
  3. Click Yes when prompted to confirm.
    The green shading is removed from the mapper, indicating that the mapper is now empty.

    See Mapping Data of Using the Oracle Mapper.

Map Faults

You can map portions of a message into the fault message to compose a description that helps you understand the fault.

To map a fault:
  1. Click the Fault Mappings icon in an integration.

  2. For each fault type, do the following:
    1. Under Route To, select the type of fault.
    2. Under Map, click the Mapper icon of the fault map to perform mapping.

    The mapper appears with the source fault data structure on the left and the target fault data structure on the right. When returning from the mapper, the map icon changes color to indicate it is complete.
  3. Click Close .
  4. Return to the mapping to make any necessary changes to how you mapped your data.

    See Mapping Data of Using the Oracle Mapper.

Encode and Decode File Attachment Content

The virtual file system (VFS) enables you to store files and internally use references to these files in the message payload. You can also map the VFS file's content to a string element.

For example, you can store files and use references in the VFS as follows:
  • The REST Adapter supports the multipart attachment and application/octet-stream features. The attachment is stored in a staging area and an attachmentReference (string key) is generated. The attachmentReference key is sent as part of the message payload and later fetches the attachment instance from the staging area.

  • The FTP Adapter uses fileReference for reading/writing a file without a schema. fileReference is also a reference to a file stored in the VFS.

In addition, mapping the VFS file's content to a string element enables you to:
  • Map the content of a staged file attachment to a string element by converting the content to a base64 string.

  • Store the base64 string as an attachment and generate a VFS reference.

Two XPath functions are provided to perform these tasks. These functions work with any adapter.

  • encodeReferenceToBase64(String reference): Accepts the VFS’s file reference as input and returns the base64–encoded content of the file as the return value. This function has a file size limit of 10 MB. If a file is larger than 10 MB, an exception message of Maximum file size supported is 10 MB is displayed.

  • decodeBase64ToReference(String base64String): Accepts the base64–encoded content as input, decodes it, stores the base64–decoded value in a file in the VFS, and returns the reference to this file. There is no size limit because the content is already in memory.

The location is the relative path (reference) of the file stored in Oracle Integration. The relative path is one of the following elements:
  • fileReference

  • attachmentReference

  • streamReference

The two XPath functions are available for use in Oracle Integration:
  • Expression Builder, when configuring the following actions in an orchestrated integration:

    • Notification

    • Logging

    • Switch

    • Assign

  • Mapper (visible after selecting Mapping Components - Functions - Advanced):


    Description of encode_decode.png follows
    Description of the illustration encode_decode.png

The attachments are not restricted to document file types. For example, an image can be base64–encoded and later decoded back to the original file.

When an attachment is stored in the VFS, a key is generated to retrieve the attachment at a later time. The key is shown in the mapper as attachmentReference/fileReference/streamReference. This key is propagated within Oracle Integration as part of the payload. The attachment is claimed only when needed. The names attachmentReference, fileReference, and streamReference are based on the adapter type. For example, in the REST Adapter, streamReference is used. The data type of the reference is a string.

With a multipart feature, the HTTP request payload has multiple parts separated by boundaries. Each of the individual parts are considered an attachment. For raw bytes, streamReference is used. FTP uses fileReference.

Sometimes the endpoints accept only base64–encoded values. In these cases, the reference is passed as input to encodeReferenceToBase64 to get the base64–encoded content of the file. Again, the base64–encoded value can be passed as input to decodeBase64ToReference to get the reference (location) to a file that contains the decoded content.

Add Customized Mappings to Prebuilt Integrations

It is a common practice to customize the application endpoints of the prebuilt integrations that you import into Oracle Integration from the Oracle Marketplace (for example, adding custom fields). As a result, you must customize the integration mappings to take advantage of these custom fields. Oracle Integration enables you to customize the mappings in the prebuilt integrations that you import from the Oracle Marketplace. This action creates a customized mapping layer on top of the base mapping file, which is not modified. You can only add customized mappings to prebuilt integrations imported from the Oracle Marketplace, and not to integrations you or another user created.

To add customized mappings to prebuilt integrations:
  1. In the navigation pane, click Integrations.
  2. Locate the name of the prebuilt integration to customize. Prebuilt integrations are designated with the words BUILT BY ORACLE to the right of the integration name.
  3. From the menu at the far right of the integration name, select Customize.
    The message Customizing... is displayed above the integration.

    If the existence of more than one customized version of the same prebuilt integration is detected, a dialog is displayed that shows a list of versions from which to copy customizations. You can select a version and click Apply, or select Skip to bypass the copying of customizations and create your own customizations in the mapper, as described in the steps below.
    Description of apply_customizations.png follows
    Description of the illustration apply_customizations.png

  4. Click the icon for the type of mapping you want to customize. You can customize request, response, fault, enrichment source, and enrichment response mappings.

    An icon for customizing the selected mapper is displayed.
  5. Click Customize.

    The mapper is displayed in customization mode.
  6. Drag and drop source fields to target elements.
    Blue dots are added to the left of the mapped target elements in the Mapping column to indicate that these are customized mappings. These mappings are added to a customized layer on top of the base mapping file, which is not modified. This dot differentiates the customized mappings from the regular mappings created as part of the prebuilt integration, which are displayed without a blue dot.

  7. Click Close, then click Apply to save your changes.
    A blue dot with the words Customized Response Mapping is displayed in the lower right corner of the icon for the customized mapper (for this example, the response mapper was customized). The other mappers do not have a blue dot because they were not customized (for this example, the request, fault, and request enrichment mappers).

See Mapping Data of Using the Oracle Mapper.

Remove Customized Mappings from Prebuilt Integrations

You can remove the customized mappings that you added to prebuilt integrations that you imported from the Oracle Marketplace. You can remove all customized mappings or specific subsets of mappings (for example, request, response, faults, enrichment source, or enrichment response mappings).

To remove customized mappings from prebuilt integrations:
  1. In the navigation pane, click Integrations.
  2. Locate the prebuilt integration in which you want to remove the customized mappings. Prebuilt integrations that have been customized are designated with the words BUILT BY ORACLE and Customized to the right of the integration name.
  3. Click the integration name.
    You can remove all customized mappings added to the integration or specific subsets of mappings (for example, request, response, fault, request enrichment, or response enrichment mappings).
  4. To remove all customized mappings from the integration, perform the following step:
    1. Click Remove All Customizations in the upper right corner.

  5. To remove specific subsets of request, response, fault, request enrichment, or response enrichment mappings, perform either of the following steps:
    1. Click the mapper icon, then click Remove Customizations for the customized mapping to delete (for this example, the customized response mapping is selected).

    or
    1. Click the mapper icon, then click Customize to access the specific mapper.
    2. Click Remove Customizations in the upper right corner of the mapper page.
  6. Click Yes when prompted to confirm your selection.
    This action removes the specific customized mappings in the integration. Note that the blue dots that previously identified the customized mappings are removed. The existing mappings that are part of the original prebuilt integration are not removed.

Import Map Files

Review the following topics to learn how to import map files into Oracle JDeveloper and Oracle Integration.

You can export an integration that includes a map file that you want to edit in Oracle JDeveloper. See Export an Integration.

Import a Map File into Oracle JDeveloper

You can import an Oracle Integration archive file into an Oracle Service Bus project in Oracle JDeveloper. The archive file can include a map file that is largely complete in content or a map file that is empty of content. This action enables you to perform advanced XSLT tasks (create variables, use templates, and so on) in Oracle JDeveloper that you cannot perform in the Oracle Integration mapper. After you complete these advanced tasks in Oracle JDeveloper, you can save and re-import the map file into Oracle Integration.

  1. See Export an Integration for instructions on exporting an integration that includes the map file you want to edit in Oracle JDeveloper.
  2. Create an Oracle Service Bus application with a project in Oracle JDeveloper.
  3. In the application navigator, right-click the Oracle Service Bus project and select Import.
    The Import dialog is displayed.
  4. Select Service Bus Resources, and click OK.
    The Import Service Bus Resources wizard is displayed.
  5. Select Zipped/Archived Resources, and click Next.
  6. Click the Browse Zip Source icon to the right of the Zip Source field.
    The Select ZIP File dialog is displayed.
  7. If using Oracle JDeveloper 12.2.1.x, perform the following steps:
    1. From the File Type menu, select ICS Archive (*.iar).
    2. Browse for and select the Oracle Integration IAR archive file that you previously exported.
  8. If using Oracle JDeveloper 12.1.3, perform the following steps:
    1. Ensure that you first rename the .iar file extension to .zip.
    2. Browse for and select the ZIP file to import.
  9. Click OK, then click Next on the wizard page.
    The contents of the JAR file are displayed and can be selected for import.
  10. Select the resources folder in which to import the archive file. Note that the entire Resource tree is selected by default, including everything above the hierarchy node that you want to select. Ensure that you deselect the parts above the relevant hierarchy node, then click Finish.

    The resources are imported into the Oracle Service Bus project. You can now open the map file for editing with the XSLT Map Editor in Oracle JDeveloper.

Import a Map File into Oracle Integration

There may be scenarios in which you need to perform an advanced XSLT task (create variables, use templates, and so on) that you cannot perform in the Oracle Integration mapper. For these cases, you can export the integration, import the integration into Oracle JDeveloper, perform these advanced tasks in the map file in the XSLT Map Editor in Oracle JDeveloper, and then save and re-import the map file into Oracle Integration. The map file must be from an Oracle Service Project in Oracle JDeveloper.

Note:

You cannot view or edit a map file imported into the mapper.
  1. In the navigation pane, click Integrations.
  2. Click the specific integration in which to import the map file.
  3. Click the mapper icon to display a menu.
  4. Click More Actions > Import.
  5. Click Browse to select the map (.xsl) file. Note that while you exported the entire integration, you do not import the entire integration back into Oracle Integration. You only import the map file of the exported integration back into Oracle Integration.
  6. Click Import.