HR connector
HR connector
In this use case is described productized HR connector, which is used for importing user and work period related data to IGA solution. Productized HR connector can read data from XML, CSV or JSON file formats, which Customer exports from the HR system.
Use Case Description
This use case is available only for IGA Growth and Enterprise packages.
Please notice, that with productized HR connector, it is possible to read data, if writing data is required, Efecte Integration Services (or similar integration platform) is recommended to be used.
| Description | |
Overview |
This use case describes how users and their work periods are imported by using productized HR connector. |
Operators |
IGA solution |
Prerequisites |
Customer has delivered pre-defined JSON, CSV or XML file to agreed location, where integration can read it and start importing user and work period data to IGA solution. |
Result |
User and related work period data is read to IGA solution. IGA solution can start workflows related to user lifecycle management or other use cases. |
Operating chain |
|
Related datacards |
IGA Work Period |
Configuration Changes
Customer can select these configurations, without them affecting project schedule or work estimations.
1. Unique ID
Customer can choose if employee ID or Social security number is used as unique ID for users
2. Scheduling
Customer can define scheduling sequence, as long as the previous file has been imported.
3. Validation
Customer can define mandatory and optional attributes. Note that Unique ID is always mandatory.
Expansion Possibilities
These expansion possibilities always need Efecte consultants review, before implementation and work estimations can be agreed.
1. Customer can also use connector for reading organizational units, costs centers and titles.
How HR connector works?
General Overview
HR-connector is using Efecte Provisioning Engine (Custom Script connector) for reading data from the file. Connector is used only for reading data to IGA solution.
1. Connector uses extra arguments, defined in the scheduled-based provisioning task, for finding the file from the path (if extra argument is missing, process stops)
2. Files are transformed to JSON format (dict) and stored as JSON
3. Each file can be run as full or partial run
4. Partial run always compares data to the archived file (if archive file is missing, process stops)
5. Validation file is used to check that each row (object) contains mandatory fields and give warnings if optional fields are missing
6. Connector will import IGA Admin Task to IGA solution including errors and JSON files containing archived and imported rows, after import has been executed.
About connector files,
| File | Description |
| error_(data_type)_archive.json | Stores rows that did not pass the validation during the run. These rows are not imported to IGA solution. File is overwritten each run. |
| IGAConnector.py | Connector script |
| (data_type_archive.json | Stores all rows from the file that has been run, including valid and invalid. File is overwritten each run. |
| ./logs/3_output.json | Includes the rows that passed the validation and should be imported to IGA solution |
| ./data/backup | Contains example files for JSON, XML and CSV formats |
| translation.json |
1. Used for translating report cases to given language. 2. New languages can be added by adding "language" e.g. "de" or "en", under all cases with key "text". Each report cases needs to have new language, otherwise connector runs into error. 3. To use specific language, extra arguments need key "language" with value found from translation.json |
Generate File from HR-system
Productized HR connector expects that file is generated from the HR-system based on following logic.
| Logic | Additional information |
| All users with active work period(s) | Users are selected based on work period dates |
| All users with active work period in the future | One month ahead |
| All users with active work period in the past | One month from the past, this is needed if changes to user information is made afterwards employment has already ended. |
| Users are sorted based on unique ID | Unique ID can be either employee number or social security number. |
| Last update timestamp | Users can be selected based on last update timestamp, but please check with Customer HR Specialist which changes updates the timestamp. |
Parameters, Validation & Exceptions
Parameters
HR connector uses following parameters,
| Parameter | Description | Mandatory / optional value |
| file_path | Path and file pattern, where file is located. | Mandatory |
| data_type | Values: costcenter, organization, title or workperiod. | Mandatory |
| run_type |
Run type specifies if comparison to previous file will be done. Values: full load or partial, default is partial |
Optional |
| update_limit |
How many updates are allowed to IGA solution. If import notices that there would be coming updates to more than update_limit number of objects, it stops processing before doing any updates and logs ERROR message to log ending to constant text: "Stopping ETL Worker process". |
Mandatory |
| override_update_limit | Overrides update limit, if amount of updates is more than given limit. Values, true or false, default is set to false. | Optional |
| minimum_row_count | What is the minimum amount of rows, that should exists in the file. | Optional |
| webapi_user | ESM user for report creation. Requires create and update permissions to IGA Admin Task. | Mandatory |
| webapi_password | Password for ESM webapi_user | Mandatory |
| webapi_url | URL to ESM environment. | Mandatory |
| report_template_code | Target template code. | Mandatory |
| report_folder_code | Target folder code. | Mandatory |
| debug | Enables debug logging. Values, true or false, default is set to false. | Optional |
Validation
HR connector validates following attributes, exceptions listed in second table
| Attribute | Mandatory / optional |
| Last Name | Mandatory |
| First Name |
Mandatory |
| Social Security Number |
Mandatory |
| Employee ID |
Mandatory |
| Employment start date |
Mandatory |
| Title ID |
Mandatory |
| Manager ID |
Mandatory |
| Organization Unit ID |
Mandatory |
| Spoken Name | Optional |
| Second Name |
Optional |
| Employment End Date |
Optional |
| Employment type |
Optional |
| Is User Manager? |
Optional |
| Title |
Optional |
| Manager Name |
Optional |
| User Type |
Optional |
| Cost Center |
Optional |
| Organizational Unit Name | Optional |
Exceptions and IGA Admin Tasks
HR connector creates IGA Administration Task, if one of following exceptions occurs,
| Exception | Description | IGA Admin actions |
| File is not received or is empty, integration generates IGA Admin Task | IGA Admin Task is generated, for IGA Admins review | IGA Admin validates that is there reason, why file is not generated from the HR system or why the file is empty. |
| User is missing unique ID |
Users with unique ID is imported, and IGA Admin Task is created for manual review for those users who were missing information. |
Users unique ID must be entered to the HR system, file is re-generated and provisioning task is run manually |
| Scheduled-based provisioning task (type ETL-worker) is missing extra arguments |
Mandatory extra arguments are: file_path data_type update_limit webapi_user webapi_password webapi_url report_template_code |
Extra arguments needs to be added to the scheduled-based provisioning task and task needs to be re-run by IGA Module Admin. |
| Archive file is missing | Archive file is mandatory to found for partial run to be able to complete | IGA Admin Task for solving the issue with missing file. |
| Missing mandatory field (object) or value of the field | Row is blocked and import is finalized, single row is excluded from processing | IGA Admin can see from connector report (IGA Admin Task) if any rows were blocked. Information needs to be added to the source system and file re-generated and run again. |
| Update limit (update_limit) is exceeded | Import is interrupted (not run). | IGA Admin Task is created to IGA Admin, for solving the issue. IGA Module Admin needs to run task again. |
| Minimum row account is not exceeded | Import is interrupted (not run). | IGA Admin Task is created to IGA Admin, for solving the issue. IGA Module Admin needs to run task again. |
Relations & configuration instructions
Relations to other use cases,
Relations to other data cards,
Configuration instructions,
Create Custom Backend task
Productized HR connector requires that EPE Custom Backend is configured to ESM.
- Log into ESM as administrator and go to Administrator site
- Select IGA tab
- Create new Custom Backend task
- Fill up the required fields and test the run. For example
Example about 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/HRconnector_file*.csv", "data_type":"workperiod", "run_type":"full", "update_limit": 10, "override_update_limit":true, "minimum_row_count": 3, "webapi_user": "username_here", "webapi_password": "username_here", "webapi_url":"https://baseline.efectecloud-dev.com", "report_template_code":"IGAWorkflowTaskInformation", "report_folder_code":"iga_tasks", "debug": true}
See more technical description of HR connector
https://docs.efecte.com/configure-connectors/hr-connector-import
Table of Contents