Who is this article for?

Ideagen EHSQ Enterprise or Decani Administrators exploring interface options

Reference Data Loader (RDL) interface support required

Best practice person and organization
HTML REST API (Representational State Transfer API) is a set of guidelines for exchanging data between a client and a server, enabling asynchronous communication. REST APIs are commonly used for web services and support various data formats and request types. The REST interface would take the place of the RDL steps 1 and 2 shown below.

The SynchPerson interface is a Reference Data Loader (RDL) that has been developed to automate the creation of User records. In general terms, the overall process operates as follows:

1. Daily, customers provide flat files (described above) that lists all new users, users to be modified, and users to be disabled. These files are placed on the platform's SFTP server.
2. The Reference Data Loader (RDL) tool processes the file, creating, modifying, or disabling Person records.
3. The Person record is then automatically saved and the SynchPerson interface is triggered. This interface creates, modifies, or disables the associated User record. 

The SynchPerson interface is triggered any time a Person record is saved, even if done manually. The SynchPerson field mappings include: 

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

If any changes are required, please note that SynchPerson is a one-way process. Updates made to the Person record will be reflected in the User record, but changes made to the User record will not update the Person record. Therefore, if an admin needs to update information about a user, the change should be made in the Person record.

If an Admin modification, like a job title change, does not stick and reverts to the previous value the next day, it means the value is being updated from the file mentioned in step 1 above. To ensure these changes are retained, they need to be made in the source system so that the updated information is included in the daily file.

Initial Load

During an implementation project, the initial load file is used for a single loading event in each specific environment. It’s important to make sure all relevant data is correctly included in this initial load, as it forms the base dataset for the platform’s operations. Taking care with this one-time loading process is key, as it lays the groundwork for all future activities and interactions within the system. 

Initial Load example
For example, the initial loading of an organization or site interface might include a detailed list covering every organization, site, division, and department, as well as the identification numbers of the individuals assigned to them. 

By meticulously preparing this file, we can enhance the likelihood of a seamless transition and integration for all parties involved.

Project Updates

After the initial load is finished, any updates to the files should be sent in a separate list that includes only the changes, rather than the entire file. Different files will be required for objects that need to be added, modified, or disabled. Please ensure these files are uploaded to an agreed folder on the SFTP server, at a mutually agreed time of day.

The file layout between the initial load and updates will remain the same (see File Structure Section).

Assumptions

• The updated files will only include objects that have been modified or newly added since the initial or previous version.
• In the case of a person list, the interface will assign a single, unique role and reporting authority to each newly created user.
• User deactivation can be performed via the status field. This action will disable the account and render the personnel object inactive, thereby preventing the user from logging in and restricting other users from making assignments to the inactive user.

Specifications

File Formatting

CSV ("comma-separated value") is the preferred format. The data must meet the following criteria:

• Single header rows must be included; this allows the interface to validate the contents before acting on them.
• The comma character (ASCII 0x2C) is the preferred delimiter. The pipe character (ASCII 0x7C) is an alternate.
• Data should be wrapped in quote characters (ASCII 0x22) like this: "James", "Albright", "A12345", "Electrical Engineer"
• Inner quotes should be escaped with a preceding quote character, for example: "1/2"" valve, brass gate"

File Encoding

Data files should be encoded in one of the following schemes. Other encodings will result in errors that are difficult to track down and delays in file processing.

• ISO-8859-1 "Latin-1 Western European"
• Windows 1252 "Western European"
• UTF-8, no BOM (byte order marker)

File Naming Convention

To avoid potential problems during testing and integration, we encourage our customers to adopt the following file naming conventions before interface implementation begins:

• Avoid the use of spaces (ASCII 0x20) in file names
• Make sure file names are meaningful outside of the context of their directory structure; for example, 0052.txt is more difficult to understand than reporting-procedure-0052.txt
• Dates within file names that follow the ISO 8601 standard will be sorted in order when displayed in a group such as a directory listing

File Structure

For any interface it is necessary that each item have a unique search key which we can use to identify objects. If more than one unique exists in the system, it will error out. 

A typical example of the unique key for a person’s interface would be EmployeeID and for Organization interface it would be OrgID.

Persons File

The person interface 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 of record.

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

Organizations File

The organization interface can map data into any of the header or child level fields within the Foundation Organization module. The standard header row fields which dictate the data contained in the file is as

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

Summary Checklist

1. Customer provides CSV data sample — Customer
2. Mapping exercise (CSV headers → Person module fields) — Customer + Ideagen
3. Create HR interface subscriber role in Config — Ideagen
4. Create HR interface account (assigned to role in c) in Config — Ideagen
5. Request FTP credentials for customer — Ideagen
6. Produce XML mapping and hand off for RDL setup — Ideagen
7. RDL configured in Config on 4h scheduler — Ideagen
8. Config validation — Customer sends CSV via FTP, confirm results — Customer + Ideagen
9. Repeat c–h in PROD after Config sign-off — Ideagen
10. PROD validation with customer — Customer + Ideagen