Field Service Extension - Administrator Guide

Purpose

The purpose of this Administrator Guide is to provide information about the capabilities and available functionality for the Field Service Extension (FSE). The content in this guide is optional, and may be utilised either during implementation, or after a project has gone live. The intended audience for this document is System Administrators.

Prerequisites

The information provided in this document assumes the following level of proficiency with the Field Service Extension.

Configuration & Implementation
1. General knowledge of the configuration of the Field Service Extension, and its function within 2cloudnine Payroll.
2cloudnine Payroll Processes
1. Familiarity with the descriptions and process overviews documented in the related Key Information QRG.
2. Familiarity with 2cloudnine Payroll processes outlined in the related Instructional QRGs.

To review any of the supporting documentation referenced above, proceed to Further Information.

Feature Overview

Standard Features The Field Service Extension offers the following features and functionality to enable the integration of Time Sheet data for use within 2cloudnine Payroll:

Service Resource Data Integration
- Link Employee Contact, Payee, User and Service Resource data
Time Sheet Data Integration
- Automate Time Sheet data Integration
- Insert Allowance Timesheet Items
Resource Absence Data Integration
- Generate Resource Absences

Optional Features In addition to the above, several optional features are available for configuration, depending on the specific requirements of each Org.

Service Resource Data Integration
- Create Service Resources via Payee
- Validate User records
- Define ownership for new Service Resources
Time Sheet Data Integration
- Merge Time Entries
- Manage Travel Times
Resource Absence Data Integration
- Insert Break Times
- Define Record Type for Breaks

Service Resource Integration

Link Employee Contact, Payee, User and Service Resource data The Field Service Extension enables Users and Service Resources to be linked to 2cloudnine Payroll Payee and Employee Contact records, to facilitate Time Sheet data integration. The following Object fields may be used to validate whether 2cloudnine Employee data has been successfully integrated with Field Service records:

Employee Contact : Corresponding Service Resource displayed in Related Lists.
Payee: Service Resource field reflects corresponding Field Service record.
User: Employee ID field reflects corresponding Employee Contact record.
Service Resource : Employee field reflects corresponding Employee Contact record.

Create Service Resources via Payee (optional) Enable Service Resources to be created from an Employee Contact’s Primary Payee record.

Selecting the Create Service Resource checkbox field will initiate automatic creation of a new Service Resource record, which is automatically related to the Payee and the Employee Contact.
Recommended for Orgs where Employee data is primarily maintained using 2cloudnine Payroll (rather than Field Service).

To enable this feature, ensure the Create Service Resource field has been added to each Payee Page Layout currently in use. To add the Create Service Resource field to a Page Layout: Go to Setup > Object Manager > Payee > Page Layouts

Select a suitable Page Layout from the available list.
Confirm if the field Create Service Resource is currently displayed on the Page Layout, and if not, click and drag the field to a suitable section.
Click Save .
Repeat for any remaining Page Layouts that also require this functionality.

When this field is populated and saved on a Payee, FSE automation will perform validation to determine whether an existing Service Resource can be identified for the Payee/Employee Contact. If no existing records are found, a new User and Service Resource will be created and related with the 2cloudnine data.

Important Notes(Create Service Resources via Payee)At least one active User record (either Standard or Community User) is required to facilitate Service Resource creation, and only one User may be associated with each Service Resource / Employee Contact record.

Validate User records (optional) When enabled, integration performs a validation on existing User records each time Service Resource creation is triggered from the Payee Object.

If an existing User is identified for the related Employee Contact, the Service Resource will be populated with a lookup to the record upon creation, and no further action will occur.
If an existing User cannot be identified, User creation will proceed for the Service Resource, based on the related Employee Contact data.

This feature is primarily used in Orgs where User records are provisioned for some Employees (i.e. via Employee/Approver Community access), but is not part of standard Employee access. To review User record validation settings: Go to Setup > Custom Settings > Field Service Integration Configuration > Manage

