Automation and scripting with ArcGIS Workforce

Caution:

This is an advanced topic meant for administrators and project owners working with the feature layers directly, such as through ArcGIS API for Python or ArcGIS REST API.

Note:

Classic projects have a different schema than described below. For information on how to automate and script Classic Workforce projects, see Automate and script Workforce (Classic). To migrate Classic projects to the new schema, see Migrate Classic projects.

For more information, see What is a Classic project.

ArcGIS Workforce allows you to plan, manage, and complete workflows for all types of field activities. It integrates into your ArcGIS organization with a web app for creating and assigning work and a mobile app for mobile workers to manage their assignments. Once the project owner creates and configures a Workforce project, dispatchers use the Workforce web app to create and assign work, and mobile workers view and complete work that is assigned to them using Workforce and other ArcGIS apps on their mobile device. The entire workflow is driven by the Workforce project, a collection of feature layers and maps.

The Workforce web app allows a dispatcher to quickly and efficiently create work assignments and manage existing assignments. However, there may be things you want to do with assignments that are outside the scope of the web app. For example, some of the most common requests received for Workforce are regarding integration with other systems—such as third-party work order, asset, or maintenance management systems—and the handling of recurring or repeating assignments.

Using automation and scripting with Workforce allows you to achieve those capabilities. You're not limited to using the web app to create assignments. Workforce works with the content of the Assignments feature layer, regardless of how the records were created. Work can originate from other systems within an organization, such as from an asset or maintenance management system or a 311 system. Workforce can be integrated with external sources for creating and updating assignments. The Assignments layer includes a workOrderId field that can act as a foreign key, storing a unique identifier referencing an external system. The workOrderId field is available in the Assignment details as ID—dispatchers can provide the information, and mobile workers can view it.

Make sure you understand the schema of Workforce projects and how the assignment status date and time fields operate before you begin automating and scripting. While it is recommended that you use ArcGIS API for Python, you can also automate Workforce using ArcGIS REST API for feature layers.

Schema overview

A Workforce project is composed of two feature layers, three tables, and three coded value domains within a single feature service. The Workforce feature service is automatically generated at the time the project is created along with a folder, a group, and the dispatcher and worker web maps. The feature service has an item relationship with the two web maps and is in a predefined schema, shown below.

Note:

Certain field names are different in ArcGIS Enterprise. Instead of OBJECTID, GlobalID, CreationDate, Creator, EditDate, and Editor, they are objectid, globalid, created_date, created_user, last_edited_date, and last_edited_user, respectively.

Workforce feature service

The Workforce feature service contains the following layers and tables:

• Workers layer
  • A point feature layer that contains a record for each mobile worker who is included in the project.
  • Includes information about the mobile worker, including their contact number and job title.
  • The mobile worker's ArcGIS organizational username is stored in the userid field.
  • The layer tracks who created and last updated each mobile worker.
  • There is a primary key-foreign key (PK-FK) relationship from GlobalID to Assignments.workerid. Using the GlobalID value from the Workers layer as the Assignments.workerid field value associates the mobile worker with all their assignments.
  • The layer has the following coded value domain associations:
    • The status field is associated with the Worker_Status coded value domain to track the mobile worker's status.
• Assignments layer
  • A point feature layer that contains a record for each assignment.
  • Includes information about the assignment, including its status, location, and description, among others.
  • The layer tracks who created and last updated each assignment.
  • Attachments are enabled on the feature layer.
  • The layer contains foreign keys for some fields, associating values from another layer with this layer:
    • Assignments.workerid to Workers.GlobalID.
    • Assignments.dispatcherid to Dispatchers.GlobalID.
    • Assignments.workorderid can be used as a foreign key to an external system, such as an asset or maintenance management system, by providing values from the other system.
    • There is a PK-FK relationship from GlobalID to Assignment.assignmenttype. Using the GlobalID value from the Assignments layer as the Assignments.assignmenttype field value associates the assignment with the assignment type.
  • The layer has the following coded value domain associations:
    • The status field is associated with the Assign_Status coded value domain to track the assignment status.
    • The priority field is associated with the Priority coded value domain to manage the priority of work assignments.

  Caution:

  If an assignment has a null value for its geometry, it will not appear in Workforce.

• Dispatchers table
  • A table that contains a record for each dispatcher in the project.
  • Includes information about the dispatcher, including their name and contact number.
  • The dispatcher's ArcGIS organizational username is stored in the userid field.
  • The layer tracks who created and last updated each dispatcher.
  • There is a PK-FK relationship from GlobalID to Assignments.dispatcherid. Using the GlobalID value from the Dispatchers table as the Assignments.dispatcherid field value associates the dispatcher with all the assignments they assigned.
• Assignment Types table
  • A table that contains a record for each assignment type in the project.
  • This table is empty when the project is created. It contains values once assignment types have been added during project configuration.
  • It includes the descriptions for the assignment types specified by the project owner when the assignment types were added.
  • There is a PK-FK relationship from GlobalID to Assignments.assignmenttype. Using the GlobalID field value from the Assignment Types table associates the assignment type with assignments.
