A Guide to Running Payroll

Getting started with Payroll

The payroll and accrual workflow is divided into two parts:

Stage Payroll

Payroll can be staged as part of an API or Boomi-based integration. The process starts with the Stage Payroll Asynchronously (POST /v1/commons/payroll/staging/async) API payroll or accrual asynchronous staging API operation, which allows you to specify a pay group, dates, and other payroll or accrual parameters. Each request receives a unique identifier called a requestId. The system tracks the status of each request, which can be queried using the Retrieve Payroll Staging Asynchronous Request Status by ID (GET /v1/commons/payroll/staging/{requestId}/status) operation. The Payroll Staging and Payroll Export resources follow our standard asynchronous request structure:

Payroll Staging

Operation	Method	URL Endpoint	Purpose
Stage Payroll Asynchronously	POST	`/v1/commons/payroll/staging/async`	Create asynchronous job
Retrieve Payroll Staging Asynchronous Request Status by ID	GET	`/v1/commons/payroll/staging/{requestId}/status`	Retrieve status of a single asynchronous job
Retrieve Asynchronous Payroll Extraction Details by ID	GET	`/v1/commons/payroll/staging/{requestId}/details`	Retrieve details about a single asynchronous job

Payroll Export

Operation	Method	URL Endpoint	Purpose
Export Payroll Asynchronously	POST	`/v1/commons/payroll/export/async`	Create asynchronous job
Retrieve Payroll Export Asynchronous Request Status by ID	GET	`/v1/commons/payroll/export/async/{exportId}/status`	Retrieve status of a single asynchronous job
Retrieve Summary of Asynchronous Payroll Export Jobs	GET	`/v1/commons/payroll/export/async`	Retrieve the statuses of all asynchronous requests
Retrieve Payroll Export Asynchronous Response Payload by ID	GET	`/v1/commons/payroll/export/async/{exportId}/response`	Retrieve the response body for a completed asynchronous job

The Stage Payroll Asynchronously operation extracts data from the system based on the parameters passed in the request. Once the data is assembled, the status of the asychronous job changes to completed.

Export Payroll

Once generated, the integration extracts exported payroll or accrual data based on the request ID using the streaming or asynchronous Payroll Export operations. Based on available staging table columns for payroll or accrual data (refer to Pre-defined payroll staging columns and Pre-defined accrual staging columns for available columns), the call specifies a valid SQL query containing data columns based on your requirements with or without headers and footers.

The integration uses the Retrieve Payroll Staging Asynchronous Request Status by ID](ref:retrieve-payroll-staging-asynchronous-request-status-by-id) (GET /v1/commons/payroll/export/async/{exportId}/status) operation to poll the status of your request. Once the status is completed, call the Retrieve Payroll Export Asynchronous Response Payload by ID (GET /v1/commons/payroll/export/async/{exportId}/response) operation to extract the data according to your needs. This operation supports various output formats, including CSV, JSON, a specific filename, a compression option, and so on.

Pre-defined configuration data

The Payroll Extraction operations provide configuration data elements containing payroll and accrual staging columns that are already part of the system configuration. You can edit some pre-defined configuration data to suit your business needs.

Pre-defined payroll staging columns

The following is a list of the columns available for payroll staging.

