Suomi
Platform status: -
  1. Nepton
  2. Support
  3. Integration
  4. HR data

Person Import

  • Updated

The person import features allow you to import personnel data (aka HR data) from third-party systems and files, directly into the platform. These imports can add information to the employee information managed and used in Personnel - section of the service This can be done manually, or automatically on a schedule. The feature is especially useful for making mass edits, or for when your HR master data is stored in another system. Our articles on exporting person data might also be of interest to you.

Nepton can import person data using three different methods:

 

1. Manual import: A single file containing personnel data can be selected to be manually imported to Nepton via Employees section. See guidance for manual person import here.

2. Scheduled import: the link for scheduled task can be found under Employees-Administration-Scheduled tasks. This method can be used to fetch data from a SFTP server or REST web service. If person import is scheduled to import persons from a SFTP server then we need to make sure that file name is unique to avoid any overwriting of the file. We append file creation time stamp with the csv-file's name, for example staff_import_20200305_234500.csv. Fields headings can be set either in scheduled task or as a part of the imported file. If the fields heading information is not in the import file, it must be set in the scheduled task. Guidance on how a scheduled task is created can be found here.

3. Via web service: customer can use our webservice methods ImportUsersFromCSV or ImportUsersFromXML to import person's information. API description can be found here.

Supported File Types

  • CSV
    • Semicolon (;) is used as field delimited character
    • Windows style \r\n or UNIX style \n new line character is used as line feed character
    • The first row must contain the list of person import headers separated by semicolon for fields used in each subsequent rows - unless the are provided separately (like Header row setting in Scheduled task - person import) in which case this first row of headers should not be provided.
  • Excel
    • The first row must contain the list of person import headers column by column for fields used in each subsequent rows. If the file contains columns that should not be imported, the list of column names included in import can be defined in the Fields to import setting in Scheduled task - person import.
  • XML or JSON
    • You can use existing names (names already mentioned at the bottom of the page in Table 1: Person import field names) as xml element/JSON field names. You only need to replace a space " " character with "_". For instance, "First name" becomes "First_name". Please note that Table1 has a separate column for xml field names.
    • The field name you want to use should comply to the followings:
      • Should start with a letter or _
      • Cannot start with xml or Xml
      • Cannot contains spaces
      • Can contains letters, digits, hyphens, underscores and periods
    • Person data separator node that contains person's data
      • If using a web service (only available for XML format) then provide xml node name in SeparatorNodeName parameter
      • If using a scheduled task then specify the node name in XML Separator text box (option only available for XML format)
      • If separator node is not specified then our service looks persons' data under ImportUserData XML node/JSON object

Xml file example: The node <ImportuserData> is person data separator node in the example below

<?xml version="1.0" encoding="UTF-8"?>
<Persons>
    <ImportUserData>
        <First_name>User</First_name>
        <Last_name>1</Last_name>
        <Username>User 1</Username>
        <Email>testuser1@test.com</Email>
    </ImportUserData>
    <ImportUserData>
        <First_name>User</First_name>
        <Last_name>2</Last_name>
        <Username>User 2</Username>
        <Email>testuser2@test.com</Email>
    </ImportUserData>
</Persons>

Supported Encodings

  • UTF-8
  • ISO-8859-1

Person import headers

Person import headers describe those columns that the transferred file contains. Header information can be set as the scheduled task header information or it can be part of the file that is transferred. You can find the columns supported by the person import in here. These fields are available when person import type is selected as to be 'default'. There are also system specific import types which are described in this guidance.

  • A field can be ignored by the importer by setting the field header to the capitalised keyword IGNORE

Mandatory Fields

For insert

  • First name
  • Last name

For update

  • Username or Employee number
  • If both are provided, the username is used as primary identifier, allowing the employee number to be changed
  • Usernames cannot be changed using the person importer. If username is trying to be updated then all data on that row is skipped and a warning message is shown for that row. 

Person's data validities - importing future changes

Person import supports cases where information is imported without validities and with validity information. Imported information should always contain data validities when possible. When the information has the validity set, the data can contain changes to validities in the past. If the imported information does not contain validities, then changes to the past validities of the person data is not possible.

 

Person Group

  • If the target person group doesn't exist, it is created at the root of the person group tree
  • A reset keyword will remove the person from any person group. There is no validity support for person group membership.