Identify the value defined for the following field:
1. Use Existing User = TRUE/FALSE

Define ownership for new Service Resources (optional) An additional configuration option allows Service Resource ownership to be inherited from the Payee that triggered record creation (provided this functionality is also enabled).

If configured, the new Service Resource Owner will be inherited from the related Payee record.
Each User record created for new Service Resources will be automatically provisioned with the relevant Field Service Permission Sets.
New User records will be populated with basic data from the related Employee Contact.

To review Service Resource ownership settings: Go to Setup > Custom Settings > Field Service Integration Configuration > Manage

Identify the value defined for the following field:
1. Payee Owner is Service Resource Owner = TRUE/FALSE

Time Sheet Integration

Automate Time Sheet data Integration To enable the Field Service Extension to initiate data integration for Time Sheets, the following conditions must be met:

Field Service Time Sheet
- Status = Approved
- 2c9 Integration Status =New
- Do Not Send to 2c9 = False
- Field Service Time Sheet Entry (related)
  - Field Service Time Sheet Entry Status = Approved
  - Field Service Time Sheet Entry Local Start Time / Local End Time = Within Time Sheet Date range

Time Sheet Integration is facilitated by ScheduleBatch_TimesheetIntegration .

This Job checks for Approved Field Service Time Sheets every 10 minutes.
Batch Size is set in Custom Metadata Type > Field Service Batch Size (set to 50 as default).

Important Notes(Time Sheet corrections)Once a Field Service Time Sheet has been approved and integrated to 2cloudnine Payroll, it can no longer be adjusted or modified within Field Services, and any changes required for the period must be managed directly within 2cloudnine Payroll.

Insert Allowance Timesheet Items To insert 2cloudnine Allowance Timesheet Items during integration, a Pay Condition Allocation must be associated with at least one validated Time Sheet Entry.

Pay Condition Allocations may be related directly to Time Sheet Entries, or linked via Work Order/Expense data.
An Allowance Pay Condition must be entered in the available lookup field, and the populated record must include either an Allowance Pay Code or Payee Allowance record.
If the Pay Condition Allocated is linked via related Field Service Expense, the Expense must fall within the defined Timesheet period, and the Quantity must be populated.
- The Expense Quantity entered will determine the amount of Allowance Timesheet Items to be created.

Merge Time Entries (optional) When this feature is enabled, the extension will merge entered Times that occur consecutively and fall within the defined Break and Gap thresholds. The following logic may be applied to consolidate Time Sheet Entry data during integration:

Entries for Standard Time are combined if occurring consecutively within defined thresholds.
Start and End Times are automatically adjusted (i.e. ‘topped up’) to create a single continuous Entry, provided gaps between Entries do not exceed the maximum threshold defined.

To review Timesheet Entry Merge settings: Go to Setup > Custom Settings > Field Service Integration Configuration > Manage

Identify the value defined for the following fields:
1. Timesheet Entry Break Threshold = (Not NULL)
2. Timesheet Entry Gap Threshold = (Not NULL)

Manage Travel Times (optional) Allows Travel Entries to be integrated according to the time of day and duration of travel entered.

As outlined in the above section, merge logic may be applied to combine consecutive Travel Entries that fall within the threshold defined.
Custom features also enable the first and/or last Travel Entry of each day to be excluded from integration, and also may be used to define a threshold for Travel Entry merge logic.

To review Travel Time settings: Go to Setup > Custom Settings > Field Service Integration Configuration > Manage

Identify the value defined for the following field:
1. Exclude First Travel of the Day = TRUE/FALSE
2. Exclude Last Travel of the Day = TRUE/FALSE
3. Travel Merge Threshold = (Not NULL)

Resource Absence Integration

Generate Resource Absences Once Payee and Service Resource records are related, each new Payee Leave Event will trigger the creation of a Resource Absence record, following Approval. The Resource Absence will reflect the below values:

