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:how_to_contract_sync [2019/08/14 13:19] – [Check contracts on user 'john.roe'] doischerttutorial:adm:how_to_contract_sync [2022/12/21 09:27] (current) – moved the info about correlation to docu apeterova
Line 1: Line 1:
-====== Systems - CSV file: users contracts synchronization  ======+====== Systems - CSV file: users contracts synchronization ====== 
 {{tag> contract tutorial sync}} {{tag> contract tutorial sync}}
  
 ===== What is synchronization of contractual relationships? ===== ===== What is synchronization of contractual relationships? =====
-The principle of this synchronization is the same as for identity synchronization. However, the aim of this synchronization is not a direct identity, but his/her contractual relationship. 
-More on what constitutes a contractual relationship can be found [[devel:dev:contractual-relationship|here]]. 
-<note tip>Typically, one contractual relationship is equal to one contract in a company per identity.</note> 
  
-<note>More on the sync of contractual relationships can be found here [[devel:dev:synchronization:relation-sync|here]].</note>+The principle of this synchronization is the same as for identity synchronization. However, the aim of this synchronization is not a direct identity, but his/her contractual relationship. More on what constitutes a contractual relationship can be found [[:devel:documentation:contracts|here]]. <note tip>Typically, one contractual relationship is equal to one contract in a company per identity.</note> 
 + 
 +<note>More on the sync of contractual relationships can be found [[:devel:documentation:synchronization:dev:relation-sync|here]].</note>
  
 ===== What you need before you start ===== ===== What you need before you start =====
-    * You need to install CzechIdM 7.5.0 (and higher). + 
-    * You need to be logged in as 'admin'. +  * You need to install CzechIdM 7.5.0 (and higher). 
-    * You need to have two users ready: 'john.doe' and 'john.roe'.+  * You need to be logged in as 'admin'. 
 +  * You need to have two users ready: 'john.doe' and 'john.roe'.
  
 ===== Create data with contracts in CSV format ===== ===== Create data with contracts in CSV format =====
-First we need to create sample data that we will synchronize. + 
-We will be using the CSV connector, for which we need to create a CSV source file with our sample contracts.+First we need to create sample data that we will synchronize. We will be using the CSV connector, for which we need to create a CSV source file with our sample contracts.
  
 Here are the sample data in CSV format: Here are the sample data in CSV format:
 <code> <code>
 +
 ID,NAME,STATE,DISBLED,DESCRIPTION,VALID_FROM,VALID_TO,TEAM_LEADER,LEADER,MAIN,CHANGED,ORGANIZATION_NAME,ORGANIZATION_CODE,OWNER ID,NAME,STATE,DISBLED,DESCRIPTION,VALID_FROM,VALID_TO,TEAM_LEADER,LEADER,MAIN,CHANGED,ORGANIZATION_NAME,ORGANIZATION_CODE,OWNER
 1,"Contract one","30","false","visualize dot-com ROI","2016-05-04","2016-06-21","john.doe","john.doe","true","2016-06-25","Skinder","68016-376","john.roe" 1,"Contract one","30","false","visualize dot-com ROI","2016-05-04","2016-06-21","john.doe","john.doe","true","2016-06-25","Skinder","68016-376","john.roe"
 2,"Contract two","20","true","revolutionize viral experiences","2017-04-06","","","","true","2016-06-15","Einti","60429-911","john.roe" 2,"Contract two","20","true","revolutionize viral experiences","2017-04-06","","","","true","2016-06-15","Einti","60429-911","john.roe"
 +
 </code> </code>
  
-Create a new file "contracts.csv" which contains the above data. This file can be saved in your user space. In my case, the path is: "/home/svandav/csv/contracts.csv". +Create a new file "contracts.csv" which contains the above data. This file can be saved in your user space. In my case, the path is: "/home/svandav/csv/contracts.csv".
  
 ===== Create system 'Contracts - CSV' ===== ===== Create system 'Contracts - CSV' =====
-Create a new system in CzechIdM, with the name 'Contracts - CSV'. 
  
