README revision 7d7e57e489804077bc11a889cafce9f7503c5f86
539N/A/**
539N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
539N/A *
539N/A * Copyright (c) 2015 ForgeRock AS. All rights reserved.
943N/A *
539N/A * The contents of this file are subject to the terms
539N/A * of the Common Development and Distribution License
919N/A * (the License). You may not use this file except in
919N/A * compliance with the License.
919N/A *
919N/A * You can obtain a copy of the License at
919N/A * http://forgerock.org/license/CDDLv1.0.html
919N/A * See the License for the specific language governing
919N/A * permission and limitations under the License.
919N/A *
919N/A * When distributing Covered Code, include this CDDL
919N/A * Header Notice in each file and include the License file
919N/A * at http://forgerock.org/license/CDDLv1.0.html
919N/A * If applicable, add the following below the CDDL Header,
919N/A * with the fields enclosed by brackets [] replaced by
919N/A * your own identifying information:
919N/A * "Portions Copyrighted [year] [name of copyright owner]"
919N/A */
919N/A
539N/AWorkflow Use Cases
539N/A==================
539N/A
539N/AThe openidm/samples/usecase directory includes a number of sample workflows that demonstrate typical
539N/Ause cases for OpenIDM. The use cases work together to describe a complete business story, with the
539N/Asame set of sample data. Each of the use cases is integrated with the Self-Service UI.
539N/A
804N/AThese use cases use OrientDB as a repository by default. Alternative repository configuration files
539N/Aare provided in the openidm/samples/usecase/db directory. If you want to use one of these alternative
911N/Arepositories, remove the repo.orientdb.json file from the conf/ directory of the use case you are
911N/Atesting and copy the appropriate JDBC repository configuration files into that conf/ directory. For
911N/Amore information on using an alternative repository, see the OpenIDM Installation Guide.
911N/A
539N/AEach use case builds on the previous one. You must run the use cases in order, from use case 1 through
539N/A3, before you try the remaining use cases. Use cases 2 onwards depend on the hr_data.ldif file that you
539N/Aimport and reconcile when you run use case 1.
970N/A
970N/AAll the samples assume an initial setup of managed users in OpenIDM. The users are organized as follows:
970N/A- there are 20 ordinary users: user.0 ... user.19 where
970N/A
970N/A - user.0 .. user.4 belong to Human Resources having user.0 as Manager,
970N/A user.0 .. user.3 employees and user.4 contractor
970N/A
970N/A - user.5 .. user.9 belong to Production Planning having user.5 as Manager,
539N/A user.5 .. user.8 employees and user.9 contractor
539N/A
804N/A - user.10 .. user.14 belong to Sales & Distribution having user.10 as Manager,
539N/A user.10 .. user.13 employees and user.14 contractor
970N/A
970N/A - user.15 .. user.19 belong to Treasury & Payments having user.15 as Manager,
970N/A user.15 .. user.18 employees and user.19 contractor
539N/A
The following "special" users are defined:
- hradmin: user representing the human interaction of the HR department
- systemadmin: user representing the human interaction of the populated systems (“Business” and “Project”)
- superadmin: user representing the manager of the managers
Usecase1 - Initial Reconciliation
---------------------------------
In this step we import the users from OpenDJ to OpenIDM using reconciliation.
To prepare to run the sample, download OpenDJ directory server from
http://forgerock.org/opendj.html. Install OpenDJ using QuickSetup:
* Use "password" as the password for cn=Directory Manager.
* Import samples/usecase/data/hr_data.ldif during installation.
1. Start OpenIDM with the configuration for usecase1.
$ cd /path/to/openidm
$ ./startup.sh -p samples/usecase/usecase1
2. Run reconciliation.
$ curl -k -u openidm-admin:openidm-admin -H "Content-Type: application/json" \
-X POST "https://localhost:8443/openidm/recon?_action=recon&mapping=systemHRAccounts_managedUser"
3. Query the managed users created by reconciliation
$ curl -k -u openidm-admin:openidm-admin "https://localhost:8443/openidm/managed/user?_queryId=query-all-ids"
There should be 23 users created. The default password of the imported users is "Passw0rd".
Usecase 2 - New User Onboarding
-------------------------------
In this step we simulate an HR employee starting the onboarding process for an employee
and the approval step of the manager.
To use email notification as part of the process make the following changes:
1. Enable external email. This process is described in the Integrator's Guide at
http://openidm.forgerock.org/doc/bootstrap/integrators-guide/#chap-mail.
2. Change the notification email properties in the workflow definition file.
To do so:
- Copy the workflow bar file (samples/usecase/usecase2/workflow/newUserCreate.bar)
to a temporary location.
- Unzip the temporary workflow bar file and edit the extracted workflow
definition (newUserCreate.bpmn20.xml).
Original:
emailParams = [from : 'usecasetest@forgerock.com', to : 'notification@example.com',
subject : 'Use Case Test Notification', type : 'text/plain',
body : 'The requested user ' + userName + ' was successfully created']
Change the from and to fields to contain valid email addresses.
- When you have completed the edit, zip up the workflow definition file,
along with the two xhtml templates required for the sample, using a
command similar to the following:
$ zip newUserCreate.bar newUserCreate.bpmn20.xml nUCDecideApprovalForm.xhtml nUCStartForm.xhtml
- Copy the resulting bar file to the workflow directory, overwriting
the existing bar file:
$ cp /tmp/newUserCreate.bar /path/to/openidm/samples/usecase/usecase2/workflow
1. Start OpenIDM with the configuration for usecase2.
$ cd /path/to/openidm
$ ./startup.sh -p samples/usecase/usecase2
2. Log in to the Self-Service UI (https://localhost:8443) as user.1. This user belongs to HR department
and has a default password of 'Passw0rd'.
3. Click Details next to User Onboarding Process link and complete the fields for a sample new user.
4. Complete the fields on the form.
- Department field:
Select one of the four departments to define which department the new user will belong to.
Based on the department, the workflow will select the possible candidate assignees
for the manager approval user task: either superadmin (as manager of everyone) or the
manager of the selected department (see description above).
For example, if the department is HR, the manager candidates will be user.0 and superadmin.
- User Type field:
If the User Type is Employee, the user will have access to an account called "Business".
This is represented in the managed user entry by an "accounts" attribute:
accounts : [ "Business"]
If the User Type is Contractor, the new user will have no accounts associated with it in
its managed user entry.
- Send Email Notification field:
If you select "No" here, no email notifications are sent. Notifications are simply added
to the OpenIDM repository, and appear when the user logs into the Self-Service UI.
5. Click Start to start the workflow.
6. Log out and log in as the manager of the department that you selected in the initial form.
For example, if you selected HR, log in as user.0.
7. Click on the Onboarding Approval task in the group queue and assign the user task to user.0
(select 'Assign it to me'). The task appears now in 'My tasks'.
8. Select Details next to the task name.
The complete new user request is displayed for the manager's approval. As the manager, you can
add any information that was missing from the original request. You can also specify the
following information:
- Start Date. Completing this field results in the user being created, with a "startDate" added
to that user's managed user entry. The status of the user is inactive. This field is optional,
and is used by the task scanner to trigger the Sunrise workflow.
- End Date. Completing this field results in the user being created, with an "endDate" added to
that user's managed user entry. The field is optional, and is used by the task scanner to trigger
the Sunset workflow.
- Decision. Selecting Reject here terminates the workflow and sends a notification to the user who
initiated the workflow. Selecting Accept creates the managed user entry in OpenIDM. The password
of the new user is Passw0rd.
Complete the task by clicking on 'Complete' button.
9. Two notifications are created when the request is accepted - one for the user who initiated the
workflow, and one for the newly created user. The notifications are visible in the UI after login.
If you selected email notification, one email is sent to the user that you defined when you
configured email notification.
10. Initiate the sunrise workflow:
To trigger the sunrise workflow (which activates the account), enable the sunrise task scanning
schedule. The schedule is disabled by default. Modify the schedule configuration file
(/conf/schedule-taskscan_sunrise.json), setting the "enabled" property to true.
The scan runs every minute, and checks the repository for users that have a sunrise date that is
anything up to one day after the current date. When the scan is triggered, it locates the newly
created user and starts the sunrise workflow on this user. The workflow takes the following
actions:
- Changes the account status of the user to active.
- Generates a notification for the new user, which is visible when the user logs into the
Self-Service UI.
11. Initiate the sunset workflow:
If a sunset date is set for the new user, you can trigger the sunset workflow to deactivate the
user account when the end of his work period is reached. To trigger the sunset workflow, enable
the sunset task scanning schedule. The schedule is disabled by default. Modify the schedule
configuration file (schedule-taskscan_sunset.json), setting the "enabled" property to true.
The scan runs every minute, and checks the repository for users that have a sunset date that is
anything up to one day after the current date. When the scan is triggered, it locates users
whose contracts are about to end, and starts the sunset workflow on these users. When the workflow
is initiated, it assigns a task to the manager of the affected user. In our example, the task is
assigned to user.0.
When the sunset schedule has been enabled, log in to the Self-Service UI as user.0 (with password
Passw0rd). If the user's sunset date is within one day of the current date, a Contract Termination
task becomes available under the manager's My Group's Tasks section. Select the contract termination
task and click Details.
In the Decision field, select either "Accept termination" or "Modify date", then click Complete.
When you accept the termination, the user's account status is set to inactive and the HR
administrative user receives notification to that effect, next time that user logs into the UI.
The deactivated user is no longer able to log into the UI.
If you select to modify the date, the sunset date of that user is changed to the value that you
specify in the End Date field on that form. The management user receives a UI notification that the
employee's contract has been extended.
Shut down OpenIDM before you proceed with the next use case..
Usecase 3 - User Access Request
-------------------------------
This step simulates a user initiating an access request, with two levels of approval for the request.
If you want to use email notifications as part of the process make the following changes:
- Configure outbound email as you did for the previous use cases.
- Change the notification email properties in the workflow definition file:
samples/usecase/usecase3/workflow/accessRequest.bpmn20.xml
Original:
emailParams = [from : 'usecasetest@forgerock.com', to : 'notification@example.com',
subject : 'Use Case Test Notification', type : 'text/plain', body : 'The access request was accepted']
Change the from and to fields to contain valid email addresses.
Note that there are two occurrences of the emailParams, change both.
1. Start OpenIDM with the configuration for usecase3.
$ cd /path/to/openidm
$ ./startup.sh -p samples/usecase/usecase3
2. Log in to the UI as user.1 (this user belongs to HR department, default password is 'Passw0rd').
3. Select the Access Request Process by clicking on it and start the workflow.
4. A new task appears in 'My tasks', click on it and select 'Details'.
- Access to Business system field: the value reflects the current value in the managed user repository.
- Access to Project system field: the value reflects the current value in the managed user repository.
- Send Email Notification field:
If you select 'No' here, no email notifications will be sent.
Instead, notifications are added to the OpenIDM repository and appear when you log in to the UI.
- Request field: Cancel terminates the process and does not change anything.
Accept starts a user task assigned to the manager of the user (user.0 in this sample).
Click Complete after selecting the values.
5. Log out and log in as the manager of the start user (user.0 in this sample).
6. Next to the User Access Request Approval task in the group queue, select 'Assign to me').
The task is now in the list of 'My Tasks'.
7. Click on Details, next to the task.
The two fields showing the required access rights can be modified by the manager.
Complete the task by clicking Complete button after selecting the Decision.
The decision can be one of the following:
- Reject: The user who initiated the request (in our sample user.1) receives a notification about the
rejection. A notification about this event is generated and is displayed in the UI when
user.1 logs in.
If you configured email notification, an email is sent to the address you configured at the
beginning of the sample.
- Accept: A user task is initiated and assigned to the systemadmin user.
8. If the manager accepted log out and log in as systemadmin (default password is "Passw0rd").
9. Click Details next to the User Access Request Approval task under My Tasks.
The two fields showing the required access rights can be modified by the systemadmin.
Complete the task by clicking Complete after selecting the Decision.
The decision can be:
- Reject: The user who initiated the task (in our sample user.1) receives a notification about the
rejection. A notification about this event is generated and is displayed in the UI when
user.1 logs in.
If you configured email notification, an email is sent to the address you configured at the
beginning of the sample.
- Accept: user.1 is updated in the managed user repository, with the requested changes.
A notification about this event is generated and is displayed in the UI when user.1 logs in.
If you configured email notification, an email is sent to the address you configured at the
beginning of the sample.
In this sample there is an escalation step attached to the manager approval task. If the manager does not
complete the user task within 10 minutes, a new user task is created and assigned to superadmin. This task
has the same interface as the one assigned to the manager of the user and has the same functionality. If
the superadmin completes this task, the execution is passed to the administrator for approval (systemadmin).
Usecase 4 - Orphan Account Detection and Manual Linking Started From Reconciliation
-----------------------------------------------------------------------------------
This use case demonstrates two asynchronous tasks started from reconciliation:
- detecting orphan accounts on the target object set
- handling ambiguous results of the correlation phase
1. Before you start this use case, rename the following file:
samples/usecase/usecase4/conf/syncManagedBusiness.json to samples/usecase/usecase4/conf/sync.json
This file defines a mapping, recon_managedUser_systemBusiness, that has managed users as source and a
CSV file as the target object set. The target object set is defined in samples/usecase/usecase4/data/business.csv.
The CSV file includes all the users from the initial reconciliation (usecase1), who are employees and
therefore have "Business" in their 'accounts' attribute (see usecase2 User Type).
Because this mapping has a 'validSource' field defined, only the managed users who are employees are
taken into account during the reconciliation.
There are some extra users in that csv file:
- user.50 is defined only in the csv file so when running the reconciliation this user will be
detected as an orphan account (orphan account workflow is triggered when the situation is
"UNQUALIFIED" or "UNASSIGNED").
- user.33: the 'userName' attribute of this user is 'user.3', same as for user.3.
When running the correlation query during reconciliation there will be two candidate users
to be linked with user.3 from managed users (correlation query is based on userName attribute).
2. Start OpenIDM with the configuration for usecase4.
$ cd /path/to/openidm
$ ./startup.sh -p samples/usecase/usecase4
3. Run reconciliation.
$ curl -k -u openidm-admin:openidm-admin -H "Content-Type: application/json" -X POST "https://localhost:8443/openidm/recon?_action=recon&mapping=recon_managedUser_systemBusiness"
Two asynchronous workflows are started: an orphanAccountReport for user.50 and a
manualMatch for user.3 of managed users.
4. Log in to the Self-Service UI as systemadmin (with password 'Passw0rd').
5. Next to the Manual Linking Task in the My Tasks list, click Details.
The 'Possible targets' field is modifiable by systemadmin and it is required.
The decision can be one of the following:
- Ignore: no action will be taken (no link will be created) and the workflow terminates.
- user.3 (user.3 - Atrc, Aaron) or user.3 (user.33 - Atrc, Aaron): these are the two candidate
users found in the target object set by executing the correlation query. These values
are queried in the workflow and the possible values of that field are determined
at runtime. Select one user from this list.
After choosing one of the users the workflow links the managed user user.3 to the selected
user in the target object set.
6. Next to the Orphan Account Task in the My Tasks list, click Details.
'Link to' and 'Decision' fields are modifiable by systemadmin.
Complete the task by clicking on 'Complete' button after selecting the Decision.
The decision can be one of the following:
- Link: To select this option, enter a valid managed user ID to link the orphan account to.
You can use any managed user ID that has not yet been linked to a users in the csv file,
for example, user.5.
- Delete: the user will be deleted from the target object set and the workflow terminates.
**Use case 5 has been removed from the sample use cases.**
Usecase6 - Password Change Reminder
-----------------------------------
This use case uses the TaskScanner to trigger a password change reminder workflow.
Managed users have a dedicated attribute to store the date of the last password change event (lastPasswordSet).
The value of this attribute is updated by an onStore script defined in managed.json, which sets the date of
the attribute if a new password is stored for the user. The TaskScanner scans that attribute and starts a
workflow if the password was changed more than an hour ago.
The workflow is started by the usecase6/script/passwordchange.js script.
By default, the workflow sends notifications to the user entry, visible when the user logs into the UI. If you want
notifications sent by email, configure the external email service, as follows:
- Set up external email as described for usecase 2.
- Change the following parameter in the passwordchange.js script:
"emailEnabled" : "false",
to
"emailEnabled" : "true",
- Make sure that all managed users have a valid email address in their "mail" attribute.
The workflow does the following:
- Sends a notification to the user.
- Five minutes later sends another notification to the user (if the password was not changed yet).
- Two minutes later changes the user's 'accountStatus' to 'inactive' and sends notification to the user (if the
password was not changed yet).
1. Start OpenIDM with the configuration for usecase6.
$ cd /path/to/openidm
$ ./startup.sh -p samples/usecase/usecase6
2. Activate the password change task scanner schedule (the schedule is inactive by default):
In samples/usecase/usecase6/conf/schedule-taskscan_passwordchange.json
Change: "enabled" : false, to "enabled" : true,
3. Log in to the Self-Service UI as one of the sample users, e.g. user.0 (default password is 'Passw0rd').
When the task scanner is triggered, a notification is sent to the user in the UI.
4. To test the workflow, change the user's password by selecting Change Password from the top right dropdown list.