• Assignment Integrations table
  • A table that contains a record for each assignment integration in the project.
  • This table contains a record for integration with ArcGIS Navigator when created.
  • The Assignment Integrations table contains the following user-defined attributes, in addition to the standard system-defined attributes:
    • app—An identifier for the integrated app that will help find the integration configurations needed to populate the configuration experience in the web app—for example, arcgis-collector or https://collector.arcgis.app.
    • assignmenttype—The GlobalID of an assignment type if the integration should only be shown for certain assignment types. A value of null indicates that the integration supports all assignment types in the project.
    • prompt—The prompt displayed in the mobile client—for example, Navigate to assignment.
    • urltemplate—The template URL that is used to invoke the integrated app.
  • To find the integrations that are applicable to a particular assignment, use one of the following where clauses: assignmenttype = null or assignmenttype = '<assignment-type-id>'. These find all project-level integrations and all type-level integrations for the current assignment's type.
  • To find the integrations applicable to a project, query by the app using a where clause, for example, appid = 'arcgis-collector'.

The three coded value domains are as follows:

• Assign_Status—Stores the seven valid values for the status of an assignment. The values from 0-20 are reserved for future use by Workforce. Customers who want to store their own values in this field should choose a value from outside that range.
• Priority—Stores the four valid values for the priority of an assignment.
• Worker_Status—Stores the three valid values for the status of the mobile worker.

  For the values of the coded value domains, see the Workforce schema diagram.

Web map item relationship

The item relationship between the Workforce feature service and the worker and dispatcher web maps has the following definition:

• Relationship type—WorkforceMap2FeatureService
• Origin type—Web Map
• Destination type—Feature Service
• Rules
  • mustOwnAllItems—The project owner establishes the relationship and they must own the related map.

When a web map has an item relationship with the Workforce feature service, the following information is added to its metadata:

• title—The title of the project.
• snippet—The short description of the project.
• thumbnail—The thumbnail for the project.
• typeKeywords—Workforce Worker is added to the Worker map and Workforce Dispatcher is added to the Dispatcher map.

Assignment status date and time fields

Each assignment status defined in the Assign_Status domain has a corresponding date and time field in the Assignments feature layer. These fields contain the last date and time an assignment was in the corresponding state. When a status is first used for a particular assignment, the associated date and time field is populated. When an assignment is in the same status later, the date and time field is updated with the new date and time. For example, when an assignment is first assigned, its assigned date is the current date and time. If it is reassigned three hours later, the assignedDate field is updated to the new time, and the original assignment time is removed.

If the inprogressdate, declineddate, or pauseddate field is populated when an assignment is reassigned, it is set to null.

Assignment status	Corresponding date and time field
Unassigned	creationdate
Assigned	assigneddate
In Progress	inprogressdate
Completed	completeddate
Declined	declineddate
Paused	pauseddate

Note:

The Canceled status doesn't have an associated date and time field. The editdate Editor Tracking field can be used to determine the date and time an assignment was canceled, as long as no other edits have been made since the cancellation.

To better understand the values and when they are set, consider the following scenarios:

• Reassigning previously assigned work
  • You assigned an assignment at time t1, so assigneddate is t1.
  • Later, at time t2, the assignment is reassigned to another mobile worker, so assigneddate is t2.
• Reassigning declined work
  • You assigned an assignment at time t1, so assigneddate is t1.
  • The mobile worker declines the assignment at time t2, so declineddate is t2. The assigneddate value remains t1.
  • You assign the assignment to another mobile worker at time t3, so assigneddate is t3. The declineddate value is now null.
• Pausing and resuming work
  • You assigned an assignment at time t1, so assignedDate is t1.
  • The mobile worker starts the assignment at time t2, so inprogressDate is t2. The assigneddate value remains t1.
  • The mobile worker pauses the assignment at time t3, so pauseddate is t3. The assigneddate value remains t1 and the inProgressDate value remains t2.
  • The mobile worker restarts the assignment at time t4, so inprogressdate is t4. The assigneddate value remains t1, and the pauseddate value remains t3.
• Reassigning paused work
  • You assigned an assignment at time t1, so assigneddate is t1.
  • The mobile worker starts the assignment at time t2, so inprogressdate is t2. The assigneddate value remains t1.
  • The mobile worker pauses the assignment at time t3, so pauseddate is t3. The assigneddate value remains t1 and the inprogressdate value remains t2.
  • You assign the assignment to another mobile worker at time t4, so assigneddate is t4. The inprogressDate and pauseddate values are now null.

Use ArcGIS API for Python (recommended)

