You are viewing an earlier version of the admin guide. For the latest version, please visit EmpowerID Admin Guide v7.211.0.0.

Configure Code-Free Flat File Connector

A Flat File Connector in EmpowerID is a powerful tool designed for bidirectional communication between EmpowerID and external identity-aware systems and applications using flat files, enabling data synchronization and interoperability. With this connector, you can effortlessly import data from external systems, whether it's stored in CSV or flat file formats, and it supports various delimiters like pipes and tabs. Moreover, EmpowerID can export data into these flat file formats, simplifying data exchange with external systems, even those lacking SDKs or APIs.

There are three synchronization modes available to meet your specific needs. Please follow the instructions below to configure the flat file connector.

Inbound

Use inbound mode to sync or inventory Identity data from the external systems into EmpowerID.

Outbound

With Outbound mode, identity object changes in EmpowerID can be exported as flat files for the external systems.

Bidirectional

Bidirectional mode synchronizes data from the External system into EmpowerId and vice versa using flat files.

Steps to Configure a Flat File Connector

Before connecting EmpowerID to an external directory, please review the Getting Started with Directory Systems topic. The topic walks you through the prerequisites you need to complete before connecting to an external directory for the first time. These prerequisites include:

  • Configuring the appropriate server roles for your EmpowerID servers

  • Reviewing the Join and Provision Rules for your environment

  • Reviewing the Join and Provision Filters for your environment

Please don’t include any spaces while providing values for column names.

Create a new Account Store

  1. Navigate to Admin->Application and Directories ->Account Stores and Systems

  2. Click on Create Universal Flat File Connector Account Store

You will see the Create page for the Flat File Account store.

 

Enter basic details for the Resource System.

  1. Sync Direction- Choose the Synchronization mode of data between an external system and EmpowerID. Supported Modes of synchronization are discussed above.

  2. Name- This field is the Identifier for the account store.

  3. Display Name- Explanatory & friendly name for the account store. The value provided for the display name appears in the UI.

Click on submit to find a page titled “Resource System Settings “ to provide the necessary configuration for the connector.

Configure User Inventory (Account table)

Resource System Settings has multiple tabs to configure the account store. The first tab on this page allows you to configure the User Inventory.

  1. File Path: Please provide the complete path to the flat files containing the user data that you want to inventory. If your FlatFile AccountStore is configured with a Cloud Gateway server, the path should be given from the Cloud Gateway server. However, if Cloud Gateway is not configured, then the path should be given from the local machine where the inventory is being run.

  2. EID Copy File Path: EID makes a copy of each input file to compare the records with the updated input files and will only inventory the changes into EID. Provide a file path of the copy files to be created.

  3. Date Time Culture: Culture format of the DateTime used in the flat file e.g. en-US, da-DK.

  4. DateTime Format: The date time format used in flat file for e.g MM/dd/yyyy HH:mm.

  5. Delimiter: A Single character that marks the end of a unit of data in the flat file. For e.g “,“ comma for a CSV file.

  6. Primary Key: Specify the column that uniquely identifies each account or a user in the flat file. This field is mapped to the identifier on the account.

  7. User Mandatory Fields: Mandatory fields in a record or a row. Specify the name of columns that cannot be null, the whole row will be discarded while syncing if any of the specified fields are found null. Use comma-separated values for multiple fields.

  8. Logon Name Column: Data from this field will be mapped to LogonName in EID.

  9. Path Column: This field maps to DistinguishedName in EID.

  10. Data Model Mapping File Path: Provide the full path to the Data Model Mapping File. Data Model mapping file maps the columns of the delimited file to EmpowerID person attributes. In simple words, it specifies which field value should set to what attribute of EmpowerID person.

  11. Is Remote (Requires Cloud Gateway): Check the checkbox when EID is a SaaS/Azure tenant and the flat file is not accessible to the EID servers.

  12. Send Notification For Missing Mandatory Fields: Check the option to send an email notification along with the data for missing values. If any rows in the flat files have no value for columns specified in User Mandatory Fields are treated as missing values.

    1. Missing Mandatory Info Attachment File Name: Provide the name of the attachment file for the email. This file will contain all the records that are missing mandatory fields.

    2. Missing MandatoryInfo Attachment File Delimiter: Specify a single character value as a delimiter for the file attachment.

    3. Missing Mandatory Info Attachment File List Of Columns: Specify the column name (without space) to include in the attachment file for the missing records. Use comma-separated values for multiple fields.

    4. Missing Mandatory Info Email Message Name: Name value of a localized email template in EID (EMailMessage table).

    5. Missing Mandatory Info ManagementRoles To Be Notified: Choose a management role, members of the selected role will receive an email for missing records.

  13. Send Notification For Duplicates: Check the option to send an email notification along with the data for duplicate values. If rows in the flat files have a duplicate primary key, such records will be marked duplicate and ignored.

    1. Duplicates Attachment File Name: Provide the name of the attachment file for the email.

    2. Duplicates Attachment File Delimiter: Specify a single character value as a delimiter for the file attachment.

    3. Duplicates Attachment File List Of Columns: Specify the column name (without space) to include in the attachment file for the duplicate records. Use comma-separated values for multiple fields.

    4. Management Role To Be Notified For Duplicates: Choose a management role, members of the selected role will receive an email for duplicate records.

    5. Duplicates Email Message Name: Name value of a localized email template in EID (EMailMessage table).

 

