Who is this article for?

Ideagen EHSQ Enterprise or Decani administrators exploring data loader vs API interface options

Reference Data Loader (RDL) interface support required

Best practice person and organization

Organizations can use a RESTConnect API integration as an alternative to file-based RDL processing.

The Person and Organization Reference Data Loader (RDL) interfaces automate the management of personnel and organizational data in Ideagen EHSQ Enterprise and Ideagen EHS Decani.

This article explains how the RDL processes imports data, how the SynchPerson interface synchronizes Person objects and User accounts, and the requirements for implementing and maintaining these integrations. The same RDL framework can also be used to create and maintain Organization objects from external source systems. 

SynchPerson interface

Customers upload daily personnel data files containing new users, updates, and deactivations to an SFTP server. The Reference Data Loader (RDL) processes the data and creates, updates, or deactivates Person object.

Saving a Person object automatically triggers the SynchPerson interface, which creates, updates, or deactivates the associated User object.

The SynchPerson interface runs whenever a Person object is saved, including when an administrator updates the object manually. Changes made to a Person object synchronize to the associated User account. Changes made directly to a User account do not synchronize back to the Person object. To update user information, make the change on the Person object. The interface can synchronize the following fields:

• FirstName,
• MiddleName
• LastName
• UserName
• User
• DomainUser
• PrimaryEmail
• Number

If a value reverts after an administrator updates it, the daily source file is likely overwriting the change. Update the value in the source system to ensure the change persists.

Initial load

During implementation, perform a one-time initial load in each environment. Ensure the file contains all required personnel and organizational data because it establishes the baseline dataset used by the platform.

For example, an organization interface initial load might contain all organizations, sites, divisions, departments, and associated personnel identifiers. Preparing a complete and accurate file helps ensure a successful implementation. 

Data updates

After completing the initial load, submit update files that contain only additions, modifications, or deactivations since the previous load. Do not resend the full dataset. Use separate files for each action type and upload them to the agreed SFTP location at the agreed time. The file structure must remain the same as the initial load.

Assumptions

• Update files only include data that is new or has changed since the last load.
• The person interface assigns a single role and reporting authority to each newly created user.
• Setting a user status to inactive deactivates both the User account and associated Person object.
• Inactive users cannot sign in and will not receive new assignments or updates to assignments. 

Specifications

File formatting

CSV (comma-separated values) is the preferred file format.

Files must meet the following requirements:

• Include a single header row to allow validation before processing.
• Use a comma (ASCII 0x2C) as the preferred delimiter.
• Alternatively, use a pipe character (ASCII 0x7C).
• Enclose values in quotation marks (ASCII 0x22) - "James", "Albright", "A12345", "Electrical Engineer".
• Escape embedded quotation marks by preceding them with another quotation mark - "1/2"" valve, brass gate".

File encoding

Use one of the following encodings:

• ISO-8859-1 (Latin-1 Western European)
• Windows-1252 (Western European)
• UTF-8 without a byte order marker (BOM)

Using other encodings can cause processing errors and delays.

File naming convention

Follow these naming conventions when preparing interface files:

• Do not use spaces in file names.
• Use descriptive names that remain meaningful outside their directory location - reporting-procedure-0052.txt vs 0052.txt.
• Use ISO 8601 date formats when including dates in file names to support chronological sorting.

File structure

Each interface requires a unique identifier that can be used to locate and update objects. For example, EmployeeID is commonly used for Person object, while OrgID is commonly used for Organization objects. Duplicate values can prevent the interface from processing objects successfully.

 

Persons file

The Reference Data Loader (RDL) can map data into any of the header or child level fields within the Person module. The standard header row fields which dictate the data contained in the file is as follows. When utilizing SSO, the USERID must contain the official login name from the system.

"USERID","EMAIL_ADDR","DEPTID","DEPTNAME","EMPLOYEEID","FIRST_NAME","JOBTITLE","LAST_NAME","MIDDLE_NAME","BUSINESS_PHONE_NUM","MGR_USERID","STATUS"

"DEPTID","DEPTNAME","BUSINESS_UNIT_HR","PARENTID","MANAGER_ID","STATUS"