Mapper Options in OIC Guide

Introduction

Mapper Options in OIC are one of the most powerful features used when building integrations in Oracle Integration Cloud. During real implementation projects, data rarely flows between systems in the exact same format. ERP, HCM, CRM, and external applications often use different structures, field names, and data formats. Because of this, consultants rely heavily on the OIC mapper to transform and manipulate data before sending it to the target system.

In real-world Oracle Fusion Cloud integrations, developers frequently encounter situations where the source payload needs transformations such as conditional mapping, string manipulation, date conversions, or looping through repeating elements. The Mapper Options in OIC provide a visual and functional way to handle these transformations without writing large amounts of custom code.

For example:

• Mapping employee data from a CSV file into Fusion HCM

• Transforming supplier records from a REST API into Oracle ERP

• Converting XML payload structures between two enterprise systems

Understanding how mapper options work is essential for anyone working with integrations in OIC Gen 3. In this guide, we will explore the architecture, real-world implementation scenarios, configuration steps, testing strategies, and best practices used by experienced Oracle integration consultants.

What are Mapper Options in OIC?

The Mapper in Oracle Integration Cloud is a graphical data transformation tool that allows developers to map data between a source structure and a target structure.

Mapper options provide built-in transformation functions that allow you to:

• Manipulate string values

• Perform conditional logic

• Convert date and number formats

• Loop through repeating elements

• Handle null values

• Perform mathematical calculations

• Build complex XML or JSON payload structures

Internally, the mapper generates XSLT transformations, but the developer does not need to manually write XSLT code.

Key Mapper Capabilities

In OIC Gen 3, the mapper has improved performance and enhanced visual debugging capabilities compared to earlier versions.

Key Mapper Options in OIC

The mapper provides a rich set of transformation functions organized into categories.

1. String Functions

String functions are used when working with textual data.

Common examples include:

• concat

• substring

• upper-case

• lower-case

• replace

• trim

Example:

Source field:

Using concat:

Result:

Real-world use case:

Mapping employee full name in Oracle Fusion HCM integration.

2. Number Functions

Used for performing calculations on numeric values.

Examples:

• sum

• round

• multiply

• divide

• abs

Example scenario:

Calculating invoice total amount.

Example:

This is common in ERP financial integrations.

3. Date and Time Functions

Used when transforming date formats between systems.

Examples:

• current-date

• current-dateTime

• format-date

• add-days

• add-hours

Example:

Source date format:

Target format required:

Using format-date:

This is frequently used in Fusion Financials integrations.

4. Logical Functions

Used to apply business logic.

Examples:

• if

• and

• or

• not

Example:

This logic is used when mapping role classifications or approval conditions.

5. Node Functions

Used when working with XML structures.

Examples:

• exists

• count

• first

• last

Example:

This returns the number of employee elements in the payload.

6. Lookup Functions

Lookups are used to convert values from one format to another.

Example:

Source system sends department codes:

Target system requires:

Lookup mapping converts these values during transformation.

Real-World Integration Use Cases

Scenario 1 — Employee Data Integration (Fusion HCM)

A company uploads employee data using a CSV file through the OIC File Server.

Integration flow:

Mapper usage:

• Convert CSV fields to XML structure

• Concatenate employee name

• Format hire date

• Map department using lookup

Scenario 2 — Supplier Integration (Fusion ERP)

A procurement system sends supplier data using REST.

Integration flow:

Mapper tasks:

• Map nested supplier address structures

• Convert phone number format

• Apply conditional mapping for supplier type

Scenario 3 — Order Integration (SCM)

An eCommerce platform sends orders to Oracle SCM Cloud.

Integration flow:

Mapper tasks:

• Loop through order lines

• Calculate order totals

• Map product codes using lookup

Architecture / Technical Flow

A typical OIC mapper architecture looks like this:

The mapper sits between the trigger and invoke actions, transforming payload data before sending it to the destination system.

Prerequisites

Before using mapper options, ensure the following are configured.

Typical connections include:

• REST Adapter

• SOAP Adapter

• FTP Adapter

• Fusion Application Adapter

Step-by-Step Build Process

Step 1 – Login to Oracle Integration Cloud

Open your OIC Gen 3 instance.

Navigate to:

Choose integration type:

Step 2 – Configure Trigger Connection

Add a trigger adapter.

Example:

Define:

• Resource URI

• Request payload structure

Example payload:

Step 3 – Add Invoke Connection

Add the target connection.

Example:

Select the operation such as:

Step 4 – Open Mapper

When the invoke connection is added, OIC automatically opens the mapper window.

The screen shows:

Left side → Source structure
Right side → Target structure

Step 5 – Map Fields

Drag source fields to target fields.

Example:

Step 6 – Apply Mapper Functions

Use the component panel to apply transformations.

Example: Full Name

Example: Format Date

Step 7 – Validate Mapping

Click:

If there are mapping errors, OIC displays warnings.

Step 8 – Activate Integration

Navigate to:

Once activated, the integration is ready to receive requests.

Testing the Technical Component

Testing ensures mapper transformations work correctly.

Test Payload

Example request:

Expected Transformation

Testing Steps

1. Open integration

2. Click Run

3. Send test payload

4. Check tracking dashboard

Navigation:

Verify the transformed payload in the integration instance.

Common Errors and Troubleshooting

1. Null Pointer Mapping Errors

Cause:

Source field is empty.

Solution:

Use conditional mapping.

Example:

2. Incorrect Date Format

Cause:

Target API expects a specific date format.

Solution:

Use format-date function.

3. Namespace Issues in XML

Cause:

Incorrect schema mapping.

Solution:

Ensure the correct namespace is selected in the mapper.

4. Array Mapping Problems

Cause:

Improper looping structure.

Solution:

Use For-Each loops with mapper node mapping.

Best Practices Used by Oracle Integration Consultants

1. Use Lookups Instead of Hardcoding

Avoid:

Use OIC lookup tables instead.

2. Keep Mapper Logic Simple

Avoid creating very complex nested expressions.

Break transformations into multiple stages.

3. Use Stage Files for Complex Transformations

When processing large file structures, use stage file actions before mapping.

4. Validate Mappings Early

Always validate mapping before activating the integration.

5. Use Integration Tracking

Monitor payload transformations using:

This helps identify mapping issues quickly.

Summary

Mapper Options in OIC are essential for transforming data between systems during integration development. In real-world Oracle Cloud implementations, almost every integration requires some form of data transformation.

Key takeaways:

• Mapper provides a visual transformation tool

• Supports string, numeric, date, and logical functions

• Enables complex data manipulation without manual coding

• Plays a central role in OIC Gen 3 integrations

When implemented properly, mapper options simplify integration logic and improve maintainability of enterprise integrations across Oracle Fusion applications, external systems, and cloud services.

For deeper technical documentation and advanced examples, Oracle learners can refer to the official Oracle documentation:

https://docs.oracle.com/en/cloud/saas/index.html

FAQ

What is the mapper used for in OIC?

The mapper is used to transform data between source and target payload structures during integration execution.

Does OIC mapper generate XSLT?

Yes. Internally, the mapper generates XSLT transformations, but developers interact with it through a graphical interface.

Can we write custom expressions in OIC mapper?

Yes. Advanced expressions can be written using XPath and built-in transformation functions.