====== Systems - How to connect generic system ======

System connection configuration is initiated in the menu tab **Systems**. Above the list of current systems there is a button **Add**.


{{ :tutorial:adm:system_table.png?700 | System list}}


===== Basic information =====

Click on it to connect new system. On the new system page one must provide some basic information: {{  .:system_detail.png?700  | Connecting a new system}}

  * **System name**  - naming of your choice
  * **Use remote connector server**  - Connectors are means of interface between CzechIdM and other systems. Connectors run in a connector server. A local server provided by CzechIdM directly is usually used. So this checkbox will be usually unticked. There are some exceptions for specific connectors that must run remotely. For example connectors which call commands locally on the connected system server and therefore must be placed there. Exchange connector, for instance, uses calling of PowerShell commands directly on a domain controller server in an AD domain.
  * **Password policy**  for validation and generation - [[.:password_policy|see the chapter]] about password policies.
  * **Lower criticality of password policy for validation by role**  - If this checkbox is selected, the password validation will use the criticality level defined for the role instead of the system policy.
  * **Lower criticality of password policy for generating by role**  - If this checkbox is selected, the password generation will use the criticality level defined for the role instead of the system policy.
  * **Description**  – an optional description of the system. It is customary to describe the purpose of the connected system, for example: “HR system – loading of job positions and departments”.
  * **State**  – system states other than active:
      * **Readonly**  - **with**  provisioning queue – Systems marked in this way allow data reading only and are either source systems in CzechIdM or systems which are controlled but provisioning of data to them is intentionally prohibited for some time. In the latter case, all provisioned data is sent to the provisioning queue. The provisioning queue and history is displayed by: Systems → system detail (magnifying glass) → Provisioning. See the chapter [[.:audit|Audit]].
      * **Readonly**  - **without**  provisioning queue – Systems marked in this way allow data reading only. Provisioning operations are not saved into queue, cannot be executed again. IdM account is created only (uid attribute only).
      * **Inactive**  - **with**  provisioning queue - Inactive systems do not allow even reading operations. If provisioning to such a system is to take place, then the operations end up in a queue as in the case of Readonly systems.
      * **Inactive**  - **without**  provisioning queue - Inactive systems do not allow even reading operations. Provisioning operations are not saved into queue, cannot be executed again. IdM account is created only (uid attribute only).
  * **Asynchronous provisioning**  - if the provisioning is asynchronous for the system, all the data is stored in the queue and managed by appropriate scheduled task. [[:devel:adm:scheduled_tasks|Long running task]] ProvisioningQueueTaskExecutor operates above the queue periodically and starts CREATED provisioning operation processing. Make sure you have **ProvisioningQueueTaskExecutor**  configured, if you have some target system switched to use asynchronous provisioning. This is recommended option, since it significantly improves responsiveness of the application.
  * **Block operations**  - Block (create, edit or delete) operation will block checked operation.
<note important> Attribute values of Inactive systems with provisioning queue is available **are**  calculated in the provisioning log.</note>

<note important> Even if a system is inactive, accounts and uids are computed for the system. If you want to completely avoid creating new accounts, you can use the script **Can an account be created  **in the tab Mapping - Account management. Use this simple script: "return false".</note>


===== Configuration =====

Subsequently, a connector, which will connect the selected system, needs to be chosen in the tab **Configuration**. The configuration setting of the system connection always differs according to the selected connector.
{{ :devel:adm:connector_configuration.png?600 | Connector configuration}}

When the connector is configured, the green button **Test Connector** can be used to test to connection to real system.

<note tip>Some connectors do not support "test" operation</note> 

The system of connectors provides connection to a system without the need to edit the administered system itself since their standardly provided interfaces are utilized.

The basic provided connectors are:
  * Database Table Connector – connects a table in the database
  * Scripted SQL Connector – connects any DB supporting JDBC.
  * LDAP Connector – connects LDAP, even MS AD for some basic usage.
  * CSVDirConnector – input/output from a CSV format text file

Other connectors can be added arbitrarily from publicly accessible [[../dev:system:supported-connectors|sources]] (AD and Exchange connector), via own implementation or by inquiring of CzechIdM developers. Connectors use widely extended framework ConnId, formerly OpenICF, connector framework. 

<note tip>Additional connectors must be added to ''_TOMCATHOME_/idm/WEB-INF/lib/'' directory so IdM could load them properly. Moreover, if you don't see the newly added connector in the select box, clear the browser cache e.g. by closing and opening the browser window.</note> 
===== Attributes Scheme =====

