Skip To Content

Workforce schema

Workforce for ArcGIS lets you 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 Workforceproject, 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 Workforceproject, a collection of feature layers and maps.

The Workforce web app is designed to allow a dispatcher to quickly and efficiently create new work assignments and manage existing assignments. However, you're not limited to using the web app to create new assignments. 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 workOrderIdfield is available in the Assignment details as ID—dispatchers can provide the information, and mobile workers can view it.

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 how to handle recurring or repeating assignments.

The best way to handle each of these scenarios is to follow examples of how to accomplish these tasks through the REST API for feature layers. With this in mind, the schema for a Workforce project is documented and published. Assignments created with the same schema can be interpreted by Workforce. You can also use the sample scripts that demonstrate the best practices for integrating Workforce with your own systems. The scripts are available at https://github.com/Esri/workforce-scripts.

This topic describes the schema of Workforce projects, along with how to properly automate creating and updating of assignments through the REST API. When using the REST API, you'll need to use the Feature object format to create and update assignments.

Caution:

This is an advanced topic meant for administrators and project owners working with the feature layers directly through the REST API.

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.

Workforce schema diagram
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:

  1. Workers
    • A point feature layer that contains a record for each worker who is included in the project.
    • Includes information about the worker, including their contact number and job title.
    • The worker's ArcGIS organizational user name is stored in the userId field.
    • The layer tracks who created and last updated each 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 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 worker status.
  2. 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 Prioritycoded 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.
  3. 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 user name 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.
  4. 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:

  1. Assign_Status—Stores the six valid values for the status of an assignment.
  2. Priority—Stores the four valid values for the priority of an assignment.
  3. Assign_Type—Stores the assignment types for the project. This coded value domain is empty when the project is first created. It contains values once assignment types have been added during project configuration.
  4. 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.

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 the 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, use the REST API 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:

FieldDefinitionValue 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

  • 0 (Unassigned) to create unassigned work
  • 1 (Assigned) if you are going to assign the work as part of its creation
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 if the 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 fieldDefinitionValue to provide

description

Information for the mobile worker about the assignment

Text for the mobile worker. Whitespace 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:

FieldDefinitionValue 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 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:

FieldDefinitionValue to provide

status

The assignment's status, from the values in the Assign_Status domain

  • 1 (Assigned)

workerId

The ID of the mobile worker to whom the assignment is being assigned (workers.OBJECTID from the Workers layer)

OBJECTID of the 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

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 statusCorresponding 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 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.