Configure Outbound Settings
The next step is to provide the outbound settings. The outbound setting is mandatory to be provided for the bidirectional and outbound modes of synchronization.

  1. Create Export Files: Select the checkbox if you want flat file exports from EID with the changes in values. If you don’t select this, the flat file connector will only work in inbound mode.

  2. Select if Full File Export is Required: Select the checkbox if you want to export all data and not only the records which are changed.

    1. Processing Action Column Name For Full File: This field will contain the processing action column header for the full export file. Example - Action

    2. Delimiter For Full Export File: This field contains the delimiter for the full export file.

    3. Full Export File Time Stamp: This field contains the timestamp naming convention for the full export file. Providing a value will add a timestamp to the end of the filename. When exporting a file named "data.csv" on September 21, 2023, using the "DDMMYYYY" setting, it would be saved as "data_21092023.csv" to indicate the date of export.

    4. Action For Full Export: This field contains the processing action for full export file. Example - U.

  3. Select if Delta File Export is Required: Select for a differential export that only includes records that have attribute changes since the last export was successful.

    1. Processing Action Column Name For Delta File: Provide a header for the column to include in export files that flags the nature of change in the row. The next inputs described below determine the values of this column. Example - Action

    2. Action For Differential Export Add: Provide a single character value that will flag a record as added. This character value gets set in the processing action column defined above to indicate if a particular record was added. Example - A.

    3. Action For Differential Export Update: Specify the single character that will identify a row with changes in values in the exported files. This value will be set in the processing action column by EID. Example - U.

    4. Action For Differential Export Delete: Provide a value to set in the processing action column to indicate that data is deleted in EID. Example - D.

    5. Delimiter For Delta Export File: Specify the delimiter for export files. Use single character value for e.g ‘,' comma, '|' pipe.

    6. Delta Export File Time Stamp: This field contains the timestamp naming convention for the delta export file. All files exported will append a timestamp with the provided naming convention. When exporting a file named "data.csv" on September 21, 2023, using the "DDMMYYYY" setting, it would be saved as "data_21092023.csv" to indicate the date of export.

  4. Number of Export Files: Specify the number of files. Multiple no of files are handy in the scenario of huge data exports.

 

Configure the Company Inventory (ExternalOrgZone table)

  1. CompanyFileExists: Select this option if you want to inventory company data from flat files.

  2. Company FilePath: Provide a full path to the delimited file which has the company data. If your FlatFile AccountStore is configured with a Cloud Gateway server, the path should be given from the Cloud Gateway server. However, if Cloud Gateway is not configured, then the path should be given from the local machine where the inventory is being run.

  3. Company EID FilePath: EID makes a copy of the input file. This field contains the file path for the copy of the input company file. The copy file is used to compare the records with the updated input files and will only inventory the changes into EID.

  4. Company Delimiter: Delimiter use in the flat file, e.g. ‘,' or ';’ or any other single character value.

  5. Company Mandatory Fields: Specify the Mandatory fields in a record of a company. Specify the name of columns that cannot be null to represent a record of the company.
    EID inventory process will ignore any records with missing mandatory fields. We can configure to send an email notification for the company records with missing fields.

  6. Company PrimaryKey: Specify the column that uniquely identifies each row or company in the flat file. EID will inventory company data by matching this key.

  7. Company PrimaryKey For User: Specify the column that links a user to the company. This field defines which company a user belongs to.

  8. Company Model Mapping File Path: Provide the full path to the Company Data Model Mapping File.

  9. Company Send Notification For Missing Mandatory Fields: A record is ignored in the inventory process if the flat file is missing columns specified in Company Mandatory Fields. Select the checkbox to send an email notification for the missing records.

    1. Company Missing MandatoryInfo ManagementRoles To Be Notified:Choose a management role,members of the selected role will be recipients of the mail.

    2. Company Missing MandatoryInfo Email Message Name: Name value of a localized email template in EID (EMailMessage table).

    3. Company Missing MandatoryInfo Attachment File List Of Columns: Specify the columns to include in the attachment file for the missing records. Use comma-separated values for multiple fields without any spaces.

    4. Company Missing MandatoryInfo Attachment File Delimiter: Provide a single character value for the delimiter of the attached file.

    5. Company Missing MandatoryInfo Attachment File Name: Provide the name to use for the file attached to the email. This file will contain all the records that are missing mandatory fields.

  10. Company Send Notification For Duplicates: Check the option to send an email notification along with duplicate company records.

    1. Company Duplicates Management Roles To Be Notified: Choose a management role,members of the selected role will be recipients of the mail for duplicate company records.

    2. Company Duplicates Email Message Name: Name value of a localized email template in EID (EMailMessage table).

    3. Company Duplicates Attachment File List Of Columns: Specify the column name (without space) to include in the attachment file for the missing records. Use comma-separated values for multiple fields.

    4. Company Duplicates Attachment File Delimiter: Provide a single character value for the delimiter of the attached file.

    5. Company Duplicates Attachment File Name: Provide the name to use for the file attachment.

 

 

