The HR connector uses the Generic Python Script connector for reading data from the file. The connector is designed to be used in IGA solution user lifecycle management use cases. Using it for another purpose requires the script to be exported from the host machine and modified according to customer requirements. Note that it is also possible to create a new script from the beginning and use a custom script connector to validate and import it.

The HR connector supports one or several work periods, as long as work periods are generated as described in the "Generate file from HR solution" chapter.

Basic principles for the HR connector:

1. The connector uses extra arguments, defined in the scheduled-based provisioning task, for finding the file from the path (if an extra argument is missing, the process stops)
2. Files are transformed to JSON format (dict) and stored as JSON
3. Each file can be run as a full or partial run
4. A partial run always compares data to the archived file (if the archive file is missing, the process stops)
5. In a JSON-formatted file, all mapped attributes are mandatory, and the task stops the import if mandatory attributes are missing from any imported object. CSV format works differently: it is enough that all mapped attributes are found as columns in the header row.
6. The connector creates an IGA admin task in the IGA solution, including errors and JSON files containing archived and imported rows, after the import has been executed.

Connector files:

The HR connector expects that the file is generated from the HR solution based on the following logic, and that the file is stored on the customer's SFTP server, where the connector can fetch the file(s). Note that encoding needs to be UTF-8.

If you use the CSV file format, the default field separator used by the HR connector script is ; (semicolon).

Generating the file varies according to the HR solution the customer is using. For example, the IGA solution in particular requires that information is received from the past and from the future.

For Workday HR solutions, it is recommended to create a custom report in Workday that reports the needed information, and use JSON format for that report.

Examples of information used for generating the required file:

If a customer wants to use the HR connector to import several different types of data, it is recommended to have one HR connector per data type.

For example, if a customer wants to import organizations and users, they should have two connectors, such as "HR connector Organizations" and "HR connector Users".

With those two connectors on the same FTP server, the folder structure could be, for example:

/sftp/iga/in/organisation

/sftp/iga/in/organization/archive

/sftp/iga/in/user

/sftp/iga/in/user/archive

The data folder should contain only one file at a time.

With that folder structure, you can use these script parameters for HR connector Organizations:

"sftp_remote_path_data":"/sftp/iga/in/organization",

"sftp_remote_path_archive":"/sftp/iga/in/organization/archive",

"file_path":"./organization/*.csv"

And similarly, different script parameters for HR connector Users.

Please make sure the following tasks are done before running the scheduled task for the HR connector:

1. HR-Connector-scheduled.py or IGAConnector.py script can be found on the customer's test & production environments
   1. If it is missing, please contact Matrix42 Service Desk
2. HR connector is configured in the customer's Pro/IGA solution test environment
3. HR connector is tested in the customer's Pro/IGA solution test environment
   1. Create needed test data, test users and test cases
4. Data quality has been confirmed by the customer's HR specialists & future IGA admin
5. File is correctly generated, scheduled and stored on the customer's SFTP server
6. For the IGA solution, implement the configuration instructions for user lifecycle management use cases
   1. IGA set work period information data card(s) are in place
   2. IGA set account information data card(s) are in place
   3. Simulation phase has been agreed, and IGA admin validates received data for an agreed period of time before provisioning (once data quality is ensured, full automation can be enabled by changing settings in the IGA set work period information data card(s))

To access connector management, the user needs permissions to Platform configuration.

1. Open the solution administration area (a gear symbol).
2. Open the connectors view.
3. Choose New connector.

2. Select Data Source type to be Custom Backend

3. Fill in information:

• Fill in a unique connector name for the connector; note that the name cannot be changed afterwards.
• Select HR-Connector-scheduled.py or IGAConnector.py script from the provisioning script field.
• A parameters encryption password is needed for hiding/revealing parameters after the connector has been saved.
• A Web API user is needed when the HR connector is writing data to the customer's Pro/IGA solution.
• A Web API password is needed when the HR connector is writing data to the customer's Pro/IGA solution.

4. Reveal & modify parameters according to customer definitions

