====== Systems - CSV file: users contracts synchronization via wizard  ======
{{tag> contract tutorial sync}}

===== 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:documentation:synchronization:dev:contract-slice-sync|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:documentation:synchronization:dev:contract-slice-sync|here]].</note>

===== What you need before you start =====
    * You need to install CzechIdM 10.7.1 (and higher).
    * You need to be logged in as 'admin'.
    * You need to have two users ready: 'john.doe' and 'john.roe'. You can create both users manually in IdM- Users, or you can import them from CSV file - [[tutorial:adm:how_to_identity_sync_via_wizard|]]

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

Here are the sample data in CSV format:
<code>
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"
2,"Contract two","20","true","revolutionize viral experiences","2017-04-06","","","","true","2016-06-15","Einti","60429-911","john.roe"
</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/soval/csv/contracts.csv". 

===== Create system 'Contracts - CSV' =====

Start on the main screen, select Systems and click the Add button.

{{ :tutorial:adm:systems_-_csv_file:main_screen.png |}}

On the wizards selection screen, select the wizard for CSV files.

{{ :tutorial:adm:systems_-_csv_file:csv_wizard_selection.png |}}

==== Connector configuration ====
Now we can start to configure the CSV connector and its settings. 

<note important>Remember, you have to set correct path to your contracts.csv file! The entered path must be accessible from the server on which the CzechIdM application is running.</note>

{{ :tutorial:adm:systems_-_csv_file:csv_wiz_step_1.png |}}

==== Primary attribute ====
In the second step one of the attributes must be selected as primary identifier.

{{ :tutorial:adm:systems_-_csv_file:csv_wiz_step_2.png |}}

==== Mapping ====

In the next step, we must choose whether the data will flow from the CzechIdM system or to the CzechIdM system and which type of object in CzechIdM will be used for this data processing.

{{ :tutorial:adm:systems_-_csv_file:csv_wiz_step_3.png |}}

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

=== Primary attribute ===
One of the attributes must be selected as primary identifier. If we chose identity as object what we were going to process in the previous step, the primary attribute would be assigned automatically. Because we chose identity contracts, we must enter primary attribute manually.

* Select '_ _ NAME _ _' from schema attributes.

{{ :tutorial:adm:systems_-_csv_file:csv_wiz_step_4a.png |}}

=== Name attribute ===
Defines the name of the contractual relationship.

* Select 'NAME' from schema attributes.
* Tick checkbox 'Entity attr.'.
* In the 'Entity field' select the item 'Name of positions'.

{{ :tutorial:adm:systems_-_csv_file:csv_wiz_step_4b.png |}}

=== Guarantee attribute ===
Defines the list of superiors, directly linked to the contractual relationship (more details see below).

* Select 'LEADER' from schema attributes.
* Tick checkbox 'Entity attr.'.
* In the 'Entity field' select the item 'Guarantees'.

{{ :tutorial:adm:systems_-_csv_file:csv_wiz_step_4c.png |}}

=== Owner attribute ===
Defines relation owner. Must be an identity in IdM. This field is required for every relation.

* Select 'OWNER' from schema attributes.
* Tick checkbox 'Entity attr.'.
* In the 'Entity field' select the item 'Owner'.

{{ :tutorial:adm:systems_-_csv_file:csv_wiz_step_4d.png |}}

=== 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).

<code javascript>
import org.joda.time.LocalDate;

if(attributeValue){
    return new LocalDate(attributeValue);
}
</code>

* 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"

{{ :tutorial:adm:systems_-_csv_file:csv_wiz_step_4e.png |}}

=== 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).

<code javascript>
import org.joda.time.LocalDate;

if(attributeValue){
    return new LocalDate(attributeValue);
}
</code>

* 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"

{{ :tutorial:adm:systems_-_csv_file:csv_wiz_step_4f.png |}}

===  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'.

To resolve the situation described above we created the transformation script '**compileIdentityRelationState**'.

* 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**'.

{{ :tutorial:adm:systems_-_csv_file:csv_wiz_step_4g.png |}}


The final result of the mapping should be similar to what you see here.


{{ :tutorial:adm:systems_-_csv_file:csv_wiz_step_4h.png |}}

==== Create sync 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.
* Tick checkbox 'Allowed'.
* Tick checkbox 'Reconciliation'.
* Tick checkbox 'Process only differences'.
* Fill the name of sync 'Sync contracts'.
* In the selectbox 'Set of mapped attributes', select 'Sync - Identity contract - Synchronization'.
* In the selectbox 'Collation attribute', select '_ _ NAME _ _'.


{{ :tutorial:adm:systems_-_csv_file:csv_wiz_step_5a.png |}}


* 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 'Next'.

{{ :tutorial:adm:systems_-_csv_file:csv_wiz_step_5b.png |}}

Save the result by clicking on the "Finish" button.

{{ :tutorial:adm:systems_-_csv_file:csv_wiz_step_6.png |}}

==== Start sync ====
<note tip>Finally we can start synchronization of contract relationships.</note>

* In Systems, select the settings we just created by its name and click the "Play" button.

{{ :tutorial:adm:systems_-_csv_file:csv_wiz_sync_start.png |}}

==== Log of sync ====
After the sync ended (it should not take than a few seconds), you can check result of sync.
* You should see this:

{{ :tutorial:adm:systems_-_csv_file:csv_wiz_sync_status.png |}}

==== Check contracts on user 'john.roe' ====
Finally, you can check the new contract relations of the user 'john.roe'.

* Find the user 'john.roe'.
* 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:systems_-_csv_file:csv_wiz_sync_result.png |}}

<note tip>**If you see the same result, then congratulations on your first successful synchronization of contract relationships!**</note>