Record type : Defaults to the value defined for in the Custom Settings Resource Abscence Record Type field.
Field Service Last Integration Time : Auto-generated Time/Date stamp.
Payee Leave Event : Lookup to corresponding Payee Leave Event.
Payee Leave Rule : Formula field populated with the Payee Leave Rule from the corresponding Payee Leave Event.
Start Time and End Time : Defaults to the value defined for the Custom Settings Resource Absence Start Time and End Time fields.

Important Notes(Create Resource Absences via Payee Leave Event)The maximum limitation for a Resource Absence period generated from a single Payee Leave Event is a 32-week span.

Insert Break Times (optional) The extension may be customised to insert Break Entries using Resource Absence data during Time Sheet integration.

The same merge logic that may be applied to Time Sheet and Travel Entries is available for Break Times, so that integration is able to consolidate any consecutive Breaks for insertion as a single Entry, provided each Break falls within the defined thresholds.

To review Resource Absence Break settings: Go to Setup > Custom Settings > Field Service Integration Configuration > Manage

Identify the value defined for the following field:
1. Resource Absence Start Time = (Not NULL)
2. Resource Absence End Time = (Not NULL)

Define Record Type for Breaks (optional) In addition to the ability to insert Break Entries using Resource Absences, the extension may be configured to nominate which Resource Absence Record Type is able to trigger Break insertion.

This functions to ensure that integration is able to distinguish between Non-Availability and Break Resource Absence records when assessing Time Sheet data for integration.

To review Resource Absence Type settings: Go to Setup > Custom Settings > Field Service Integration Configuration > Manage

Identify the value defined for the following field:
1. Resource Absence Record Type = Break

Field Mapping

This section details each field referenced by the Field Service Extension during data integration, for a comprehensive overview of the specific data consumed by the Field Service Extension during integration. The information provided in these tables may also be used as a tool to validate the data entry required for successful integration of both standard and custom features. Pay Conditions Fields Referenced by FSE

Field Name	Data Requirement	Populated via	Guidance
Record Type	Compulsory	Automation	See Create Pay Conditions QRG for further information.
Owner	Compulsory	Automation	See Create Pay Conditions QRG for further information.
Pay Condition name	Compulsory	Manual Entry	Recommend using an identifier referencing related 2c9 records and/or applicable Timesheet Entry conditions (i.e. Sleepover, Wakeup, Travel Expense, etc.).
Allowance Type	Conditional	Manual Entry	Required if relating to Payee Allowance data.
Predefined Quantity	Conditional	Manual Entry	Required if Predefined Quantity is selected from the Allowance Type field.
Payee Allowance Record	Conditional	Manual Entry	Required if no Pay Code record populated.
Pay Code	Conditional	Manual Entry	Required if no Payee Allowance record populated.
Timesheet Activity	Optional	Manual Entry	See Create Pay Conditions QRG for further information.
Deduct Hours Start time	Optional	Manual Entry	See Create Pay Conditions QRG for further information.
Deduct Hours End time	Optional	Manual Entry	See Create Pay Conditions QRG for further information.
Quantity Cap	Optional	Manual Entry	See Create Pay Conditions QRG for further information.
Quantity Cap Start Time	Conditional	Manual Entry	Required if Quantity Cap = True
Quantity Cap End Time	Conditional	Manual Entry	Required if Quantity Cap = True
Project Code	Conditional	Manual Entry	Required if related to Pay Code data.
Pay Condition Allocations

Fields Referenced by FSE

Field Name	Data Requirement	Populated via	Guidance
Record Type	Compulsory	Automation	Part of the minimum record detail required for Pay Condition integration.
Work Order Pay Condition Name	Compulsory	Automation	See Create Pay Condition Allocations QRG for further information.
Work Order	Conditional	Manual Entry	Required if Work Order Line Item & Expense fields are not populated.
Work Order Line Item	Conditional	Manual Entry	Required if Work Order Line Item & Expense fields are not populated.
Expense	Conditional	Manual Entry	Required if neither Work Order nor Work Order Line Item fields are populated.
Pay Condition	Compulsory	Manual Entry	See Create Pay Condition Allocations QRG for further information.
Owner Id	Compulsory	Automation	See Create Pay Condition Allocations QRG for further information.
Pay Condition Allocation Name	Compulsory	Automation	See Create Pay Condition Allocations QRG for further information.
Status	Compulsory	Manual Entry	See Create Pay Condition Allocations QRG for further information.
FS Timesheet Entry	Conditional	Manual Entry	Required if Record Type is Timesheet Entry.
Service Appointment	Conditional	Manual Entry	Required if Record Type is Service Appointment