A scheme represents a list of attributes of some object (e.g. Account) in the connected system. By defining a scheme, CzechIdM is enabled to control management of object's attributes. The system scheme can be found in the tab **Systems → System detail → Scheme **.

The easiest and preferred way of how to create attributes scheme is to click the **Generate scheme**. Thus the attribute scheme is generated by the system's connector - all available attributes of the object are returned from the connector and can be modified by clicking on the object name in the table e.g. <nowiki>__</nowiki>ACCOUNT<nowiki>__</nowiki>.

{{  :devel:adm:attribue_schema_account.png?600  | Generate attributes scheme}}

<note important>Not all connectors support automatic scheme generation. From the selection of standard connectors, this functionality is supported by Database Table connector and LDAP connector, for instance.</note>

The other option of defining scheme is clicking on the green **Add button**, define the object e.g. <nowiki>__</nowiki>ACCOUNT<nowiki>__</nowiki> and then add attributes into the scheme manually one by one.

{{  :devel:adm:new_scheme_manually.png?400  | New schema created manually}}

If editing (magnifying glass by the attribute name), or creating (green Add button) attributes in scheme, their names on the system and their data types need to be filled in.

{{  :devel:adm:scheme_attributes_list.png?400  | Attributes list in scheme}}

Usual data types are

  * java.lang.String
  * java.lang.Integer

All allowed types based on connid FrameworkUtil

  * String.class
  * Long.class
  * Character.class
  * Double.class
  * Float.class
  * Integer.class
  * Boolean.class
  * Byte.class
  * byte[].class
  * BigDecimal.class
  * BigInteger.class
  * Map.class

{{  :devel:adm:attribute_detail.png?600  | Attribute detail}}

<note tip>Every connector has some significant attributes, they are usually introduced by "<nowiki>__</nowiki>" characters like <nowiki>__</nowiki>NAME<nowiki>__</nowiki>. Meaning of the attribute depends on the connector.</note>

Then, some of the following settings can be enabled for each attribute:

  * **Required**  - Must be provided when creating an account. If //true//, a new account cannot be created without this attribute. **Typically applies to:** //login//, //name//, or other //mandatory identifiers//. This property mainly affects account creation, not necessarily updates. 
<note tip>Note: For some connectors (e.g., JDBC), an attribute may be marked as required based on the database column definition (NOT NULL). Actual behavior always depends on the connector implementation and the target system.</note>
  * **multivalued**  - Indicates whether the attribute can contain multiple values at the same time. If //true//, the attribute may contain a list of values. **Typical examples:** group memberships, multiple phone numbers, aliases, multiple email addresses.
  * **able to read**  - Indicates whether the attribute value can be read from the target system. If //true//, the system can retrieve the attribute value. If //false//, the attribute is write-only. **Typical example:** Password – it can be set, but it cannot be read back from the target system.
  * **able to create**  - Indicates whether the attribute can be set during account creation. If //true//, the value can be provided when creating the account. If //false//, the value is either generated by the target system or cannot be set during creation. **Typical examples:** ID generated by the target system, system-managed attributes.
  * **able to edit**  - Indicates whether the attribute value can be changed for an existing account. If //true//, the attribute can be modified after the account is created. If //false//, the attribute cannot be changed once it has been created. **Typical example:** Login or GUID is often not updateable. 
  * **returned by default**  - The attribute is included in the result when reading an account from the system. It should not be checked for attributes containing sensitive data (e.g., passwords) that do not need to be read from the system. If //true//, the attribute is included in the default response. If //false//, the attribute is returned only when explicitly requested. **Typically used for:** sensitive values, large attributes (e.g., photos), rarely used attributes.
<note important>Note: This setting is also evaluated by the IdM layer. If the connector returns the attribute but it is configured as //false// in the IdM schema, the attribute will be filtered out at the IdM level.
</note>

<note tip>**What is the difference between isReadable and isReturnedByDefault?** //isReadable// defines whether the attribute can be read from the target system.
//isReturnedByDefault// defines whether the attribute is automatically returned during a standard account read.

Example (photo):
  * isReadable = true
  * isReturnedByDefault = false

The photo can be read from the target system, but it is not included in a standard user read.
It must be explicitly requested. </note>
===== Attributes mapping =====

