Customizing with User Hooks
This section gives hints for customizations with user hook implementations.
| if you configure user hooks, you must provide their implementation in Java *.jar libraries and deploy them to the relevant IdS-J Server into the sub-folder confdb/jobs/ CertificationCampaign/lib.After you complete these tasks, make sure you re-start the IdS-J Server. |
Documentation and Sample Source Code
You can find the Java documentation of the user hooks interfaces and samples on the DirX Identity DVD in the folder:
Documentation/DirXIdentity/CertificationCampaign
The sample source code is delivered in the folder:
Additions/CertificationCampaign
Select Approvers with a “Find Approvers” User Hook
The Find Approvers user hook allows you to change the default approvers for certifications. For a user certification campaign, the default approver is the manager of the user, and for a privilege certification campaign, the default approver is the owner of the privilege. You can override this default implementation with a custom Find Approvers user hook.
The FindApprovers user hook must implement the FindApproversUserhook Java interface. This interface contains the following methods:
void setContext(FindApproversContext context);FindApproversContext getContext();boolean before();boolean after();TreeNode<StorageObject> findApprover(FindApproversContext context) throws NoApproverException;The method setContext is used by the campaign controller to give the user hook access to some DirX Identity context objects:
GlobalContext object – an object that can be used to access different attributes from the IdS-J Server.
Campaign object - a StorageObject that contains details about the current campaign.
Certification object - a StorageObject that contains details about the current certification task.
Subject object - a StorageObject that contains details about the current subject to be certified (for example, in a user certification campaign, it is a SvcUser object).
Inside the user hook, you can change objects, especially the Certification (task). For example, you can store the due date in the attribute dxrEndDate. If you do so, you must store your changes to LDAP on your own.
Before – Creating the Certification Task in the User Hook
The method before() is executed before all controller actions and the method after() is called after the controller finishes all the actions for the current certification object. If these methods return false, the default implementation of the Certification Campaign controller will not be executed.
This is especially important for the method before(). If it returns false, the controller assumes that the complete certification task object has been created by the user hook. In this case, the user hook must find the approvers, the assignments to certify per subject (user), set the state and the start and end dates, and at the end save the certification task object(s).
After – Changing Default Attributes
When the method after() is called, the certification object has already been created and saved to LDAP. The user hook can then override some attribute values and must store its changes in LDAP.
Find Approvers – Adding Additional Approvers
You can also use the Find Approvers user hook to add more approval tasks (called sub-certifications) for the given subject. In this way, you can even create a hierarchy of approval tasks by several approvers, as illustrated in the following diagram:
To create this kind of structure for a certification, you must implement the following method inside the FindApprovers user hook:
TreeNodeStorageObject findApprover(FindApproversContext context)
This method returns a tree structure of StorageObjects. The controller creates a certification object (which reflects one approval task) for each approver in the tree structure. The tasks are processed according the campaign field Approver Sequence top down or bottom up. Each sub-certification follows the same states as a normal certification. The last approval task determines the state of the whole subject certification.
Select Campaign Subjects with a “Find Subjects” User Hook
A user hook that implements the FindSubjectsUserhook Java interface can select the subjects. The subjects are users for a user certification and privileges for a privilege certification. This action is helpful when an LDAP filter is not sufficient to identify the subjects of the campaign.
You need to implement the following methods:
FindSubjectsContext getContext()setContext(FindSubjectsContext context)List<String> findSubjects(FindSubjectsContext context)The first two methods have the same functionality as in the FindApprovers user hook. You can use setContext method to store the FindSubjectContext object.
The method findSubjects is called before the controller starts to find the subjects for the certification campaign. You can use this user hook method to override this functionality and return your own list of subjects (a list of DNs) instead. The FindSubjectContext provides access to a GlobalContext object and to the Campaign object.
Limit Resources with a “Limit Resources” User Hook
A user hook that implements the LimitResourcesUserhook Java interface can reduce the list of resources to be certified. The resources are privileges for a user certification and users for a privilege certification.
The default implementation considers the resource base and filter. If they are empty, all resources must be certified. If they have values, the resources must be descendants of the resource base (including the resource base itself), and their attributes must match the LDAP filter.
If the LDAP filter is not sufficient, you can implement this user hook. If you do, both resource base and resource filter are ignored.
You need to implement the following methods:
LimitResourcesContext getContext()setContext(LimitResourcesContext context)List<String> limitResources(LimitResourcesContext context)The first two methods have the same functionality as the FindApprovers user hook. You can use the setContext method to store the LimitResourcesContext object.
The method limitResources is called before the controller starts to find resources for the certification campaign. You can use this user hook method to override this functionality and return your own list of resources (a list of DNs) instead. The LimitResourcesContext provides access to the GlobalContext object and to the Campaign object.
Send emails with the “Send Email” User Hook
With a user hook that implements the SendEmailUserhook Java interface, you can send notifications your own way.
The user hook needs to implement the following methods:
SendEmailContext getContext()setContext(SendEmailContext context)boolean onSendEmail (SendEmailContext context)boolean before()boolean after()The first two methods have the same functionality as the FindApprovers user hook. You can use setContext method to store the SendEmailContext object.
The SendEmailContext method contains the following objects: GlobalContext object, Campaign object, a list with Certification objects used for sending emails, a list with NotificationProcessor objects which can be used to process the email templates.
The before() and after() methods are called before and after sending emails. If these methods return false, the default implementation from the Certification Controller will not be executed.
With the onSendEmail method, you can override the default implementation of the Certification Campaign controller. If you don’t want to execute the default sendEmail implementation, the user hook method must return false.
Override Campaign Creation with “Campaign Creator”
With an implementation of the CampaignCreatorUserhook Java interface, you can completely override the creation of a campaign: find the subjects, select the assignments and calculate the approvers.
You need to implement the following methods:
CampaignContext getContext()setContext(CampaignContext context)boolean before()boolean after()The first two methods have the same functionality as the FindApprovers user hook. You can use the setContext method to store the CampaignContext object.
The method before() is called by the controller when it is ready to start creation of the certifications task entries. If it returns false, the controller skips the default implementation and assumes that all the certification tasks have been created and stored by the user hook.
If the method after() returns false, the default implementation is skipped, which means that the notification about the started campaign will not be sent.