Configuring the PrismHR API for Initial Imports

As records are retrieved from HRP, Import Queue (tblImportQueue) records are created and modified.  The Import Queue Management dashboard and detail pages allow the user to reset queue item statuses (reset to ‘Pending’, set to ‘Complete’) and to interrogate error data via the Log Data field. 

This Management suite is available from the System Admin  > Imports > Manage Import Queue.

Configuration Overview

The following areas must be configured:

• ImportIDs for Lookups and other data (ClientSpace)
• Import Map Headers (ClientSpace)
• Import Map Details (ClientSpace)
• API Configuration form (ClientSpace)
• The PrismHR Site

Import IDs

Certain Lookups and other data require translation to HRP values.  This is done using ImportIDs on the following data:

• Contract Type (ClientMaster)
• Contract Status (ClientMaster)
• HR Rep User
• Sales Rep User
• Employment Status (Employee)
• Employment Type (Employee)
• Marital Status (Employee)
• Gender (Employee)
• Ethnic Classification (Employee)
• Work State Filing Status (Employee)
• Home State Filing Status (Employee)
• Pay Method (Employment)
• Pay Frequency (Employment)

Import Map Headers

Import Map Headers must be configured for each file type to be produced and MUST match the PEO headers listed below***.  The Custom Import Class for each Header must be configured:

• HRPAPI_initial_company*.csv
  • ClientSpace.PEO.Import.ClientMaster
• HRPAPI_initial_clientteam*.csv
  • No custom import class
• HRPAPI_initial_employee*.csv
  • ClientSpace.PEO.Import.Employee
• HRPAPI_initial_employment*.csv
  • ClientSpace.PEO.Import.Employment
• HRPAPI_initial_location*.csv
  • ClientSpace.PEO.Import.Location

 ***These import map configurations should have been pushed to your site but may be inactive.  If you find these configurations do not exist on your site, create an Extranet case to have these configurations added.

Import Map Details

Import Map Details must be configured with an ‘API Path’ value for each Field to be included in the import file. 

API Configuration

The API Configuration form System Admin  > Advanced > API Configuration has an “API Configuration” fieldset which contains the information necessary to connect to the specific HRP installation for the Client. (Screenshot above shows test data. Use actual client data when configuring.)

• API Type [lookup]
  • Choose “PrismHR API”
• Application Code [textbox]
  • Use  a unique value to denote the PrismHR installation such as “PrismHRAPI”
• Application Name [textbox]
  • Description that displays in the ClientSpace lists, use something to indicate the installation such as  “PrismHR API”
• Username [textbox]
  • The username registered with the HRP API for this site
• Password [textbox]
  • The password associated with the HRP Account Username for this site
• Endpoint [textbox]
  • A formatted Url pointing to the API services for the specific HRP client and site(must include the trailing ‘/’ character)
• Secondary ID [textbox]
• An identifier used to enable the monitoring of all HRP Clients at an installation
• Logging Level [lookup] 
  • The HRP Export process for Company Information and Employee/Employment information contains significant log information to aid in monitoring the activity of the Exports from ClientSpace to HRP
  • When set to Level 2 (Verbose), ALL log data will be stored in the Scheduled Process History Table.  This includes entry/status/exit entries for every HRP API call and ClientSpace action (up to the Import Phase).  Errors and Information entries are created
  • When set to Level 1, only ERRORS will be logged to the Scheduled Process History Table
  • When Set to Level 0 (None), No log data is produced.
• Additional Parameters: This is a set of ‘name value’ pairs used to configure the process. Click Add Parameter to begin adding these:
  
  • HRPRunImport=1: The files generated by the API Import will automatically be imported into ClientSpace
  • HRPRunImport=0: The files generated by the API Import will appear in the Manage Import File List at status ‘Ready for Import’
  • InitialImportClients=x: Sets how many queue records of each import map type will be processed at a time.
  • KeepLeadingZeros=0: Any leading zeroes on CompanyID in PrismHR will be stripped off before the Client Record is saved
  • KeepLeadingZeros=1: Leading zeroes on CompanyID will be retained when importing records into ClientSpace.
  • processvouchers=0: Queued Employee Payroll Vouchers will not be processed immediately
  • processvouchers=1: Employee Payroll Vouchers will be processed as they are imported.
  • ExcludeCompanyFromSync=0: The Company Initial import map WILL be included in the Sync if the map is active (i.e., will update 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 Client Sync.
  • ExcludeCompanyFromSync=1: The Company Initial import map will NOT be included in the Sync whether or not the map is active (i.e., all other active Initial maps will be processed).

HRP Subscription Dataforms

In the Admin workspace, you will see the following Dataforms:

• Client Schema
• Employee Schema
• Payroll Schema
• Security Schema
• Voucher Schema

 Each form contains:

• Schema: for Import Ongoing only, defines the type of data this particular Subscription ID evaluates
• Subscription ID: The HRP ID of the registered Subscription for this ClientSpace installation
• Replay ID: The last ‘Event’ marker processed, from the last time the Ongoing Scheduled Process successfully ran
• Voucher Last Process Date: The last date the Voucher Scheduled Process successfully ran
• Notes: general information such as the date and time the scheduled process ran, the Replay ID used, etc.

The Client, Employee, Payroll, and Security records are AUTOMATICALLY populated by the PrismHR Import Queue Initial Clients Scheduled Process.  For the system to auto populate the record, you must create “stub records” for the Client, Employee, Payroll, and Security imports:

• Create semi-blank HRP Subscription dataforms for Client, Employee, Payroll, and Security.  On these forms, all you have to do is select the Schema and Classes (Client-Master,Location; Employee-Person,Client,Compensation)
• On those dataforms leave all other fields empty (no subscription id, no replay id, etc.)
• Run the Import Ongoing scheduled process
• If the connection info is correct and PrismHR has properly configured our user account, the process will
  • acknowledge that new subscriptions have to be created in HRP
  • create the new subscriptions in HRP
  • update our subscription dataforms with the new information
  • check for any new events (most likely there won’t be any since we grab the highest event replay id when the subscription is created)
  • exit

 You can check the HRP API Import Ongoing log ad hoc report to see if the process was successful.   

The Voucher record must be manually generated:

• Schema: Voucher
• Voucher Last Process Date: enter the date from which you wish to Import Vouchers.  After this field is populated and the Import Voucher Scheduled Process runs, the process will update this field
• No other fields need to be configured

PrismHR Site

The HRP Site must be configured with the following parameters before use of the API can commence.  This configuration will be done in the client Payroll System:

• Valid User account
  • Username (case sensitive)
  • Password (case sensitive)
  • PEO ID (case sensitive)
  • HRP API URL.  The endpoint of the WSDL on the server to be used
• The Account must be Enabled
• The Account must have permission to create subscriptions (for Imports only).  The following subscriptions will be automatically created on the HRP server when the process first executes:
  • Employee/Person|Client|Compensation.  Description is: “ClientSpace Employee Person-Client-Compensation Subscription All Clients”
  • Client/Master|Location.  Description is "ClientSpace Client master Subscription All Clients”
• HRP requires the following for each Client:
  • Business Entity Type (Example: LLC, S Corp, etc.) (Client Details)
  • Payroll Check Account (Account)
  • Garnishments Check Account (Account)
  • Receipts Account (Account)
  • Processing Schedule (Control)
  • GL Template (Control)
  • Bill Format (Billing)
  • Billing Template (Billing)
  • Delivery Method (Payroll)
  • Pay Groups (Payroll)
    • Pay Group
    • Description
    • Pay Schedule
    • Pay Date
  • Job Codes (Positions)