-{{ :tutorial:adm:contract-new-system.png |}}+Start on the main screen, select Systems and click the Add button. Create a new system in CzechIdM, with the name 'Contracts - CSV'.
  
 ==== Connector configuration ==== ==== Connector configuration ====
-Now we can configure the CSV connector and its settings. + 
 +Now we can configure the CSV connector and its settings.
  
 <note important>Remember, you have to set correct path to your contracts.csv file!</note> <note important>Remember, you have to set correct path to your contracts.csv file!</note>
  
-{{ :tutorial:adm:contract-connector-config_one.png |}}+{{  .:contract-connector-config_one.png  }}
  
-{{ :tutorial:adm:contract-connector-config_two.png |}}+{{  .:contract-connector-config_two.png  }}
  
 ==== Generate schema ==== ==== Generate schema ====
  
-Once we have configured the system, we need to generate its schema. +Once we have configured the system, we need to generate its schema. Go to the scheme tab and click on the "Generate scheme" button.
-Go to the scheme tab and click on the "Generate scheme" button.+
  
-{{ :tutorial:adm:contract-schema.png |}}+{{  .:contract-schema.png  }}
  
 ==== Create sync mapping ==== ==== Create sync mapping ====
 +
 System mapping for synchronizing contractual relationships can be created in the tab "Mapping". System mapping for synchronizing contractual relationships can be created in the tab "Mapping".
  
-{{ :tutorial:adm:contract-mapping.png |}}+{{  .:contract-mapping.png  }}
  
 ==== Create mapped attributes ==== ==== Create mapped attributes ====
 +
 Now we have to map our attributes. These are definitions specifying the way the data from our CSV file should be represented in IdM. Now we have to map our attributes. These are definitions specifying the way the data from our CSV file should be represented in IdM.
  
 === Primary attribute === === Primary attribute ===
 +
 One of the attributes must be selected as primary identifier. One of the attributes must be selected as primary identifier.
  
-* Select '_ _ NAME _ _' from schema attributes. +* Select '_ _ NAME _ _' from schema attributes. * Checkbox 'Identifier' must be checked. {{  .:contract-attribute-nameid.png  }}
-* Checkbox 'Identifier' must be checked. +
-{{ :tutorial:adm:contract-attribute-nameid.png |}}+
  
 === Name attribute === === Name attribute ===
 +
 Defines the name of the contractual relationship. Defines the name of the contractual relationship.
  
-* Select 'NAME' from schema attributes. +* Select 'NAME' from schema attributes. * Tick checkbox 'Entity attr.'. * In the 'Entity field' select the item 'Name of positions'.
-* Tick checkbox 'Entity attr.'. +
-* In the 'Entity field' select the item 'Name of positions'.+
  
-{{ :tutorial:adm:contract-attribute-name.png |}}+{{  .:contract-attribute-name.png  }}
  
 === Guarantee attribute === === Guarantee attribute ===
 +
 Defines the list of superiors, directly linked to the contractual relationship (more details see below). Defines the list of superiors, directly linked to the contractual relationship (more details see below).
  
-* Select 'LEADER' from schema attributes. +* Select 'LEADER' from schema attributes. * Tick checkbox 'Entity attr.'. * In the 'Entity field' select the item 'Guarantees'.
-* Tick checkbox 'Entity attr.'. +
-* In the 'Entity field' select the item 'Guarantees'. +
- +
-{{ :tutorial:adm:contract-attribute-leader.png |}}+
  
 +{{  .:contract-attribute-leader.png  }}
  
 === Owner attribute === === Owner attribute ===
 +
 Defines relation owner. Must be an identity in IdM. This field is required for every relation. Defines relation owner. Must be an identity in IdM. This field is required for every relation.
  
-* Select 'OWNER' from schema attributes. +* Select 'OWNER' from schema attributes. * Tick checkbox 'Entity attr.'. * In the 'Entity field' select the item 'Owner'.
-* Tick checkbox 'Entity attr.'. +
-* In the 'Entity field' select the item 'Owner'. +
- +
-{{ :tutorial:adm:contract-attribute-owner.png |}}+
  
 +{{  .:contract-attribute-owner.png  }}
  
 === Valid from attribute === === Valid from attribute ===