Service Resources Fields Referenced by FSE

Field Name	Data Requirement	Populated via	Guidance
Active	Compulsory	Integration	When record creation is initiated by the FSE integration, this field is set to False as default.
Name	Compulsory	Integration	Integration populates this field by matching the values from the related Employee Contact record.
Owner	Compulsory	Integration	Automatically populated via integration, depending on the selections made in the following fields: Payee Owner is Service Resource Owner (checkbox) Owner of Service Resource - ID If above settings blank, defaults to owner of Payee
Resource Type	Compulsory	Integration	Defaults to the value Technician.
User	Compulsory	Integration	Populated by integration using the value from User.Employee_Id__c
2c9 Employee	Compulsory	Integration	Populated by integration using the value from Contact.Id

Payees Fields Referenced by FSE

Field Name	Data Requirement	Populated via	Guidance
Employee	Compulsory	Manual Entry	Used to establish integration between 2c9 Employee and Field Service Resource data.
Primary Record	Compulsory	Manual Entry	Set to TRUE upon creation of a new Payee, if no existing Payee records exist for the related Employee Contact. Only Contacts with a Primary Payee Record are integrated as Service Resources.
Create Service Resource	Optional	Manual Entry	Must be populated manually; defaults to FALSE. When TRUE, integration will create a Service Resource, or update the related record to match Payee values.
Service Resource	Optional	Integration	Record the Service Resource Id generated for the Contact during integration. Required for Integration Purpose. Not null indicates that the integration was successful. To record references to corresponding external data, use the Tech Service External Id field.

Users Fields Referenced by FSE

Field Name	Data Requirement	Populated via	Guidance
Contact	Compulsory	Inherited Value	To be populated with text matching the corresponding Employee Contact. As Salesforce does not allow for a lookup to be added, this text field is used to store the Contact Id.
Employee	Compulsory	Integration	Populated according to related Employee Contact data.
Email	Compulsory	Inherited Value	Populated according to related Employee Contact data.
First Name	Compulsory	Inherited Value	Populated according to related Employee Contact data.
Last Name	Compulsory	Inherited Value	Populated according to related Employee Contact data.
Alias	Compulsory	Inherited Value	Populated according to related Employee Contact data.
Username	Compulsory	Inherited Value	Populated according to related Employee Contact data.
Profile ID	Compulsory	Automation	Value generated upon record creation.
Email Encoding	Optional	Integration	Ensures any emails issued by the User from Salesforce display characters in accordance with the set language.

Important Notes(User Field Mapping)As previously stated, each Service Resource must be related to one User record. If manually creating Users for Service Resource records, rather than using the features to automate this process, please reference the above table to ensure required fields are populated with the necessary data.

Resource Absences Fields Referenced by FSE

