> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/administration-guide/platform/import-export-and-promotion/import-export-reference.md). # Import and export reference Every object type, field, configuration key, command flag and artifact shape of the import-export utility, what it does not cover, and what the two Webconsole Export and Import screens really do. ## What this covers These tables support [Promote configuration between environments](/administration-guide/platform/import-export-and-promotion.md). Read that page to do a promotion; come here for the detail — what an export of each object type contains, what an import does with it, every configuration key and command flag, the shape of the files on disk, and the catalogue of objects the utility does not touch. Two other things named "export" are documented here too, because both are routinely mistaken for the utility: the Webconsole's **Export Objects** and **Import Objects** screens, and the corrections older documentation needs. ## The Webconsole export and import screens The Webconsole ships two screens under the System area. Both routes work and both render a real page. | Screen | Route | What it does | | -------------- | --------------------------- | -------------------------------------------------------- | | Export Objects | `/webconsole/exportObjects` | Ignores every checkbox and downloads a fixed sample file | | Import Objects | `/webconsole/importObjects` | Nothing | The export page shows eight checkboxes — Password Policies, Authentication Policies, System Configuration, Email Templates, Resources, Roles, Groups, Organizations. The import page shows a file chooser labelled *Select a JSON file to import* and an **Import** button. {% hint style="danger" %} **Export Objects returns the same 442 KB `export.json` that ships inside the Webconsole**, whatever you tick: **3 groups, 8 roles and 439 resources**, beginning with `HR_GRP` / "HR Group", role `1` / "End User" and resource `0` / "OPENIAM". Confirm it in ten seconds — download it, open it, search for `HR_GRP`. If that string is there you are holding the sample and not your configuration, and the file size will be the same on every environment you try. **The Import button has no handler behind it.** No file is uploaded, no request is sent, no error is shown, and nothing appears in the audit log. Silence is the whole behaviour. {% endhint %} Two mitigating facts. Neither screen is reachable from the shipped menu, so they appear only if somebody types the path or a stale runbook links to it. And because the export returns a fixed file and the import does nothing, neither can damage your data. The risk is entirely one of false assurance. ## Corrections to older documentation The superseded *Import / Export* page described a **database-to-database** tool. None of it is true of the current utility, and anyone following it fails on the first command. | Older documentation said | The current utility | | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | Two scripts, `export.py` and `import.py` | One script, `main.py`, with `export` and `import` as subcommands | | A JSON configuration with `source_db` and `target_db` | YAML (JSON also parses) with **no database connection parameters anywhere**. The utility never opens a database connection | | `update_existing` decides conflicts | The `--on-conflict` flag does. There is no `update_existing` key | | An `object` key names the object type | The object type is a subcommand | | An `export_path` key | `--output` is required on every export. There is no `export_path` key | | `authentication_provider` and `content_provider` are supported | Neither is supported | If a runbook in your organisation quotes `source_db`, replace it with the procedure in [Promote configuration between environments](/administration-guide/platform/import-export-and-promotion.md). ## How the utility authenticates Every command signs in with the service account's password and then completes an **OAuth 2.0 implicit grant** against the environment's authorization endpoint — the same grant a browser would use, driven by a password login instead of a login page. Knowing that much is enough to tell an OAuth-client problem from a credential problem, because the two halves fail with different messages: | Message on the first command | What it means | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *"authToken missing from login response"* | The password sign-in did not succeed. The credential, or that account's entitlements, is where to look | | *"Authorize did not redirect: 200"* | The sign-in worked and the OAuth client did not. **Authorization Grant Flow** is not **Implicit**, or **Redirect URL** does not match `redirect_uri` character for character | Four consequences worth knowing: * **No client secret is used.** A `client_secret` in the configuration is read and never sent anywhere, so a configuration that supplies one but omits `username` and `password` cannot authenticate at all. * The access token is reused for its stated lifetime less a 60-second margin, and for 1800 seconds when no lifetime is stated. A token that expires mid-run is renewed, not fatal. * Every call the utility makes carries **both** its access token **and** the `OPENIAM_AUTH_TOKEN` session cookie. A reverse proxy or gateway that strips cookies breaks the utility even though the token is intact — the one failure that looks like a permissions problem and is not. * A logout runs after every command, so a run leaves no session behind on the environment. ## The configuration file `--config`/`-c` names the file. Without it, the utility takes the first of `config.yaml`, `config.yml` or `config.json` it finds in the working directory, and exits if none exists. Both YAML and JSON parse. Exactly four keys are required, and a run missing any of them stops immediately and names them — which makes a bad configuration the cheapest failure the tool has. | Key | Meaning | Default | Required | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | -------- | | `api.base_url` | The environment's base URL. Trailing slashes are stripped | — | **Yes** | | `api.client_id` | Client ID of the Implicit-grant OAuth client | — | **Yes** | | `api.username` | Service account login | — | **Yes** | | `api.password` | That account's password | — | **Yes** | | `api.redirect_uri` | Must match the OAuth client's Redirect URL exactly | `http://localhost`; the shipped samples use `http://localhost:5000/callback` | No | | `api.login_endpoint` | Where the utility signs in. Its default is correct for every OpenIAM deployment — leave it unset | the utility's own | No | | `api.authorize_endpoint` | The environment's OAuth authorization endpoint | `/idp/oauth2/authorize` | No | | `api.logout_endpoint` | Used by the post-command logout. Read from configuration but absent from both shipped samples | `/idp/logout` | No | | `api.timeout` | Per-request timeout in seconds. Applies to the login, the authorize and every API call | `30` | No | | `api.client_secret` | Read into the client and never sent. Present only for compatibility with the v1 client-credentials flow | — | No | | `output.default_path` | Fallback directory for the `cleanup` command when `--path` is omitted. **Not** a default for `--output`, which is required on every export | `./exports` | No | | `logging.level` | `DEBUG`, `INFO`, `WARNING` or `ERROR`. `--verbose` forces `DEBUG` | `INFO` | No | | `logging.file` | Log file in addition to the console. Parent directories are created | unset — console only | No | {% hint style="info" %} **Keys in the samples that no code reads.** `environment`, `output.cleanup.enabled`, `output.cleanup.days_to_keep`, `defaults.on_conflict`, `defaults.validate_data`, `defaults.export.include_metadata` and `defaults.export.recursive_children` all appear in the shipped `examples/config.yaml` and in the README's configuration reference. Nothing in the `v3` tree reads any of them. Conflict behaviour, data validation and child recursion come **only** from command-line flags, and `cleanup` takes its retention from `--days`, default 30. Writing `defaults.on_conflict: update` into the file and expecting imports to update is a silent no-op — the flag default is `skip`. {% endhint %} **Environment variables.** A value is substituted only when the **entire** string is `${NAME}`, and when the variable is unset the literal `${NAME}` is **left in place** rather than failing. Partial interpolation — `base_url: "https://${HOST}/openiam"` — is not expanded at all. ## The five object types | Object type | Subcommand | What an export contains | What an import does with it | | ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Roles** | `roles` | Eighteen core fields — `name`, `description`, `status`, `managedSysId`, `managedSysName`, `mdTypeId`, `riskId`, `maxUserNumber`, `membershipDuration`, `assignToAll`, `visible`, `excludeFromAuth`, `virtualTenantRole`, `startDate`, `endDate`, `owner`, `admin` and the resolved policy — plus seven relationship lists: `parents`, `children`, `groups`, `resources`, `organizations`, `users`, `approvers`. System and audit fields are excluded. The role's own `MANAGED_SYS` resource is filtered out of `resources`, and the owner and admin users are filtered out of `users` | Searches the target by name; creates the role, or updates the one it found; then a **second pass** adds groups, organizations, child roles, resources, user members and approver associations | | **Groups** | `groups` | Twenty-two core fields — the role set plus `classificationId`, `classificationName`, `adGroupTypeId`, `adGroupTypeName`, `adGroupScopeId`, `adGroupScopeName` — plus `parents`, `children`, `roles`, `resources`, `organizations`, `users`, `approvers` | The same two-pass shape as roles | | **Organizations** | `organizations` | Fourteen core fields — `name`, `description`, `status`, `organizationTypeId`, `organizationTypeName`, `alias`, `abbreviation`, `symbol`, `classification`, `domainName`, `ldapStr`, `selectable`, `attributes` and the resolved policy — plus `certifier` rewritten as `{"type": "USER", "login": …}` and `parents`, `children`, `roles`, `groups`, `resources`, `users`, `approvers`. Each organization attribute is stripped of `id`, `organizationId` and `objectState`, and unnamed attributes are dropped entirely | Creates or updates the organization, then assigns the hierarchy, the entitlements, the users and the approvers. The certifier is resolved back to a target ID by login lookup | | **Resources** | `resources` | `name`, `description`, `status`, `resourceTypeId`, `mdTypeId`, `coorelatedName`, `public`, `visible`, `url`, `risk`, `owner`, `admin`, `resourceProps` and `groovyScript`, plus `parents`, `children`, `groups`, `roles`, `organizations`, `users`, `approvers` and `questionnaires`. `groovyScript` is converted from an environment ID to `{scriptPath, scriptVersion}`, and each `resourceProp` loses `id`, `resourceId`, `objectState` and the four requestor/audit fields | Creates or updates the resource, then assigns relationships and saves questionnaires. **`--name` matches `coorelatedName` — the display name — not the internal `name` field**, and the error message says so when it misses | | **Business rules** | `business-rules` | The rule with `name`, `description`, `status`, `ruleType`, `priority` and every other non-excluded field, plus the serialized `condition` tree and the `onDo` and `onUndo` targets with their actions. `id`, `conditions`, `targets`, `operation` and `lastUpdated` are excluded | Resolves every reference back to a target ID as a **pre-flight**, creates any missing rule target first with resolved action values, then writes the rule. Unresolvable references are reported as errors before anything is written | ### The three things `v3` added **Portable policy.** A `policyId` is environment-specific, so the exporter replaces it: role, group and organization exports carry the policy's name and its definition instead, and the import looks that pair back up on the target by name. A file exported before `v3` carries a raw `policyId` and will silently point at whatever object happens to hold that id on the target — so check the files for `policyId` before importing anything you did not export with `v3`. **Metadata type resolution.** Five business-rule condition attributes hold metadata type IDs, and `v3` maps each to its grouping so the value can travel: | `expressionAttribute` | Grouping searched on import | | --------------------- | --------------------------- | | `STATUS` | `USER` | | `SECONDARY_STATUS` | `USER_2ND_STATUS` | | `EMPLOYEE_TYPE_ID` | `USER_EMPLOYEE_TYPE` | | `JOB_CODE_ID` | `JOB_CODE` | | `TYPE_ID` | `USER_OBJECT_TYPE` | Export writes `{name, grouping}` in place of the id; import looks the pair up and reports *"Metadata type not found: '' (grouping=)"* when the target has no matching type. That message is the one to search the run log for — it is a warning, and the object it belongs to still reports as imported. **Per-run caching.** Repeated lookups — roles, groups, user logins, policies, resources and organizations — are cached in memory for the length of one run, keyed by name and managed system. The cache holds **misses as well as hits**, and that is the part that matters operationally: if a dependency is missing when the run starts and you create it in the Webconsole while the run is still going, the run keeps reporting it as missing until you start a new one. Never fix a dependency mid-run; stop, fix, re-run. ## Commands and flags Two global options apply to every command: `--config`/`-c` and `--verbose`/`-v`. `--verbose` overrides `logging.level` to `DEBUG`, which logs every API call with its status and duration. The command groups are `export` and `import` — `import` is registered under that name explicitly because it is a Python keyword. | Export command | Flags | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `export roles` | `--output`/`-o` (**required**), `--name`, `--since`, `--recursive-children`, `--managed-system`, `--status`, `--dry-run` | | `export groups` | `--output`/`-o` (**required**), `--name`, `--since`, `--recursive-children`, `--status`, `--dry-run` | | `export resources` | `--output`/`-o` (**required**), `--name`, `--resource-type`, `--dry-run` | | `export organizations` | `--output`/`-o` (**required**), `--name`, `--org-type`, `--dry-run` | | `export business-rules` | `--output`/`-o` (**required**), `--name`, `--since`, `--status`, `--rule-type`, `--dry-run` | `--name` exports one object; without it the command exports everything the search returns, paginated 30 at a time for roles and groups and 100 at a time for resources, organizations and rules. | Import command | Flags | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `import roles` | `--input`/`-i` (**required**, must exist), `--on-conflict` `skip`\|`update`\|`error` (default **`skip`**), `--dry-run`, `--preview` | | `import groups` | The same four | | `import resources` | `--input`/`-i`, `--on-conflict`, `--dry-run` — **no `--preview`** | | `import organizations` | `--input`/`-i`, `--on-conflict`, `--dry-run` — **no `--preview`** | | `import business-rules` | All four | `--input` takes either a single JSON file or a directory. For a directory it matches `/-*.json` and, finding nothing, falls back to `/s/-*.json` — so both `--input ./exports` and `--input ./exports/roles` work. | Other command | What it does | | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `test-connection` | Obtains a token and prints `✓ Successfully connected to OpenIAM API`. Note the hyphen in the command name | | `cleanup --days N --path DIR` | Deletes export files older than N days. `--days` defaults to 30; `--path` falls back to `output.default_path` | | `examples [--object-type role\|group\|resource\|organization\|business_rule]` | Prints worked command lines | | `version` | Prints `OpenIAM Import/Export Utility v1.0`, which is stale on `v3` | ## What an exported artifact looks like **Directories.** An export writes into `/s`, so a single `--output ./exports` produces `exports/roles/`, `exports/groups/`, `exports/resources/`, `exports/organizations/` and `exports/business_rules/`. The README's import examples name `./exports/group`, `./exports/resource` and `./exports/organization` — singular directories no export ever creates. Use the plural names, or point `--input` at the parent. **Filenames.** `--.json`. The name keeps only alphanumerics, spaces, hyphens and underscores, and spaces become hyphens — so the role `Manager Role` becomes `role-Manager-Role-2026-04-14T09-12-33.json`. Two roles whose names differ only in a stripped character collide on one filename, and one of them is lost with no warning; compare the file count against the number of objects you expected. **Envelope.** The payload is wrapped in exactly four metadata keys: `object_type`, `object_name`, `exported_at` and `version`, the last always `"1.0"` regardless of which branch produced it. The README's sample shows a fifth key, `source_environment`, which no export writes — do not build tooling that expects it, and do not rely on `version` to tell you which branch made the file; record the branch yourself. An import accepts either the enveloped form or a bare object, treating a file with no `metadata`/`data` pair as legacy and using it whole. ### The v1 shape, and why a v1 file is not safe to import {% code title="role-AdministratorAccess-2025-08-18T22-39-58.json (v1, abridged)" overflow="wrap" expandable="true" %} ```json { "metadata": { "object_type": "role", "object_name": "AdministratorAccess", "exported_at": "2025-08-18T22:39:58Z", "version": "1.0" }, "data": { "role": { "name": "AdministratorAccess", "description": "Provides full access to AWS services and resources.", "status": "ACTIVE", "managedSysId": "AWS_MANAGED_SYS", "managedSysName": "05 AWS Managed System", "mdTypeId": "8a80816d797ff44e017980bbef37003c", "metadataTypeName": "AWS Policy", "policyId": "4000", "objectState": "NEW", "createDate": 1621363624000, "visible": true, "assignToAll": false, "objectType": "ROLE" }, "children": [], "groups": [], "resources": [], "approvers": [] } } ``` {% endcode %} `v1` wrote the raw API response — `objectState`, `createDate`, `mdGrouping`, `requestorSessionID` and a raw `policyId`, all of them either environment-specific or meaningless on a target. `v3` writes only the named core fields, drops every system and audit field, resolves `policyId` to `policyName`/`policyDefId`, and adds the `parents`, `organizations` and `users` lists that `v1` did not fetch at all. **`objectState` or `createDate` in a file you are about to import means it came from `v1`.** ### The v3 shape {% code title="role-Manager-2026-04-14T09-12-33.json (v3 shape)" overflow="wrap" expandable="true" %} ```json { "metadata": { "object_type": "role", "object_name": "Manager", "exported_at": "2026-04-14T09:12:33Z", "version": "1.0" }, "data": { "role": { "name": "Manager", "description": "Manager role with team oversight", "status": "ACTIVE", "managedSysId": "AD_MANAGED_SYS", "managedSysName": "ActiveDirectory", "mdTypeId": "ACCESS_ROLE", "policyName": "Default Password Policy", "policyDefId": "PASSWORD_POLICY", "visible": true, "assignToAll": false, "owner": { "type": "USER", "id": "uid-1", "login": "jsmith" } }, "parents": [ { "name": "AllRoles", "managedSysName": "ActiveDirectory" } ], "children": [ { "name": "TeamLead", "managedSysName": "ActiveDirectory" } ], "groups": [ { "name": "ManagersGroup", "managedSysName": "ActiveDirectory" } ], "resources": [ { "id": "res-payroll", "name": "PayrollSystem", "resourceTypeId": "APPLICATION" } ], "organizations": [ { "name": "Finance", "type": "DEPARTMENT" } ], "users": [ { "login": "alice", "firstName": "Alice", "lastName": "Smith", "email": "alice@example.com" } ], "approvers": [ { "approverType": "USER", "approverLevel": 0, "mandatory": true, "login": "jsmith", "escalations": [], "notifyOnApproved": [], "notifyOnRejected": [] } ] } } ``` {% endcode %} `resources` carries an `id` as well as a name: resource IDs are treated as stable across OpenIAM environments and used as the primary resolution key, with the name as fallback. Everything else resolves by name — roles, groups and their managed system name; organizations by name; users and approvers by `login`. ## Behaviours to plan around ### Conflict handling decides the scalar fields only The `--on-conflict` decision is made once per object, after searching the target for a same-named object, and identically for every object type: | Mode | When the object exists on the target | When it does not | | -------------------- | ------------------------------------------------------------------------------ | ---------------- | | `skip` (**default**) | Returns `skipped` with the **existing object's ID** and makes no scalar change | Creates it | | `update` | Rewrites the scalar fields on the existing object | Creates it | | `error` | Returns `failed` for that object and continues with the rest | Creates it | {% hint style="danger" %} **`skip` still assigns relationships.** A skipped object still yields the existing object's id, and the second pass runs against every object the run touched — so `--on-conflict skip` leaves the role's own fields alone and still adds groups, organizations, child roles, resources, **user members** and approver associations to it. If what you wanted was "import only what is new", `skip` is not that command: filter the input directory instead. The evidence is in the target, not in the run output, which reports the object as skipped. **Approver associations are deleted and recreated on every import of that object.** Every existing approver association on the target object is removed first, then rebuilt from the file — so approvers an administrator configured on the target after the last export are destroyed, and the run reports success. Export the target's approvers before you import over them, and diff afterwards. {% endhint %} ### Relationship assignment is add-only An import adds the groups, organizations, child roles, resources and user members named in the file, and removes nothing. An entitlement present on the target and absent from the export **stays**. Repeated imports therefore converge upwards only: the target becomes the union of every version you ever imported, which is the opposite of what "promote this configuration" usually means. To remove something you remove it by hand in the Webconsole. ### References resolve by name, and a failure to resolve is a warning A reference that cannot be resolved on the target produces a **warning** and the import moves on — `"Child role not found: X"`, `"Group not found: X"`, `"User not found for login 'X', skipping role membership"`, `"Admin/owner GROUP not found: X"` — and the object itself is still reported as a success. So an import can report `Created=40, Failed=0` and have silently dropped a third of the entitlements because the dependencies did not exist on the target yet. **The `Failed` count is not a measure of correctness.** Two specific traps: * **The conflict search matches on name only.** The managed system name is sent to the search but not used in the match that follows, so two roles with the same name on different managed systems can be conflated — and the import will update the wrong one without complaint. * **An unresolved policy silently becomes policy `4000`.** Where the export carries no `policyName`, the import falls back to policy `4000`, the seeded default, and to a metadata type of `ACCESS_ROLE` where that is missing too. A role whose policy could not be resolved lands on the default password policy rather than failing, so open a promoted role and read its policy back rather than assuming. Always read the run's warnings, not just its `Created/Updated/Skipped/Failed` line. `--verbose` logs every API call with status and duration; `logging.file` keeps it. ### Ordering between object types is yours to get right The tool has no cross-type ordering and no `migrate` command — a combined export-and-import step is listed in the README as an intended v4 feature. Within one object type there are two passes, so intra-type parents and children resolve. Across types nothing coordinates, and because a missing reference is a warning rather than a failure, importing in the wrong order produces objects that look created and are half-wired. Import in this order, and re-run the later types if the earlier ones reported creations: **organizations → resources → groups → roles → business rules.** Business rules go last because their conditions and targets reference roles, groups, resources and organizations by name. Users are never created by this tool, so any `users` list in an export resolves only against identities that already exist on the target. ### One export directory per run Filenames carry a timestamp, so a second export into the same directory adds a **second generation of the same objects** rather than replacing the first. An import of that directory matches `-*.json` and applies **every** match, in filesystem order rather than sorted order — so both generations are imported in an arbitrary sequence and whichever lands last wins. Nothing warns you. Use a fresh, dated directory for every export, and `cleanup --days N` to retire the old ones. ### Partial exports are expected The README states a **20 to 40% success rate** as normal for large role exports, because OpenIAM's role search can return ids whose detail fetch then returns 404. Each failure is logged and the run continues, so the command exits successfully either way. Count the files written and compare that against the source environment's object count before you treat an export as complete — an export that silently covered two thirds of the catalogue is the worst possible input to a promotion, and the number of files is the only check that catches it. ### Flags that are accepted and do nothing * **`--dry-run` on an *****export***** does nothing at all.** It prints *"DRY RUN MODE - No files will be written"* and returns **before it contacts the API**, on all five object types. Use `test-connection` to prove reachability instead. * **`export roles --managed-system` is accepted and never applied.** Supplying `--managed-system` or `--status` switches the run to a path that exports *everything* and then filters the files it wrote — on `status` only. The observable check is the file count: a filtered export producing as many files as an unfiltered one did not filter. Filter afterwards, or export one object at a time with `--name`. ## What the utility does not cover Everything below is outside the tool entirely, and stays a hand rebuild — see [The rest of a promotion](/administration-guide/platform/import-export-and-promotion.md#the-rest-of-a-promotion-what-the-utility-does-not-move). | Not covered | Note | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Managed systems and connectors, policy maps, provisioning configuration | No export of any kind | | Content providers and URI patterns, authentication providers and authentication rules | No export of any kind. Older documentation wrongly listed the two provider types as supported | | Synchronization and reconciliation configurations, and the CSV formats behind them | No export of any kind | | Users and their memberships | Users are resolved by login and **never created** | | Groovy scripts | A resource's script is exported as a `{scriptPath, scriptVersion}` reference; the body is not. Use Groovy Manager's zip export, and import it **before** the resources that reference it | | System properties, page templates, custom fields, request categories, questionnaires as standalone objects, IT policies, OTP providers, mailbox configurations, mail templates, analytics tiles, SoD rule sets, certification campaigns | No export of any kind | | Secrets | Nothing in the vault is exported, and nothing should be | | Deletion and drift detection | No comparison mode, and no way to make a target match a source by removing what the source does not have. Both are listed in the README as intended v4 features | ## Related * [Promote configuration between environments](/administration-guide/platform/import-export-and-promotion.md) — the procedure these tables support * [What a backup and restore must cover](/administration-guide/platform/backup-and-restore-scope.md) — the other thing people mean by "export" * [Shipped Groovy scripts](/administration-guide/reference/shipped-groovy-scripts.md) — the 745 scripts a zip export will contain * [Where settings live](/administration-guide/start/where-settings-live.md) — why properties and secrets are promoted differently *Applies to OpenIAM 2026.8.1. Last reviewed 7 August 2026.* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/administration-guide/platform/import-export-and-promotion/import-export-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.