Configure the Universal People Import Integration

This topic describes how to configure this integration.

This integration pack imports employee records from a flat file.

Universal integration packs exchange data by way of flat files, either to export data to the file or import data from the file. Other systems access the data in these flat files to complete the import or export integration. The default settings allow rapid configuration and runs of the integration process, while the exposure of the data maps and cross-reference tables in the extensions allows overrides and customizations of the default data mappings or values.

Before you start

Deploy the PeopleImport integration pack; see Deploy Integrations.

Configure the integration

  1. Open the Integration Template Designer: Select Main Menu  > Administration > Application Setup > Integrations Setup > Design Integration Templates.

    Note: If prompted, enter your Username and Password. Click Tap Log in.

  2. Select the Manage tab > Atom Management.
  3. Select your environment.
  1. In Administration, click tap Environment Extensions.
  2. In Process Filter, click tap the magnifying glass Search button. It can take several seconds before the button becomes active.
  3. Scroll to and select the integration pack: Universal People Import > PeopleImport.

Caution: If you select Use Default for the connection settings and process properties, ensure that Value is blank. If Value is not blank, that value overrides the default value whether or not Use Default is selected or cleared. Example: If the default value is abc, but Value shows xyz, the integration uses xyz regardless of the setting of Use Default.

  1. Select Connection Settings.

  2. From the Connection dropdown list, select and configure the following:

    Connection Settings
    Setting Required Actions
    APIGatewayServer Required

    To change the default API gateway server:

    1. Clear Use Default.
    2. Enter the URL to the server.

      Example: <tenantURL>/api
    SFTPServer Required

    The SFTP server setting defines the connection to the file that contains the records. Integrations access only the internal SFTP account.

    To change the default SFTP server parameters:

    1. For each field, clear Use Default.
    2. Enter the following values:

      • Enter the name of the internal Host.

      • Enter the number of the Port for the internal SFTP account.

      • In User, enter the username for the internal SFTP account.

      • In Password, select <Encrypted>. Enter the new password for the internal SFTP account.

      • Click Tap Apply.
  1. Select Process Properties.

  2. Caution: Do not edit the default values of the AuthenticationProperties. By default, cookies are enabled and set the values for authentication properties.

    Only while you test or design integration templates, should you edit the properties to connect to the authentication server and get the access token to execute APIs.

    1. From the Process Property dropdown list, select AuthenticationProperties.
    2. In GatewayDefaultPort, clear Use Default. Enter the path to the port for the API gateway.

    3. Note: You no longer need an AppKey to call API operations. If one is defined, it is ignored.

  3. From the Process Property dropdown list, select PeopleImport-v1_CRTConfig to define headers in cross-reference tables.

    Cross-reference tables (CRT) are the look-up tables that the integrations use to translate parameter values. One or more data values from the source system can be used to assign one or more parameters in the destination system.

    Caution: The Boomi™ application does not return default values for cross-reference table headers. You have to enter the headings in Value.

    Note: For details, see Configure cross-reference tables.

    For each of the tables:

    1. Clear Use Default. 
    2. In Value, enter the header column names, separated by commas (,) but no spaces, exactly as shown below the Value field. You can select and copy the headers from the screen, then paste them in the Value field.
    3. Repeat for the other tables.

  4. From the Process Property dropdown list, select PeopleImport_ProcessProperties to set process properties that must be configured before the integration can run.

    Caution: If you select Use Default for the connection settings and process properties, ensure that Value is blank. If Value is not blank, that value overrides the default value whether or not Use Default is selected or cleared. Example: If the default value is abc, but Value shows xyz, the integration uses xyz regardless of the setting of Use Default.

    Process Properties
    Property Required Actions
    DisqualifyActive Not required

    To not process person records of active employees:

    1. Clear Use Default. 
    2. Select Value.
    DisqualifyInactive Not required

    To not process person records of inactive employees:

    1. Clear Use Default. 
    2. Select Value.
    DisqualifyTerminated Not required

    To not process person records of terminated employees:

    1. Clear Use Default. 
    2. Select Value.
    DisqualifyNew Not required

    To not process person records of new employees:

    1. Clear Use Default. 
    2. Select Value.
    DisqualifyExisting Not required

    To not process person records of current employees:

    1. Clear Use Default. 
    2. Select Value.
    AssignLicenses Not required

    Default = Hourly Timekeeping, Scheduling

    To change the value:

    1. Clear Use Default.
    2. Select Value.
    3. Enter a comma-separated list of licenses to assign during the import or update of records.
    EnableTransactionAssistant Not required

    Default = true

    To not submit import errors to Transaction Assistant Corrects transaction errors in integrations without the need to resubmit entire projects.:

    1. Clear Use Default. 
    2. Select Value.
    BatchName Not required

    Default = Generic People Import

    To change the value:

    1. Clear Use Default.
    2. Select Value.
    3. Enter the batch name to group the failed records in Transaction Assistant.

    _EnableCustomMapping

    		Not required

    To use a custom map:

    1. Clear Use Default.
    2. Select Value.

    _DisableReportsToMapping

    		Not required

    Caution: If the people records include new managers, the Reports To field for their employees can be wrong and cause errors because the manager records may be imported after the employee records. To prevent these errors, the person who imports the people records must run the integration twice: the first time with DisableReportsTo selected, and the second time with DisableReportsTo not selected.

    Default = True, do not send employee-record reports to reporting manager.

    To send the reports to the reporting manager:

    1. Clear Use Default.
    2. Leave Value blank. 
    Delimiter Not required

    Default = comma (,)

    To change the character that separates data values in the flat file:

    1. Clear Use Default. 

    2. Enter the character.
    UnassignLicenses Not required

    To remove licenses during the import:

    1. Clear Use Default.
    2. Enter the licenses, separated by commas (,).
    Roles Not required

    Default = Employee,Manager

    Caution: Managers can have multiple roles. In most cases, People Import integrations update only the attribute values of the default role if the source of record has changed, and do not import data for other roles that are assigned to the managers. However, integrations can be modified to support imports of multiple manager roles.

    To change the roles to assign during the import or update:

    1. Clear Use Default. 
    2. Enter the licenses separated by commas (,).
    Hyperfind A search engine that filters and selects groups of employees through queries that specify conditions or locations (criteria). Not required

    Default = 1 (shown as blank) which indicates All Home A query that returns a list of employees associated with a manager's employee group. All Home finds people who are active employees or active users as of today. and includes all active employees.

    To use a Hyperfind query for another group of employees:

    1. Clear Use Default.
    2. Enter the ID of the Hyperfind.
      Note:
      • Ad-hoc Hyperfinds are not supported.
      • All Home does not include terminated and inactive employees even if they have totals during the period. To include these totals, configure a Hyperfind that includes terminated and inactive employees and select that Hyperfind in this process property.
      • The maximum number of employees in a Hyperfind is 3500. To process more employee records, divide the population into smaller Hyperfinds to run sequentially.
    PayPeriod Not required

    Default = 13 (Today)

    To change the pay period:

    1. Clear Use Default.
    2. Enter one of the following values for the pay period:

      0 = Previous pay period

      1 = Current pay period

      2 = Next pay period

      3 = Previous schedule period A repeating span of days in the schedule that is defined for administrative purposes, such as pay periods.

      4 = Current schedule period

      5 = Next schedule period

      6 = Week to date

      7 = Last week

      8 = Yesterday

      10 = Range of relative dates

      11 = Specific date

      12 = Relative specific date

      13 = Today
    _PayPeriodSpan Not required

    To define a fixed span for which to get data:

    1. Clear Use Default.
    2. Enter the date span in MM/DD/YYYY MM/DD/YYYY format.
    _Threshold Not required

    Default = 5000

    To define a larger or smaller maximum number of people for which to get data:

    1. Clear Use Default.
    2. Enter the maximum number without decimals.
    _ProcessExtendedDataMap1 Not required

    To enable processing by way of an extended data map:

    1. Clear Use Default.
    2. Select Value.
    _ProcessExtendedDataMap2
    _ProcessExtendedDataMap3

    _ProcessExtendedDataMap4

    EnableLogging Not required

    Tip: By default the logs for API responses are created in the atom cloud. To view the logs for process errors, select Manage > Process Reporting.

    To create log files of data map output:

    1. Clear Use Default.
    2. Select Value.
    _EnableFixedLengthMapping Not required

    To set data transformation to fixed-length profile mapping:

    1. Clear Use Default.
    2. Select Value.

  5. From the Process Property dropdown list, select PeopleImport_RehireProcessProperties to set process properties for the integration to process data for rehired employees.

    Rehire Process Properties
    Property Required Actions
    _EnableCustomMappingForRehire Not required

    To define custom mapping and not use the default data map for rehired employees:

    1. Clear Use Default.
    2. Select Value.
    _ProcessRehires Not required

    To enable processing of rehired employees:

    1. Clear Use Default.
    2. Select Value.
    _ProcessExtendedMapForRehire1 Not required

    To enable processing by way of an extended data map:

    1. Clear Use Default.
    2. Select Value.
    _ProcessExtendedMapForRehire2
    _ProcessExtendedMapForRehire3
    _ProcessExtendedMapForRehire4
    HyperfindTypeForRehire Not required

    Default = Hyperfind

    Do not change this property.
    HyperfindForRehire Not required

    Default = 1 (shown as blank) which indicates All Home and includes all active employees.

    To use a Hyperfind query for another group of employees:

    1. Clear Use Default.
    2. Enter the ID of the Hyperfind.
      Note:
      • Ad-hoc Hyperfinds are not supported.
      • All Home does not include terminated and inactive employees even if they have totals during the period. To include these totals, configure a Hyperfind that includes terminated and inactive employees and select that Hyperfind in this process property.
      • The maximum number of employees in a Hyperfind is 3500. To process more employee records, divide the population into smaller Hyperfinds to run sequentially.
    PayPeriodForRehire Not required

    Default = 13 (Today)

    To change the pay period:

    1. Clear Use Default.
    2. Enter one of the following values for the pay period:

      0 = Previous pay period

      1 = Current pay period

      2 = Next pay period

      3 = Previous schedule period

      4 = Current schedule period

      5 = Next schedule period

      6 = Week to date

      7 = Last week

      8 = Yesterday

      10 = Range of relative dates

      11 = Specific date

      12 = Relative specific date

      13 = Today
    _PayPeriodSpanForRehire Not required

    To define a fixed span for which to get data:

    1. Clear Use Default.
    2. Enter the date span in MM/DD/YYYY MM/DD/YYYY format.
    _ThresholdRehire Not required

    Default = 5000

    To define a larger or smaller maximum number of people for which to get data:

    1. Clear Use Default.
    2. Enter the maximum number without decimals.
    EmploymentStatusEffDateForRehire Not required

    To set a default effective date for the employment status of rehired employees to change to hired:

    1. Clear Use Default. 
    2. Enter the date in MM/DD/YYYY format.
    _EnableFixedLengthProfileMapping Not required

    To set data transformation to fixed-length profile mapping:

    1. Clear Use Default.
    2. Select Value.

  6. From the Process Property dropdown list, select PeopleImport_SFTPProperties.

    SFTP Properties
    Property Required Actions
    SourceDirectory Required

    The directory path on the SFTP server where the integration process reads the file.

    Default = Use the /Inbound directory.

    To define a different directory path:

    1. Clear Use Default.
    2. Enter the path to the directory.

      Caution: Make sure that this directory is configured on the SFTP server.
    _OutputDirectory Not required

    Directory on the SFTP server where the destination file is archived after processing.

    Default = use the default /outbound directory.

    To define a different directory path:

    1. Clear Use Default.
    2. Enter the path to the directory.

      Caution: Make sure that this directory is configured on the SFTP server.
    _MoveProcessedFileToDirectory Not required

    The directory on the SFTP server to move the destination file after data is successfully uploaded.

    Default = true, use the default directory.

    To define a different directory path:

    1. Clear Use Default.
    2. Enter the path to the directory.

      Caution: Make sure that this directory is configured on the SFTP server.
    _DeleteSourceFileAfterReading Not required

    Default = false; do not delete the source file after processing.

    To delete the source file but archive it to _DestinationDirectoryPath:

    1. Clear Use Default.
    2. Select Value.

    SourceFileName

    		Not required

    The name of the file that contains the data to import.

    Default = true, use the default file name.

    To define a different file name:

    1. Clear Use Default. 

    2. Enter the filename. Use a .csv extension.

      You can use the asterisk (*) or question mark (?) as wildcard characters to enter patterns of file names so that the integration reads only files that have names that match this filter.

    Default = Baseline_PeopleImport_univ.csv.