Field Name	Data Requirement	Populated via	Guidance
Payee Leave Event	Optional	Integration	Populated with the corresponding Payee Leave Event.
Leave Rule	Conditional	Manual Entry	If not created via FSE automation, this field must be manually populated with the related 2c9 record.
Leave Type	Conditional	Manual Entry	If not created via FSE automation, this field must be manually populated to align with the related 2c9 Leave Entry.
Absence Number	Compulsory	Automation	Automatically generated upon record creation.
Created By	Compulsory	Automation	Automatically generated upon record creation.
Created Date	Compulsory	Automation	Automatically generated upon record creation.
Last Integration Time	Compulsory	Integration	Populated using the Date & Time value of the most recently executed integration Apex Job.
End Date	Compulsory	Manual Entry	If not created via FSE automation, this field must be manually populated. When creation is triggered via FSE, this field is populated using the Payee Leave Event End Date value.
Start Date	Compulsory	Manual Entry	If not created via FSE automation, this field must be manually populated. When creation is triggered via FSE, this field is populated using the Payee Leave Event Start Date value.
Local Start Time	Compulsory	Manual Entry	If not created via FSE automation, this field must be manually populated. When creation is triggered via FSE, this field is populated using the Payee Leave Event End Time value.
Local End Time	Compulsory	Manual Entry	If not created via FSE automation, this field must be manually populated. When creation is triggered via FSE, this field is populated using the Payee Leave Event Start Time value.
Local Duration in Minutes	Compulsory	Automation	Automatically calculated based on the values entered in the Date and Time fields.
2c9 Integration Status	Compulsory	Manual Entry	Must be manually set to New following record creation. Status will be automatically updated to either Processed or Failed following data integration.
2cloudnine Timesheet Entry	Compulsory	Integration	Populated automatically upon successful data integration.

Payee Leave Event Fields Referenced by FSE

Field Name	Data Requirement	Populated via	Guidance
Approval Status	Compulsory	Automation	Status must = Approved to enable FSE data integration.
Employee	Compulsory	Manual Entry	If not created via FSE automation, this field must be manually populated. When creation is triggered via FSE, this field is populated with the related Employee Contact.
End Date	Compulsory	Manual Entry	If not created via FSE automation, this field must be manually populated.
Hours	Compulsory	Manual Entry	If not created via FSE automation, this field must be manually populated.
Payee	Compulsory	Manual Entry	If not created via FSE automation, this field must be manually populated.
Payee Leave Rule	Compulsory	Manual Entry	If not created via FSE automation, this field must be manually populated. The Payee Leave Rule will be used by the FSE to set the Leave Availability End Date for the corresponding Resource Absence, when creation is triggered via Payee Leave Event.
Record Type	Compulsory	Automation	FSE will only integrate data for Leave Take or Resource Absence Payee Leave Event records.
Skip Manager Approval	Compulsory	Manual Entry	Must be Yes to enable automatic creation of Resource Absences via Payee Leave Events.
Start Date	Compulsory	Manual Entry	If not created via FSE automation, this field must be manually populated. The value entered here will be used to populate the Leave Availability Start Dates for the Resource Absence.
Timesheet	Compulsory	Manual Entry	If not created via FSE automation, this field must be manually populated.
Void	Optional	Manual Entry	See QRG suite for further information.
Processed by Interpretation Rule	Compulsory	Automation	Must = TRUE to before FSE can commence data integration activities.

Field Service Time Sheet Fields Referenced by FSE

Field Name	Data Requirement	Populated via	Guidance
Id	Compulsory	Automation	Part of the minimum record detail required for Time Sheet integration.
Name	Compulsory	Automation	Part of the minimum record detail required for Time Sheet integration.
Owner	Compulsory	Automation	Part of the minimum record detail required for Time Sheet integration.
Service Resource	Compulsory	Manual Entry	Required by FSE to relate Field Service data with 2c9 Employee data.
Status	Compulsory	Automation	Must = Approved before integration can identify the Time Sheet.
Timesheet End Date	Conditional	Manual Entry	Part of the minimum record detail required for Time Sheet integration.
Timesheet Start Date	Conditional	Manual Entry	Part of the minimum record detail required for Time Sheet integration.
Total Duration (In Hours)	Conditional	Manual Entry	Part of the minimum record detail required for Time Sheet integration.
2cloudnine Timesheet	Compulsory	Integration	Populated by integration using the value from the 2cloudnine Timesheet (tc9_et__Timesheet__r.Id) identified and related to this data.
Do Not Send to 2c9	Compulsory	Manual Entry	Upon record creation, this field is automatically set to TRUE. Must be manually updated to reflect FALSE to enable FSE Time Sheet data integration.
Last Integration Time	Optional	Integration	Populated by integration using the value of the Date & Time of the last integration Apex Job execution.
2c9 Integration Status	Compulsory	Manual Entry	Defaults to New once minimum integration requirements have been met. Automatically updated to reflect the status of the most recent FSE Time Sheet data integration attempt: New = Ready to be processed Processed = Time Sheet data successfully integrated Failed = Data integration failure, manual intervention required to resolve (refer to Debug Log to identify cause).

