User profile synchronization

Description

User accounts may be created either manually on the interface by an administrator with account administration rights, or through a structured file import from the source information system (typically the HRIS).

Each account is assigned:

  • An access perimeter, based on the hierarchical structure of the organizations (see Organization synchronization), or the groups of organizations. This access perimeter may therefore be:

    • A particular organization: the user then has access to all of the employees (and documents/requests/tasks) associated with this organization

    • An organization and its sub-organizations: the user then has access to all of the employees (and documents/requests/tasks) associated with this organization or associated with one of its sub-organizations.

    • A group of organizations: the user then has access to all of the organizations included in the group of organizations, or in the list of organizations (Note: the “list” option is only usable via import).

  • A predefined role. Roles define general access rights (access to different parts of the application).

../../_images/organisation-tree-complete-view.png

Note

Roles are set up during the platform configuration phase and can be modified any time from the interface by an administrator.

Import file

Format

The synchronization of user accounts 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.

Accounts import can be defined as:

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

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

Note

Text type values can be single quoted ' if you need to declare the delimeter char ; in your text. It is also important to escape apostrophes if your text contains such characters. For example the text John's ID becomes 'John''s ID'

Structure

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

  • Mandatory attributes: Can be named as you wish, but 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 CSV file for User import must contain 11 mandatory attributes. The first row can therefore look like this:

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

  • Optional attributes: Have to follow the mandatory attributes, in any order, and their names must be as described in the present documentation. The first row can therefore look like this:

    1;2;3;4;5;6;7;8;9;10;11;timezone;language

    Or like this:

    1;2;3;4;5;6;7;8;9;10;11;language;timezone

  • Custom field filters: Have to follow the optional attributes (if any), and their names must be built as described in the present documentation. The first row can therefore look like this:

    1;2;3;4;5;6;7;8;9;10;11;timezone;language;employee_filter_service

    Or like this:

    1;2;3;4;5;6;7;8;9;10;11;employee_filter_service

Mandatory attributes

  1. lastname: VARCHAR(70) / mandatory value

    User last name

  2. firstname: VARCHAR(30) / mandatory value

    User first name

  3. technical_id: VARCHAR(50) / optional value

    Technical identifier of the user

    This identifier, which is obtained from the main information system (typically the HRIS), is optional. If present, it should be unique between the users and the employees and it becomes the unique identification key for this user (else the email is used). This identifier must be used, for example in the case of SSO (see Single sign-on with SAMLv2)

  4. email_pro: VARCHAR(70) / mandatory value

    User e-mail

    This e-mail is also the account login ID. For new accounts without SSO, users receive an invitation to activate their account at this address. They can then choose a personal password.

    Note: We do not currently support email addresses containing non-ASCII characters (RFC 6532 - Internationalized Email Headers).

  5. phone_number: VARCHAR(50) / optional value

    Phone number of the user. Format using International prefix format; for example 0018002251561.

  6. role_code: VARCHAR(70) / optional value or mandatory value

    Secondary identifier of the role

    Used to map the role identifiers within the third-party system and the UKG HR Service Delivery roles. This identifier is mandatory if the field role_id is not filled in.

  7. role_id: VARCHAR(70) / optional value or mandatory value

    UKG HR Service Delivery identifier of the role of the account user

    This identifier is mandatory if the field role_code is not filled in.

  8. type: {organization, organization_group, organization_list} / mandatory value

    Type of account access perimeter

    May take the values organization, organization group or organization list.

  9. operator: {=,<=,<>} / mandatory value

    • If the type is organization it may take the values:

      • = in order to define a parameter based on a single organization (without hierarchy)

      • <= in order to define a parameter based on an organization and its sub-organizations

    • If the type is organization_group it may take the value:

      • = in order to define a parameter based on a single organization (without hierarchy)

    • If the type is organization_list it may take the values:

      • = in order to define a parameter based on a single organization (without hierarchy)

      • <> in order to define a parameter based on all organizations with the exception of those indicated

  10. organization_code: TEXTFIELD / mandatory value

    • If the type is organization: Organization code

    • If the type is organization_group: Organization group

    • If the type is organization_list: List of organization codes, separated by ,

  11. delete: VARCHAR(1) / optional value

    Used to delete the user profile

    Enter the character ‘X’ to delete the profile, leave empty for a new profile or an update.

