Work order generation in resco.FieldService

Warning

Automatic work order generation is no longer part of the default projects. Contact your business development manager at Resco if you are interested in this feature.

Work order is perhaps the most important concept in field service. resco.FieldService includes multiple ways how to create work orders:

• Create a work order manually from scratch.
• Create a work order manually from a customer incident.
• Create a work order manually from maintenance plan notification.
• Generate a work order automatically (described in this article).

Prerequisites

resco.FieldService organizations created after release 14.2 can automatically generate work orders. If you created your organization after September 28, 2021, your organization contains all the necessary components for this function out of the box.

If you have an older organization, you have two main options:

• Create a new organization. Import data (and maybe app projects) from old to new.
• Create a new organization. Import data model changes and server-side business logic (plugin and server processes) from new to old.

Consider using the Connected Environments function in the Admin Console to perform the migration.

Main components

What are the components involved in automatic work order generation?

Affected entities

The following entities and fields are needed:

• Maintenance Job (fs_agreementjob) is the entity where automatic generation can be configured. Make sure the following two fields are enabled and available on the form:
  • Action X-days in Advance (fs_actionxdaysinadvance): whole number
  • Additional Action (fs_advancedaction): option set
    
• Work order (fs_workorder)
• Job template (fs_incidenttemplate)
• Customer (account)
• Service agreement (fs_agreement)

Important UI elements

The form for the Maintenance Job entity is important for managing the whole process. If you are trying to use automatic generation in an older field service organization, consider importing this form from the new organization.

Field service plugin

FieldServicePlugin: This is a Resco Cloud server plugin with several critical functions for automatic generation. See Exporting plugins for information on how to transfer plugins to a different organization.

Create work order

These are the input parameters of the FieldService.CreateWorkOrder function:

• name
• customerid (required): stored in work order field customerid
• jobtemplateid: ID of the job template that should be used for the work order. Tasks, products, and skills are copied from the template to the work order. If set, this also creates a fs_workorderincident record.
• originatingid: depending on the reference, this ID is stored either as:

• originatingincidentid (if it is incident)
• originatingagreementjobid (if it is fs_agreementjob)
• originatingagreementjobdateid (if it is fs_agreementjobdate)

• pricelevelid: stored in pricelevelid. If not included in the function call, the function tries to find the right value from the parent customer, job template, or the latest price with the same currency as customer or job template

The work order created in this manner has the status "Ready".

Agreement job dates

This is a rough flow of the FieldService.HandleAgreementJobDates function:

1. Load agreements, jobs, and their dates. Agreements and their jobs must be in the state "Approved"; job dates status must be "Pending"
2. Go through all the job dates and generate work orders if:
   • the agreement job's "fs_advancedaction" is set to "CreateWorkOrder"
   • the job date's "fs_jobdate" falls within range today + "fs_actionxdaysinadvance"
3. When creating a work order in this way, the price list is taken from (first wins)
   • agreement
   • customer
   • job template
4. Customer is taken from agreement
5. Job template is taken from agreement job
6. If a work order was created, set the job date's status to "processed".

Agreement triggering

This is a rough flow of the FieldService.HandleAgreementJobTriggers function:

1. Check if the agreement trigger rule is set that ANY or ALL triggers must be satisfied:
   • We can create a work order if all active triggers for the agreement job are triggered and the agreement job trigger type is ALL.
   • We can create a work order if at least one trigger is triggered and the trigger type is ANY.
2. Check if there is a work order already created. Don't create a new work order if:
   • there is an active work order related either to this agreement job without a schedule (originatingagreementjobid == agreementjob)
   • there is a work order created AND scheduled for this agreement job within "fs_actionxdaysinadvance" days
3. When creating a work order this way, the price list is taken from:
   • agreement
   • customer
   • job template
4. Customer is taken from agreement
5. Job template is taken from agreement job
6. If the work order is properly created then triggers are untriggered.

Jobs and workflows

These are the server processes that trigger and execute plugin functions. You can create or modify these to suit your needs.

HandleJobDates: daily job, running at midnight

ServerExecute

Plugin.FieldService.HandleAgreementJobDates

PropertyLogTrigger: workflow triggers when a Reading record is created or modified.

ServerExecute

Plugin.FieldService.UpdatePropertyTriggers Entity.@this

CheckMaintenanceWorkTriggers: workflow triggers when a Maintenance Job Trigger is modified.