ICS-20099: Unable to retrieve integration from the archive — fix

ICS-20099 is the error Oracle Integration Cloud throws when the import validator decides a provided .iar archive is not a faithful copy of one the design editor produced. The user-facing message is usually:

ICS-20099: Unable to retrieve integration from the archive
"Import has failed because IAR has been modified outside of the integration design editor"

Oracle's official position, per MOS 2896228.1: "You cannot manually edit an exported IAR file outside of Oracle Integration and then import it into another instance. If you need to modify the file, contact Oracle Support Services."

Root cause: the mod integrity hash

Every IAR Oracle exports carries an integrity field at icspackage/project/<PROJECT>/ics_project_attributes.properties:

mod=csiyL2JIDTnU8K10o63Xlw==

The value is base64-encoded 16 bytes — an MD5-length digest the OIC server recomputes on every save and on every export. When you unzip an IAR, edit any resource (an XSL transform, a WSDL, the project.xml) and re-zip without rewriting mod, the server checks the field, finds it stale, and rejects the import with ICS-20099.

We confirmed this against OIC Gen 3 build 26.01.0.8 with multiple Engie and Orange production IARs. The hash derivation is canonicalised across the resource set, not just project.xml — MD5 of the project.xml alone never matches.

When you typically see this error

The four most common scenarios:

• You exported an IAR from dev, opened it in an editor to fix a connection name or a typo in a mapping, re-zipped, and tried to import to test.
• You wrote a CI pipeline that mutates an IAR via unzip → patch → zip and pushes via POST /integrations/archive.
• You exported from OIC Gen 2 and tried to import into OIC Gen 3, where the hash validator is strict (Gen 2 was lenient).
• You attempted to merge two IARs by hand to combine integrations.

What to do

Path 1 — Re-export and re-import (Oracle's supported path)

Open the integration in Designer, make the change, save (the server rewrites mod), export the new IAR, import that to the target environment. This works but does not scale — you cannot diff, you cannot review, and Designer is the only producer of valid archives.

Path 2 — Push logic into lookups and libraries

OIC does expose REST endpoints for lookups (POST /lookups/{name}) and JS libraries (POST /libraries/{id}/archive). Move conditional logic, branch tables, and reusable transforms into those surfaces and you can ship changes without touching the IAR. Your flow becomes a thin orchestration that calls into hot-replaceable artifacts.

Path 3 — Stop using IAR as the source of truth

Most teams that hit ICS-20099 repeatedly have outgrown OIC's authoring model. The integration platform you actually want has:

• A human-readable artifact (yaml or json) that lives in your Git repo, not a sealed zip.
• A promotion model where the same flow definition runs in dev/test/prod via configuration, not by re-exporting.
• An AI assistant that can read your existing OIC project and translate it for you.

That is what we built ERPHive for. Drop your .iar on erphive.com/migrate and you get back a readable flow.yaml in under a second — across our verification runs against a 1.3MB / 158-step Engie integration, the worst case was 542ms. The output is open source under BSL 1.1.

See also

• ICS-10994: IAR has been modified outside of the integration design editor — the companion error message; same root cause.
• The OIC mod integrity hash explained — what we know from reverse-engineering eight production IARs.
• Anatomy of an OIC IAR file — what's actually inside the archive.
• MOS 2896228.1 — Oracle's KB article on this error