README revision c355621bcb8725bc8482a3205306b97ebaa2e368
In the usecase folder there are a set of files which together tell a user story based on some common examples.
These files are copied and organized in an appropriate folder structure,
each usecase folder contains the files that are needed for that certain use case sample.
All the samples assume a certain initial setup of managed users in OpenIDM.
The users are organized the following way:
- there are 20 ordinary users: user.0 ... user.19 where
- user.0 .. user.4 belong to Human Resources having user.0 as Manager,
user.0 .. user.3 employees and user.4 contractor
- user.5 .. user.9 belong to Production Planning having user.5 as Manager,
user.5 .. user.8 employees and user.9 contractor
- user.10 .. user.14 belong to Sales & Distribution having user.10 as Manager,
user.10 .. user.13 employees and user.14 contractor
- user.15 .. user.19 belong to Treasury & Payments having user.15 as Manager,
user.15 .. user.18 employees and user.19 contractor
Furthermore we have the following special users:
- 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
List of use cases
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
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 approval step of the manager.
If we want to use email notifications as part of the process make the following changes:
- External email service of OpenIDM has to be configured using the following file:
Update the smtp settings in this file before starting the workflow.
- Change the notification email properties in the workflow definition file:
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.
1. Start OpenIDM with the configuration for usecase2.
$ cd /path/to/openidm
2. Log in to the UI as user.1 (this user belongs to HR department, default password is 'Passw0rd')
3. Select the User Onboarding Process by clicking on it.
4. Fill the fields of the form presented by the UI. The fields marked with x are mandatory.
- Department field:
By selecting one of the four departments we define which department the new user
will belong to. Based on this the workflow will select the possible candidate assignees
for the manager approval user task: it will be either superadmin (as manager of everyone)
or the manager of the selected department (see description above).
example: if HR is selected the manager candidates will be user.0 and superadmin.
- User Type field:
if the User Type field is Employee then the user will have access to an account called "Business".
This is represented on the managed user in OpenIDM repository by having the following attribute on
the managed user:
accounts : [ "Business"]
if the User Type is Contractor then the new user won't have any accounts associated to it in
managed user representation in OpenIDM.
- Send Email Notification field:
If 'No' is selected for this field then no email notifications will be sent.
Notifications will be added to the OpenIDM repository which will appear on UI.
5. Start the workflow by clicking on Start button.
6. Log out and log in as the manager of the department selected in the initial start form
example: if HR was selected then log in as user.0
7. Click on the Onboarding approval task appearing on UI as 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. Click on the Task and then on the 'Details' button.
- Start Date field:
filling this field results in the user being created and adding the startDate property
to the user. Furthermore, the user status will be 'inactive'.
The field is optional, it will be used by TaskScanner to trigger sunrise workflow.
- End Date field:
filling this field results in the user being created and adding the startDate property
to the user.
The field is optional, it will be used by TaskScanner to trigger sunset workflow.
- Manager field:
Selecting yes will add 'title' field to the new managed user with the value 'manager'.
- Decision field:
Selecting 'Reject' terminates the workflow and sends a notification to the start user
of the workflow.
Complete the task by clicking on 'Complete' button.
9. If 'Accept' was selected then the user is created as a managed user in OpenIDM.
The password of the new user is "Passw0rd".
Two OpenIDM notifications are created about this event: one for the start user and one for the
new user. Those are visible on the UI after login with the appropriate user.
If email notification was selected then one email is sent to the user configured at the
beginning of the use case sample.
10. Sunrise workflow
If the sunrise date of the new user was set then the user was created with inactive account status.
To trigger sunrise activate the sunrise task scanner (it's inactive by default):
Change: "enabled" : false
to "enabled" : true
The scan will run every minute and checks for users having sunrise date before
current date plus one day.
Once the scan is triggered it picks the new user, starts the sunrise workflow on it:
- changes the account status to active
- adds an OpenIDM notification to the new user (visible when logging in to OpenIDM UI).
11. Sunset workflow
If the sunset date of the new user was set then sunset workflow can be triggered
To trigger sunset activate the sunset task scanner (it's inactive by default):
Change: "enabled" : false
to "enabled" : true
The scan will run every minute and checks for users having sunset date before
current date plus one day.
Once the scan is triggered it picks the new user, starts the sunset workflow on it:
- a user task is assigned to the manager of the user (e.g. in our sample the assignee is user.0)
- Log in to OpenIDM UI with user.0 and select the task in 'My tasks'
- Decision field:
- Accept termination: the user's account status will be set to inactive and hradmin
receives an OpenIDM notification about it.
- Modify date: the sunset date of the user will be changed and the manager
of the user receives an OpenIDM notification about it (user.0 in our sample).
Usecase 3 - User access request
In this step we simulate a user starting an access request and having 2-level approval for it.
If we want to use email notifications as part of the process make the following changes:
- External email service of OpenIDM has to be configured using the following file:
Update the smtp settings in this file before starting the workflow.
- Change the notification email properties in the workflow definition file:
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 2 occurences of the emailParams, change both.
1. Start OpenIDM with the configuration for usecase3.
$ cd /path/to/openidm
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 is reflecting the current value in OpenIDM database
- Access to Project system field: the value is reflecting the current value in OpenIDM database
- Send Email Notification field:
If 'No' is selected for this field then no email notifications will be sent.
Notifications will be added to the OpenIDM repository which will appear on 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 on Complete after selecting the values.
5. Log out and log in as the manager of the start user (user.0 in this sample)
6. Click on the User Access Request Approval task appearing on UI as 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'.
7. Click on the task and then on the 'Details' button.
The two fields showing the required access rights are modifiable by the manager.
Complete the task by clicking on 'Complete' button after selecting the Decision.
The decision can be
- Reject: the start user (in our sample user.1) receives a notification about the denial. An OpenIDM
notification is created about this event which is visible on the UI after log in with the appropriate user.
If email notification was selected then one email will be sent to the user configured at the
beginning of the use case sample.
- Accept:
Accept starts a user task assigned to systemadmin.
8. If the manager accepted log out and log in as systemadmin (default password is "Passw0rd").
9. Click on the User Access Request Approval task appearing on UI in 'My tasks' and then on the 'Details' button.
The two fields showing the required access rights are modifiable by the systemadmin.
Complete the task by clicking on 'Complete' button after selecting the Decision.
The request can be
- Reject: the start user (in our sample user.1) receives a notification about the denial. An OpenIDM
notification is created about this event which is visible on the UI after log in with the appropriate user.
If email notification was selected then one email will be sent to the user configured at the
beginning of the use case sample.
- Accept: user.1 is updated in managed users table of OpenIDM reflecting the requested changes.
An OpenIDM notification is created about this event which is visible on the UI after login with the appropriate user.
If email notification was selected then one email will be sent to the user configured at the
beginning of the use case 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 then a new user task is created and assigned to superadmin. It has the same user interface
as the one assigned to the manager of the user and has the same functionalities. If the superadmin
completes this task then the execution is passed to the administrator approval (systemadmin).
Usecase 4 - Orphan account detection and manual linking task started from reconciliation
In this use case we show two different asynchronous tasks started from reconciliation:
detecting orphan accounts on the target objects set and handling ambiguous results of correlation phase.
1. Before starting the test we need to rename the following file:
rename samples/usecase/usecase4/conf/syncManagedBusiness.json to samples/usecase/usecase4/conf/sync.json
In that file we have a mapping defined: recon_managedUser_systemBusiness.
This mapping has managed users as source and a csv file as target object set. The target object set
is defined in samples/usecase/usecase4/data/business.csv file.
In that file we have all the users of the initial reconciliation (usecase1) which are employees
and therefore have "Business" in the 'accounts' attribute (see usecase2 User Type).
Since this mapping has a 'validSource' field defined only those managed users will be taken into
account which are employees.
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
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 UI as systemadmin (default password is 'Passw0rd').
5. Click on the 'Details' button of the 'Manual Linking' task.
The 'Possible targets' field is modifiable by systemadmin and it is required.
The decision can be
- 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. Here we can choose the user we need.
After choosing one of the users the workflow will link user.3 of managed user to the selected user
of the target object set.
6. Click on the 'Details' button of the 'Orphan Account' task.
'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
- Delete: the user will be deleted from the target object set and the workflow terminates.
- Link: when choosing this option valid managed user id needs to be entered to link the orphan account to.
Pick any user id from managed users where the managed user is not linked to any users in the csv file yet:
if this use case is started after the initial reconciliation then pick e.g. user.5.
If users are created e.g. by using sample2 that user can be used here as well.
Usecase5 - Certification workflow
In this use case we have a scheduled task fetching all the managed users and starting a certification workflow
for all of them.
1. Start OpenIDM with the configuration for usecase5.
$ cd /path/to/openidm
2. The scheduled task can be triggered by enabling the scheduled task in the
3. Log in to the UI as user.0 (default password is 'Passw0rd').
4. Click on the Certification process task appearing on UI as 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'.
5. Click on the 'Details' button of the 'Access Status Check' task.
- 'Access to Business system:' and 'Access to Project system:' fields can be modified.
Those reflect the content of the 'accounts' field of the managed user being certified.
6. Complete the task by clicking on 'Complete' button after selecting the Decision.
The decision can be
- Certify: no action will be taken, the certified user is not modified and the workflow terminates.
- Change: a new user task is created and assigned to systemadmin user.
7. If 'Change' was selected in the previous step log in to the UI as systemadmin.
8. Click on the 'Details' button of the 'Access Status Check' task.
- 'Access to Business system:' and 'Access to Project system:' fields can be modified.
9. Complete the task by clicking on 'Complete' button after selecting the Decision.
The decision can be
- Accept: the user being certified is updated by the actual values of the access fields
and a notification is sent to the user about the change
(visible on the UI after log in with the appropriate user).
- Reject: the user being certified will not be modified and a notification is sent to the manager
about the certification change request being rejected by systemadmin.
Usecase6 - Password change reminder
In this use case we use TaskScanner to trigger a password change reminder workflow.
Every managed user created in OpenIDM has a dedicated attribute to store the date of the last password change event (lastPasswordSet).
This value is updated by an onStore script defined in managed.json which
sets the date of this 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 passwordchange.js javascript. There are two options to run this workflow:
- By default it sends the default OpenIDM notifications to the user (visible on the UI).
- It can send email notification to the user if configured.
External email service of OpenIDM has to be configured using the following file:
Update the smtp settings of this file and copy it to samples/usecase/usecase6/conf/ folder.
Note that if you want to use this option you have to make sure that the 'mail' attribute of the
managed user(s) used for this test case are valid email addresses.
To enable email notifications change the following parameter of passwordchange.js:
change "emailEnabled" : "false",
to "emailEnabled" : "true",
The workflow does the following:
- sends a notification to the user
- five minutes later sends an other notification to the user (if password was not changed yet)
- two minutes later changes the user's 'accountStatus' to 'inactive' and sends notification to the user (if password was not changed yet)
1. Start OpenIDM with the configuration for usecase6.
$ cd /path/to/openidm
2. Activate the password change task scanner (it's inactive by default):
Change: "enabled" : false
to "enabled" : true
3. Log in to the UI as one of the sample users, e.g. user.0 (default password is 'Passw0rd').
Once the task scanner was triggered a notification is visible for the user on the OpenIDM UI.
4. To test the workflow the user can change the password either on the UI or using the following REST call:
curl -u openidm-admin:openidm-admin -X POST "http://localhost:8080/openidm/managed/user/user.0?_action=patch" -H "Content-Type: application/json" --data '[{"operation":"replace", "field":"password", "value":"newPassw0rd"}]'