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:

  1. Go to System Admin > Advanced > API Configuration.
    The API Configuration dashboard opens.
  2. 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
The PrismHR Export process for Company Information and Employee/Employment information contains important log information to monitor the export activity from ClientSpace to PrismHR.
When set to Level 2 (Verbose), ALL log data is stored in the Scheduled Process History Table. This includes entry/status/exit entries for every PrismHR API call and ClientSpace action (up to the Import Phase). Errors and Information entries are created.
When set to Level 1, only ERRORS are logged to the Scheduled Process History Table.
When set to Level 0 (None), No log data is produced.
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.

  1. Click Add Parameter.
    A new row opens.

  2. Select from the following list to add parameters.

Parameter

Value settings

AllowUserTypes

Defines the types of users included in a user import:

  • I: Internal User. Someone who works for the PEO or someone at PrismHR.
  • M: Manager. Someone who works in payroll or human resources for a PEO client.
  • A: Trusted Advisor. Same as Manager but without an Employee ID. Used for consultants.
  • E: Employee.
  • S: Super User in the legacy HRPWE. Similar to I.
  • C: Client Manager in HRPWE.

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:

  • If the CanCreateWorkspaces parameter is set to a value of 1 and the Client Number does not already exist for the PEOID, a new workspace is created.

  • If the CanCreateWorkspaces parameter is set to a value of 0 or is blank, a new workspace is not created.

ContactImportBehavior

  • Insert/Both: Allows Import Queue record creation for Contacts in PrismHR but not in ClientSpace.
  • Update: For Contacts in PrismHR but not in ClientSpace, it does not create an Import Queue record. It updates existing ClientSpace Contacts with changes.

DefaultProjectCode

Defines where an employee portal case is created if no workspace match is found. Uses ProjectCode from workspace settings.

ExcludeCompanyFromSync

  • 0: The Company Initial import map is included in the sync if the map is active (updates Company information and all other active Initial maps). Note: Initial sync of company data can be applied to individual workspaces using the option Sync with PrismHR on the Client Master. See PrismHR to ClientSpace Client sync.
  • 1: The Company Initial import map is NOT included in the sync whether or not the map is active (all other active Initial maps are processed).

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

  • 0: Reprocesses all failed Import Queue records.
  • X: Reprocesses failed Import Queue records with an UpdatedDate greater than X hours.
  • If not present (default), failed Import Queue records are not reprocessed.

GetPayrollBatchCutoffDate

Remote Cutoff Date is the deadline for reporting payroll.

  • 0: Do not retrieve the Batch Control Remote Cutoff Date in the import.

  • 1: Include the Remote Cutoff Date if available in the Payroll Batch in PrismHR.

  • If GetPayrollBatchCutoffDate not present, defaults to 0.

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

  • 0: The files generated by the API Import appear in the Manage Import File List at status Ready for Import.
  • 1: The files generated by the API Import automatically import into ClientSpace.

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.

  • If no Value is set, it processes all Employees for Clients (up to the InitialImportClients count) during a scheduled process run.
  • If a Value is set, after obtaining a list of Employees, if the number exceeds the parameter Value, no additional processing occurs for that run. Subsequent runs for the scheduled process resume the import, picking up where the last run ended when the maximum threshold was met. This parameter eliminates session timeouts for groups of Clients with high Employee counts.

KeepLeadingZeros

  • 0: Any leading zeros on CompanyID in PrismHR are stripped off before the Client Record is saved.
  • 1: Leading zeroes on CompanyID are retained when importing records into ClientSpace.

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.

  • Not Present: If the parameter is not present, then limit the number of years to the past year.
  • 1 or Less: If the parameter is set to 1 or less, then limit the number of years to the past year.
  • 2 If the parameter equals 2, then limit the number of years to the past two years.
  • 3 or Greater: If the parameter equals 3 or greater, then limit the number of years to the past three years.

ProcessVouchers

  • 0: Queued Employee Payroll Vouchers are not processed immediately.
  • 1: Employee Payroll Vouchers are processed as they are imported.

RequireBillingVouchers

  • 0: If Billing Vouchers cannot be located for a Client, the Payroll Voucher data is processed (will be missing all Billing-related mapped fields).
  • 1: The payroll is not processed for that Client (current behavior). If the parameter is not specified, it is assumed that RequireBillingVouchers=1 (current behavior).
  1. 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.