NOTICE: You are in the old ClientSpace Help system. Please link to the new ClientSpace Help here https://extranet.clientspace.net/helpdoc/home/ClientSpace.htm

Configuring the PrismHR API for Ongoing Imports

Owned by Tony Hayes
Last updated: Oct 03, 2019 by Diane Hogan (Deactivated)
10 min read


This topic describes the PrismHR API Import process and includes step-by-step configuration information to help you get started using the PrismHR API. Before you begin, you must request access for your implementation specialist to configure the API interface. The implementation specialist will need you to provide:

  • HRP Username
  • HRP Password
  • HRP PEO ID
  • HRP API URL


The processes described in this topic are for an Ongoing process, which pulls changes from the PrismHR system into a ClientSpace installation. Validation prior to automating the process is crucial - see Prior to 'Go-Live' below.  If you are attempting to configure this on your own, and are not sure of your configuration or next steps, STOP and contact a  PrismHR application specialist. After enabled, the API overwrites existing data values potentially leading to data loss if not properly configured.

Import Queue Management and Configuration

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)
  • HRP Subscription Dataforms (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_company_ongoing*.csv
    • ClientSpace.PEO.Import.ClientMaster
  • HRPAPI_clientteam_ongoing*.csv
    • No custom import class
  • HRPAPI_employee*.csv
    • ClientSpace.PEO.Import.Employee
  • HRPAPI_employment*.csv
    • ClientSpace.PEO.Import.Employment
  • HRPAPI_location*.csv
    • ClientSpace.PEO.Import.Location
  • HRPAPI_voucher*.csv
    • ClientSpace.PEO.Import.EmployeeVoucher
  • HRPAPI_payroll_batch*.csv
    • ClientSpace.PEO.Import.PayrollBatch
  • HRPAPI_billing_voucher*.csv
    • ClientSpace.PEO.Import.BillingVoucher

 ***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 that 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 one of 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’
    • 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, there will typically be three of these 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 HRP Import Ongoing Scheduled Process. 

For the system to auto-populate the record, you will need to create “stub records” for the Client and Employee imports:

  • Create semi-blank HRP Subscription dataforms, one 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 two 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 the use of the API can commence.

This configuration is performed 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)


Web Services Company ‘blacklist’.  

Certain Companies/Employees should not be imported into ClientSpace (e.g., the PEO itself).  The HRP Configuration tool (HRPyramid) contains a Web Services Access Control interface.  Those Companies and that should not be imported into ClientSpace should be listed as ‘Deny’ on the Company List form. 

Prior to "Go Live"

After configured, a series of tests should be performed to compare the validity of the data retrieved by the API against existing data being imported into ClientSpace. This is crucial to ensure a smooth transition to API imports.  These tests consist essentially of running the imports manually with the additional parameter of HRPRunImport=0 to generate the files, but not import them. These files should then be scrutinized for accuracy and completeness. Skipping the data validation testing can lead to duplicated or corrupted data so it is critical to perform these validations prior to automating the API imports.  Should you need help with validation or have questions about this process, create a case for a staff consultant in the Extranet.

The Scheduled Process

Scheduled Processes

There are two scheduled processes involved in the HRP Import function:

  • HRP Import Ongoing
    • This process generates the following standard Import files:
      • HRPAPI_company_ongoing*.csv
      • HRPAPI_clientteam_ongoing*.csv
      • HRPAPI_employee*.csv
      • HRPAPI_employment*.csv
      • HRPAPI_location*.csv
  • HRP Import Voucher
    • This process generates the following standard Import file:
      • HRPAPI_voucher*.csv

Service Provider user type

Prism users who are not Service Provider user types are not imported using the HRPAPI_Users initial and ongoing imports. The user types included in the user import is determined using the AllowUserTypes parameter. See the list of Configuring the PrismHR API for Ongoing Imports#UserTypes.

Existing inactive users

Existing inactive users for Pulse only clients are deleted if a change is made to these users in PrismHR and the user is still inactive. The system will not delete user accounts without being triggered by a change to a user account in PrismHR.

Additional parameters

Additional parameters used by the PrismHR API include:

  • DefaultProjectCode: Sets the default workspace for a record if the system is unable to determine it 
  • KeepLeadingZeros: Tells the system to not strip leading zeroes from the client number value stored in PrismHR
  • ExcludedContractTypes (comma delimited): Sets the system to ignore clients in the PrismHR system based on the Service Type.
    • Add ExcludedContractTypes=XXX,YYY to the Additional Parameters section of the API configuration replacing XXX,YYY with the comma separated (or singular) list of PrismHR Service Types. 
    • Service Types must be comma-separated (if there are multiples to exclude).
    • This setting applies to Import Initial Queue Clients and Import Initials scheduled processes.
    • If a Client is of an excluded contract type, it is not included in the import file.
    • Import Queue records are not created for Clients that are excluded (for remaining initial import maps).
  • ExcludeEmailDomains (comma delimited): Allows a comma-separated list of partial email domains to be added. If a user account has an email domain that starts with the excluded string, the user account is not imported. Example: ExcludeEmailDomains=PrismHR,gmail would exclude any user with an email domain beginning with prismhr or gmail such as PrismHR.com.
  • ExcludeUserNames: Allows a comma-separated list of partial UserIDs from the PrismHR payroll system to be added. If a user account has a UserID that starts with the excluded string, the user account is not imported. 
  • AllowUserTypes= (if not valid, user type of user type is blank, will inactivate existing records if present).
    UserTypes are:
    • E: Worksite Employee
    • M: Worksite Manager
    • A: Worksite Trusted Advisor
    • I: Service Provider



 Scheduled Process Workflow