Person Group including hierarchy information

  • Used for both setting person's person group and importing the person group hierarchy
  • Support for importing this information depends on source system/import mapping

Person groups can be imported in two different ways

  • Using one field for person group codes and one for person group names
    • E.g. Codes, Names
      • Field naming depends on source system
    • Codes field contains pipe (|) character separated list of person group codes
      • Last rightmost code is the code of person's person group and codes left from that defined the person group hierarchy
    • Names field works the same way as codes field but it contains the names of the person groups
      • Names field usage is optional and additional information to the codes. In case only codes are defined, new groups will have code as name.
  • Using multiple fields for person group codes and multiple fields for person group names
    • E.g. Code1, Code2 and Name1, Name2
      • Field naming depends on source system
    • The order of the fields matter not the names of the fields
      • Last rightmost field is the code/name of persons person group and codes/names left from that defined the person group hierarchy
  • If person group hierarchy defined in import doesn't exist it will be created
    • If first leftmost group defined in import doesn't exist, it will be created as a root person group
      • Groups after first leftmost group in import, will be created under it, unless matching existing groups are found, in which case existing groups with members are moved to new position in the hierarchy
    • If first leftmost group defined in import exists, hierarchy defined in import will be created under it in case it doesn't exist
  • All person group codes must be unique, i.e. the same code cannot exist for two different groups even if they are in different hierarchies.

Unit

  • Can be set by either unit name or code
  • If you wish to set multiple relationships they must be separated by the pipe (|) character
  • The first Unit in the list will be set as primary unit
  • RESET keyword will remove all the units assigned to a person
    • Empty value will not remove the units for a person if the IgnoreEmptyValues setting is applied (e.g. via the web service)

Primary supervisors/Secondary supervisors

  • These two input fields are for setting primary and/or secondary supervisors by employee number (Primary supervisor and Secondary supervisors)
  • The primary supervisor field works in the following way:
    • If a value is provided then the existing primary supervisor is replaced with the new one
    • If there are more than one supervisors in this field, first one will be used as primary supervisor and rest of the supervisors will be ignored
    • Primary supervisor will be removed the field value is left empty in the import or the RESET keyword is imported as the value - regardless of if IgnoreEmptyValues setting is used or not (e.g. via the web service)
  • Secondary supervisors (Toissijaiset esimiehet) field works in the following way
    • With RESET| or NOLLA| prefix - This will replace any existing secondary supervisors, with the new supervisor(s)
    • Without RESET| or NOLLA| prefix - This will append new supervisor(s) to the existing secondary supervisors list
    • Support the RESET keyword and respects the IgnoreEmptyValues setting. i.e. It will leave supervisors as they are if an empty value is sent and IgnoreEmptyValues is True (e.g. via the web service)
  • At present the primary supervisor field only supports a single relationship, but later we will permit multiple primary supervisors

Work contract's duration change

  • Employment start date

    • If employment start date is not already set for a person, new date value is saved.
    • When employment start date has already been set for a person, it is only replaced if the new date is smaller than the set date or an empty value.

  • Employment end date

    • If employment end date is not already set for a person, new date value is saved.
    • When employment end date has already been set for a person, it is only replaced if the new date is greater then the set date or an empty value.

This restriction ensures that persons with multiple Employment start days are handled and showed correctly in Nepton. Full support for multiple Work contracts will be added to Nepton later.

If users are imported via the user interface, Employees->Persons->Import persons, any empty values in these fields are ignored.

Invalid role value

  • If an invalid role value is provided in the import file (for valid values check Roles field in article Person import fields)
    • New users will get a role of "Employee"
    • Existing user role will not be changed
    • A warning message is shown on the row has an invalid role value

Validity support in person import