Optional attributes

saml_token: optional value

To use the SAMLv2 authentication method, you need to provide a saml authentication identifier for each UKG HR Service Delivery user profile. This identifier should be inserted as the value for the attribute saml_token to be transfered in the SAML Assertion by your Identity Provider during the authentication phase.

language: optional value

Language used by the user

Language code (2-3 chars) with locale variant (2+ chars) as per IETF BCP 47, separated by a hyphen (-), e.g. en-us. Using 2 characters language codes (ex: fr, en) is still supported but deprecated.

Supported languages: en-us, en-gb, fr-fr, fr-ca, de-de, pl-pl, zh-hans, zh-hant, cs-cz, da-dk, nl-nl, fi-fi, el-gr, hu-hu, it-it, ja-jp, nb-no, pt-pt, pt-br, ro-ro, ru-ru, sr-rs, sk-sk, sl-si, es-es, es-419, sv-se, tr-tr, vi-vn

Only a subset of the languages supported by UKG HR Service Delivery might be available on the platform depending on its configuration.

timezone: optional value

Timezone in the form Area/Location, e.g. America/New_York

List of values available in the IANA “Time Zone Database”, see https://www.iana.org/time-zones

legal_firstname: VARCHAR(70) / mandatory value if activated

User legal first name

This attribute is only used if the setting Preferred and Legal first name is activated and is ignored otherwise. If the setting is activated, any data received is taken into account, even an empty value: if an empty value is given, the legal_firstname for the user is cleared.

Custom fields filters

If custom fields are defined for employees, it is possible to use them to restrict access to the resource they are associated with. For each custom field a new attribute has to be added.

Attribute naming:

The attribute name must follow the convention: employee_filter_{custom_field}. For example, if the custom field “Type of contract” is defined for the employees with contracttype as a code, then the attribute must be named: employee_filter_contracttype.

Attribute values:

The value specifies the restrictions that apply on this specific custom field. The values must be defined as follows:

  • <=, {custom field value} (only in the case of a “hierarchical” attribute, that is when the possible values of this attribute are finite and ordered; only integer type custom fields can be hierarchical)

  • =, {custom field value 1}, {custom field value 2}, {custom field value 3}

  • <>, {custom field value 1}, {custom field value 2}, {custom field value 3} (different from, not available for custom fields of type string)

Note

  • When using the <> operator with a list custom field type, provide one value only. Multiple values are not supported.

  • For boolean custom fields, any character filled in is interpreted as true. To specify false, let the value empty

  • The not equal operator != cannot be used to apply restrictions.

For example:

  • For the custom field contracttype (integer, non hierarchical): =, permanent_contract, fixed_term_contract. The corresponding user can only access only the employees (and the documents related to the employees) that have their contractype custom field with the value permanent_contract or fixed_term_contract

  • For the custom field international_mobility (boolean): =, X (true) OR =, (false)

Note

  • If the value is null for one of the rows, no access restrictions based on the custom field are applied to the corresponding user. Therefore they see all employees and their documents, whatever the custom field value for the employee is.

  • When deciding which operator to use in the values, please be aware that if several custom fields are defined for a user profile for the same resource we combine them using the OR operator. For example: you have a custom field of type list with Employees, Executives and HR as values. Defining <> Executives and <> HR to only give access to Employees is not interpreted as <> than HR AND Executives but as <> than HR OR <> than Executives. As a result you should express the same constraint with = Employees.

Sample CSV file without access restriction rules

lastname;firstname;technical_id;email_pro;phone_number;role_code;role_id;type;operator;organization_code;delete;language;timezone
Doe;John;007;john.doe@acme.com;0033600000000;CLIENT_ROLE_34;;ORGANIZATION;<=;ORGA1;;fr-fr;Europe/Paris
Doe;Jane;008;jane.doe@acme.com;;CLIENT_ROLE_32;;ORGANIZATION_GROUP;=;ORGA2;;en-us;
Left;Michael;009;michael.left@acme.com;;CLIENT_ROLE_32;;ORGANIZATION_LIST;=;ORGA2,ORGA1;;;America/New_York
Smith;Mike;010;mike.smith@acme.com;;CLIENT_ROLE_32;;ORGANIZATION_LIST;<>;ORGA2,ORGA1;;;