When the attributes [[#attributes_scheme|scheme]] for the object are ready, connected system attributes available in the scheme can be mapped onto CzechIdM entity attributes e.g. attributes of identity.

{{ :devel:adm:attribute_mapping.png?600 | Attributes mapping list}}

Attributes mapping is available at **Systems -> Mapping**. If there is none use green Add button to create a new one.

{{ :devel:adm:new_attributes_mapping.png?600 | New attributes mapping}}

  * **Operation type** - Firstly, the purpose of mapping needs to be selected. There are two options:
    * **synchronization** (upload data to CzechIdM)
    * **provisioning** (propagation of data from CzechIdM)
  * **Mapping name** -  Next the name for the mapping must be provided. The name is consequently displayed in synchronization and provisioning configuration
  * **Object name** - sets which object type on the connected system will be mapped to CzechIdM
  * **Entity type** - defines the entity in CzechIdM to which the object from connected system is mapped. Usual values are: Identity, Role, Role Catalogue, Contracted position, Tree

When the attribute mapping is created and it is clear what object in the connected system is mapped to what entity in CzechIdM, the procedure gets to the object/entity attributes configuration.
 
Click on the Add button to create a new attribute in current mapping. 

{{ :tutorial:adm:screenshot_2024-08-12_at_11.33.23.png?900 | Detail of attribute in the attributes mapping }}

These options can be filled:
  * **Disabled** - If the attribute is disabled in mapping, it is not provisioned or synchronized.
  * **Attribute in schema** - attributes from the connected system available in the current scheme.
  * **Identifier** - Attribute is unique identifier of this object.
  * **Entity attribute** - Attribute is part of entity.
  * **Extended attribute** - Attribute isn't part of entity and his value and name is stored in EAV attributes.
  * **Name** - Unique system identifier, this value is used in select boxes and in entities info
  * **Strategy** - defines the strategy for the provisioning or synchronization. Available values:
    * Set value as it is - no standard transformation takes place
    * Merge - for multivalued attributes. Provision current idm attribute values + values returned from the connected system. This strategy is often used when connecting e.g. MS AD and CzechIdM manages placing the users into groups, but not all groups are loaded in CzechIdM itself.
    * Authoritative merge - preferred strategy to fill multivalued attributes. Only CzechIdM values are sent to connected system. If the attribute originally contained other values, they are replaced by the sent one.
    * Write only on create of the entity - If checked, the attribute value is sent to end system only together with CREATE operation. If UPDATE is sent to connected system, this attribute is not sent again. The same states for the synchronization.
    * Write only if target value is null - If checked, only non existent attributes are filled in CzechIdM or connected system.

<note important>The attributes mapping must always contain one attribute marked as an **Identifier**. Otherwise the provisioning won't be possible.</note>

<note important>Some of the options behaviour may vary depending on the connector used as well as connected system itself. e.g. some connectors returns NULL if the attribute does not exists, some connectors return empty string "" instead.</note> 

Other options of the mapped attribute are:
  * **Send always** -  Send this attribute to system always even if value isn't change (transformation rules is applied).
  * **Send IdM value only if its not null** - Send this attribute only if value after transformation will not be null.
  * **Confidential attribute** - Attribute value will be stored in confidential storage.
  * **Authentication attribute** - With this attribute will be do authentication to end system (for example: username)
  * **Include on password change** - Include this attribute when is provisioning password (reset, cahnge, create new)
  * **Include only when criticality is changed to stronger** - The value of the attribute will only be sent to the target system when the aggregated password policy criticality is changed to stronger one. It will not be used in standard provisioning.
  * **Include only when criticality is changed to weaker** - The value of the attribute will only be sent to the target system when the aggregated password policy criticality is changed to weaker one. It will not be used in standard provisioning.
  * **Attribute with password** - Attribute will contain value of password. The attribute can't be override by role mapping. Into transformation will be add password in object GuardedString. Script must return null, or GuardedString.

{{ :devel:adm:attribute_mapping_detail_part1.png?600 | Detail of attribute in the attributes mapping - transformations }}

It is now clear what attribute is managed on the connected system and how the changes are propagated from/to the attribute. Obviously it is necessary to define what attribute in CzechIdM we want to connect the end system attribute to.
  * **Entity field** - attributes from CzechIdM entity can be selected. This selection is available only if **Entity attr.** is enabled.
  * **IdM key** - name of attribute in IdM, if administrator choose **Entity attribute** is this field read only and his value is set by entity field select box. If administrator choose **Extended attribute** is this field available for write and is neccessary to enter name of extended attribute.

Now almost everything is set to synchronize or provision the attribute. If the range of standard options for attributes mapping is not wide enough, administrators can use [[.:transformation_scripts|transformation scripts]] to do advanced magic.

===== Virtual Systems =====
This is a way of how to manage systems via user tasks, not directly via direct (e.g. network) communication. This feature is mainly implemented as [[devel:documentation:modules_vs| CzechIdM module]].