Importing to ClientSpace

Using scheduled processes, data from HRP is extracted and loaded into ClientSpace: 

  • HRP Import Ongoing Scheduled Process

The Import Ongoing process evaluates “HRP Events” (Company and Employee changes) that may affect existing ClientSpace Client and Employee data, as well as those events that create new Clients and Employees.  All ‘Ongoing’ Import Map configurations are processed each time the Scheduled Process executes, on the same set of HRP Events (this minimizes the amount of data retrieved from HRP).

  • The HRP Import Ongoing scheduled process executes
  • Based on the HRP configuration data provided, the process logs into the HRP server.  A failure to log in will terminate the process (a log entry is generated)
  • A list of HRP Subscriptions is retrieved from HRP
    • Typically there are two Subscriptions: one for Company Information and one for Employee Information.
    • The Subscriptions establish the type of information that must be monitored for change (Events)
  • The configuration value “HRP Run Import” is retrieved from ClientSpace
  • A list of Import Map Configurations is retrieved from ClientSpace, in this order:
    • HRPAPI_company_ongoing
    • HRPAPI_clientteam_ongoing
    • HRPAPI_location
    • HRPAPI_employee
    • HRPAPI_employment
  • For each Subscription:
    • The last ReplayID is retrieved from ClientSpace.  This indicates the last Event that was retrieved by the process.  All Events from that point to the current point in time will be evaluated
    • If the last ReplayID is equal to the current value associated with the Subscription (meaning no Events have occurred since the last process run time), no new events will be retrieved from HRP
    • If the Replay IDs are different, a list of Events is retrieved from HRP, from the last ReplayID to the current point in time.  These Events are associated with this instance of the Subscription ID.
    • For each Import Map configuration:
      • A list of Import Map Fields and Paths is retrieved
      • For each new Event:
        • If the Event action is ‘Delete’, no action is taken on this Event
        • For each Modified Attribute in the Event:
          • The Modified Attribute (the actual field in HRP that has changed) is compared to the list of Import Map Paths
          • If the Modified Attribute is not found in the Import Map Path list, this Event is ignored since it is a change ClientSpace does not need to process. The associated Subscription dataform is updated with this Attribute as an ‘Exclude’ value
          • If the Modified Attribute is found in the Import Map Path list, the Company or Employee for which this Event is associated is saved for Import
      • After all Events are evaluated, the result is a list of distinct Companies and Employees that will be queued
        • For example:
          • EventID 1: Company 123 Address changed
          • EventID 2: Company 123 Phone changed
          • EventID 3: Company 456 Fax changed
          • These three Events will produce the following list of Companies to be queued:
            • Company 123
            • Company 456
          • Company 123 is only in the list once even though it had multiple changes.  The process only operates on the unique set of Company or Employee changes
      • For each Company or Employee in the list
        • An entry is created in tblImportQueue with the following data:
          • The current Import Map Header ID
          • A formatted Identifier (EventObjectID!.!EventClientID!.!EventSchema)
          • Status of “Pending”
    • After all Import Map Configurations have been processed, the ClientSpace Subscription dataform associated with this Subscription is updated with the latest ReplayID from the Event list.
    • Regardless of whether new events were available, queued events are then processed
      • For each Import Map Configuration
        • A list of Import Map Fields and Paths is retrieved
        • A call to tblImportQueue is made to retrieve event details for and queued record whose status = “Pending” or “Failed”
        • A call is made to HRP to retrieve specific Company/Employee/Location data for each queue record
        • Based on Import Map Fields and Paths and the Company or Employee data retrieved from HRP, an Import file row is constructed for the particular Import Map being processed
        • The Import file row is presented to any Custom Import Business Class for further manipulation (if configured)
      • After all Companies or Employees are processed:
        • The Import File is generated and uploaded to ClientSpace, status = ‘Ready for Import’
        • If the configuration value “HRP Run Import” is set to True, the file will be immediately imported via the ClientSpace Import process
    • The next Import Map configuration is processed
  • The next Subscription is processed
  • After all Subscriptions are processed, the process logs out of the HRP server 

  

Excludes Import Map Detail

Review the PrismHR Security subscription record to ensure that Users=activeUser is NOT part of the Excludes Import Map Detail for the HRPAPI_users import. The import must contain a valid record for the Active flag.

User status in PrismHR and ClientSpace

The ClientSpace user Active value is automatically set to the PrismHR value so that when a user is inactivated in PrismHR, the same status is reflected in ClientSpace.


NOTICE: You are in the old ClientSpace Help system. Please link to the new ClientSpace Help here https://extranet.clientspace.net/helpdoc/home/ClientSpace.htm