11.6 Importing Roles Defined in CSV Files

The Role Catalog provides a wizard for importing roles defined in a comma-separated values (CSV) file. For example, if you define the set of roles you want to implement by using a spreadsheet, you can export the definitions of those roles to a CSV file format, then use the Import Roles Wizard to add the roles to the Role Catalog.

11.6.1 Setting Up the File to Import

When you create a file to use as input to the Import Roles wizard, you must follow the column layout defined in Table 11-9. In addition, you must also follow the CSV file format described in Section 11.6.2, Required CSV File Format.

Table 11-9 Import Record Format

Column Number

Field Name

Description

1

role level

Required field. Valid role levels are: 10, 20, and 30.

  • 10: Permission Role

  • 20: IT Role

  • 30: Business Role

If an invalid role level is specified, the wizard writes the role record to the error file. It does not create the role.

For example:

30

2

sub-container

Optional field. The name of the subcontainer relative to the role level. The wizard creates any subcontainers that do not exist. There is no limit on the number of subcontainers, but five levels is the recommended maximum depth.

For example:

"System\OTB"

3

id

Required field. The role’s identifier (CN). This name must be unique within the role level. If the CSV file contains multiple rows with the same ID, the wizard imports and creates a record for the first one it encounters. It then writes any subsequent records with the same ID to the error file.

For example:

"Doctor"

4

localized display names

Optional field. The the translated string used to display the role name. Accepts zero or more values. The value must be in this format:

"java-locale-code~string" 

The ~ delimits the locale and its localized string. The | symbol delimits each set of locale data.

For example:

"en~Doctor|it~Dottore|fr~Docteur"

If you do not want to localize display names, you can supply a single string. The wizard uses this string as the value for the default Designer locale upon import. If no value is present when you attempt to deploy the associated role, Designer generates a validation error.

5

localized descriptions

Optional field. The translated string used to display the role description. Accepts a list of zero or more values. The value must be in this format:

"java-locale-code~string" 

The ~ delimits the locale and its localized string. The | symbol delimits each set of locale data.

For example:

"en~Doctor|it~Dottore|fr~Docteur"

If you do not want to localize descriptions, you can supply a single string. The wizard uses this string as the value for the default Designer locale upon import. If no value is present when you attempt to deploy the associated role, Designer generates a validation error.

6

categories

Required field. This value should map to a valid category key based on the Role Category list defined in the directory abstraction layer. Accepts a list of zero or more values.

If you do not specify a value, the wizard inserts the role category key default.

If the value is invalid (it does not exist in the directory abstraction layer), the wizard still includes it in the newly created role; however, Designer’s validation requires that this be fixed before the role can be deployed.

For example:

"system|doctor|nurse"

7

owners

Optional field. Represents the distinguished name of the owner of the role. Accepts a list of zero or more values.

For example:

"admin.novell|ablake.users.medical-idmsample.novell”

8

trustees

Optional field. Represents the distinguished name of the trustees of the role. Accepts a list of zero or more values.

For example:

"admin.novell|ablake.users.medical-idmsample.novell”

9

contained roles

Optional field. The role level and common name (CN) of the child or contained roles. Accepts zero or more values.

For example:

"10~Administer Drugs|10~Fill Prescriptions"

10

entitlements

Optional field. DN and parameter values of the role’s entitlements. Accepts zero or more values.

For example:

"Groups.GroupEntitlementLoopback.TestDrivers.novell~Medical Operations|Groups.GroupEntitlementLoopback.TestDrivers.novell~Pharmacy”

11

approval workflow

Optional field. Specifies the name of the provisioning request common name and its quorum value. Valid values include:

  • None: Provide the empty string ““.

  • Standard: Supply key word Standard followed by the quorum value. For example:

    "Standard~50"
    
  • Custom: Enter the provisioning request definition CN. For example:

    "MyCustomPrdCN"
    

Specify Quorum values as follows:

  • Serial: Specify a quorum value of 0.

  • Quorum percentage: Specify a value between 1-100.

12

approvers

Optional field. Represents the distinguished name (DN) of the approvers when the approval workflow value is Standard. The order of the approvers in this field is important if the quorum value is serial. Accepts zero or more values.

For example:

"admin.novell|ablake.users.medical-idmsample.novell”

If the approval workflow is not Standard and you specify a list of approvers, the wizard writes the record to the error file because approvers are not valid.

