--- title: Provision users with workflow description: This sample demonstrates a typical workflow use case, provisioning new users. component: pingidm version: 8.1 page_id: pingidm:samples-guide:provisioning-with-workflow canonical_url: https://docs.pingidentity.com/pingidm/8.1/samples-guide/provisioning-with-workflow.html keywords: ["Samples", "Provisioning", "Workflows"] section_ids: provisioning-sample-prepare: Prepare the sample provisioning-sample-running: Run the sample --- # Provision users with workflow This sample demonstrates a typical workflow use case, provisioning new users. The sample uses the admin UI to set up the initial users and roles, then shows how users can complete their registration process in the end-user UI. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Starting with IDM 8.1, the [legacy admin UI is deprecated](../release-notes/deprecated-functionality.html#legacy-admin-ui-deprecated) and is no longer bundled with IDM. New deployments should use the [Platform admin UI](../setup-guide/platform-admin-ui.html), which is the replacement for the legacy admin UI.Both UIs are available as separate downloads from the [Backstage download site](https://backstage.forgerock.com/downloads):- To install the Platform admin UI, follow the steps in [Install the Platform admin UI for standalone IDM](../setup-guide/platform-admin-ui.html). - To continue using the legacy admin UI, follow the steps in [Install the legacy admin UI](../setup-guide/legacy-admin-ui.html). | | | | | - | ------------------------------------------------------------------------------------------------------------------------- | | | The end-user UI is not bundled with PingIDM. Learn more in [Install the end-user UI](../setup-guide/idm-enduser-ui.html). | The sample simulates the following scenario: * An existing employee requests that an outside contractor be granted access to an organization's system. * The *system* in this case, is the IDM managed user repository and a remote HR data source, represented by a CSV file (`hr.csv` ). * User roles are stored separately, in a second CSV file (`roles.csv` ). The sample has three mappings—two for the bidirectional synchronization of the managed user repository and the HR data store, and one for the synchronization of the roles data to the managed repository. ## Prepare the sample In this section, you start IDM and reconcile user and role data. The reconciliation operations create two managed users, `user1` and `manager1`, and two managed roles, `employee` (assigned to `user1`) and `manager` (assigned to `manager1`). | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------- | | | Workflows are not supported with a DS repository. Before you test this sample, [install a JDBC repository](../install-guide/chap-repository.html). | 1. Edit the `/path/to/openidm/samples/provisioning-with-workflow/conf/datasource.jdbc-default.json` file with the details of your JDBC repository. For more information, refer to [Select a repository](../install-guide/chap-repository.html). 2. Start IDM with the configuration for the provisioning sample: ``` cd /path/to/openidm/ ./startup.sh -p samples/provisioning-with-workflow ``` 3. Sign on to the admin UI. 4. Reconcile the role and user data: 1. From the navigation bar, click Configure > Mappings. 2. Select the first mapping (systemRolesFileRole\_internalRole), and click Reconcile. 3. To verify the reconciliation: 1. From the navigation bar, click Manage > Role. 2. On the Roles page, click the Internal tab. IDM displays the two roles created in the previous step: * `employee` * `manager` 4. From the navigation bar, click Configure > Mappings. 5. Select the second mapping (systemCsvfileAccounts\_managedUser), and click Reconcile. The reconciliation operation creates the top-level managers (users who do not have their own `manager` property) in the managed user repository. In this sample, there is only one top-level manager (`manager1`). 6. Select the second mapping again (systemCsvfileAccounts\_managedUser), and click Reconcile. This reconciliation operation creates the employees of the managers that were created by the previous reconciliation. In this sample, there is only one employee (`employee1`). 7. From the navigation bar, click Manage > User, and verify the users `manager1` and `user1` exist. 5. Verify the relationships between the new user and role objects: 1. Click user1. The Manager field displays `manager1` for this user. 2. Click the Authorization Roles tab. `user1` has two roles, `openidm-authorized` and `employee`. 3. From the breadcrumb link at the top of the page, click User, and select `manager1`. The Manager field is empty for this user. 4. Click the Authorization Roles tab. `manager1` has three roles: `manager`, `openidm-authorized`, and `openidm-tasks-manager`. 6. Verify the available workflows: 1. From the navigation bar, click Manage > Processes. 2. On the Workflow Processes page, select the Definitions tab. 3. From the Definitions list, click Contractor onboarding process. IDM displays a diagram similar to the following: ![contractorOnboarding-diag](_images/contractorOnboarding-diag.png) 7. Sign off of the admin UI. ## Run the sample During this part of the sample, an existing employee initiates a *Contractor Onboarding* process. This process is a request to add a contractor to the managed user repository, with an option to include the contractor in the original HR data source (`hr.csv`). When the employee has completed the required form, the request is sent to the manager for approval. Any user with the role `manager` can claim the approval task. If a request was made to add the contractor to the original HR data source, this is done when the manager approves the request. 1. Sign on to the end-user UI (`https://localhost:8443/`) as the user you created in the previous section (`user1`) with password `Welcome1`. 2. Navigate to the dashboard, with the Dashboard icon ([icon: tachometer-alt, set=fas]). Alternatively, select the Menu icon ([icon: bars, set=fas]), and select Dashboard. 3. Initiate the provisioning workflow as `user1`: 1. Scroll down to the Start a Process menu, and click Edit adjacent to Contractor onboarding process. 2. Complete the form for the sample user you will be creating. Use an accessible email address, as you'll need the email message to complete this workflow. 3. Enable Create in CSV File. This option enables implicit synchronization from the managed user repository to the `hr.csv` file. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | `user1` does not provide a password for this user. A password reset request is sent to the email address provided on this form to ensure that only the actual contractor can sign on with this account. | 4. Select Submit to initiate the process. 5. Sign off of the end-user UI. 4. Approve the workflow task as `manager1`: 1. Sign on to the end-user UI as `manager1` with password `Welcome1`. 2. Navigate to the dashboard, with the Dashboard icon ([icon: tachometer-alt, set=fas]). Alternatively, select the Menu icon ([icon: bars, set=fas]), and select Dashboard. 3. Under Unassigned Tasks, locate the Approve Contractor task, select Assign, and click Assign to Me. Approve Contractor is now listed under My Tasks. 4. Click Edit adjacent to the task name. 5. Review the form content, and click Accept. | | | | - | ------------------------------------------------- | | | This is the same content you provided as `user1`. | 6. Sign off of the end-user UI. 5. Verify that the contractor has been created in the HR data source (`/path/to/openidm/samples/provisioning-with-workflow/data/hr.csv` ): ```csv "username","firstname","lastname","manager", "department","jobTitle", ... "user1", "Ordinary", "Employee","manager1","dep1", "job1", ... "manager1","Big", "Manager", "", "dep1", "Manager", ... "bjensen", "Barbara", "Jensen", "user1", "Payroll", "Payroll clerk",... ``` Note the addition of the new contractor entry, `bjensen`.