Ongoing Imports: Configuring the API for Import Map Details

Configure the parameters for the import file.

To configure the API:

  1. Go to System Admin > Advanced > API Configuration.
    The API Configuration dashboard opens.
  2. On the PrismHRAPI item, click (Open).
  3. Configure as appropriate for your organization. The API Configuration fieldset connects the specific PrismHR installation for the client.
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.

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.

For GetPayrollBatchCutoffDate, ensure that the correct version of the PrismHR API is reflected in the Endpoint URL. After the scheduled process runs, review the API log for any errors.