-Valid from - Validity for the contractual relationship. + 
-This attribute requires LocalDate type. For this we need need to transform our data (as show example below).+Valid from - Validity for the contractual relationship. This attribute requires LocalDate type. For this we need need to transform our data (as show example below).
  
 <code javascript> <code javascript>
Line 102: Line 100:
     return new LocalDate(attributeValue);     return new LocalDate(attributeValue);
 } }
 +
 +
 </code> </code>
  
-* Select 'VALID_FROM' from schema attributes. +* Select 'VALID_FROM' from schema attributes. * Tick checkbox 'Entity attr.'. * In the 'Entity field' select the item 'Valid from'. * Paste transformation to "Transformation from the system"
-* Tick checkbox 'Entity attr.'. +
-* In the 'Entity field' select the item 'Valid from'. +
-* Paste transformation to "Transformation from the system"+
  
-{{ :tutorial:adm:contract-attribute-from.png |}}+{{  .:contract-attribute-from.png  }}
  
 === Valid till attribute === === Valid till attribute ===
-Valid till - Validity for the contractual relationship. + 
-This attribute requires LocalDate type. For this we need to transform our data (as show example below).+Valid till - Validity for the contractual relationship. This attribute requires LocalDate type. For this we (sometimes, depending on the format of input) need to transform our data (as show example below).
  
 <code javascript> <code javascript>
Line 121: Line 118:
     return new LocalDate(attributeValue);     return new LocalDate(attributeValue);
 } }
 +
 +
 </code> </code>
  
-* Select 'VALID_TO' from schema attributes. +* Select 'VALID_TO' from schema attributes. * Tick checkbox 'Entity attr.'. * In the 'Entity field' select the item 'Valid till'. * Paste transformation to "Transformation from the system"
-* Tick checkbox 'Entity attr.'. +
-* In the 'Entity field' select the item 'Valid till'. +
-* Paste transformation to "Transformation from the system"+
  
-{{ :tutorial:adm:contract-attribute-to.png |}}+{{  .:contract-attribute-to.png  }}
  
 +=== State attribute ===
  
-===  State attribute === +State of contract. In some situations information can be needed to determine the result state in multiple attributes. For example, we can have an attribute 'state' with one of multiple values (10,20,30) and a second attribute 'disabled' (with value true/false). In this case states '10' and '30' mark that contractual relation is 'excluded', but when the attribute 'disabled' will be 'true', then the final state of relation must be 'DISABLED'.
-State of contract.  +
-In some situations information can be needed to determine the result state in multiple attributes. +
-For example, we can have an attribute 'state' with one of multiple values (10,20,30) and a second attribute 'disabled' (with value true/false). In this case states '10' and '30' mark that contractual relation is 'excluded', but when the attribute 'disabled' will be 'true', then the final state of relation must be 'DISABLED'.+
  
 To resolve the situation described above we created the transformation script '**compileIdentityRelationState**'. To resolve the situation described above we created the transformation script '**compileIdentityRelationState**'.
  
-* Select 'STATE' from schema attributes. +* Select 'STATE' from schema attributes. * Tick checkbox 'Entity attr.'. * In the 'Entity field' select the item 'State'. * In the 'Transformation from the system' area, click on '**Insert script**' and select '**compileIdentityRelationState**'.
-* Tick checkbox 'Entity attr.'. +
-* In the 'Entity field' select the item 'State'. +
-* In the 'Transformation from the system' area, click on '**Insert script**' and select '**compileIdentityRelationState**'.+
  
-{{ :tutorial:adm:contract-attribute-state.png |}}+{{  .:contract-attribute-state.png  }}
  
 ==== Create sync configuration ==== ==== Create sync configuration ====
 +
 We have created a system with mapped attributes. Now we need to create synchronization configuration. We have created a system with mapped attributes. Now we need to create synchronization configuration.
  