prm_payroll_staging_data columns	Column Definition	Comments
id	bigint NOT NULL	unique id for this table
staging_request_id	bigint NOT NULL	id for the request
staging_datetime	timestamp without time zone NOT NULL	Current datetime
custom_parameter_1	text, 50 characters, nullable	Passed in from API request - allows integration to supply other indicators they want persisted in staging such as paygroup or timezone etc
custom_parameter_2	text, 50 characters, nullable	Passed in from API request - allows integration to supply other indicators they want persisted in staging such as paygroup or timezone etc
person_id	bigint NOT NULL	actual_total.apply_date within range passed in, actual_total.work_item_id=work_item_employee_assignment.work_item_id,work_item_employee_assignment.employee_id=wtkemployee.wtkemployeeid, wtkemployee.personid-person.personid
person_num	character varying(15)	actual_total.apply_date within range passed in, actual_total.work_item_id=work_item_employee_assignment.work_item_id,work_item_employee_assignment.employee_id=wtkemployee.wtkemployeeid, wtkemployee.personid-person.personid
full_name	character varying(64)	actual_total.apply_date within range passed in, actual_total.work_item_id=work_item_employee_assignment.work_item_id,work_item_employee_assignment.employee_id=wtkemployee.wtkemployeeid, wtkemployee.personid-person.personid
first_name	character varying(30)	actual_total.apply_date within range passed in, actual_total.work_item_id=work_item_employee_assignment.work_item_id,work_item_employee_assignment.employee_id=wtkemployee.wtkemployeeid, wtkemployee.personid-person.personid
last_name	character varying(30)	actual_total.apply_date within range passed in, actual_total.work_item_id=work_item_employee_assignment.work_item_id,work_item_employee_assignment.employee_id=wtkemployee.wtkemployeeid, wtkemployee.personid-person.personid
middle_name	character varying(1)	aactual_total.apply_date within range passed in, actual_total.work_item_id=work_item_employee_assignment.work_item_id,work_item_employee_assignment.employee_id=wtkemployee.wtkemployeeid, wtkemployee.personid-person.personid
range_start_date	timestamp without time zone NOT NULL	Pass in start date for apply_date range
range_end_date	timestamp without time zone NOT NULL	Passed in end date for apply_date range
apply_date	timestamp without time zone NOT NULL
amount_type	character varying(50)	actual_total.paycode_id = Paycode.paycodeId paycode.paycodeamttypeid=paycodeamttype.paycodeamttypeid
hours_amount	bigint
days_amount	numeric(19,6)
money_amount	numeric(19,6)
wage_multiplier	numeric(16,6)	actual_total.paycode_id = paycode.paycodeId
wage_addition	numeric(16,6)	actual_total.paycode_id = paycode.paycodeId
effective_wage_rage	numeric(19,6)	guard against dividing by 0. Ignore if amount_type is money
paycode_id	bigint NOT NULL
paycode_name	character varying(50)	actual_total.paycode_id = paycode.paycodeId
paycode_mapped_output1	character varying(50)	from paycode mapping table
paycode_mapped_output2	character varying(50)	from paycode mapping table
paycode_mapped_output3	character varying(50)	from paycode mapping table
is_historical_correction	boolean
original_date	timestamp without time zone NOT NULL
original_payperiod_start	timestamp without time zone NOT NULL	payperiod.payruleid = effective payruleid for employee on original_date
original_payperiod_end	timestamp without time zone NOT NULL	payperiod.payruleid = effective payruleid for employee on original_date
include_in_totals	numeric(1,0)	Need to take the opposite value of already_paid to get the correct value for include_in_totals
worked_job	text	actual_total.orgjob_id=org_effective_node.org_node_id and applydate between effective dates
worked_job_mapped	text	from GL mapping table (worked_job)
worked_location_job_type_path	text	actual_total.orgjob_id=org_effective_node.org_node_id and org_effective_node.org_node_type_id=org_effective_node_type.org_node_type_id
worked_labor_level1_name	description character varying(250)	actual_total.labor_account_id=laboracct.laboracctid
worked_labor_level1_id	bigint	actual_total.labor_account_id=laboracct.laboracctid
worked_labor_level2_name	description character varying(250)	actual_total.labor_account_id=laboracct.laboracctid
worked_labor_level2_id	bigint	actual_total.labor_account_id=laboracct.laboracctid
worked_labor_level3_name	description character varying(250)	actual_total.labor_account_id=laboracct.laboracctid
worked_labor_level3_id	bigint	actual_total.labor_account_id=laboracct.laboracctid
worked_labor_level4_name	description character varying(250)	actual_total.labor_account_id=laboracct.laboracctid
worked_labor_level4_id	bigint	actual_total.labor_account_id=laboracct.laboracctid
worked_labor_level5_name	description character varying(250)	actual_total.labor_account_id=laboracct.laboracctid
worked_labor_level5_id	bigint	actual_total.labor_account_id=laboracct.laboracctid
worked_labor_level6_name	description character varying(250)	actual_total.labor_account_id=laboracct.laboracctid
worked_labor_level6_id	bigint	actual_total.labor_account_id=laboracct.laboracctid
worked_cost_center_name	description character varying(250)	actual_total.labor_account_id=laboracct.laboracctid
worked_cost_center_id	bigint	actual_total.labor_account_id=laboracct.laboracctid
worked_labor_level1_mapped	character varying(50)	from GL mapping table (worked_labor_level1)
worked_labor_level2_mapped	character varying(50)	from GL mapping table (worked_labor_level2)
worked_labor_level3_mapped	character varying(50)	from GL mapping table (worked_labor_level3)
worked_labor_level4_mapped	character varying(50)	from GL mapping table (worked_labor_level4)
worked_labor_level5_mapped	character varying(50)	from GL mapping table (worked_labor_level5)
worked_labor_level6_mapped	character varying(50)	from GL mapping table (worked_labor_level6)
worked_cost_center_mapped	character varying(50)	from GL mapping table (worked_cost_center)
signoffthrudtm	timestamp without time zone
employment_status	character varying(30)	personstatusmm.personid,employmentstatid/applydate between effective dates
primary_job	text	combhomeacct.orgnodeid=org_effective_node.org_node_id and applydate between effective dates for both tables
primary_job_mapped	text
home_location_job_type_path	text	combhomeacct.orgnodeid=org_effective_node.org_node_id and org_effective_node.org_node_type_id=org_effective_node_type.org_node_type_id
home_labor_level1_name	description character varying(250)	combhomeacct.laboracctid=laboracct.laboracctid and applydate between combhomeacct effective dates
home_labor_level1_id	bigint	combhomeacct.laboracctid=laboracct.laboracctid and applydate between combhomeacct effective dates
home_labor_level2_name	description character varying(250)	combhomeacct.laboracctid=laboracct.laboracctid and applydate between combhomeacct effective dates
home_labor_level2_id	bigint	combhomeacct.laboracctid=laboracct.laboracctid and applydate between combhomeacct effective dates
home_labor_level3_name	description character varying(250)	combhomeacct.laboracctid=laboracct.laboracctid and applydate between combhomeacct effective dates
home_labor_level3_id	bigint	combhomeacct.laboracctid=laboracct.laboracctid and applydate between combhomeacct effective dates
home_labor_level4_name	description character varying(250)	combhomeacct.laboracctid=laboracct.laboracctid and applydate between combhomeacct effective dates
home_labor_level4_id	bigint	combhomeacct.laboracctid=laboracct.laboracctid and applydate between combhomeacct effective dates
home_labor_level5_name	description character varying(250)	combhomeacct.laboracctid=laboracct.laboracctid and applydate between combhomeacct effective dates
home_labor_level5_id	bigint	combhomeacct.laboracctid=laboracct.laboracctid and applydate between combhomeacct effective dates
home_labor_level6_name	description character varying(250)	combhomeacct.laboracctid=laboracct.laboracctid and applydate between combhomeacct effective dates
home_labor_level6_id	bigint	combhomeacct.laboracctid=laboracct.laboracctid and applydate between combhomeacct effective dates
home_cost_center_name	description character varying(250)	combhomeacct.laboracctid=laboracct.laboracctid and applydate between combhomeacct effective dates
home_cost_center_id	bigint	combhomeacct.laboracctid=laboracct.laboracctid and applydate between combhomeacct effective dates
home_labor_level1_mapped	character varying(50)
home_labor_level2_mapped	character varying(50)
home_labor_level3_mapped	character varying(50)
home_labor_level4_mapped	character varying(50)
home_labor_level5_mapped	character varying(50)
home_labor_level6_mapped	character varying(50)
home_cost_center_mapped	character varying(50)
base_wage_rate	numeric(16,6)	basewagerthist.employeeid=wtkemployee.employeeid and wtkemployee.personnum=person.personnum
currency_code	character varying(10)	currency.currencyid=currencyassignmnt.currencyid and currencyassignmnt.employeeid=wtkemployee.employeeid and wtkemployee.personnum=person.personnum
payrule	character varying(50)	assignpayrule.employeeid,payruleid applydate between effective dates
employment_term	character varying(50)	empgrpschedmm.employeeid,grpscheduleid apply date between effective dates/groupschedule.contractsw=1
hire_date	timestamp without time zone
badge_number	character varying(50)	Person.personid=badgeassign.personid and actual_total.apply_date between basdeassign effective dates
worker_type	character varying(50)	Person.personid= wtkemployee.personid and wtkemployee.workertypeid=workertype.workertypeid
timezone	character varying(30)	Person.personid= wtkemployee.personid timzone.timezoneid=wtkemployee.timezoneid
last_total_time	timestamp without time zone	Person.personid = totaleventts.personid
last_total_change_time	timestamp without time zone	Person.personid = totaleventts.personid
person_custom_field1_name	character varying(30)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field1_value	character varying(2000)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field2_name	character varying(30)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field2_value	character varying(2000)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field3_name	character varying(30)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field3_value	character varying(2000)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field4_name	character varying(30)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field4_value	character varying(2000)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field5_name	character varying(30)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field5_value	character varying(2000)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field6_name	character varying(30)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field6_value	character varying(2000)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field7_name	character varying(30)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field7_value	character varying(2000)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field8_name	character varying(30)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field8_value	character varying(2000)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field9_name	character varying(30)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field9_value	character varying(2000)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field10_name	character varying(30)	customdatadef.customdatadefid = personcstmdata.customdatadefid
person_custom_field10_value	character varying(2000)	customdatadef.customdatadefid = personcstmdata.customdatadefid