Download a sample user import file

Warning

You have to modify the sample values before you import this file on your platform.

Sample CSV file with access restrictions rules

lastname;firstname;technical_id;email_pro;phone_number;role_code;role_id;type;operator;organization_code;delete;language;timezone;employee_filter_contracttype
Doe;John;007;john.doe@acme.com;0033600000000;CLIENT_ROLE_34;;ORGANIZATION;<=;ORGA1;;fr-fr;Europe/Paris;=,permanent,fixed,intern
Doe;Jane;008;jane.doe@acme.com;;CLIENT_ROLE_32;;ORGANIZATION_GROUP;=;ORGA2;;en-us;;=,intern
Left;Michael;009;michael.left@acme.com;;CLIENT_ROLE_32;;ORGANIZATION_LIST;=;ORGA2,ORGA1;X;;America/New_York;
Smith;Mike;010;mike.smith@acme.com;;CLIENT_ROLE_32;;ORGANIZATION_LIST;<>;ORGA2,ORGA1;;;;<>,fixed

Sample CSV file with saml_token

lastname;firstname;technical_id;email_pro;phone_number;role_code;role_id;type;operator;organization_code;delete;saml_token;language;timezone
Doe;John;007;john.doe@acme.com;0033600000000;CLIENT_ROLE_34;;ORGANIZATION;<=;ORGA1;;saml_token_1;fr-fr;Europe/Paris
Doe;Jane;008;jane.doe@acme.com;;CLIENT_ROLE_32;;ORGANIZATION_GROUP;=;ORGA2;;saml_token_2;en-us
Left;Michael;009;michael.left@acme.com;;CLIENT_ROLE_32;;ORGANIZATION_LIST;=;ORGA2,ORGA1;X;saml_token_3;;America/New_York
Smith;Mike;010;mike.smith@acme.com;;CLIENT_ROLE_32;;ORGANIZATION_LIST;<>;ORGA2,ORGA1;;saml_token_4;;

Report file

For each import, a report file is generated. This file may be downloaded from the interface or made available on the SFTP server.

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 French format (DD/MM/YYY HH:SS) on which the report was generated.

  • JOB_DESCRIPTION: Import title

  • JOB_TYPE: usr for the user import report

  • COUNT_ROWS: Number of total lines processed

  • MESSAGE: Feedback corresponding to one line

    • ENTITY_ID: User identifier reported on the line

    • ENTITY_TYPE: “Manager” in this report

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

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

Example

<MANAGER_REPORT version="1.0">
    <JOB_REFERENCE>cmpTz0hPr.csv</JOB_REFERENCE>
    <JOB_REPORT_TIMESTAMP>28/11/2020 12:29:39</JOB_REPORT_TIMESTAMP>
    <JOB_DESCRIPTION>Managers import</JOB_DESCRIPTION>
    <JOB_TYPE>usr</JOB_TYPE>
    <COUNT_ROWS>3</COUNT_ROWS>
    <MESSAGE ENTITY_NAME="Novapost Ref">
        <ENTITY_ID/>
        <ENTITY_TYPE>Manager</ENTITY_TYPE>
        <RESULT_CODE>504</RESULT_CODE>
        <RESULT_MESSAGE>
            Role with external id BYUE does not exist line: 75
        </RESULT_MESSAGE>
    </MESSAGE>
    <MESSAGE ENTITY_NAME="Novapost Ref">
        <ENTITY_ID/>
        <ENTITY_TYPE>Manager</ENTITY_TYPE>
        <RESULT_CODE>504</RESULT_CODE>
        <RESULT_MESSAGE>
            Role with external id BYUE does not exist line: 84
        </RESULT_MESSAGE>
    </MESSAGE>
            <MESSAGE ENTITY_NAME="Novapost Ref">
                    <ENTITY_ID>pk:32513 John Doe</ENTITY_ID>
                    <ENTITY_TYPE>Manager</ENTITY_TYPE>
                    <RESULT_CODE>0</RESULT_CODE>
                    <RESULT_MESSAGE>Manager John DOE Created</RESULT_MESSAGE>
            </MESSAGE>
</MANAGER_REPORT>