General Field Formatting Rules

  • Multi-value properties: Use the | symbol as the delimiter between values.

  • DN properties: Specify in dot notation. Designer validates these properties on deploy to ensure that the values correspond to existing Identity Vault objects.

  • Character set encoding must be UTF-8

11.6.2 Required CSV File Format

When you create your spreadsheet to use as input to the Import Roles Wizard, keep in mind that the wizard expects a specific format. It expects a twelve-column document with the columns defined in the order described in Table 11-9. The wizard also expects the input file to follow the CSV format rules defined in RFC4180. This format is briefly summarized below:

  • Each role record is on a separate line.

  • Each field in a role record is separated by a comma and is quoted.

  • Each line is delimited by a line break (CRLF)

  • The first line of the file can be a header line, but this is optional. The wizard allows you to identify whether the file contains a header line.

  • If your file contains a header line, it must contain the role record’s field names. The header line field count must correspond to the field count of each line in the file.

  • Quotes on numbers are not required.

  • A role record example:

    20," ","Doctor","en~Doctor|it~Dottore|fr~Docteur","en~Doctor|it~Dottore|fr~Docteur","doctor",,"admin.novell|ablake.users.medical-idmsample.novell",,"Groups.GroupEntitlementLoopback.TestDrivers.novell~Medical Operations|Groups.GroupEntitlementLoopback.TestDrivers.novell~Pharmacy",,
    
  • Quotes and nested quotes: You can use single quotes within a text field (such as Display name). Use double quotes to enclose a column.

NOTE:For optional fields, the line must include an empty string "" as a placeholder.

11.6.3 Using the Wizard to Import Roles

  1. Open the Provisioning view of the Designer project where you want to import the roles.

  2. Right-click a Role Catalog, the Roles node, or a role level (such as Business Role), then select Import from CSV.

    Designer launches the wizard.

    If you select a role level, the wizard imports only the roles for that level and ignores the other roles in the file.

  3. Fill in the fields as follows:

    Field Name

    Description

    Role CSV File

    Specify the name and location of the CSV file you want to import.

    Ignore header row

    If the file you specify contains a header row, then select Ignore header row in CSV file.

  4. Click Finish.

    The wizard reads the CSV file and adds all of the roles that meet the criteria for import. If the wizard encounters an error (see Error Handling for a list of possible errors), the wizard writes the role record to an error file.The wizard creates the error file in the same location as the Role CSV file to import, and it names the file the same name as the Role CSV file with the _errors appended to the name.

    Only the errors identified in Error Handling are severe enough to prevent the wizard from creating the role. If the wizard encounters other types of errors, it adds the role, but you must make corrections before the role can be deployed. For example, if the category specified in the role is not yet added to the directory abstraction layer role category list, the role can be added, but Designer displays the role with an informational message as shown in Figure 11-1.

    Figure 11-1 Role Imported with Invalid Category Specified

    Roles that are created with errors like this cannot be deployed until the errors are corrected. The Project Checker notifies you of the errors if you attempt to deploy the roles or if you validate the roles objects.

    HINT:If the role has no category, the wizard adds the Default category. If the category supplied does not exist, then it causes the error shown in Figure 11-1.

11.6.4 Error Handling

Table 11-10 describes the cases where a role cannot be imported. When the wizard encounters these errors, it generates an error file and writes the complete role record to the file. It maintains the role’s original column order except that it inserts a new column as the first column in the record. This column includes the error code. You can modify the associated role to fix the error directly within the error file, delete the error code column, then specify this error file as input to the wizard.

Table 11-10 CSV Import Wizard Error Codes

Error Code

Description

INVALID_LEVEL

The row contains a container level that is not valid. This can occur if the level is missing or is not one of these values: 10, 20, or 30.

To fix this problem, change the level to 10, 20, or 30.

ROLE_ID_NOT_UNIQUE

A role with the specified ID in that level already exists. To fix this problem change the ID or the role level.

INVALID_SUBCONTAINER_NAME

The subcontainer name can contain only: alphanumeric characters, digits, underscore, and spaces. To fix this problem, update the subcontainer name to follow these rules.

INVALID_ID_NAME

The role ID contains invalid characters. To fix this problem, edit the name to follow the rules for valid characters: alphabetic characters, digits, underscores, and spaces.

INVALID_ROLE_CN