Skip to main content

Connection

A connection represents a link between a Connector and a connection package.

Examples​

The following example creates a connection for the previously created connector AD, using the package Usercube.AD@0000001 with only the export task and not the fulfill task.


<Connection Connector="AD" DisplayName_L1="Connection Active Directory" Identifier="ADExportFulfillment" Package="Usercube.AD@0000001" DeactivationExportFulfill="Fulfill"/>

We will need to configure the connection settings in the appsettings.agent.json file, by adding a ADExportFulfillment part in the Connections section, for example:

appsettings.agent.json
{
  ...
  "Connections": {
    ...
    "ADExportFulfillment": {
      "Servers": [
        {
          "Server": "contoso.server.com",
          "BaseDN": "DC=contoso,DC=com"
        }
      ],
      "AuthType": "Basic",
      "Login": "Contoso",
      "Password": "ContOso$123456789",
      "Filter": "(objectclass=*)",
      "EnableSSL": "true"
    },
    ...
  }
}

Details about these settings can be found in Identity Manager's References: Connectors.

Properties​

PropertyDetails
Connector requiredType Int64 Description Identifier of the linked connector. Note: a connection can be used by one and only one connector.
DeactivationExportFulfill default value: 0Type DeactivationExportFulfill Description For a connection having a package which implements both export and fulfill, this option can deactivate either the export or the fulfill part. 0 - None: keeps both parts. 1 - Export: deactivates export. 2 - Fulfill: deactivates fulfill.
DisplayName_L1 requiredType String Description Display name of the connection in language 1 (up to 16).
Identifier requiredType String Description Unique identifier of the connection. It must start with a letter followed by up to 441 characters, chosen from the following set: point, dash, letter, or number. Warning: identifiers are case insensitive, for example the identifiers adexport and ADEXPORT cannot exist simultaneously.
Package requiredType Enumeration Description Identifier of the linked connection package which defines the connection's capabilities and technologies to export and/or fulfill data.

Child Element: Transformation​

A connection transformation is optional, but can be needed to adjust the Excel files, output of Export Task from Excel export connections, before Prepare Synchronization Task . The following operations are possible:

  • filtering out given rows;
  • adding/removing days from specific date properties;
  • merging columns together.

Examples​

Edit dates​

The following example sets all users' end dates to the end of the day instead of the morning. This way, the end dates of users' permissions will be managed more easily.

Technically speaking, Identity Manager implements a sort of extra-task between the export and prepare-synchronization tasks of HR synchronization. The CSV files produced by the export task of the connection Directory are to be transformed: Identity Manager will add 1 day to all dates between 1900 and 2100, contained in the ContractEndDate, PositionEndDate and EndDate columns of the Directory_UserRecord table.

This date edition goes the other way around when loading data back to your systems: if Identity Manager adds a few days when synchronizing, then it removes the same few days when using the synchronized data.


<Connection Identifier="Directory" DisplayName_L1="Directory" Connector="Directory" Package="Usercube.Excel@0000001" >
    <Transformation Type="TransformDate" Table="Directory_UserRecord" Column="ContractEndDate" AddedDays="1" MinYear="1900" MaxYear="2100" />    <Transformation Type="TransformDate" Table="Directory_UserRecord" Column="PositionEndDate" AddedDays="1" MinYear="1900" MaxYear="2100" />    <Transformation Type="TransformDate" Table="Directory_UserRecord" Column="EndDate" AddedDays="1" MinYear="1900" MaxYear="2100" />
</Connection>

Filter out rows​

The following example filters the CSV files produced by the export of the Directory connection, in order to keep only German sites, i.e. the rows where Identifier starts with DE_.


<Connection Identifier="Directory" DisplayName_L1="Directory" Connector="Directory" Package="Usercube.Excel@0000001" >
    <Transformation Type="WhereValue" Table="Directory_Site" Column="Identifier" WhereOperator="StartsWith" WhereValue="DE_" />
</Connection>

Merge columns together​

Consider the situation where users' organizations are defined in 4 levels.

The following example merges the Company, Subsidiary, Department and Team columns of the Directory_UserRecord table, output of the export of the Directory connection, in order to concatenate the 4 properties into a single FullOrganization property.

Setting RemoveEmpty to true means that rather than having an organization such as Contoso//HR/Payroll, we will have Contoso/HR/Payroll.

Setting RemoveDuplicates to true means that rather than having an organization such as Contoso/Contoso/HR/Payroll, we will have Contoso/HR/Payroll.


<Connection Identifier="Directory" DisplayName_L1="Directory" Connector="Directory" Package="Usercube.Excel@0000001" >
    <Transformation Type="TransformDate" Table="Directory_UserRecord" Column="FullOranization" InputColumn="Company" InputColumn2="Subsidiary" InputColumn3="Department" InputColumn4="Team" ConcatSeparator="/" RemoveEmpty="true" RemoveDuplicates="true" />
</Connection>

Properties​

PropertyDetails
AddedDays optionalType Float Description Number of days to add to the date column to be transformed, specified in Column, when the transformation type is TransformDate. The value can be negative, for example -0.5 removes 12 hours from the date.
Column optionalType String Description Column (case-sensitive) used as input of the filtering and the date editing transformations, and as output of the merging transformation. When defining an output, Column can be an existing column or a column to be created.
ConcatSeparator optionalType String Description Separator used between the concatenated values, when the transformation type is ConcatColumns.
DatePattern optionalType String Description Format of the transformed dates to be stored when the original object is not a date, when the transformation type is TransformDate. Note: for example we could need this property when using CSV files which store everything as strings, including dates.
InputColumn optionalType String Description Column (case-sensitive) used as input when the transformation type is TransformDate, and as part of the input when the transformation type is ConcatColumns. Note: required for ConcatColumns. Note: when not specified for TransformDate, Column is used as input.
InputColumn2 optionalType String Description Second (up to fifth) input column (case-sensitive) when the transformation type is ConcatColumns.
MaxYear optionalType Int32 Description Year after which the date contained in the input of the transformation of type TransformDate is ignored by the transformation.
MinYear optionalType Int32 Description Year before which the date contained in the input of the transformation of type TransformDate is ignored by the transformation.
RemoveDuplicates optionalType Boolean Description true to keep only one of two identical and successive values, when the transformation type is ConcatColumns.
RemoveEmpty optionalType Boolean Description true to ignore empty values, when the transformation type is ConcatColumns.
SortValues optionalType Boolean Description true to sort the concatenated values by alphabetical order, when the transformation type is ConcatColumns. Note: concatenated values are sorted after duplicates are removed, when relevant.
Table optionalType String Description Table on which the transformation is to be applied. Note: must be of the format <connectionIdentifier>_<datasetName> (case-sensitive).
Type requiredType ConnectionTransformationType Description Type of the transformation: ConcatColumns: concatenates InputColumn columns into Column with a separator defined in ConcatSeparator, potentially with additional transformation options among RemoveDuplicates, RemoveEmpty, SortValues. TransformDate: adds or removes a given number of days defined in AddedDays to/from the date stored in InputColumn or Column, only for dates between MinYear and MaxYear, in order to be stored in Column in the format defined by DatePattern. WhereValue: filters the rows based on a comparison with the WhereOperator and WhereValue arguments.
WhereOperator optionalType ConnectionTransformationWhereValueOperator Description Operator of the comparison that filters out rows from the CSV file(s), when the transformation type is WhereValue: Equals; NotEquals; Contains; CotContains; StartsWith; EndsWith; Regex.
WhereValue optionalType String Description Value (case-sensitive) that the content of Column will be compared to, when the transformation type is WhereValue.