> 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/faq/identities-and-access.md). # Identities, roles and scheduled work Short answers to questions administrators ask most often about identities, roles and scheduled work. ## What this is, and when you need it Short answers to the questions this area generates most often, each linking to the page that carries the detail. If your question is not here, the section hubs route by outcome and the [error and symptom index](/administration-guide/error-and-symptom-index.md) routes by the exact message you were given. ### A custom field I just created does not appear in the page template's field list. Why? Three causes, in the order worth checking. The template has no **Template Type** yet, in which case the drop-down loads nothing at all. The field is already on this template, and the drop-down filters out fields the template already holds. Or the field's field type has not yet been swept into the Webconsole's metadata cache, which refreshes on `org.openiam.metadata.cache.sweeptime` (shipped at two minutes) and immediately on a Webconsole restart. [Full detail](/administration-guide/identities/page-templates-and-custom-fields/page-template-reference.md#why-a-custom-field-is-missing-from-the-field-drop-down) ### After an upgrade, "Edit your profile" in SelfService is completely blank. What is wrong? The URI pattern for that screen is bound to no page template. When template resolution finds nothing it throws nothing — the page metadata comes back with a null template and the screen renders with no fields, leaving only a debug-level `Page template was null.` line in the log. An upgrade that introduces a new route introduces a new URI pattern, and a new pattern starts life bound to nothing. Bind the pattern to a user page template in that template's **URI Patterns** section. [Full detail](/administration-guide/identities/page-templates-and-custom-fields.md#a-pattern-with-no-template-renders-a-blank-screen-not-an-error) ### All of my batch tasks stopped running at once and nothing is logged against them. Where do I look? At `BATCH_SCHEDULE`. The scheduler marks every due schedule row for a task as running in one query, which becomes a single `IN` predicate with one parameter per row; past the database's limit that query throws, and because the whole cycle sits in one try block the throw abandons every task the cycle had not reached yet. The result is that one task with a large backlog of due rows stops every batch task on the installation, with no failed audit record anywhere because no task was ever started. Group `BATCH_SCHEDULE` by `TASK_ID` where `COMPLETED = 'N'` to find the culprit. [Full detail](/administration-guide/automation/batch-tasks/diagnose-stalled-batch-tasks.md#how-the-schedule-table-works) ### Can a batch task generate a CSV report on a schedule, and where does the file go? Yes, and the product ships a working example of exactly that shape which is worth copying rather than starting from scratch: it takes its scope from the task parameters, builds the CSV in memory, writes it through the file service and mails it as an attachment. The file lands in the directory configured as `iam.files.location`, which ships as `${confpath}/upload/` — so `/usr/local/openiam/upload/` on an RPM installation and `/data/openiam/upload/` in a container. Put a date stamp in the file name, and split anything destructive into a report task and a separate cleanup task that acts only on the confirmed list. [Full detail](/administration-guide/automation/batch-tasks.md#producing-a-scheduled-report-file) ### Can I make one custom field's drop-down depend on the value chosen in another? There is no product setting for a dependent drop-down, but two hooks on the page template get you a workable version. The template's global data model script is published into the page as the JavaScript variable `TemplateDataModel`, and the template's **Custom JS** field is injected as an inline script after the fields are drawn, so a short script can rewrite the dependent field's options from that map. Keep the option lists in the Groovy data model rather than in the JavaScript, and remember it is presentation only — nothing on the server rejects a mismatched pair, so add a custom validator if the pairing must hold. [Full detail](/administration-guide/identities/page-templates-and-custom-fields/page-template-reference.md#dependent-drop-downs) ### Can I show a different page template to different roles on the same screen? Not by binding two templates to the same URI pattern. Template resolution keys on the URI pattern and the metadata type, and a pattern that resolves to two templates throws instead of choosing — the operator sees "This page is linked to more than one template." Entitling a template to a role is a gate applied *after* resolution, not a selector: pass it and you get that template, fail it and you get no template at all. To vary a form by who is using it, give each audience its own URI pattern, its own template and its own SelfService menu item, and entitle the menu item. [Full detail](/administration-guide/identities/page-templates-and-custom-fields.md#how-the-product-picks-the-template-for-a-request) ### How do I clean up orphan accounts, and can I do it with SQL? No — orphans have no database table. They exist only as documents in the `orphan` OpenSearch index, so a SQL script cannot touch them and there is no table to fall back to when the screen looks wrong. For anything you can enumerate, tick the orphans on the orphan screen and use **Delete selected from IDM**, which is scoped to exactly what you ticked and audited per orphan as `REMOVE_ORPHAN`. The only wholesale operation is a super-admin reindex of the orphan document type from **Administration → Reindex Opensearch Indices**, which is unscoped and should be verified in a non-production environment first. [Full detail](/administration-guide/identities/resolve-orphan-accounts.md#when-the-orphan-list-and-the-reconciliation-disagree) ### Is it safe to unlink the OpenIAM identity from a user, and how do I re-link it? It is not safe, and the product does not stop you. The OpenIAM identity is the identity every managed-system account is correlated through; unlinking deletes the `LOGIN` row and writes an orphan document, with no test for the default managed system anywhere on that path. Recovery is worse than it looks, because the link operation dereferences the user's primary principal on the default managed system while building its audit trail — so linking *any* orphan back onto that user throws before it does any work. Restore the identity from the user's identities screen first, then use **Update Identities** for the managed-system orphans. [Full detail](/administration-guide/identities/resolve-orphan-accounts.md#never-unlink-the-openiam-identity) ### Why does a user search by employee type fail from a Groovy script? Because the search bean declares `employeeType` as a `String` while the user entity maps it as an association to a metadata type, so the database search path binds a string where an entity is expected and the query fails whatever else is in the search bean. The message names the type mismatch, but the line above it in the log is the generic `Exception Occurred during RabbitMQ Call` wrapper, which says nothing useful. Set `useElasticSearch` true on the search bean — the OpenSearch path matches the same value against a string field — or select on another criterion and test the employee type in the script. [Full detail](/administration-guide/automation/batch-tasks.md#searching-for-users-from-a-batch-script) ### Why does adding a role to a user sometimes produce no ADD\_USER\_TO\_ROLE audit event? Because the action recorded depends on which screen you used. Granting from the user's own role or group tab records `ADD_USER_TO_ROLE` or `ADD_USER_TO_GROUP` for that one membership. Saving the whole user from the classic user form records `MODIFY_USER`, described "Save user with entitlements", and that single event covers every entitlement the form submitted. Whether either route also provisions is governed by `org.openiam.provision.service.user.entitlements.flag`, which ships true and produces a `PROVISIONING_MODIFY` event. To monitor privileged-role assignment completely, alert on all three actions. [Full detail](/administration-guide/identities/grant-and-revoke-access.md#verification) ### Why does only the first value of a multi-select custom field reach the managed system? Because the shipped policy-map Groovy idiom for a custom attribute reads one value and adds one value: it calls `getFirstValue()`, which returns the first element of the value list and nothing else. Changing the field from a combo box to a multi-select list therefore changes what the form captures but not what the managed system receives — the remaining values are dropped with no error anywhere. To send all of them, edit the policy map's transformation script to loop the value list and add each value; the field type is not the thing to change. [Full detail](/administration-guide/identities/page-templates-and-custom-fields/page-template-reference.md#multi-value-fields-managed-systems-and-user-search) ### I saved a user and their roles, groups or organizations did not change, or some disappeared. Why? Both halves of that come from the same thing: the entitlement lists on the classic user form are part of the save only when the page template puts them on the form, and when they are on the form the save treats the list on screen as the **complete set**. If the template does not carry **User can select a Role**, **User can select a Group** or **User can define his organizational structure**, that list is not submitted at all and saving the user cannot change it. If the template does carry it, an entry the operator removed from the list is marked for deletion rather than merely left out — so somebody tidying a long organization list on the way to correcting a phone number revokes affiliations, and the save reports success. Use the user's entitlement tabs, which change one membership at a time and audit each under its own action, and keep those three template fields off the templates your operators work in. [Full detail](/administration-guide/identities/grant-and-revoke-access.md#what-a-save-everything-screen-replaces) ### Why is a required field on the user page template not actually enforced when the user is saved? The server-side required check applies to the template's **custom** fields only. `validate` acts on a page element only when it is present in the map built from `METADATA_ELEMENT_PAGE_TEMPLATE_XREF`, so `Required` on a built-in template field — including *User can define his organizational structure* — is a hint to the form and not a constraint on the save. The user is created with the field empty, with no popup and no error, and anything downstream that depends on the value silently does not fire. Enforce it in a page template custom validation script (`IPageTemplateCustomValidator`), which runs on the same save. [Full detail](/administration-guide/identities/page-templates-and-custom-fields/page-template-reference.md#enforcing-required-on-a-built-in-template-field) *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/faq/identities-and-access.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.