Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
tutorial:adm:roles_-_import_data_from_csv [2019/06/12 14:15] – hanakptutorial:adm:roles_-_import_data_from_csv [2026/03/13 10:28] (current) – cem
Line 1: Line 1:
 ====== Roles - Import of data from CSV ====== ====== Roles - Import of data from CSV ======
  
-===== 1a. Prepare some virtual system =====+==== 1. Prepare the CSV file ====
  
-Please use [[tutorial:adm:how_to_create_virtual_system|this]] tutorial to do so!+Here is an example of a CSV file which can be used for importing (or updating) roles, setting their role attributes, guarantees (by user, or by role) and criticality, for saving them in a created catalogue and for assigning their subordinate role. To use this CSV file, create a new identity with user name <nowiki>"user-login"</nowiki>, and a new role with code <nowiki>"role_code"</nowiki> to set guarantees. Have a virtual system called 'test'.
  
-==== 1b. Prepare CSV file ====+<code> 
 +roles;code;description;attribute;guarantees;guarantee_type;guarantee_role;guarantee_role_type;criticality;catalogue;subroles;eavcode1;eavvalue1;systemname1;systemattr1;systemvalue1 
 +testimportrolename;testimportrolecode;desc;attr1;user-login;;role_code;;4;cat1|cat3;;eav;value;test;rights;testimportrolename
  
-Here is an example of CSV file which can be used for import roles. 
- 
-<code> 
-roles;description 
-Manager;Some role description 
-"MASTER RO 
-PAY-OP 
-PAY-SP 
-PAY-BLL 
-AMT-BLK 
-ACC-CLOSE";Some roles description 
 </code> </code>
  
-As you can see roles column can be single or multivalued. For multivalued roles, description from the same row will be added to every role. +In Excel, it looks like this: {{  .:00_csv.png?direct&800  }} 
-CSV file can have optional number of columns, role and description columns are specified in setup of LRT.+ 
 +As you can see roles column can contain single or multiple values (separated by a line; the separator can be specified in the settings of the LRT). For multivalued roles, values from the same row will be added to every role. The only exception here is role criticality which cannot be multivalued. CSV file can have optional number of columns: column names are specified in setup of LRT. 
 + 
 +The result of this LRT used with this CSV file should be that one new role testimportrolename (with code testimportrolecode) will be created. It will have these properties: 
 + 
 +  * description: 'desc' 
 +  * attribute: 'attr1' 
 +  * guarantee: user with username 'user-login' 
 +  * guarantee by role: role with the code 'role_code' 
 +  * criticality: 4 
 +  * catalogue: it will be in 'cat1' and 'cat3' 
 +  * it will have EAV with code 'eav' with value 'value' 
 +  * it will create an account on system 'test' and set value of attribute 'rights' to 'testimportrolename' 
 + 
 +<note important>CzechIdM uses by defaul utf-8 encoding. If your input file is encoded in diferent encoding, or if you experience some issues with non english characters, you may set different encoding in configuration of import long running task. Examples of other used encodings might be windows-1250, utf-8 or windows-1252</note>
  
 ==== Create new LongRunningTask ==== ==== Create new LongRunningTask ====
  
-Now we will create the new LongRunningTask(LRT). As shown in the picture, go to Settings → Task scheduler → Scheduled tasks and hit green "Add" button to add new LRT.+Now we will create the new LongRunningTask (LRT). As shown in the picture, go to Settings → Task scheduler → Scheduled tasks and hit green "Add" button to add new LRT. Select the task **Import roles from CSV**. (ImportRolesFromCSVExecutor) 
 + 
 +{{  .:03_scheduler.png?direct&1200  }}
  
 ==== Fill all attributes ==== ==== Fill all attributes ====
Line 31: Line 38:
 Now we need to create new LRT with these attributes: Now we need to create new LRT with these attributes:
  
