Map Data
Use the mapper to map data between the source data structure and the target data structure.
See Map Data of Using the Oracle Mapper with Oracle Integration 3.
Access the Mapper
To create mappings in an integration, you must first access the 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.
-
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. TheattachmentReference
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.
-
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 ofMaximum 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 a 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.
-
fileReference
-
attachmentReference
-
streamReference
-
Expression Builder, when configuring the following actions in an integration:
-
Notification
-
Logging
-
Switch
-
Assign
-
-
Mapper (visible after selecting > 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 3.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.
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.
- In the navigation pane, click Design, then Integrations.
- Click the specific integration in which to import the map file.
- Click the mapper icon, then select , then Import.
- 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. - Click Import.