Cross-reference tables (CRT) are the look-up tables that the integrations use to translate parameter values. One or more data values from the source system can be used to assign one or more parameters in the destination system.

A cross-reference table (CRT) translates parameter values in an integration as follows:

  • Organizes data values into rows and columns:
    • Maximums = 20 columns, 10,000 rows.
  • Can combine values from multiple columns to determine a single output value.
  • If more than one row matches a reference value, the first match is the output value.
  • If no match is found, the output value can be null, or the integration can produce errors.

  1. Caution: For the cross-reference tables that you are customizing, make sure that Use Default is not selected in Process Properties > {ProcessName}_CRTConfig, and that the headers are defined.

  2. Select Cross Reference.

  3. From the Cross Reference dropdown list, select one of the following:

    You cannot change the names of the tables.

    _PeopleImport-v1_LookupTable1—5 — Column headers:

    Field1,Field2,Field3,Field4,Field5,Field6,Field7,Field8,Field9,Field10,Field11,
    Field12,Field13,Field14,Field15,Field16,Field17,Field18,Field19,Field20

    _PeopleImport-v1_PayperiodLookupTable — Column headers:

    Payperiod,Symbolicperiod

  4. Select Override to:

    • Download the tables when you run the integration
    • Edit the table cells in Extensions
  5. Repeat for other tables.