The validities of the imported fields in person import are set with the following rules:

  1. The first values of some fields for persons imported for the first time are always defined without validity dates - regardless of Valid from date -field in the import file. These fields are First name, Last name, Password, Role, Service usage language and User account enabled.
  2. If there is a ‘Valid from date’ field (column/XML node) defined in the import file and there is a date value provided for the field:
    • Fields, for which there isn’t an existing value defined or for which the value is changing, the imported values are added or changed starting at the Valid from date value given (except for the mandatory fields which are imported for the first time, see point 1.)
    • If the imported value is already valid on the Valid from date, the validity start date is not changed.
    • Values valid before the Valid from date are not removed. If the existing value is different from imported value, its validity is ended on the day before the Valid from date.
    • The validity of the imported value is not ending. If there are existing values for the imported fields that were started/starting after the imported Valid from date, those values started/starting later will be removed and the imported value validity is continuing over these value validities.
    • If there are multiple rows imported for the same person with different Valid from date field values, the values are imported in the order of the Valid from date values. The imported row values are valid until the Valid from date field value of the next row and the row with the latest Valid from date value will be saved without a validity end date.
  3. If there is a ‘Valid from date’ field (column/XML node) defined in the import file, but the field value on the row is empty:
    • All imported values replace existing values without validity dates. Existing values with same value and without validity dates are not changed.
    • If additional rows are provided in the import file for the same person with a Valid from date value defined, these values start from the date provided and replace the values imported with empty valid from date from starting on that Valid from date.
  4. If there is no ‘Valid from date’ field (column/XML node) defined in the import file:
    • Fields, for which the person does not have previous values defined or for which the value is changed, the imported values are added or changing on the beginning of the day when the import is performed (except for the mandatory fields which are imported for the first time, see point 1.)
    • If the imported value of the field is already valid at the time of the import, the start date of the value is not changed.
    • Values valid before the day of the import are not removed. If the value is different from the value imported, its validity is ended on the day before the day the import is performed.
    • The validity of the imported field value is not ending. If the person has existing values for the imported fields for which the validity is starting later than the day of the import, the later values are removed and the imported field value validity is continuing over these value validities.

Recommendation: When importing values for the first time, it is recommended that the Valid from date is imported as an empty value. This way none of the imported values will have validity limitations and all possible existing values for these fields are removed.

Examples:

  1. Import with Valid from date value 16.09.2020 – no existing validity start dates:
    • Person has existing address: “1 First Street, City 12 345” – no validity start date.
    • Imported address: “3 Second Street, City 12 345” with Valid from date 16.09.2020.
    • Results:
      • Street address: “1 First Street” without start date, “3 Second Street” starting 16.09.2020.
      • Postcode: “12 345” without start date.
      • Town/city: “City” without start date.
  1. Import with Valid from date value 16.09.2020 – existing values with start dates:
    • Person has existing addresses:
      • “1 First Street, City 12 345” – no validity start date
      • “4 Second Road, Municipality 23 456” – validity start date 01.01.2020
      • “7 Fifth Avenue, City 12 345” – validity start date 01.10.2035
    • Imported address: “7 Third Road, Municipality 23 456” with Valid from date 16.09.2020.
    • Results:
      • Street addresses: “1 First Street” without start date, “4 Second Road” starting 01.01.2020, “7 Third Road” starting 16.09.2020.
      • Postcodes: “12345” without start date, “23 456” starting 01.01.2020.
      • Town/city fields: “City” without start date, “Municipality” starting 01.01.2020.
  1. Import with empty Valid from date:
    • Person has existing addresses:
      • “1 First Street, City 12 345” – no validity start date
      • “4 Second Road, Municipality 23 456” – validity start date 01.01.2020
      • “7 Fifth Avenue, City 12 345” – validity start date 01.10.2035
    • Imported address: “7 Third Road, Municipality 23 456” with empty Valid from date.
    • Results:
      • Street address: “7 Third Road” without start date.
      • Postcode: “23 456” without start date.
      • Town/city: “Municipality” without start date.
  1. Import without Valid from date field definition:
    • Person has existing addresses:
      • “1 First Street, City 12 345” – no validity start date
      • “4 Second Road, Municipality 23 456” – validity start date 01.01.2020
      • “7 Fifth Avenue, City 12 345” – validity start date 01.10.2035
    • Imported address: “7 Third Road, Municipality 23 456” without Valid from date field definition.
    • Results:
      • Street addresses: “1 First Street” without start date, “4 Second Road” starting 01.01.2020, “7 Third Road” without start date.
      • Postcodes: “12345” without start date, “23 456” starting 01.01.2020.
      • Town/city fields: “City” without start date, “Municipality” starting 01.01.2020.

 

 


Was this article helpful?
0 out of 0 found this helpful
Return to top