> 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/governance/certification/create-a-user-campaign.md). # Create a user campaign Scope a USER\_CERTIFICATION — the six user selection modes, what each stores, why a frozen user list goes stale, and the schedule values. ## What this is, and when you need it A user campaign asks *"for these people, is all their access still correct?"*. This page covers the **Select Users** tab — how the population is chosen and where each choice is stored. Type selection, reviewers, preview and launch are on [Plan and scope a campaign](/administration-guide/governance/certification/plan-and-scope-a-campaign.md) and are not repeated here. ## At a glance | | | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **You will end up with** | A `USER_CERTIFICATION` definition whose `USER_QUERYING_MODE` and target ids resolve to exactly the population you intended | | **Where** | `/webconsole/access-certification-edit?id=` → **Select Users** tab | | **You need first** | **Type of Certification** already set to `USER_CERTIFICATION`; the roles, groups, organizations, user type or saved search that names your population | | **Takes** | 10 to 20 minutes, plus one preview to confirm the count | | **Reversible** | Yes — scope is configuration on the definition and changing it affects only future previews. A campaign already launched keeps the population it launched with | ## Before you begin Set **Type of Certification** to `USER_CERTIFICATION` on the **Configurations** tab first; the **Select Users** tab only appears for that type. ## Scope the population {% stepper %} {% step %} ### Choose the selection mode **Selection Type** writes `CERTIFICATION.USER_QUERYING_MODE`. Six values, no others: | Stored value | Screen label | What you pick | Stored in | | ----------------- | ----------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `USER` | Search individual users | Named users | `CERTIFICATION_TARGET.ENTITY_ID`, one row per user | | `USER_ROLE` | From roles | Roles; every member is certified | `CERTIFICATION_TARGET.ENTITY_ID`, one row per role | | `USER_GROUP` | From groups | Groups; every member is certified | `CERTIFICATION_TARGET.ENTITY_ID`, one row per group | | `USER_TYPE` | By user type | Exactly one user metadata type | `CERTIFICATION_TARGET.ENTITY_ID` — a single row, and only the first is ever read, so a second one saved by hand is silently ignored | | `USER_ORG` | From organizations | Organizations; every member is certified | `CERTIFICATION_TARGET.ENTITY_ID`, one row per organization | | `EXTENDED_SEARCH` | Extended search | A saved reusable search | `CERTIFICATION.EXTENDED_SEARCH_ID`; `CERTIFICATION_TARGET` stays **empty** | For a recurring review, pick one of the four dynamic modes rather than `USER` — see [Choosing between the modes](#choosing-between-the-modes) below. {% endstep %} {% step %} ### Select the targets, or attach a saved search All five list modes share one column, so the mode is what tells the resolver how to interpret the ids. Switching modes and saving does not clear the previous ids in the UI's model — check the tab reads what you expect before you preview. For `EXTENDED_SEARCH`, build the search in the search builder on the tab and save it with **Save as...** under a name you will recognise; **Saved searches** is where it appears afterwards. Before you attach it, press **Preview Users** and read the *"N users match these criteria"* line — that is the number the campaign will scope to. This is the only mode that can express a compound predicate — an attribute *and* an organization *and* a status. {% endstep %} {% step %} ### In `USER` mode, expect to select every user by hand {% hint style="warning" %} **There is no bulk import of the user list in the console.** The **Select Users** tab offers a search and a selection list, and nothing else: no CSV upload, no export of the current selection. A list of two hundred named users is two hundred selections, and there is no way to hand OpenIAM the spreadsheet the list arrived in. This is a product gap, not a hidden feature. If a bulk load is unavoidable for your review, raise it with support — and see the **Developer Guide** if your deployment has integration work of its own. Do not plan a large `USER`-mode campaign around a bulk load that the console cannot do. {% endhint %} For anything bigger than a handful of people, use one of the four dynamic modes instead: a role, a group, an organization, a user type, or an extended search will express the same population as a rule that re-resolves every run, which is both less work now and correct next quarter. {% endstep %} {% step %} ### Set the schedule, or leave it blank **Scheduled Interval** on the **Configurations** tab writes `CERTIFICATION.SCHEDULE_TYPE`. Four values only: | Stored value | Screen label | | --------------- | ------------- | | `ANNUALLY` | Annually | | `SEMI_ANNUALLY` | Semi-annually | | `QUARTERLY` | Quarterly | | `MONTHLY` | Monthly | There is no weekly and no cron. **Reference Start Date** (`CERTIFICATION.START_DATE`) is the anchor the interval counts from. Leaving the interval blank means the certification only ever runs when someone starts a preview by hand. {% hint style="warning" %} A scheduled run produces a **preview**, not a campaign. The scheduled task `accessCertificationInitializer.initializeAccessCertification` starts a preview with the server-default validity window and returns — an administrator must then promote it. Combined with the 24-hour default in `org.openiam.certification.preview.freshness.hours`, a monthly schedule whose preview nobody looks at within a day produces nothing at all. Confirm which of the two happened after the first scheduled run: a `COMPLETED` preview on the **Preview** tab with no new campaign in the list and no `EXECUTE_CERTIFICATION` audit record means the schedule worked and is waiting for you. Either watch for the preview, or raise the freshness window to match your response time. {% endhint %} {% endstep %} {% step %} ### Save, then preview and count Every save is checked for a selection mode first. If the mode is `EXTENDED_SEARCH`, OpenIAM requires a saved search to be attached and ignores any selected targets entirely; for every other mode it requires at least one target and ignores the search. Both failures come back as the same error code, `NO_TARGET_USERS_SELECTED`, which therefore does not by itself tell you which of the two you hit — look at which mode the tab is on. Then run a preview and compare **Users — In scope** against a count you obtained independently. For `EXTENDED_SEARCH`, compare it against the *"N users match these criteria"* line that **Preview Users** gives you on the search builder. {% endstep %} {% endstepper %} ## Choosing between the modes `USER_ROLE`, `USER_GROUP`, `USER_ORG` and `USER_TYPE` are **dynamic at scope-resolution time** — the population is whoever is a member when the preview runs, not whoever was a member when you configured it. That is what you want for a recurring quarterly review. `USER` is a **frozen list** and will go stale; use it for a one-off remediation review, not a scheduled one. `EXTENDED_SEARCH` is the only mode that can express a compound predicate, and it is the answer when the population you want is not any single role, group, organization or type. ## Worked example A quarterly review of every contractor, reviewed by their supervisor, with the population resolved fresh each quarter: | Field | Value | | ------------------------ | --------------------------------------------------- | | Type of Certification | `USER_CERTIFICATION` | | Status | `Active` | | Scheduled Interval | `QUARTERLY` | | Reference Start Date | the first review date | | Email Template | a shipped campaign-notify template — **not blank** | | Manager of Access Review | the compliance owner who should receive the reports | | Selection Type | `USER_TYPE` | | Target | the contractor user metadata type | | Reviewer step 0 | `SUPERVISOR` | Then preview it. The number to check first is the **User — no reviewer** exclusion tile: contractors are the population most likely to have no supervisor set, and every one of them will be excluded with `SUPERVISOR_NOT_FOUND` rather than reviewed by someone else. ## Verification * **Mode and targets persisted:** re-open the **Select Users** tab and confirm the Selection Type and the selection it shows. The rows behind them are `CERTIFICATION_TARGET`, or `CERTIFICATION.EXTENDED_SEARCH_ID` for `EXTENDED_SEARCH`. * **Save accepted:** audit `MODIFY_CERTIFICATION` or `CREATE_CERTIFICATION` — the two constants are swapped when saving a certification, so search for either (see [Plan and scope a campaign](/administration-guide/governance/certification/plan-and-scope-a-campaign.md)). * **Population is what you intended:** run a preview and compare **Users — In scope** against a count you obtained independently. ## When it goes wrong | Symptom | Cause | Fix | | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | Save fails with `NO_TARGET_USERS_SELECTED` | `USER_QUERYING_MODE` null, or `CERTIFICATION_TARGET` empty for a list mode | Pick a Selection Type and at least one target | | Save fails with `NO_TARGET_USERS_SELECTED` while an extended search is chosen | `CERTIFICATION.EXTENDED_SEARCH_ID` is blank — the search was selected but never saved | Save the extended search first, then re-select it | | You cannot find a way to load a list of users from a file | The console has no CSV import for the user selection | Select them on the tab, or express the population with a dynamic mode; raise a bulk load with support | | Preview shows the whole directory | `USER_TYPE` mode with a metadata type that most users carry, or `USER_ORG` at the top of the hierarchy | Narrow the target, or switch to `EXTENDED_SEARCH` with a compound predicate | | Preview excludes almost everyone with `NO_ENTITLEMENTS` | The population genuinely holds no roles or groups | Correct scope, wrong population — these users have nothing to certify | | Members added after configuration are missing | `USER` mode stores a frozen id list | Switch to `USER_ROLE`, `USER_GROUP`, `USER_ORG`, `USER_TYPE` or `EXTENDED_SEARCH` | | A second `USER_TYPE` target is ignored | Only the first `CERTIFICATION_TARGET` row is read in that mode | Expected; one user type per certification | | A schedule fired but no campaign appeared | Scheduled runs create a preview that waits for promotion | Promote it from the **Preview** tab within the freshness window | ## Related * [Plan and scope a campaign](/administration-guide/governance/certification/plan-and-scope-a-campaign.md) — preview, launch and the exclusion reasons * [Configure the review workflow](/administration-guide/governance/certification/configure-the-review-workflow.md) — the supervisor step and what happens when it cannot resolve * [Enumerated values](/administration-guide/reference/enums.md) — the user selection modes and schedule intervals in the full catalogue *Applies to OpenIAM 2026.9.1. Last reviewed 14 September 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/governance/certification/create-a-user-campaign.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.