Use ArcGIS API for Python and its Workforce module to automate and script Workforce. Assignments created with the Workforce module can be interpreted by Workforce, as they follow the same schema. For examples and best practices, see the sample scripts in the Workforce scripts repository on GitHub. The scripts show how to use Python to accomplish many tasks, such as programmatically loading assignments from external data sources, importing and managing workers, removing completed assignments, and more. You can also use the Managing ArcGIS Workforce projects Jupyter notebook to see typical operations. To get started with the Workforce module, you must first install and set up ArcGIS API for Python.

Note:

To automate Workforce projects, you must use ArcGIS API for Python 1.8.3 or later.

Get started with the Workforce module

The Workforce module allows you to create Classic projects as well as projects that are enabled for offline use. Create projects with the Workforce module by completing the following steps:

1. Sign in to ArcGIS Online by running the following command in either a Python script or Python console:
   gis = arcgis.gis.GIS("https://arcgis.com", "<username>", "<password>")

2. Create either a Classic project or a project that is enabled for offline use by running one of the following commands:

   Create a Classic project

   version1_project = arcgis.apps.workforce.create_project("<project-title>", "<project-summary>", major_version=1)

   Create a project enabled for offline use

   version2_project = arcgis.apps.workforce.create_project("<project-title>", "<project-summary>", major_version=2)

For information on how to use the Workforce module to modify assignments, assignment types, workers, dispatchers, and app integrations, see the ArcGIS API for Python documentation for the Workforce module.

Use ArcGIS REST API for feature layers

Caution:

It is recommended that you use ArcGIS API for Python. It includes multiple safeguards that protect the integrity of your Workforce project.

You can automate Workforce using ArcGIS REST API for feature layers. When using ArcGIS REST API, you need to use the Feature object format to create and update assignments. See the sections below for details about creating and updating and assigning assignments using ArcGIS REST API.

Create an assignment using ArcGIS REST API

Workforce works with the content of the Assignments feature layer, regardless of how the records were created. There is no requirement to create assignments through the Workforce web app. If a record is properly created in the Assignments feature layer using ArcGIS REST API, Workforce recognizes it as a valid assignment in both the web and mobile apps.

When creating assignments using ArcGIS REST API, use the Add Features command. Some fields require values, you can provide values for other fields if your assignment requires them, and some fields cannot contain values.

The fields described in the following table require values:

Field	Definition	Value to provide
SHAPE	The point location of the assignment.	An x,y coordinate pair.
status	The assignment's status derived from the values in the assign_status domain.	0 (Unassigned)—Create unassigned work. 1 (Assigned)—Assign the work as part of its creation. Caution: If you are assigning the work, you must include values for the workerid and assigneddate fields, described below.
assignmenttype	The type of the assignment, derived from the GlobalID values in the assignment types table.	A valid GlobalID value from the assignment types table.
location	The text description of the point location of the assignment.	An address, an x,y coordinate pair, or any descriptive text.
dispatcherid	The ID of the dispatcher creating the assignment, derived from the GlobalID values in the dispatchers table.	A valid GlobalID value for a particular dispatcher associated with the project.

You can also include values for the following optional fields:

Field	Definition	Value to provide
description	Information for the mobile worker about the assignment.	Text for the mobile worker. White space is handled with the pre-line value.
priority	The priority of the assignment.	A valid value from the Priority domain.
workorderid	A foreign key referencing a work order from an external or third-party system.	A value from your external system.
duedate	The date and time by which the assignment needs to be completed.	A valid date and time, provided as UTC time in seconds from the last epoch. Note: To provide a due date without a time, specify the date and use 11:59:59 PM as the time.

To assign the work as part of its creation, use a status of 1 (as mentioned above) and provide the following fields as well:

Field	Definition	Value to provide
workerid	The ID of the mobile worker to whom the assignment is being assigned, derived from the GlobalID values in the Workers layer.	A valid GlobalID value of the mobile worker you are assigning.
assigneddate	Date and time the assignment was assigned.	The current date and time, provided as UTC time in seconds from the last epoch.

The other fields in the Assignments layer are managed by the ArcGIS platform, including the fields that are marked as part of the ArcGIS or Editor Tracking fields in the schema diagram. Do not provide or modify these values.

Assign assignments using ArcGIS REST API

In the previous section, you learned how to create an assigned assignment. Now, you'll learn how to assign an existing assignment. Use the ArcGIS REST API Update Features command, passing in the array of features to be updated. For each feature, you must provide these three fields to assign or reassign an assignment:

Field	Definition	Value to provide
status	The assignment's status, derived from the values in the Assign_Status domain.	1 (Assigned)
workerid	The ID of the mobile worker to whom the assignment is being assigned, derived from the GlobalID values in the Workers layer.	The GlobalID value of the mobile worker you are assigning.
assigneddate	The date and time the assignment was assigned.	The current date and time, provided as UTC time in seconds from the last epoch.
dispatcherid	The ID of the dispatcher assigning the assignment, derived from the GlobalID values in the Dispatchers table.	A valid GlobalID value for a particular dispatcher associated with the project.