-* Go to the tab 'Synchronization' and create a new item. +  * Go to the tab 'Synchronization' and create a new item. 
-* Tick checkbox 'Allowed'. +  * Tick checkbox 'Allowed'. 
-* Tick checkbox 'Reconciliation'. +  * Tick checkbox 'Reconciliation'. 
-* Fill the name of sync 'Sync contracts'. +  * Fill the name of sync 'Sync contracts'. 
-* In the selectbox 'Set of mapped attributes', select 'Sync - Identity contract - Synchronization'. +  * In the selectbox 'Set of mapped attributes', select 'Sync - Identity contract - Synchronization'. 
-* In the selectbox 'Collation attribute' (in 'Not linked' section), select '_ _ NAME _ _'. +  * In the selectbox 'Correlation attribute', select '_ _ NAME _ _'. 
-* On the tab 'Specific settings' select some 'Default type of structure'. In this example it does not matter which type of structure you select, because we do not want to sync relation between an organization structure and a contract relationship now. +  * On the tab 'Specific settings' select some 'Default type of structure'. In this example it does not matter which type of structure you select, because we do not want to sync relation between an organization structure and a contract relationship now. 
-* Save the sync configuration by clicking 'Save and continue'.+  * Save the sync configuration by clicking 'Save and continue'.
  
-{{ :tutorial:adm:contract-sync-basic.png |}}+{{  .:contract-sync-basic.png  }} 
 + 
 +<note>A correlation attribute for synchronizations of contracts should be typically the identifier, or some text attribute **that is not mapped to any entity attribute (e.g. Owner)**, see [[:devel:documentation:synchronization:dev:relation-sync#correlation|Correlation]]</note>
  
 ==== Start sync ==== ==== Start sync ====
 +
 <note tip>Finally we can start synchronization of contract relationships.</note> <note tip>Finally we can start synchronization of contract relationships.</note>
  
-* On the detail of the sync configuration click on the drop down button and select 'Save and run sync'. +* On the detail of the sync configuration click on the drop down button and select 'Save and run sync'. {{  .:contract-sync-specific.png  }}
-{{ :tutorial:adm:contract-sync-specific.png |}}+
  
 ==== Log of sync ==== ==== Log of sync ====
 +
 After the sync ended (it should not take than a few seconds), you can check result of sync. After the sync ended (it should not take than a few seconds), you can check result of sync.
  
-* Go to the tab 'Logs' (in the sync configuration detail). +* Go to the tab 'Logs' (in the sync configuration detail). * Refresh table with logs (reload button at the top right on the table). * You should see this: {{  .:contract-sync-log.png  }}
-* Refresh table with logs (reload button at the top right on the table). +
-* You should see this: +
-{{ :tutorial:adm:contract-sync-log.png |}} +
  
 ==== Check contracts on user 'john.roe' ==== ==== Check contracts on user 'john.roe' ====
 +
 Finally, you can check the new contract relations of the user 'john.roe'. Finally, you can check the new contract relations of the user 'john.roe'.
  
-* Find the user 'john.roe'. +* Find the user 'john.roe'. * Go to his detail and to the tab 'Positions'. * You should see three contracts:
-* Go to his detail and to the tab 'Positions'. +
-* You should see three contracts: +
-  * **Default** contract (created for this user automatically). +
-  * **Contract one** - has to be in the state excluded and as an authorizer it must have the user 'john.doe'. +
-  * **Contract two** - has to be active (state is empty).+
  
-{{ :tutorial:adm:contract-detai-john.png |}}+  * **Default**  contract (created for this user automatically). 
 +  * **Contract one**  - has to be in the state excluded and as an authorizer it must have the user 'john.doe'. 
 +  * **Contract two**  - has to be active (state is empty). 
 +{{  .:contract-detai-john.png  }}
  
 <note tip>**If you see the same result, then congratulations on your first successful synchronization of contract relationships!**</note> <note tip>**If you see the same result, then congratulations on your first successful synchronization of contract relationships!**</note>
 +
  
  • by doischert