Field Service Time Sheet Entry Fields Referenced by FSE

Field Name	Data Requirement	Populated via	Guidance
Duration (In Minutes)	Conditional	Manual Entry	Required if the corresponding 2c9 Timesheet uses Total Time format.
End Time	Conditional	Manual Entry	Required if the corresponding 2c9 Timesheet uses Start/End Time format.
Start Time	Conditional	Manual Entry	Required if the corresponding 2c9 Timesheet uses Start/End Time format.
Subject	Optional	Manual Entry	Any text included for this field will be integrated to the Employee Comments field on the corresponding 2c9 Timesheet Entry.
Type	Conditional	Manual Entry	Required if the record relates to Travel Times.
Work Order	Conditional	Manual Entry	Required if the record relates to a specific Work Order. Utilised by FSE when Pay Condition Allocations are associated, to ensure data is integrated according to the corresponding Pay Condition. See QRG Suite for more information.
Work Order Line Item	Conditional	Manual Entry	Required if the record relates to a specific Work Order. Utilised by FSE when Pay Condition Allocations are associated, to ensure data is integrated according to the corresponding Pay Condition. See QRG Suite for more information.
Do Not Send to 2c9	Compulsory	Manual Entry	Upon record creation, this field is automatically set to TRUE. Must be manually updated to reflect FALSE to enable FSE Time Sheet data integration.
Last Integration Time	Compulsory	Integration	Populated by integration using the value of the Date & Time of the last integration Apex Job execution.
2cloudnine Timesheet Entry	Compulsory	Integration	Populated following successful data integration, to reflect the corresponding 2c9 record created.
Paid Break	Optional	Manual Entry	Must = True if any Breaks associated with this record should be paid.
Local End Time	Compulsory	Manual Entry	Part of the minimum record detail required for Time Sheet integration.
Local Start Time	Compulsory	Manual Entry	Part of the minimum record detail required for Time Sheet integration.
Resource Absence	Conditional	Manual Entry	Required if record relates to any Resource Absence Times. If populated, related Resource Absences will be integrated as either Break or Leave Entry data in 2c9 Timesheets, according to the defined Record Type.
End Date	Compulsory	Manual Entry	Part of the minimum record detail required for Time Sheet integration.
Start Date	Compulsory	Manual Entry	Part of the minimum record detail required for Time Sheet integration.

Further Information

Document	Document Type	Description
Configuration Guide to 2cloudnine Payroll Suite	Configuration Guide	Configuration Guide for the implementation of 2cloudnine Payroll.
2cloudnine Field Service Extension Configuration and Implementation Guide	Configuration Guide	Configuration Guide for the implementation of the 2cloudnine Field Service Extension.
QRG Field Service Extension - Key Information	Key Information	Outlines useful information relevant to the Field Service Extension functionality. The document includes definitions, prerequisites, and other non-instructional information.
QRG Field Service Extension - Create Pay Conditions	Task Instructions	How to create Pay Conditions for use with Field Service Integration.
QRG Field Service Extension - Create Pay Condition Allocations	Task Instructions	How to create Pay Condition Allocations for use with Field Service Integration.

​Purpose

​Prerequisites

​Feature Overview

​Service Resource Integration

​Time Sheet Integration

​Resource Absence Integration

​Field Mapping

​Further Information

Purpose

Prerequisites

Feature Overview

Service Resource Integration

Time Sheet Integration

Resource Absence Integration

Field Mapping

Further Information