OIC - How to Extend a Map in an Oracle Integration Cloud (OIC) Accelerator Project

Empowering customizations while preserving upgrade compatibility in OIC accelerator integrations

---

Use Case: When and Why to Extend a Map

Imagine your OIC accelerator integration was originally designed to sync Employee Data between your HR system and a downstream service. The default mapping includes fields like EmployeeID, FirstName, and LastName. Now, your business needs to include Department Code and Work Location in the mapping, which are not in the original integration flow.

To meet this requirement without modifying the original accelerator, and to keep your extension safe across future updates, you should extend the integration through an Extension Group—Oracle’s recommended, upgrade-safe mechanism for customizations.

---

Solution Steps: How to Do It (Accurately Guided by Oracle's Documentation)

1. Open the Accelerator Project and Select the Integration

• In the OIC Projects pane, locate your accelerator project (marked with "Accelerator" and "Oracle") .
• Navigate to the integration you wish to modify.
• From the Actions menu, choose Extend—this will initiate the extension mode (note: this option is exclusive to accelerator projects) .

2. Insert an Extension Group at the Appropriate Point

• Locate the step in the integration flow where you want the extended mapping to take place (e.g., before or after an existing Map or Invoke action).
• Click the Add (+) icon at that point and select Extension Group, or choose Extend before / Extend after using the Actions menu inside the relevant action block .

3. Add the Map Action to the Extension Group

• Inside the newly created Extension Group, click the Add icon or Integration actions menu and choose Map to create an ad-hoc mapping action .
• The OIC mapper will open; drag and drop your new fields from source (e.g., DepartmentCode, WorkLocation) to the corresponding targets, applying any transformations as needed.

Notes for Extending a Map in OIC

When working with a complex XSLT, the Design view may not be available, and only the Code view will be be displayed. In such cases, follow the steps below to rebuild the required namespace references before updating the XSLT.

1. Create a New Map and Generate Namespace Prefixes
1. Create a new mapper.
2. Drag and map the required source elements to their corresponding target elements.
3. This automatically generates the required namespace prefixes in the new XSLT.
2. Add Custom DVM Mappings
1. Add any required Domain Value Map (DVM) lookups to the new mapper.
2. This ensures the DVM namespaces are generated correctly, as namespace references can cause issues when working with an extended map.
3. Add Custom Functions
1. Drag and drop the required custom functions into the mapper.
2. Note the namespace prefixes generated for these functions, as they will be required in the final XSLT.
4. Update the XSLT
1. Copy the XSLT from the existing map and save it in a text editor (such as Notepad) as a backup.
2. Update the namespace prefixes in the new map to match those used in the existing XSLT. 
3. In some cases, you may also need to update the XPath expressions. Compare the old and new XSLT structures and replace the XPath references wherever the source or target schema, namespace, or element hierarchy has changed. This is especially common when extending a mapper with a different namespace or schema structure. Example : /nssrcmpr:ICS_OFSC_ProcessActivity to /nssrcmpr:INT_OFSC_ES_INT/OFSC_PA
4. Replace the entire template (not just individual sections) with the original XSLT code in the extended map to ensure all namespace references and mappings remain intact.
5. Add New Elements
1. Introduce any additional elements required by the business use case and map them appropriately.

4. Additional Customization (Optional But Powerful)

You can further enhance your extension with other actions, such as:

• Data Stitch: To merge multiple payloads or variables.
• For-Each: To process repeated elements.
• Switch: To implement conditional routing within your flow.
• Integration Invoke: To call child integrations.
• Global Variables, Lookups, or JavaScript Libraries: For reusable variables, code translation/lookup logic, or custom script-based logic.

5. Save, Validate, and Activate

• Once your extended mapping (and any extra actions) are configured, save the integration.
• Validate the mapping; OIC will surface any missing or invalid connections.
• Finally, activate the integration to apply your extension.

6. Preserve Your Extensions During Upgrades

One of the biggest advantages of using an Extension Group is that your customizations remain intact during future accelerator upgrades:

• When a new version of the accelerator becomes available, you can choose to Merge latest extensions during the installation. Oracle will automatically apply your Extension Group customizations to the upgraded version.
• Alternatively, if you skip automatic merging, you can still manually merge your extensions into the new version later.

---

Blog Summary: Why Use Extension Groups for Map Customization

Benefit	Description
Upgrade-safe	Your custom mapping stays intact during accelerator updates.
Structured customization	Extensions are isolated in their own group—easy to manage and modify.
Flexible extensibility	Besides maps, you can add loops, lookups, global vars, child integrations, and more.
Low-impact	No changes to the original accelerator code, minimizing risks.

---