Suomi
Platform status: -
  1. Nepton Support
  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.

 

If you are using a service, that has an specific implementation, then import content should is set up based on the specific example provided. Service specific guidance is explained in this article.

 

Import methods

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
    • You can use existing field names as xml element field names. You only need to replace a space " " character with "_" for XML-format. 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 (XML-format)
      • 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
  • JSON
    • Use existing field names as  field names
    • On default import type, import persons as "ImportUserData"-table elements
    • Import empty field values "null" or "" 
    • For files use file extension ".json"
    • See the JSON content example from lower on the article

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>

JSON-example file content:

{
   "ImportUserData":[
      {
         "Henkilönumero":"123456",
         "Etunimi":"Matti",
         "Sukunimi":"Esimerkki",
         "Ammattinimike":"Suunnittelija",
         "Työsuhteen alkupäivä":"01.04.2019",
         "Työsuhteen päättymispäivä":""
      },
      {
         "Henkilönumero":"23456",
         "Etunimi":"Juha",
         "Sukunimi":"Esimerkki",
         "Työsuhteen alkupäivä":"01.07.2022",
         "Työsuhteen päättymispäivä":null
      }
   ]
}

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

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.

Include the date on which value changes should become effective on

By including a date on which imported information becomes valid, the data can be imported correctly no matter when the actual import is done. This also makes recovery in the event of failures, much easier. More about the subject.

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.