Import Roles

This section describes how you can develop your own transformation script to import roles. While there are several OTB example, there will be times when its necessary to create your own.

The steps below assume that you have already completed the Synchronization configuration described in the Administrators guide.

While the example below is based on a CVS, the concepts will work with any connector as well. You will need to adjust the incoming source attribute name.

Assume that we are working with the following CSV file:

NAME, DESCRIPTION, CUSTOM_ATTRIBUTE_1, APPROVER_1, ROLE_OWNER, ROLE_ADMIN,PARENT_ROLE
DEVELOPER,Developer role granting access to common tools, ATTR-1-VALUE1, SUPERVISOR,donald.duck,elmer.fudd,NULL
SR_JAVA_DEVELOPER, Senior Java Developer role,ATTR-1-VALUE2,michael.smith ,donald.duck,elmer.fudd,DEVELOPER

While this file appears to be trivial, creating a Groovy script to import this file will demonstrate how to:

Map primary attributes to the Role object
Add custom attributes
Add approvers
Assign role owners and admin
Create hierarchical relationship

Each of above topics will be covered in order they are shown above.

Create new groovy script

The first step in developing a transformation script is to create the body of the script. You can do this by going to Webconsole -> Administration -> Groovy Manager. From the Groovy manager, select the New button has shown below.

New groovy script

Next create the body of the script as show in example below (you may paste the example below to help get started). There are a few things to now when doing this:

Class name below and the Groovy script name must be the same; Change the name to suite your needs. It should be something meaningful to aid in maintainability.
Class must extend AbstractRoleTransformScript as shown below
Class must override execute() and init() shown below.

The execute() and init() will be called by the synchronization framework when synchronization starts. The execute() method is where all the work will need to happen.

import org.openiam.base.AttributeOperationEnum
import org.openiam.idm.srvc.continfo.dto.Address
import org.openiam.idm.srvc.continfo.dto.EmailAddress
import org.openiam.idm.srvc.continfo.dto.Phone
import org.openiam.idm.srvc.org.dto.Organization
import org.openiam.idm.srvc.role.dto.Role
import org.openiam.idm.srvc.role.dto.RoleStatus
import org.openiam.idm.srvc.role.dto.RoleAttribute
import org.openiam.sync.service.TransformScript
import org.openiam.idm.srvc.synch.dto.LineObject
import org.openiam.idm.srvc.user.dto.User
import org.openiam.idm.srvc.user.dto.UserAttribute
import org.openiam.idm.srvc.user.dto.UserStatusEnum
import org.openiam.idm.srvc.user.dto.UserToRoleMembershipXref
import org.openiam.provision.dto.ProvisionUser
import org.openiam.provision.type.Attribute
import org.openiam.idm.srvc.membership.dto.AbstractMembershipXref
import org.openiam.sync.service.impl.service.AbstractRoleTransformScript
import org.openiam.common.beans.mq.RoleRabbitMQService

class MyCSVRoleTransformationScript extends AbstractRoleTransformScript {
    
    /* OTB password policy and role type. customize for your needs. */
    static final String DEFAULT_PASSWORD_POLICY_ID = "4000";
    static final String PROVISION_ROLE_METADATA_TYPE_ID = "PROVISION_ROLE";

    @Override
    int execute(LineObject rowObj, Role role) {
       
        println "** - Role Transformation script called."
        try {
            populateObject(rowObj, role)
        }catch(Exception ex) {
            ex.printStackTrace();
            println "** - Transformation script error."
            return -1;
        }
        println "** - Transformation script completed."
        return TransformScript.NO_DELETE
    }

    private void populateObject(LineObject rowObj, Role role) {

    }

    @Override
    void init() {}



}

Save the script. OpenIAM will ask you for a path. Unless you defined a directory structure for your scripts, consider using /synch/role/.

OpenIAM will compile your script. Only if its free of compilation errors, will the file save successfully. Otherwise, the compilation error will be shown.

New groovy script

Map primary fields

The next step is to develop the populateObject() method that was created in the previous step as a placeholder. We can start by mapping the primary fields such as NAME and DESCRIPTION from the CSV file.

Add the following code fragment to the populateObject() method as shown below.

    /* isNewUser is inherited from AbstractTransformScript and determines if this is a new object. */
    if (isNewUser) {
        role.id = null;
        role.policyId=DEFAULT_PASSWORD_POLICY_ID;
        role.mdTypeId=PROVISION_ROLE_METADATA_TYPE_ID;
        role.status=RoleStatus.ACTIVE.name();
    }

    def columnMap =  rowObj.columnMap

    role.name = columnMap.get("NAME")?.value
    role.description = columnMap.get("DESCRIPTION")?.value

Add custom attribute

The next step in developing our script it to add custom attributes. All entitlement objects in OpenIAM are designed to support custom attributes from both the UI, API(including groovy scripts). The synchronization framework will take care of passing fields from the CSV file to the synchronization script. Follow the steps below to process the custom attributes in the script.

Add the method shown below to your script, after the populateObject() method.

 private void addAttribute(Role r, String attrName, String attrValue) {
        if (r.roleAttributes?.find({ attrName.equalsIgnoreCase(it.name) })) {
            RoleAttribute ra = r.roleAttributes?.find({ attrName.equalsIgnoreCase(it.name) })
            ra.addValue(attrValue)
        } else {
            RoleAttribute ra = new RoleAttribute()
            ra.setRoleId(r.getId())
            ra.setName(attrName)
            ra.addValue(attrValue)
            if (!r.roleAttributes) {
                r.roleAttributes = new HashSet<RoleAttribute>()

            }
            r.roleAttributes.add(ra)
        }
    }

Next, call this method from your populateObject(). Include the custom attribute column name from your CSV file as shown below.

       Attribute attrVal = columnMap.get("CUSTOM_ATTRIBUTE_1")
        if (attrVal) {
            this.addAttribute(role, "CUSTOM_ATTRIBUTE_1", attrVal.value)
        }

Azure AD

Synchronization Validation Script