Initial Import: Configuring the API for Import Map Details
This topic guides you through configuring the Import Map Details. In the Add Parameter section, you specify a set of name-value pairs for each Field to be included in the import file.
To configure the API:
- Go to System Admin > Advanced > API Configuration.
The API Configuration dashboard opens. - If there is no API entry in the list, then click Add.
The API Configuration form opens. The API Configuration form has an API Configuration fieldset that contains the information necessary to connect to the specific PrismHR installation for the Client. The example shows test data. Use actual client data when configuring.
API Type | Select PrismHR API. | ||||||||||||
Application Code | Use a unique value to denote the PrismHR installation, such as PrismHRAPI. | ||||||||||||
Application Name | A description that displays in the ClientSpace lists. Use something to indicate the installation, such as PrismHR API. | ||||||||||||
Username | The username registered with the PrismHR API for this site. | ||||||||||||
Password | The password that is associated with the PrismHR Account Username for this site. | ||||||||||||
Description | Provide a description. | ||||||||||||
Endpoint |
A formatted URL pointing to the API services for the specific PrismHR client and site (must include the trailing / character).
For the GetPayrollBatchCutoffDate parameter, specify version 1.22 or higher of the PrismHR API. Note: Failure to update the version in the API Endpoint config results in the following error in the API log: Error Processing Batch Control Info '202023.104', error=Unexpected character encountered while parsing value: }. Path 'PayrollBatchWithOptionsResponse', line 1, position 35., queue record will be in Pending status. |
||||||||||||
Secondary ID | An identifier that is used to enable the monitoring of all PrismHR clients at an installation. | ||||||||||||
Logging Level |
|
||||||||||||
Active | When this option is selected, the configuration is active (enabled). |
To configure Additional Parameters:
This is where you specify a set of name-value pairs to configure the process.
-
Click Add Parameter.
A new row opens. -
Select from the following list to add parameters.
Parameter |
Value settings |
---|---|
AllowUserTypes |
Defines the types of users included in a user import:
|
BillingBatchCount |
Controls the number of payroll batches processed at once during the PrismHR Import Payroll Batch Complete scheduled process (which is one of two scheduled processes used by the Payroll Batch process.) By default, it is set to 250. This means that an import file containing more than 250 batches is processed in chunks of 250 to reduce impact on the server. Also see Configuring the Payroll Batch Scheduled Processes. |
CanCreateWorkspaces |
Created to support multi-tenant environments where there are multiple PrismHR API imports and a need to specify which PrismHR import feeds create a new workspace from an import record and which do not.
When PrismHR nightly imports run, ClientSpace evaluates each import file to determine if the PEOID in the import file matches the Secondary ID entered on the API Configuration record. If there is a match, ClientSpace then references the CanCreateWorkspaces parameter to determine if a workspace should be created using the following logic:
|
ContactImportBehavior |
|
DefaultProjectCode |
Defines where an employee portal case is created if no workspace match is found. Uses ProjectCode from workspace settings. |
ExcludeCompanyFromSync |
|
ExcludedContractTypes |
ASO and HRO are the PrismHR Service Types that should not be imported into ClientSpace. |
ExcludeEmailDomains |
Email domains that should not be imported into ClientSpace. Supports comma-separated list. |
ExcludeUserNames |
User names that should not be imported into ClientSpace. |
FailureRetryTime |
|
GetPayrollBatchCutoffDate |
Remote Cutoff Date is the deadline for reporting payroll.
GetPayrollBatchCutoffDate parameter requires version 1.22 or higher of the PrismHR API. Specify the version in the URL in Endpoint. For example, https://api.prismhr.com/api-1.22/services/. |
HRPRunImport |
|
InitialImportClients |
Sets how many queue records of each import map type are processed at a time. |
InitialMaxEmployeeCount |
Sets the threshold of maximum number of Employees to import during a scheduled process run.
|
KeepLeadingZeros |
|
NumberOfEvents |
Sets the max number of records to import per subscription record on each run of the HRPAPI_Ongoing import. Setting NumberOfEvents to 0 defaults the max records imported per subscription to 100. This parameter minimizes the risk of imports failing due to large record sets. |
OSHAYearsToProcess |
This parameter denotes the number of years to get the OSHA totals from PrismHR.
|
ProcessVouchers |
|
RequireBillingVouchers |
|
- Click Save.
How InitialImportClients and InitialMaxEmployeeCount work together
Let's look at how InitialImportClients and InitialMaxEmployeeCount are processed. The scenario is as follows:
- API Parameter InitialImportClients = 5 (5 clients will be processed during each scheduled process run)
- API Parameter InitialMaxEmployeeCount= 10 is the maximum number of Employees to import during a scheduled process run
First Scheduled Process Run
The first scheduled process run: 5 Clients at a time, Max Employee Threshold is 10
Client |
Employees processed |
---|---|
Client 1 has 5 employees |
5 Employees will be processed |
Client 2 has 2 Employees |
2 Employees will be processed |
Client 3 has 4 Employees |
4 Employees will be processed |
Client 4 has 20 Employees |
Client 4 will not be processed during this run, Max Employee Count has been exceeded |
Client 5 has 30 Employees |
Client 5 will not be processed during this run, Max Employee Count has been exceeded |
Second Scheduled Process Run
The second scheduled process run: 5 Clients at a time, Max Employee Threshold is 10
Client |
Employees processed |
---|---|
Client 4 has 20 Employees |
20 Employees will be processed |
Client 5 has 30 Employees |
Client 5 will not be processed during this run, Max Employee Count has been exceeded |
Client 6 has 2 Employees |
Client 6 will not be processed during this run, Max Employee Count has been exceeded |
Client 7 has 50 Employees |
Client 7 will not be processed during this run, Max Employee Count has been exceeded |
Client 8 has 9 Employees |
Client 8 will not be processed during this run, Max Employee Count has been exceeded |
If InitialMaxEmployeeCount = 0, all Clients (up to InitialImportClients count) and their Employees will be processed each scheduled process run.