1. Using Integrations in Oracle Integration Generation 2
  2. Map Data and Create Lookups
  3. Map Data

Map Data

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

Topics:

See Map Data of Using the Oracle Mapper with Oracle Integration Generation 2.

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 style you are using.

See Access the Mapper in Using the Oracle Mapper with Oracle Integration Generation 2.

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 77u/ text at the start of an encoded base64 string is related to the byte order mark and indicates the encoding scheme used (UTF-8). This is not needed for decoding of base64 string to a binary.

    This is needed for representing binary data in a string. This text must be extracted and removed from the original base64 string to ensure it doesn't cause decoding issues. If this is not removed from the encoded string, the decoded data, if converted to a string, has additional space.

    You can extract and remove this from the base64-encoded string with the help of standard mapper functions for strings. This information is not needed to decode the base64-encoded string to binary data. This is needed for reading the binary data using UTF-8 encoding.

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 Functions link > Functions > Advanced)

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.

Import Map Files

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

Note:

As an alternative, you can directly edit XSLT code in the mapper. This eliminates the need to export your XSLT code from Oracle Integration, edit the code manually in a text editor or in a separate graphical tool such as Eclipse or Oracle JDeveloper, and then re-import the code into the mapper in Oracle Integration. See Edit the XSLT Code in the Mapper in Using the Oracle Mapper with Oracle Integration Generation 2.

Topics:

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.
    Description of mapper_select_jar_conf.png follows
    Description of the illustration mapper_select_jar_conf.png

    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.

  1. In the left navigation pane, click Home > Integrations > 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.