Configure Role Inventory (ExternalOrgRole table)

  1. RoleFileExists: Select this option if you want to inventory the role data from flat files.

  2. Role FilePath: Full path to the delimited file having Role data. If your FlatFile AccountStore is configured with a Cloud Gateway server, the path should be given from the Cloud Gateway server. However, if Cloud Gateway is not configured, then the path should be given from the local machine where the inventory is being run.

  3. Role EID FilePath: This field contains the file path for the copy of the input role file. The copy file is used to compare the records with the update input files and will only inventory the changes into EID.

  4. Role Delimiter: Delimiter used in the flat file.

  5. Role Mandatory Fields: Specefiy the mandatory fields in a record of role. Specify the name of fields that cannot be null or missing to represent a Role.

  6. Role PrimaryKey: Specify the column that uniquely identifies each role in the flat file.

  7. Role PrimaryKey For User: Specify the column that links the user to its role.

  8. Role Model Mapping File Path: Full path to the Role Data Model Mapping File. Role Data mapping file maps the attributes of external role to EmpowerID role attributes.

  9. Role Send Notification For Duplicates: Check the option to send an email notification along with duplicate role records.

    1. Role Duplicates ManagementRoles To Be Notified: Choose the recipient management role for the email. 

    2. Role Duplicates Email Message Name: Name value of a localized email template in EID (EMailMessage table).

    3. Role Duplicates Attachment File List Of Columns: Specify the column name (without space) to include in the attachment file for the duplicate records.

    4. Role Duplicates Attachment File Delimiter: Provide a single character value for the delimiter of the attached file.

    5. Role Duplicates Attachment File Name: Provide the name to use for the file attachment.

  10. Role Send Notification For Missing Mandatory Fields:

    1. Role Missing MandatoryInfo ManagementRoles To Be Notified: Choose a management role, members of the selected role will be recipients of the mail for the missing role records of flat files.

    2. Role Missing Mandatory Info Email Message Name: Name value of a localized email template in EID (EMailMessage table).

    3. Role Missing MandatoryInfo Attachment File List Of Columns: Specify the columns to include in the attachment file for the missing records. Use comma-separated values for multiple fields.

    4. Role Missing Mandatory Info Attachment File Delimiter: Provide a single character to use as a delimiter for the attached file.

    5. Role Missing MandatoryInfo Attachment File Name: Provide the name to use for the file attached to the email. This file will contain all the records that are missing mandatory fields.

 

General System Settings

  1. Inventory Enabled: Select the checkbox to Enable the inventory process.

  2. Inventory Auto Provision OUs as IT System Locations: Automatically provision external locations (ExternalOrgZones) as internal locations (OrgZones) in EID while inventorying the data.

  3. Inventory Auto Provision Business Roles: Automatically provision external roles (ExternalOrgRoles) as internal Business Roles (OrgRoles) in EID while inventorying the data.

  4. Allow Person Provisioning (Joiner Source): Select the checkbox if this Account Store is a source for new Person Identities for accounts matching the Account Inbox Provision rule.

  5. Allow Attribute Flow: Select true to enable attribute flow.

  6. Allow Provisioning (By RET): Select true to provision Accounts in this new Account Store by RET.

  7. Allow Deprovisioning (By RET): Select true to deprovision Accounts in this new Account Store by RET.

  8. Allow Business Role and Location Re-Evaluation: Select true if this Account Store is a source for attributes and/or External Roles and Locations to determine EmpowerID Person Business Roles and Locations.

Finally, click on Submit to create the flat file connector.

 

Restart the IIS and EmpowerID services

You will have to restart IIS & the service pools of EmpowerID so that the account store can obtain the configuration information.

To restart the EmpowerID in cloud instance you can do the following.

  1. Navigate to IT Shop-> Workflows

  2. Click on Recycle Service Environment

If you have EmpowerID deployed On-premise, we will have to follow the standard windows procedure to restart the service and IIS.

  1. Execute the command iisreset from the command prompt to restart your IIS.

  2. Open Services. Click Start, click Run, and then type services.msc.

    1. Right Click on the following services and click on Restart service

      1. EmpowerID Web Role Service

      2. EmpowerID Worker Role Service

 

 

Verify the Flat File Connector is working

After the service restart, the flat file connector will inventory the data from the configured flat-file location. To verify that the inventory job ran successfully, navigate to the view one page of the resource just created.

  1. Navigate to Admin->Application and Directories ->Account Stores and Systems

  2. Search the connector and click on it to open the details view.

  3. Click on the Job History tab which will list all the latest inventory jobs with the status.

If you don’t see any error, your flat file connector should be working fine. Click on the User Accounts tab, you should be able to find the accounts inventoried from the flat file.

Â