This topic describes how to configure this integration.
This integration imports one employee record for each API request.
Tip: For an overview of API-based integrations and example APIs, see API-Based Integrations.
Before you start
Deploy the API-PeopleImport integration pack; see Deploy Integrations.
Configure the integration
Select the environment
-
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.
- Select the Manage tab > Atom Management.
- Select your environment.
Select environment extensions
- In Administration, click tap Environment Extensions.
- In Process Filter, click tap the magnifying glass
. It can take several seconds before the button becomes active. - Scroll to and select the integration pack: API-PeopleImport > API-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.
Configure connection settings
- Select Connection Settings.
-
From the Connection dropdown list, select and configure:
Connection Settings Setting Required Actions APIGatewayServer Required (Optional) To change the default API gateway server:
- Clear Use Default.
- Enter the URL to the server.
Example: <tenantURL>/api
AuthenticationServer Required - Clear Use Default.
- Enter the URL to the OpenAM server. OpenAM is an open-source server platform that manages access, authentication, authorization rules, entitlement, and federation. The URL must contain the server name and port followed by openam/oauth2. Example: http://<servername>:9012/openam/oauth2
Configure process properties
- Select Process Properties.
-
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.
- From the Process Property dropdown list, select AuthenticationProperties.
- In GatewayDefaultPort, clear Use Default. Enter the path to the port for the API gateway.
- In AppKey, clear Use Default. This disables cookies to set the access token such as to test or debug the integration. Enter an external AppKey.
-
From the Process Property dropdown list, select API-PeopleImport_ProcessProperties to set process properties that must be configured before the integration can run.
Process Properties Property Required Actions DisqualifyActive Not required To not process person records of active employees:
- Clear Use Default.
- Select Value.
DisqualifyInactive Not required To not process person records of inactive employees:
- Clear Use Default.
- Select Value.
DisqualifyTerminated Not required To not process person records of terminated employees:
- Clear Use Default.
- Select Value.
DisqualifyNew Not required To not process person records of new employees:
- Clear Use Default.
- Select Value.
DisqualifyExisting Not required To not process person records of current employees:
- Clear Use Default.
- Select Value.
AssignLicenses Not required Default = Hourly Timekeeping, Scheduling
To change the value:
- Clear Use Default.
- Select Value.
- Enter a comma-separated list of licenses to assign during the import or update of records.
AssignSkills Not required To assign skills during import:
The Scheduler license is required.
- Clear Use Default.
- Select Value.
AssignCertifications Not required To assign certifications during import:
The Scheduler license is required.
- Clear Use Default.
- Select Value.
_EnableCustomMapping
Not required To use a custom map:
- Clear Use Default.
- Select Value.
_DisableReportsToMapping
Not required Default = True, do not send employee-record reports to reporting manager.
To send the reports to the reporting manager:
- Clear Use Default.
- Leave Value blank.
RunRehireProcess Not required To import records of rehired people:
- Clear Use Default.
- Select the check box under Value.
EmpStatusEffDate Not required To change the effective date of the current status of employees:
- Clear Use Default.
- Enter the date; use YYYY-MM-DDformat.
Configure data maps
(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.
To customize data transformation, select the data map extension.
- Select Data Maps.
- From the Data Maps dropdown list, select one of the following:
- API-PeopleImport_SourceProfile—API-PeopleImport_PeopleImportProfile
- Custom map: The _EnableCustomMapping process property must be set to true. The source is empty and ready for you to add and map fields.
-
Select
to expand or 
to collapse levels. To expand all levels, right-click the green boxes icon
. Select Expand AllThe lines show the links between fields in the source (left side), any intermediate functions, and the destination (right side).
-
(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.
- In Function, click tap the plus button
to add an intermediate function.
- 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 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.
- Select the function from the list in the selected category.
- Click Tap OK.
- If prompted in Configure Defaults, enter the relevant values. Select a Caching. Click Tap OK.
- Select and drag from a source field to an input of the function.
- Select and drag from the output of the function to a destination field.
- Repeat to add another function.
- In Function, click tap the plus button
- Change mappings — When you customize a default data map, you can add fields only to the end of the map.
- When you finish, click tap OK.
Request format
Requests to the integration must be in JSON and have the following sections:
- Parameters: To pass from the source
- Data: For the integration to process
Example request
{
"parameters": [
{
"name": "falconExecutionId",
"value": "7"
},
{
"name": "tenantId",
"value": "combined"
},
{
"name": "DisqualifyActive",
"value": "false"
},
{
"name": "DisqualifyInactive",
"value": "true"
},
{
"name": "DisqualifyTerminated",
"value": "true"
}
],
"data": [
{
"name": "PersonNumber",
"value": "123456"
},
{
"name": "FirstName",
"value": "John"
},
{
"name": "LastName",
"value": "Smith"
},
{
"name": "MiddleInitial",
"value": "A"
},
{
"name": "ShortName",
"value": "JS"
},
{
"name": "BadgeNumber",
"value": "123456"
},
{
"name": "BirthDate",
"value": "1/30/1985"
},
{
"name": "PhoneNumber",
"value": "12345678901"
},
{
"name": "Email",
"value": "john.smith@company.com"
},
{
"name": "HomeAddressStreet",
"value": "100 Main Road"
},
{
"name": "HomeAddressCity",
"value": "Anytown"
},
{
"name": "HomeAddressState",
"value": "ST"
},
{
"name": "HomeAddressPostalCode",
"value": "01234"
},
{
"name": "HomeAddressCountry",
"value": "USA"
},
{
"name": "EmployeeStatus",
"value": "Active"
},
{
"name": "StatusStartDate",
"value": "7/22/2015"
},
{
"name": "HireDate",
"value": "7/20/2015"
},
{
"name": "WorkerType",
"value": "Full Time"
},
{
"name": "PrimaryJob",
"value": "Organization/United States/Metropolitan Plant/Machine Shop/Apprentice Welder"
},
{
"name": "EmployeeStandardHours",
"value": "42.5"
},
{
"name": "EmployeeFullTimeHours",
"value": "42.5"
},
{
"name": "IsManager",
"value": "Yes"
},
{
"name": "PayRule",
"value": "Full Time"
},
{
"name": "UserID",
"value": "123456"
},
{
"name": "Password",
"value": "5ecretPa$$w0rd"
},
{
"name": "UserAccountStatus",
"value": "Active"
}
]
}