• Save the encryption password in a secure place; you will need it later if there is a need to adjust the parameters. See References - Parameters table below for more information about Parameters.
  
  Example parameters:
  {"objectGUID_field_name":"objectGUID", "sftp_server_fqdn":"transfer.xx.com", "sftp_server_ssh_port_number":"22", "sftp_username":"username_here", "sftp_password":"username_here", "sftp_remote_path_data":"/sftp/data", "sftp_remote_path_archive":"/sftp/archive", 
"file_path":"./data/workperiod*.csv", // Path and file pattern where the file is located. Mandatory value
"data_type":"workperiod", // Values: costcenter, organization, title or workperiod. Mandatory value
"run_type":"partial", // Run type specifies if comparison to the previous file will be done. Values: full or partial. Optional value, default is 'partial'
"update_limit": 100, // How many updates are allowed to the IGA system. Mandatory value
"override_update_limit":false, // Overrides the update limit if the amount of updates is more than the given limit. Values: true or false. Optional value, default is 'false'
"minimum_row_count": 10, // The minimum number of rows that should exist in the file. Optional value
"webapi_user": "IGA.WebAPI", // Web API user for report creation. Requires Create and Read permissions to the IGA Administration task. Mandatory value
"webapi_password": "aeiou", // Web API user's password. Mandatory value
"webapi_url":"https://eisdemo.efectecloud-demo.com", // URL to the ESM environment. Mandatory value
"report_template_code":"IGAWorkflowTaskInformation", // Target template code. Mandatory value
"report_folder_code":"iga_tasks", // Target folder code. Mandatory value
"debug": false, // Enables debug logging. Values: true or false. Optional value, default is 'false'
"language": "en" // Sets the IGA Administration Task report language. Optional value, default is 'en'
}

5. Create a new scheduled task for the HR connector

6. Fill in Task Details

• Unique task name for the connector; note that the name cannot be changed afterwards.
• Task usage is set to scheduled.
• Mappings type is set to generic (one template).

• Attribute name for ObjectGUID. Write the name of your input data column/attribute that contains the unique identifier for the row, for example: objectGUID.

7. Fill in failure information

Optional settings for failure handling: if the scheduled task fails, it can create a data card that displays the error. If failure settings are defined, the administrator does not need to manually check the status of scheduled tasks.

• Failure template – select a template for the data card that is created in case of errors during provisioning (connection to data sources, timeouts, etc.)
• Failure folder – select the folder where the failure data card is stored.
• Failure attribute – select the attribute in the failure template where the error information should be stored.

8. Fill in mappings for the generic template

Generic data is read into any template the user wants; it is mandatory to set the target folder, data source ID, and unique values used for identifying data between the customer's HR system and the Matrix42 Pro/IGA solution.

• Target template – select a template to define attribute mappings
• Target folder – select a folder from a list of folders, narrowed down to match compatibility with the selected template.
• Data Source Type mapping – optional. Contains a constant string of the Generic Python Script connector type.
• Task ID mapping – mandatory to map, for example to a datasourceid or taskid attribute. This is used by the "Set value to datacard for objects deleted from source system" feature. This same attribute must also be in the mappings table, and must be a non-unique attribute.
• Attribute mappings:
  1. HR attribute (external attribute) – which attribute from the file is mapped to Pro/IGA
  2. Local attribute – which attribute in Pro/IGA the data is mapped to

9. If you need to modify the actual script, it needs to be downloaded from the customer's host machine, modified and uploaded again.

• If you don't have access to the host machine, please contact Matrix42 Service Desk for assistance.

10. Save your changes

11. Before running the scheduled task for the HR connector:

• Check that all configuration related to workflows and settings in data cards is in place.
• When running for the first time, make sure that provisioning is disabled towards directories & applications.

12. Run the task manually, or wait until the scheduled run starts.

13. Validate that data has been read into the correct data cards and that the correct attributes are in place.

14. Troubleshooting

• If a failure template is used, check the correct data card.
• Check scheduled task history from connector management.
• Check logs.

Parameters define the settings for the HR connector, which are validated when the script is run.
Remember to store the password in a secure place, in case you need to review parameters after the scheduled task has been saved.

The HR connector uses the following parameters:

Validation means that the HR connector checks that all mandatory information related to users is received from the HR solution; if it is missing, the HR connector creates an IGA admin task by default.

A customer can define more attributes to be read, outside of the list below, but this requires the HR connector's script to be modified (read more in the "How to customize import" chapter).

A customer can define in which template, folder and attribute the HR connector generates the following exceptions:

HR-Connector-scheduled.py is the new baseline script for the HR connector, delivered as the direct successor to IGAConnector.py. It uses the same Generic Python Script connector mechanism, the same parameter model, and the same validation/exception approach described elsewhere in this article: it is not a redesign, but a hardened and extended version intended as the foundation for future HR connector improvements.