-- Task type - **ImportRolesFromCSVExecutor** +**General:** 
-- Import csv file - dropzone to select or drop csv file + 
-- Column with roles - Name of the column with roles in csv file +  * Upload a CSV file - dropzone to select or drop csv file 
-- Column with description - name of the column with role description, can be also used to update description +  * Column with role names - name of the column with roles in csv file 
-- Column separator - separator of columns in csv file +  * Column with role codes - name of the column with role codes in csv file; if left empty, the role code is based on the role name, only spaces are replaced by underscores 
-- Multi value separator - ( Char, default: new line ) separator of multi valued role names in csv file, new line separator is default export from excel, but for better clarity of csv file, it's recommended to use some symbol instead +  * Column with description - name of the column with role description, can be also used to update description (if your CSV file doesn't contain descriptions, i.e., you are not setting description for any of your roles, leave this line empty) 
-- System name - name of the system to connect with roles +  * Column with criticality - name of the column with role criticality, can be also used to update criticality (if your CSV file doesn't contain criticality, i.e., you are not setting criticality for any of your roles, leave this line empty); if no criticality is specified, the default is 0 
-- MemberOf attribute name - ( default: rights ) - name of multi valued attribute for merge, attribute named "rights" is automatically created on every virtual system, but you can create your own and change setup of LRT +  * Column with catalogue names - name of the column with catalogue names, can be also used to update catalogue names (if your CSV file doesn't contain catalogue names, i.e., you are not setting catalogues for any of your roles, leave this line empty) 
-- Can be requested - ( Boolean ) - Fills can be requested, can be also used to update already imported settings+  * Column with subrole codes - name of the column with subordinate roles codes, can be also used to update subordinate roles (if your CSV file doesn't contain subordinate roles codes, i.e., you are not setting subordinate roles for any of your roles, leave this line empty) 
 +  * Column separator - separator of columns in csv file (default ; ) 
 +  * Multi value separator - (Char, default: |) separator of multi valued role names in the csv file, new line separator is default export from excel, but for better clarity of the csv file, it's recommended to use some symbol instead 
 +  * Role environment - the name of the environment to which you want to add the role; only supported during creating, not updating roles! 
 +  * Can be requested - (Boolean) - Roles can be requested, can be also used to update already imported settings; it allows not selecting value when updating (not when creating!) roles which will not change the Can be requested property of roles. When creating roles, either Yes or No must be selected. 
 +  * Skip assignments of sub-roles - If checked, sub-roles won't be assigned to users with assigned parent role (useful for sub-role assignment under roles which aren't assigned to user, available from version 14.6.0) 
 + 
 +**Role attributes:** 
 + 
 +  * Column with role attributes - name of the column with role attributes, can be also used to update attributes (if your CSV file doesn't contain attributes, i.e., you are not setting attributes for any of your roles, leave this line empty) 
 +  * Form definition code - the code for the definition which will contain the added attributes (you only have to fill this if you are setting attributes) 
 + 
 +**Role EAVs:** 
 + 
 +You can set value to multiple role EAVs. The mechanism used for this is prefixes which are followed by the order number of the column (e. g., 'eavcode1', where 'eavcode' is the prefix and '1' the order number). The combination of the prefix and the number identifies a column uniquely. 
 + 
 +  * Prefix of column with name of EAV attribute: Only attributes from the main role definition can be imported and they must of type SHORTTEXT. Supports update (the current value of the attribute will be overwritten if imported). 
 +  * Prefix of column with value of EAV attribute 
 + 
 +**Guarantees:** 
 + 
 +  * Column with guarantee - name of the column with role guarantee by identity login, can be also used to update guarantee (if your CSV file doesn't contain guarantees, i.e., you are not setting guarantees for any of your roles, leave this line empty) 
 +  * Column with guarantee types - name of the column with role guarantee by identity [[.:new_role|type]] (if your CSV file doesn't contain guarantee types, i.e., you are not setting guarantee types for any of your roles, leave this line empty) (since Extras 2.2.0) 
 +  * Update guarantee types - check if you want to add new guarantee type to an existing guarantee (this will create a new guarantee with the selected type, the original one will still exist) (since Extras 2.2.0) 
 +  * Column with guarantee role - name of the column with role guarantee by role code, can be also used to update role guarantee (if your CSV file doesn't contain role guarantees, i.e., you are not setting role guarantees for any of your roles, leave this line empty) 
 +  * Column with guarantee role types - name of the column with role guarantee by role [[.:new_role|type]] (if your CSV file doesn't contain guarantee role types, i.e., you are not setting guarantee role types for any of your roles, leave this line empty) (since Extras 2.2.0) 
 +  * Update guarantee role types - check if you want to add new guarantee type to an existing guarantee role (this will create a new guarantee with the selected type, the original one will still exist) (since Extras 2.2.0) 
 + 
 +**System:** 
 + 
 +You can set attributes at multiple systems or set multiple attributes in one system. The mechanism used for this is prefixes which are followed by the order number of the column (e. g., 'systemname1', where 'systemname' is the prefix and '1' the order number). The combination of the prefix and the number identifies a column uniquely. 
 + 
 +  * Prefix of column with system name 
 +  * Prefix of column with system attribute codes 
 +  * Prefix of column with system attribute values: The attribute has to a multivalued attribute with merge strategy set. It should not contain ":" (colon), see the important note below. 
 + 
 +Since module version **14.1.0** **15.1.0**, you can configure columns for parameters that specify the selection of mapping for linking a role to a system. All of these parameters are optional: 
 + 
 +  * prefix of column with flag whether the role creates an account on the system: If not set, the default value is true. In import file, you can use values true/false, yes/no, or 1/0 (case-insensitive). 
 +  * prefix of column with entity type: If not set, IDENTITY is used by default. Possible values are IDENTITY and TECHNICAL_ACCOUNT. 
 +  * prefix of column with account type: If not set, this field remains empty. Possible values are PERSONAL, PERSONAL_OTHER (both are compatible with the IDENTITY entity type), and TECHNICAL (compatible with the TECHNICAL_ACCOUNT entity type). 
 + 
 +The entity type and account type act as filters for available mappings. The system selects the first mapping returned by the filter (if multiple mappings match, one is selected essentially at random). The flag for account creation then defines the specific behavior for that link; in previous versions, the default behavior was always used, where the role automatically creates an account on the system. 
 + 
 +For example, consider the following import file: 
 +<code> 
 + 
 +name;code;system1;roleCreatesAccount1;accountType1;entityType1;system2;roleCreatesAccount2;accountType2;entityType2 
 +My role;my-role;Some system;Yes;PERSONAL;IDENTITY;Other system;false;PERSONAL_OTHER;IDENTITY 
 + 
 +</code> 
 + 
 +Set the folowing: 
 + 
 +  * Prefix of column with system name: system 
 +  * Prefix of column with the setting of whether the role automatically creates an account on the system: roleCreatesAccount 
 +  * Prefix of column with account type: accountType 
 +  * Prefix of column with entity type: entityType 
 + 
 +Then, the import 
 + 
 +  - will create a role with the name 'My role' and the code 'my-role' 
 +  - will connect the role with system Some system via provisioning mapping of personal accounts and role assignment will create account on system 
 +  - will connect the role with system Other system via provisioning mapping of other personal accounts and role assignment won't create account on system 
 + 
 +<note important>If you are updating the roles, make sure to set the same form definition the role already have (if they have any). Also, each role can only have one definition, so if you by mistake set a different definition in the LRT configuration, you will likely get an error. Generally, DO NOT use this LRT to change the definition of a role. You can only change the definition if the role has no attributes set yet. Supports update (the current value of the attribute will be overwritten if imported).</note> 
 + 
 +<note important>System attribute values currently do NOT support ":" (colon) character. If the value contains a colon, the whole string after the colon is ignored.</note> 
 + 
 +<note>This LRT can be used to update existing values but it **does not**  remove old values. The only overwritten values during update are role criticality, description and MemberOf attribute value. They will be changed only if they are not empty in the CSV file</note> 
 + 
 +{{  .:lrt_roles_import.jpg?nolink&  |lrt_roles_import.jpg}}
  
-{{:tutorial:adm:import-roles-lrt.png?500|}} 
 ==== Run the task ==== ==== Run the task ====
  
-Now we just need to hit run.+Now we need to hit run.
  
-{{:tutorial:adm:aaaaaaaa6.png?100|}}+{{.:aaaaaaaa6.png?100}}
  
-And we also need to process it in all tasks.+Now we must go to the "all tasks" panel, select the newly created LRT (check the checkbox), click Operation with selected record and Run selected task.
  
-{{:tutorial:adm:aaaaaaaa7.png?400|}}+{{  .:05_start.png?direct&1200  }}
  
-You can check status about created roles in "all tasks" panel in task detail. Here you can find information about created, updated or already existing roles.+You can also check the status of the created roles there in the task detail. Here you can find information about roles created, updated, or already existing.
  
-Everything should be set up so far and when the task ends, roles are imported in IdM, placed in catalogue named by system name.+At this point, everything should be set up and when the task ends, roles are imported in IdM with their attributes and other imported values, and placed in the catalogue named by the system name. 
 + 
 +{{  .:04_resultrole.png?direct&1200  }}
  
 ==== Known issues ==== ==== Known issues ====
  
 If you delete or upload new file via dropzone, you should delete old files, created from previous uploads. If you delete or upload new file via dropzone, you should delete old files, created from previous uploads.
 +
  
  • by hanakp