Mapper Options in OIC
Mapper Options in OIC: Complete Guide to Oracle Integration Cloud Mapper
In Oracle Integration Cloud (OIC), applications often use different data structures, field names, formats, and values. The Mapper is one of the most important tools in OIC because it allows developers to transform and map data between source and target applications.
For example, an employee application might send:
employee_id
employee_name
department
while the target application expects:
EmployeeNumber
Name
DepartmentName
The OIC Mapper allows you to connect these source and target fields and apply functions, conditions, lookups, and transformations when simple mapping is not enough.
Oracle describes mappings as transformation maps that use XSL to define data transformations. The OIC Mapper supports XSLT 2.0 and provides functions, operators, and XSLT constructs for more complex mappings.
In this guide from Learnomate Technologies, we will explore the important Mapper options in OIC, how mapping works, mapping recommendations, functions, operators, lookups, conditional mappings, default values, XSLT, testing, and common mapper best practices.
What Is the Mapper in OIC?
The Oracle Integration Cloud Mapper is a visual data transformation tool used to define how data moves from a source structure to a target structure.
When you open a mapping, OIC displays:
Source Structure Mapping Canvas Target Structure
| | |
| | |
+-------------------->|------------------->|
You can generally drag a source element and drop it onto the corresponding target element.
For example:
Source Target
Employee_ID ----------------> EmployeeNumber
Employee_Name ----------------> Name
Department ------------------> DepartmentName
Oracle’s Mapper documentation describes this drag-and-drop approach as the basic method of creating mappings between source and target element nodes.
Why Is the OIC Mapper Important?
The Mapper is essential because source and target applications rarely have exactly the same data structure.
Consider an integration between an HR system and an external payroll application.
Source
{
"employeeId": "1001",
"firstName": "John",
"salary": "75000"
}
Target
{
"EmployeeNumber": "1001",
"EmployeeName": "John",
"AnnualSalary": 75000
}
The Mapper can handle:
- Direct field mapping
- Data transformation
- String manipulation
- Numeric calculations
- Date conversion
- Conditional mapping
- Lookups
- Default values
- Repeating elements
- Functions
- XSLT expressions
- Multiple source structures
- Complex transformations
Understanding the OIC Mapper Interface
The Mapper generally contains three major areas.
+----------------+----------------------+----------------+
| | | |
| Source Tree | Mapping Canvas | Target Tree |
| | | |
| Employee_ID | ------------------> | EmployeeNumber |
| First_Name | ------------------> | Name |
| Department | ------------------> | Department |
| | | |
+----------------+----------------------+----------------+
Source Tree
The source tree contains the data structure coming from the trigger or source application.
Mapping Canvas
The middle section contains mapping relationships and transformation expressions.
Target Tree
The target tree contains the structure expected by the destination application.
Oracle documents the Mapper as displaying source data structures on the left and target structures on the right, with mappings created between their element nodes.
Important Mapper Options in OIC
The OIC Mapper provides several options that make complex mappings easier to create and troubleshoot.
Let’s understand the most important ones.
1. Direct Mapping
Direct mapping is the simplest type of mapping.
You simply drag a source field to the corresponding target field.
Example:
Source Target
EmployeeID ------------> EmployeeNumber
FirstName ------------> EmployeeName
Email ------------> EmailAddress
This creates a direct mapping expression.
Direct mapping is appropriate when:
- Field names are different but data is compatible.
- No transformation is required.
- Source and target data types are compatible.
2. Mapping Recommendations
OIC can provide mapping recommendations for target elements.
When recommendations are available, the Mapper can display suggested mappings, allowing developers to accept recommended mappings instead of manually creating every mapping.
Oracle documentation describes the Recommendations Engine as a feature that can suggest target element mappings and reduce the need to analyze and perform each individual source-to-target mapping manually.
For example:
Source:
employeeNumber
Recommended Target:
EmployeeNumber
You can review the recommendation and accept it.
Benefit
Mapping recommendations can save time when working with large schemas.
3. Functions
Functions are one of the most powerful Mapper options in OIC.
Instead of simply connecting:
Source → Target
you can use:
Source → Function → Target
Oracle provides functions and operators through the Mapper’s function interface.
Examples include functions for:
- String manipulation
- Numeric operations
- Date and time processing
- Boolean operations
- Conversion
- Conditional logic
- Lookup processing
4. String Functions
String functions are useful when source and target applications use different text formats.
For example, suppose:
Source:
John Doe
and the target requires:
JOHN DOE
You can apply an appropriate string transformation.
Other common requirements include:
First Name + Last Name
becoming:
John Doe
String functions are particularly useful for:
- Concatenation
- Case conversion
- Substring extraction
- Trimming spaces
- Searching text
- Replacing characters
- Formatting values
5. Numeric Functions
Numeric functions are useful when calculations are required.
For example:
Salary = 50000
Bonus = 5000
Target:
Total Compensation = 55000
Conceptually:
Salary + Bonus → Total Compensation
Other examples include:
- Addition
- Subtraction
- Multiplication
- Division
- Rounding
- Comparisons
6. Date Functions
Date transformations are common in enterprise integrations.
For example:
Source:
2026-08-25
Target may require another format.
Date functions can help with:
- Date conversion
- Date formatting
- Date extraction
- Date comparisons
- Adding or subtracting time
- Working with timestamps
Always verify the source and target data types before applying date transformations.
7. Conditional Mapping
Conditional mapping allows you to map a value only when a specific condition is satisfied.
For example:
If Department = "IT"
→ "Technology"
Otherwise
→ "Other"
Conceptually:
Department
|
v
Is IT?
/ \
Yes No
| |
Technology Other
OIC supports conditional constructs such as if, choose, when, and otherwise in the Mapper.
8. Using IF Conditions in the Mapper
Suppose the source contains:
EmployeeStatus
Possible values:
ACTIVE
INACTIVE
The target requires:
A
I
The mapping can implement logic such as:
IF EmployeeStatus = "ACTIVE"
→ "A"
ELSE
→ "I"
This is useful when the target system uses different business codes.
9. Choose / When / Otherwise
For more complex conditions, the Mapper supports XSLT flow-control constructs.
For example:
Choose
|
+--- When Department = "IT"
| → Technology
|
+--- When Department = "HR"
| → Human Resources
|
+--- Otherwise
→ Other
Oracle documents choose, when, and otherwise as available conditional constructs in the Mapper.
This is particularly useful when multiple business rules need to be evaluated.
10. Lookup in OIC Mapper
A Lookup is useful when the source and target systems use different values for the same business concept.
For example:
| Source Value | Target Value |
|---|---|
| IN | India |
| US | United States |
| UK | United Kingdom |
Instead of hardcoding these values into the mapping, you can maintain them in an OIC Lookup.
The Mapper can then use the lookupValue function.
Oracle describes lookupValue as a specialized Mapper function for retrieving values from an existing lookup table.
Example of lookupValue
Suppose the source contains:
CountryCode = IN
The lookup contains:
IN → India
US → United States
UK → United Kingdom
The mapping becomes conceptually:
CountryCode
|
v
lookupValue()
|
v
India
The lookupValue function can use parameters including the lookup location, source column, source value, target column, and default value.
11. Default Values
Sometimes the source doesn’t provide a value, but the target requires one.
For example:
Source:
Department = NULL
Target:
Department = "UNKNOWN"
You can use a default value in the Mapper.
OIC also provides an Add Default Value option when the target node has a defined default value in its schema.
Conceptually:
IF source value exists
|
+----> Use source value
|
ELSE
|
+----> Use default value12. Mapper Functions Panel
The Functions area allows you to search for and add functions to your mapping.
A typical workflow is:
Open Mapper
|
v
Open Functions
|
v
Search Function
|
v
Select Function
|
v
Configure Parameters
|
v
Map to Target
Oracle documentation identifies the Mapper’s function option as the place to add functions, operators, and XSLT expressions to mappings.
13. Operators
Operators allow you to perform comparisons and calculations inside mappings.
Common categories include:
- Arithmetic
- Comparison
- Logical
- String-related operations
For example:
Salary > 50000
or:
Department = "IT"
or:
Salary + Bonus
Operators become especially useful when building conditional mappings and complex expressions.
14. XSLT in OIC Mapper
OIC mappings are transformation maps based on XSL.
Oracle states that the Mapper supports XSL version 2.0, while XSL version 1.0 is not supported.
For advanced transformations, developers can work with XSLT constructs.
For example:
xsl:if
xsl:for-each
choose
when
otherwise
The Mapper provides access to XSLT functions and constructs for complex data manipulation.
15. For-Each in the Mapper
When working with repeating data, you may need to map multiple records.
For example:
Employees
|
+--- Employee 1
+--- Employee 2
+--- Employee 3
The Mapper supports XSLT constructs such as xsl:for-each for repeating data transformations.
This should not be confused with the OIC For Each action.
OIC For Each Action
Used to execute integration actions for each repeating item.
XSLT for-each
Used within a transformation to process repeating data.
16. Node Info
The Node Info option provides useful information about a source or target element.
Depending on the schema, you can inspect details such as:
- Data type
- Required status
- Repeating status
- XPath
- Default value
- Content type
- Nillable
- Minimum occurrences
- Maximum occurrences
Oracle specifically documents Node Info as a way to inspect schema details for elements and attributes.
This is extremely useful when troubleshooting mapping errors.
17. Filter Option
Large schemas can contain hundreds or thousands of fields.
The Mapper provides filtering capabilities to make large structures easier to navigate.
You can filter:
- Required fields
- Errors
- Warnings
- Source elements
- Target elements
Oracle documents the Filter option as a way to filter displayed element nodes, errors, and warnings in the source and target structures.
18. Search Data Fields
Instead of manually expanding a large schema, you can search for a specific field.
For example:
Search:
employeeNumber
The Mapper can help you quickly locate the required source or target element.
This is especially helpful when working with large Oracle ERP, HCM, CRM, REST, or SOAP schemas.
19. View Options
The Mapper provides view options that can help developers understand complex schemas.
You can display information such as:
Namespace Prefix
Data Type
This can be particularly useful when dealing with XML namespaces and complex schemas.
Oracle documents options for displaying namespace prefixes and types in source and target element nodes.
20. Developer View
OIC provides a developer-oriented view that can be useful when working with technical field names and expressions.
The standard interface can display user-friendly names, while the Developer option allows you to work with more technical source and target element names.
This can be helpful when troubleshooting:
Field Name
XPath
Namespace
Data Type21. Undo and Redo
Mapper development often involves experimenting with different transformations.
The Mapper provides:
Undo
Redo
For example:
Create Mapping
↓
Undo
↓
Create New Mapping
↓
Redo if required
This makes it easier to modify complex mappings without manually recreating everything.
Oracle lists Undo and Redo among the Mapper toolbar options.
22. Maximize Mapper
Large source and target structures can make mapping difficult.
The Maximize option allows you to expand the Mapper interface and get more working space.
This is particularly useful when:
- Working with large schemas
- Mapping nested XML structures
- Working with multiple repeating elements
- Creating complex expressions
23. Testing Mappings
Testing is an important part of Mapper development.
Before deploying an integration, validate the mapping using representative input data.
For example:
Input:
Employee ID = 1001
Department = IT
Salary = 75000
Expected output:
EmployeeNumber = 1001
DepartmentName = Technology
Salary = 75000
Oracle provides mapping testing capabilities to help validate transformation results before using the mapping in production.
24. Mapping Multiple Source Structures
Some integrations need data from more than one source structure.
For example:
Employee
+
Department
+
Location
|
v
Target Employee
The Mapper supports working with multiple source structures and mapping them into a target structure. Oracle includes this capability among its mapping features.
This is useful when building complex enterprise integrations.
25. Repeating Target Elements
Sometimes a target structure needs multiple occurrences of an element.
For example:
Target Order
|
+--- Line 1
+--- Line 2
+--- Line 3
The Mapper provides functionality for repeating target elements and mapping them from appropriate source structures.
Practical Example: Employee Data Mapping
Let’s consider a simple integration between an HR system and a payroll system.
Source
{
"employeeId": "1001",
"firstName": "John",
"lastName": "Smith",
"department": "IT",
"country": "IN"
}
Target
{
"EmployeeNumber": "1001",
"FullName": "John Smith",
"Department": "Technology",
"Country": "India"
}
The mapping could be:
employeeId
|
+------------------> EmployeeNumber
firstName + lastName
|
+------------------> FullName
department
|
+--- Lookup --------> Department
country
|
+--- Lookup --------> Country
Here we are using:
- Direct mapping
- String transformation
- Lookup
- Target mapping
Practical Example: Conditional Salary Mapping
Suppose the source contains:
Salary = 75000
The target requires:
SalaryCategory
Business rule:
Salary >= 100000 → HIGH
Salary >= 50000 → MEDIUM
Otherwise → LOW
The Mapper can implement this using conditional constructs.
Conceptually:
Salary
|
v
+-------+-------+
| |
>= 100000 >= 50000
| |
HIGH MEDIUM
|
Otherwise
|
LOW
This demonstrates how the Mapper can perform business-rule-based transformations.
Practical Example: Lookup-Based Transformation
Suppose an external application sends:
Status = A
But the target expects:
Status = ACTIVE
Create an OIC lookup:
| Source | Target |
|---|---|
| A | ACTIVE |
| I | INACTIVE |
| P | PENDING |
Then use lookupValue in the Mapper.
The transformation becomes:
A
|
v
lookupValue()
|
v
ACTIVE
Oracle’s lookupValue wizard allows you to select the lookup, source and target columns, and a default value for cases where a match is not found.
Common Mapper Errors in OIC
1. Required Target Field Not Mapped
If a required target field is not mapped, the integration may fail validation or produce an invalid target payload.
Solution
Use the Mapper’s required-field filter to identify mandatory fields. Required elements are indicated in the Mapper, and Oracle provides a filter to show required fields.
2. Data Type Mismatch
Example:
Source:
Salary = String
Target:
Salary = Number
A transformation may be required.
Always verify data types using Node Info before troubleshooting the mapping.
3. Incorrect Namespace
XML-based integrations can fail because of namespace differences.
Use:
Node Info
View Options
Namespace Prefix
to inspect the schema.
4. Lookup Returns No Match
Suppose:
Source = "CA"
but the lookup contains only:
IN
US
UK
The lookup cannot find a matching value.
Configure an appropriate default value when using lookupValue. Oracle documents the default value as the value returned when no matching lookup entry is found.
5. Incorrect Repeating Element Mapping
When working with arrays or repeating XML elements, ensure that source and target structures have compatible repeating definitions.
Incorrect handling of repeating structures can lead to missing or duplicated data.
OIC Mapper Best Practices
1. Understand the Source and Target Structures First
Before creating mappings, understand:
Source Schema
Target Schema
Data Types
Required Fields
Repeating Fields
Namespaces
2. Use Direct Mapping Where Possible
Don’t use complex functions when a simple drag-and-drop mapping is sufficient.
Prefer:
Source → Target
over:
Source → Function → Function → Target
when no transformation is required.
3. Use Lookups for Business Codes
If values need to be translated between applications, use OIC Lookups instead of hardcoding large sets of values.
Example:
IN → India
US → United States
UK → United Kingdom
4. Use Meaningful Mapping Logic
Complex expressions should be understandable to another developer.
Avoid unnecessarily complicated nested functions.
5. Validate Required Fields
Always check required target fields before activating the integration.
6. Test Edge Cases
Don’t test only successful data.
Test:
Normal value
Null value
Empty value
Invalid value
Unexpected value
Large value
Missing field
Duplicate record
7. Use Default Values Carefully
Default values are useful, but they should represent a valid business value.
Don’t use arbitrary defaults simply to make validation pass.
8. Use Node Info for Troubleshooting
When you’re unsure about a field, check:
Data Type
Required
Repeating
Nillable
Default Value
XPath
Node Info provides this schema-level information.
OIC Mapper vs Assign Action
Both Mapper and Assign can be used to work with values, but their purposes differ.
| Mapper | Assign |
|---|---|
| Primarily transforms source data to target structures | Assigns values to variables |
| Used around invokes/triggers | Used during orchestration logic |
| Supports complex mapping expressions | Useful for runtime variables |
| Source-to-target transformation | Variable manipulation |
A typical integration may use both:
Invoke
|
v
Mapper
|
v
Target
|
v
Assign
|
v
Variable
OIC Mapper vs XSLT
The OIC Mapper provides a visual interface for creating transformation maps, while XSLT provides more technical control over XML transformations.
Mapper
Drag & Drop
XSLT
Code-Based Transformation
OIC uses XSL-based transformation maps and supports XSLT 2.0.
For most standard transformations, the visual Mapper is easier to maintain.
For highly complex transformations, understanding XSLT can be valuable.
OIC Mapper Interview Questions
If you’re preparing for an OIC interview, these are important Mapper questions.
1. What is the Mapper in OIC?
The Mapper is a visual transformation tool used to map and transform data between source and target structures.
2. What is direct mapping?
Direct mapping connects a source element directly to a target element without applying additional transformation logic.
3. What is lookupValue?
lookupValue is a Mapper function used to retrieve a target value from an OIC Lookup based on a source value.
4. What is conditional mapping?
Conditional mapping applies mapping logic based on conditions using constructs such as if, choose, when, and otherwise.
5. What is the purpose of Node Info?
Node Info helps developers inspect schema properties such as data type, required status, repeating status, XPath, and default value.
6. Does OIC Mapper support XSLT?
Yes. OIC transformation maps use XSL, and Oracle documents support for XSLT 2.0.
7. Why are Lookups used in OIC?
Lookups are useful for translating values between source and target applications when they use different codes or terminology.
8. Can Mapper process repeating elements?
Yes. The Mapper supports XSLT constructs such as xsl:for-each for processing repeating data.
Frequently Asked Questions
What is Mapper in OIC?
The Mapper in OIC is a visual tool used to define how data is transformed and transferred from source applications to target applications.
What are the main Mapper options in OIC?
Important options include direct mapping, functions, operators, lookups, conditional mappings, default values, XSLT, recommendations, filtering, search, Node Info, testing, undo, redo, and view options.
What is lookupValue in OIC Mapper?
lookupValue retrieves a corresponding target value from an OIC Lookup using a source value. It can also return a configured default value when no match is found.
Can I use IF conditions in OIC Mapper?
Yes. Conditional mappings can use constructs such as if, choose, when, and otherwise.
Does OIC Mapper support XSLT?
Yes. OIC uses XSL-based transformation maps and supports XSLT 2.0.
How do I troubleshoot mapping errors in OIC?
Start by checking required fields, data types, repeating elements, namespaces, XPath expressions, lookup values, and validation errors. The Mapper’s Node Info and Filter options are particularly useful.
Final Thoughts
The Mapper is one of the most important components of Oracle Integration Cloud because it connects the data structures of different applications and performs the transformations required for successful integration.
A simple mapping may look like:
Source Field
|
v
Target Field
But real-world integrations often require:
Source
|
+--- Function
|
+--- Condition
|
+--- Lookup
|
+--- Default Value
|
+--- Transformation
|
v
Target
To become proficient in OIC, you should be comfortable with direct mapping, functions, operators, conditional mappings, lookups, default values, repeating elements, XSLT, testing, and troubleshooting.
The most important principle is to understand the source and target schemas before designing the mapping. Once you understand the data structures and business rules, the Mapper becomes a powerful tool for building reliable enterprise integrations.
Learnomate Technologies helps professionals build practical skills in Oracle technologies, cloud computing, databases, and integration platforms. Mastering the OIC Mapper is an important step toward becoming a skilled Oracle Integration Cloud developer.
Learn. Practice. Implement. Grow.