Pre-defined accrual staging columns

The following is a list of the columns available for accrual staging.

prm_accrual_staging_datacolumns	Columns definition
staging_request_id	bigint NOT NULL
staging_datetime	timestamp without time zone NOT NULL
custom_parameter_1	character varying(50)
custom_parameter_2	character varying(50)
person_id	bigint NOT NULL
person_num	character varying(15)
range_start_date	timestamp without time zone NOT NULL
range_end_date	timestamp without time zone NOT NULL
accrual_code_name	character varying(50) NOT NULL
accrual_amount_type	character varying(10) NOT NULL
available_starting_balance	numeric(19,6)
available_ending_balance	numeric(19,6)
vested_starting_balance	numeric(19,6)
vested_ending_balance	numeric(19,6)
probationary_starting_balance	numeric(19,6)
probationary_ending_balance	numeric(19,6)
accrual_output_1	character varying(50)
accrual_output_2	character varying(50)
accrual_output_3	character varying(50)
*accrual_taking_sum	numeric(19,6)
accrual_earnings_sum	numeric(19,6)
*accrual_reporting_period_taking_sum	numeric(19,6)
accrual_reporting_period_earning_sum	numeric(19,6)

Note: Accrual Taking should be a positive number. Accrual Taking does support a negative taking which would be a taken credit. A historical correction is one example. You must perform an activity to negate the operation on the respective field's sign.