Organization synchronization¶

Format¶

The synchronization of organizations is done through the import of a UTF-8-encoded CSV file. This import may be done manually through the administration web interface, or automatically using SFTP.

Organization import can be defined as:

• incremental: Only new and updated organizations are in the CSV file. New organizations are created. Existing organizations mentioned in the file are updated with its content. Existing organizations not in the file are left unchanged.

• or complete: All organizations are in the CSV file. New organizations are created. Existing organizations are updated with its content only if changes are detected.

Structure¶

The first row of the CSV file must comply with the following rule:

All attributes** must be present and in the order described in the present documentation. Their values, however, can be optional (see the description for each mandatory attribute below). The first row can therefore look like this:

1;2;3;4;5;6;7;8;9;10;11;12;13;14

1. organization_code: VARCHAR(64) / mandatory value

   Organization code. This code must be unique throughout the tree structure of the organizations

2. name: VARCHAR (255) / mandatory value

   Organization name. This is the name that is used in the interface to refer to this organization

3. parent_organization_code: VARCHAR(64) / mandatory value or optional value

   Code of the parent organization. Used to define the organization hierarchy (in this case, mandatory). Leave blank to define a primary-level organization

4. description: VARCHAR(255) / optional value

   Description of the organization (displayed only in the administration interface)

5. company_name: VARCHAR (50) / optional value

   Legal name of the organization (displayed only in the administration interface). Mandatory when packages are delivered containing printed files

6. firstname: VARCHAR(50) / optional value

   First name of the contact within the organization. Mandatory when packages are delivered containing printed files

7. lastname: VARCHAR(70) / optional value

   Last name of the contact within the organization. Mandatory when packages are delivered containing printed files

8. address1: VARCHAR(250) / optional value

   Address of the contact within the organization. Mandatory when packages are delivered containing printed files

9. address2: VARCHAR(250) / optional value

   Additional address information for the contact within the organization. Used when packages are delivered containing printed files

10. zip_code: VARCHAR(10) / optional value

    Zip code of the contact within the organization. Mandatory when packages are delivered containing printed files

11. city: VARCHAR(50) / optional value

    City of the contact within the organization. Mandatory when packages are delivered containing printed files

12. country_code: VARCHAR(2) / optional value

    ISO country code (FR, EN, ES…). Mandatory when packages are delivered containing printed files

13. phone_number: VARCHAR(50) / optional value

    Phone number of the contact within the organization. Used when packages are delivered containing printed files. Format using International prefix format; e.g. 0018002251561.

14. email: VARCHAR(70) / optional value

    E-mail address of the contact within the organization. Used when packages are delivered containing printed files

    E-mail address of the contact within the organization. Used when packages are delivered containing printed files

Example of a complete CSV file¶

'Org code';'Name';'Parent code (empty if primary)';'Description';'Company name';'First name';'Last name';'Address 1';'Adress 2';'ZIP code';'City';'Country code';'Phone';'Email'
'X00001';'JS Corporation';;'Description of the primary company A';'JS Corp';'John';'Smith';'277 Wellington Street West';'Suite 801';'M5V3E4';'Toronto';'CA';'4168618530';'[email protected]'
'X0000A';'A';'X00001';;;;;;;;;;;
'X0000B';'B';'X0000A';;;;;;;;;;;
'X0000Aa';'Aa';'X0000A';;;;;;;;;;;
'X0000Aa1';'Aa1';'X0000Aa';;;;;;;;;;;
'X0000Aa2';'Aa2';'X0000Aa';;;;;;;;;;;
'X0000Ba';'Ba';'X0000B';;;;;;;;;;;

Download a sample organization import file

Format¶

The report file is produced in XML format. The fields are the following:

• JOB_REFERENCE: Internal processing reference, corresponding to the name of the import file renamed on UKG HR Service Delivery

• JOB_REPORT_TIMESTAMP: Date in ISO format (YYYY-MM-DDThh:mm:ss±hh:mm) on which the report was generated.

• JOB_DESCRIPTION: Import title

• JOB_TYPE: sir for the organization import report

• COUNT_ROWS: Number of total lines processed

• MESSAGE: Feedback corresponding to one line

  • ENTITY_ID: Organization code indicated on the line

  • ENTITY_TYPE: “Organization” in this report

  • RESULT_CODE: 0 (organization created), 1 (organization updated), != 1 (error)

  • RESULT_MESSAGE: Message describing the action performed or the error encountered

Example¶

<ORGANIZATION_REPORT version="1.0">
    <JOB_REFERENCE>cmpjTABvS.csv</JOB_REFERENCE>
    <JOB_REPORT_TIMESTAMP>2021-03-19T13:05:50.648461+00:00</JOB_REPORT_TIMESTAMP>
    <JOB_DESCRIPTION>Organization import DEMO</JOB_DESCRIPTION>
    <JOB_TYPE>sir</JOB_TYPE>
    <COUNT_ROWS>3</COUNT_ROWS>
    <MESSAGE ENTITY_NAME="Novapost Ref">
        <ENTITY_ID>sub-sub-org</ENTITY_ID>
        <ENTITY_TYPE>Organization</ENTITY_TYPE>
        <RESULT_CODE>0</RESULT_CODE>
        <RESULT_MESSAGE>Organization Created</RESULT_MESSAGE>
    </MESSAGE>
    <MESSAGE ENTITY_NAME="Novapost Ref">
        <ENTITY_ID>sub-org</ENTITY_ID>
        <ENTITY_TYPE>Organization</ENTITY_TYPE>
        <RESULT_CODE>0</RESULT_CODE>
        <RESULT_MESSAGE>Organization Created</RESULT_MESSAGE>
    </MESSAGE>
    <MESSAGE ENTITY_NAME="Novapost Ref">
        <ENTITY_ID>org</ENTITY_ID>
        <ENTITY_TYPE>Organization</ENTITY_TYPE>
        <RESULT_CODE>0</RESULT_CODE>
        <RESULT_MESSAGE>Organization Created</RESULT_MESSAGE>
    </MESSAGE>
</ORGANIZATION_REPORT>