(Optional)

A data map translates a data structure from the source format to the destination format. Examples: Map "PersonID" in the source to "Person ID" in the destination or "LastName" to "Last Name".

Each integration pack has a default data map. Editing of the default map is limited to adding fields, changing mappings, or inserting functions. Any changes override the previous values. If the predefined fields do not suite your requirements, use the default map as a guide when you create your custom data map.

Override fields by a null output

A person record has PrimaryEmail which maps to EMailAddress1 and SecondaryEmail which maps to EMailAddress2.

If the integration imports only the SecondaryEmail address and not the PrimaryEmail address, insert a function to map EMailAddress2 to a null value as follows:

  1. Insert a String Replace function between SecondaryEmail and EMailAddress2.
  2. Map SecondaryEmail to Original String and String to Search.
  3. Map Result to EMailAddress2 > Address.

Override field example

Requirements

  • All fields require the Timekeeping license.
  • Each of the templates must define record disqualification and exclusion criteria.

Customize data transformation

  1. Select Data Maps.

  2. From the Data Maps dropdown list, select one of the following:

    • Default map: PeopleImport_A_FlatFileProfile

      Data map: Import People Records from flat file

      • Required fields are defined in the API and are indicated in the table.
      • Effective dating is defined in the API. If effective dates are not provided, the dates default to today.
      • Date fields use YYYY-MM-DD format.
    • Custom map: PeopleImport_B_CustomFlatFileProfile

      The _EnableCustomMapping process property must be set to true. The source is empty and ready for you to add and map fields.

      Map source, empty

    • The other data maps are variations for extended data maps. The corresponding _ProcessExtendedDataMap process properties must be enabled.

  3. Select Expand to expand or Collapse to collapse levels.

    To expand all levels, right-click the green boxes icon Map level options. Select Expand AllExpand all map levels.

    The lines show the links between fields in the source (left side), any intermediate functions, and the destination (right side).

  4. (Optional)

    Caution: The default mappings are developed and tested based on best practices. If you make changes, you may get unexpected results. Modify and test carefully.

    • Change mappings — When you customize a default data map, you can add fields only to the end of the map.

      You can select and drag to change the links between the source (left column), function (middle column), and destination (right column) items. A single source field can link to multiple destination fields, but a destination field can link to only one source field.

    • Transform the data — A map can include intermediate functions that transform the data. Examples: Perform mathematical calculations on the values or get values from a cross-reference table.

      Note: To override a field — for example because you cannot delete it from a default map — insert a function that has a null output.

      1. In Function, click tap the plus button Add map function to add an intermediate function.
      2. From Category, select a category of functions:

        String — Trim, add to, concatenate, replace, remove, split, or change the case of text.

        Caution: Do not use special characters Special characters are characters that are neither alphabetic nor numeric. These characters may not be allowed in text because they have programmatic uses. Other terms for special characters include reserved characters, restricted characters, forbidden characters, excluded characters, included characters. such as angle brackets (< or >) in data in cross-reference tables, data maps, and input files. These characters can make the integration fail.

        Numeric — Perform mathematical calculations on the data.

        Date — Change the format or get the current date.

        Lookup — Get data from a cross-reference table (CRT), document cache, SQL query, or define a key-value change.

        Connector — Call a value from a connector to an application or data source.

        Custom Scripting — Transform data by way of Groovy or JavaScript code.

        Properties — Get or set process or document properties.

      3. Select the function from the list in the selected category.
      4. Click Tap OK.
      5. If prompted in Configure Defaults, enter the relevant values. Select a Caching. Click Tap OK.
      6. Select and drag from a source field to an input of the function.
      7. Select and drag from the output of the function to a destination field.
      8. Repeat to add another function.
  5. When you finish, click tap OK.

Base integrations: PeopleImport-v1 and Universal People Import (QA or NPR)

Default source file = Baseline_PeopleImport_univ.csv.

Design

This section provides detailed information to help you to assess whether this integration meets your business needs.

Universal people import flowchart