14.0:documentation:modules_extras:approval_of_extern_created_from_hub

Approval of externs created from Hub

This feature brings the possibility to have all externs created from Hub approved by someone in IdM. Who should approve and what should happen when approved/disapproved is fully configurable, because it is encapsulated in IdM scripts.

When this feature is enabled and there is extern created from Hub, it is created in disabled state (identity has DISABLED state and all its contracts EXCLUDED state). Approval workflow is started and standard approval task is created (so standard notifications to approvers are sent and it can be seen on dashboard). Upon task approval/disapproval configured scripts are processed.

Configuration

To set up this feature, you need to add some configuration:

Meaning:

  • idm.sec.hub.extern.creation.approvable - must exist and be set to true to enable the feature
  • idm.sec.hub.extern.creation.approval.workflow - workflow used for approval, the only meaningful value now is extrasApproveExternCreationFromHub (it is configurable because in case there would be e.g. need to have approval from two IdM users, all you have to do is to create workflow with two approvers and set it here)
  • idm.sec.hub.extern.creator.role - role identifying user that creates externs from Hub, so the meaning is "if (and only if) extern is created by user with this role (and approval is enabled), then start approval process"
  • idm.sec.hub.script.approve - IdM system script that performs desired action in case creation is approved (for reference purposes let it be extrasApproveIdentityRequestViaHub)
  • idm.sec.hub.script.approvers - IdM system script that returns list of IdM users which can approve extern creation (for reference purposes let it be extrasGetApproversForIdentityRequestViaHub)
  • idm.sec.hub.script.disapprove - IdM system script that performs desired action after in case creation is disapproved (for reference purposes let it be extrasDisapproveIdentityRequestViaHub)

    Scripts

There are three scripts mentioned in configuration, so we need to create them. Each receives two input variables that can be used (so it is possible e.g. to define approvers dynamically as guarantees of org unit extern should be in or as manager of creator):

  • externId - UUID of created extern
  • creatorId - UUID of user that created the extern in Hub

This script defines what happens when extern creation is approved. When extern identity that should be approved is created, it is set to DISABLED state and all its contracts are set to EXCLUDED state. So the minimal meaningful action in this script should be to set identity state to VALID and all contracts to default state:

import eu.bcvsolutions.idm.core.api.domain.IdentityState;
//
identity = identityService.get(externId);
identity.setState(IdentityState.VALID);
identityService.save(identity);
//
contracts = identityContractService.findAllByIdentity(identity.getId());
if (contracts != null) {
  for (contract in contracts) {
    contract.setState(null);
    identityContractService.save(contract);
  }
}

For this script to work, it has to have these authorities:

Service: identityContractService
Service: identityService
Class: eu.bcvsolutions.idm.core.api.dto.IdmIdentityContractDto
Class: eu.bcvsolutions.idm.core.api.dto.IdmIdentityDto

This script returns list of possible approvers (any of them can approve creation). The simplest and still quite powerful implementation is to return all users with specific role:

return identityService.findAllByRoleName("externApprover");

And authority for this script:

Service: identityService

This script defines what happens when extern creation is disapproved. For example we can delete that rejected extern in IdM:

identityService.deleteById(externId);

And authority for this script:

Service: identityService