Caution:
This topic covers how to automate and script Classic Workforce projects that appear in Workforce for ArcGIS. For information on how to automate and script projects that are enabled for offline use, and that appear in ArcGIS Workforce, see Automate Workforce.
This is an advanced topic meant for administrators and project owners working with the feature layers directly, such as through the ArcGIS API for Python or the REST API.
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 application 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 is designed to allow 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 around integration with other systems, such as third-party work order, asset, or maintenance management systems, as well as handling of recurring or repeating assignments.
Using automation and scripting with Workforce allows you to achieve those capabilities today. 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 has 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 through the REST API for feature layers. As long as assignments are created with the same schema, Workforce can interpret them.
Overview of the schema
A workforce project is composed of four feature layers and four coded value domains with a predefined schema. The name of each feature layer is a combination of a moniker, describing the purpose of the feature layer, appended with the GUID of the Workforce project item. For example, the Workers layer associated with a project with GUID 5dd018fcd88c4d33814cf3da9c44061e would be named workers_5dd018fcd88c4d33814cf3da9c44061e. This guarantees uniqueness of each feature layer.
Note:
The editor tracking fields are different in ArcGIS Enterprise. Instead of CreationDate, Creator, EditDate, and Editor, they are created_date, created_user, last_edited_date, and last_edited_user, respectively.
The four feature layers are as follows:
- Workers
- 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 OBJECTID to Assignments.workerId. Using the OBJECTID 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 status.
- Assignments
- 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.OBJECTID.
- Assignments.dispatcherId to Dispatchers.OBJECTID.
- 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.
- 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.
- The assignmentType field is associated with the Assign_Type coded value domain to store the assignment types for the project.
- Dispatchers
- A point feature layer that contains a record for each dispatcher within 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 OBJECTID to Assignments.dispatcherId. Using the OBJECTID value from the Dispatchers layer as the Assignments.dispatcherId field value associates the dispatcher with all the assignments they assigned.
- Location Tracking
- A point feature layer that contains a record for each point location logged while location tracking is enabled.
- The layer tracks who created and last updated each location track.
The four coded value domains are as follows:
- Assign_Status—Stores the six valid values for the status of an assignment.
- Priority—Stores the four valid values for the priority of an assignment.
- Assign_Type—Stores the assignment types for the project. This coded value domain is empty when the project is created. It contains values once assignment types have been added during project configuration.
- 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.
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 at which an assignment was in the corresponding state. When a status is first used for a particular assignment, the associated date and time field is first populated. When an assignment is in the same status again 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 lost.
| 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 at which 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 remains t1.
- You assign the assignment to another mobile worker at time t3, so assignedDate is t3.
- 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 remains t1.
- The mobile worker pauses the assignment at time t3, so pausedDate is t3. The assignedDate remains t1 and the inProgressDate remains t2.
- The mobile worker restarts the assignment at time t4, so inProgressDate is t4. The assignedDate remains t1, and the pausedDate remains t3.
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'll follow the same schema. For examples and best practices, see the sample scripts available 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 this Jupyter notebook to see some typical operations.
The Workforce module was introduced with ArcGIS API for Python 1.4.1. While you were able to use Python before this module was introduced, it simplifies the automation of Workforce tasks. The Workforce module encapsulates the Workforce project schema and rules. It includes safeguards as well, protecting the integrity of your Workforce project.
Note:
Have a comment or feedback on one of the scripts? Or an idea for another script you'd like provided? Share it on GitHub.
Use the REST API for feature layers
Caution:
It is recommended that you use ArcGIS API for Python. It has multiple safeguards in place that protect the integrity of the Workforce project.
You can automate Workforce through the REST API for feature layers. When using the REST API, you'll need to use the Feature object format to create and update assignments. See the following sections for details about creating and updating, as well as assigning, assignments through the REST API.
Create an assignment through the 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 created in the Assignments feature layer properly through the REST API, Workforce recognizes it as a valid assignment in both the web and mobile apps.
When creating assignments with the REST API, use the Add features command. There are some fields you are required to provide values for, some fields you can provide values for if your assignment requires them, and others that you shouldn't provide values for.
You need to supply values for the following fields:
| Field | Definition | Value to provide |
|---|---|---|
SHAPE | The point location of the assignment | An x,y coordinate pair |
status | The assignment's status, from the values in the Assign_Status domain |
Caution:If you are going to assign the work, you also need to include values for the workerId and assignedDate fields, described in a later table. |
assignmentType | The type of the assignment, from the values in the Assign_Type domain | Any valid value from the Assign_Type domain |
location | Text description of the point location of the assignment | An address; an x,y coordinate pair; or any descriptive text |
assignmentRead | Specifies whether the mobile worker has viewed the assignment | 0 since the assignment is unread |
dispatcherId | The ID of the dispatcher creating the assignment (dispatchers.OBJECTID from the Dispatchers layer) | May be the dispatcher ID for the ArcGIS organizational user you are connected as, or could be the ID of a particular dispatcher associated with the project |
You can also include values for the following optional fields:
| Optional 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 | 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. |
If you want 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 (workers.OBJECTID from the Workers layer) | OBJECTID of the mobile worker you are assigning |
assignedDate | Date and time when the assignment was assigned | The current date and time, provided as UTC time in seconds from the last epoch |
The other fields on 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. You shouldn't provide or modify their values.
Assign assignments through the REST API
In the previous section, you saw how to create an assigned assignment. Here, you'll see how to assign an existing assignment. Use the REST API Update Features command, passing in the array of features to be updated. For each feature, you'll need to provide these three fields to assign or reassign an assignment:
| Field | Definition | Value to provide |
|---|---|---|
status | The assignment's status, from the values in the Assign_Status domain |
|
workerId | The ID of the mobile worker to whom the assignment is being assigned (workers.OBJECTID from the Workers layer) | OBJECTID of the mobile worker you are assigning |
assignedDate | Date and time when 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, if different from the dispatcher who created it (dispatchers.OBJECTID from the Dispatchers layer) | May be the dispatcher ID for the ArcGIS organizational user you are connected as, or could be the ID of a particular dispatcher associated with the project |