12.3 Importing Resources Defined in CSV Files

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

12.3.1 Setting Up the File to Import

When you create a file to use as input to the Import Resources Wizard, you must follow the column layout defined in Table 12-3. In addition, you must also follow the CSV file format described in Section 12.3.2, Required CSV File Format.

Table 12-3 Import Record Format

Column Number

Field Name

Description

1

id

Required field. The resource’s identifier (CN). This name must be unique . 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"

2

localized display names

Optional field. The translated string used to display the resource 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 resource, Designer generates a validation error.

3

localized descriptions

Optional field. The translated string used to display the resource 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 resource, Designer generates a validation error.

4

categories

Required field. This value should map to a valid category key based on the resource 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 resource 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 resource; however, Designer’s validation requires that this be fixed before the resource can be deployed.

5

owners

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

For example:

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

6

trustees

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

For example:

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

7

Grant 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.

8

Grant Approvers 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.

9

Revoke 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.

10

Revoke Approvers 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 the keyword 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.

11

Role Approval overrides Resource Approval

Boolean field for Role Approval to override Resource Approval. It takes True or False.

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.

12.3.2 Required CSV File Format

When you create your spreadsheet to use as input to the Import Resources 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 12-3. The wizard also expects the input file to follow the CSV format rules defined in RFC4180. This format is briefly summarized below:

  • Each Resource record is on a separate line.

  • Each field in a Resource 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, then it must contain the Resource 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 resource record example:

    Doctor,en~Doctor,en~Doctor|it~Dottore|fr~Docteur,,admin.novell|ablake.users.medical-idmsample.novell,admin.novell|ablake.users.medical-idmsample.novell,admin.novell|ablake.users.medical-idmsample.novell,Standard~50,admin.novell|ablake.users.medical-idmsample.novell,MyCustomPrdCN,true
    
  • 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.

12.3.3 Using the Wizard to Import Roles from a CSV File

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

    Select the Resources node, right-click then select Import from CSV.Designer launches the wizard.

  2. 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, select Ignore header row in CSV file.

  3. Click Finish.

The wizard reads the CSV file and adds all the resources 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 Resource 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 resource. If the wizard encounters other types of errors, it adds the resource, but you must make corrections before the resource 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 resource can be added, but Designer displays the resource with an informational message.

Resource 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 resource or if you validate the resource objects.

12.3.4 Error Handling

Table 12-4 describes the cases where a resource cannot be imported. When the wizard encounters these errors, it generates an error file and writes the complete resource record to the file. It maintains the resource 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 resource 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 12-4 CSV Import Wizard Error Codes

Error Code

Description

RESOURCE_ID_NOT_UNIQUE

A resource with the specified ID already exists.

INVALID_ID_NAME

The resource 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_RESOURCE_CN

The role ID contains invalid characters.