Community

Automate Workforce with ArcGIS API for Python: Clean and Maintain

2914
0
04-28-2020 06:33 AM
JoshuaClifford1
by Esri Contributor
Esri Contributor
3 0 2,914
‎04-28-2020 06:33 AM

Over time, projects in Workforce may become cluttered with assignments that are no longer needed in the regular working view of the Workforce project. The project may also contain workers who, for various reasons, have not correctly updated their working status. 

 

This blog post will teach you several ways to clean out and maintain your Workforce projects using ArcGIS API for Python. You’ll learn how to delete assignments and assignment types, how to archive assignments by copying them to a new feature layer, and how to reset workers who have been inactive. You’ll also learn how to verify assignment completion based on the completion of work orders.

 

These scripts will make tidying up your Workforce projects a quick and efficient task.  

 

Overview

  • Install ArcGIS API for Python
  • Download Workforce scripts
  • Delete assignments
  • Delete assignment types
  • Copy assignments to a feature layer 
  • Reset stale workers
  • Report incomplete assignments that have completed work orders
  • Additional resources

 

Download Workforce scripts

 

First, clone or download the workforce-scripts GitHub repository This contains the Python scripts for Workforce as well as the version of the Python API needed to automate Workforce projects. Once it's downloaded, navigate to the “workforce-scripts” folder in either the terminal or the command prompt. A Windows operating system is used for this example. 

 

cd C:\Users\user\Desktop\workforce-scripts

 

Install ArcGIS API for Python

 

To automate and script Workforce projects, you must use ArcGIS API for Python 1.8.3 or later. Version 1.8.3 is included in workforce-scripts file. 

 

Run the following command in either a Python script or Python console to create the virtual environment with the correct dependencies and to install ArcGIS API for Python 1.8.3: 

 

conda env create --file environment.yml

 

Next, activate the environment:

 

conda activate workforce-scripts

 

Once you've created and activated the environment, you are ready to use the Workforce scripts. 

 

Delete assignments

Caution: The following script will permanently delete assignments from your Workforce project. Be sure to create a backup of assignments before running this script. One way to create a backup of assignments is by running the copy_assignments_to_fs script, shown later in this blog.

 

The delete_assignments script allows you to delete assignments based on a specific field within the assignments layer. Quickly delete assignments based on completion status, assigned worker, or any queried field using the following script:

 

python delete_assignments.py -u username -p password -org "https://<org>.maps.arcgis.com" -project-id <project-id> -log-file "../log.txt" -where "1=1"

 

Run this in the terminal or command prompt after editing the username, password, organization, and project-id to match your own credentials.

 

Note: If you are working with a Classic project (a v1 project), the Project ID is the item ID of the project item. If you are working with projects enabled for offline use (a v2 project), the Project ID is the item ID of the Workforce feature service. Regardless of what version you are working with, the Project ID can be found in the URL of your project. 

 

Edit the where clause to query for the assignments you want to delete. Here are a few examples that demonstrate how you can write the query when using this script:

 

  • Someone left a company after completing hundreds of assignments during their tenure. The company queries their Worker ID and deletes all assignments they were assigned to.
  • Query: -where “WorkerID=1”
  • A snow plowing team has no reason to keep completed assignments. They query for completed assignments and delete them all.
  • Query: -where “status=3"
  • A landscaping company has completely changed their system of assigning work. They use the default where clause to delete all existing assignments.
  • Query: -where “1=1”

 

For more information on the values you can query for, see Overview of the Workforce Schema.

For more information on this script, see the delete_assignments readme.

 

Delete assignment types

The delete_assignment_types script allows you to delete all assignment types within a project. This is useful if you have many assignment types that you need to change or replace. Instead of making a new Workforce project or manually removing assignment types one by one – use the following script to delete all assignment types at once:

 

python delete_assignment_types.py -u username -p password -org "https://<org>.maps.arcgis.com" -project-id <project-id> -log-file "../log.txt"

 

 

Run this in the terminal or command prompt after editing the username, password, organization, and project-id to match your own credentials.

 

Note: The script will not run if any of the assignment types are in use.

 

For example, a Workforce project contained 25 assignment types related to maintaining community parks. Park maintenance standards were updated, so the assignment types needed to be replaced. The delete_assignment_types script was used to delete all of the existing types at once to make room for the new assignment types.

 

For more information on this script, see the delete_assignment_types readme.

 

Copy assignments to a different feature layer

The copy_assignments_to_fs script copies assignments from your assignments layer  to a new feature layer. This script is useful for archiving assignments -  allowing you to clean out your project without permanently deleting its assignment history.

 

You’ll first need to identify or create the target feature layer you want to copy assignments to. Name it something meaningful. For example, if you’re copying assignments from a tree inspection project, name the target layer tree assignment copies or tree assignment archive.  

 

This script uses a JSON configuration file (shown below) to map the assignment layer field names to those in the target feature layer. The field names on the left belong to the assignments layer, and those on the right belong to the target feature layer.

 

Default configuration file

 

When creating the target feature layer, use different field names to distinguish them from the assignments layer. If you don’t want to edit the default configuration file, name your target fields “Original_” followed by the original field name (shown above).

 

It’s important that you create a new OBJECTID and GLOBALID field in your target feature layer (named Original_OBJECTID and Original_GLOBALID, respectively). Since these are system generated fields, you may encounter duplicated values if you don’t create new fields. The Original_OBJECTID field should be an integer value, and the Original_GLOBALID field should be a string value.

 

Note: If your target feature layer has different field names than those shown above, edit the configuration file to match your target field names. Then save the file.

 

Once you have created your target feature layer and have edited the target field names in the configuration file, you are ready to run the script:

 

python copy_assignments_to_fs.py -config-file "../sample_data/fieldMappings.json" -u username -p password -org "https://.maps.arcgis.com" -target-fl -where "1=1" -project-id -log-file "log.txt" --copy-attachments

 

Be sure to edit the following:

  • Provide the file path to the config-file  
  • Provide your username, password, and organization to connect to your content.
  • Provide the complete feature service URL of the target feature layer (-target-fl). For example:
  • "https://services.arcgis.com/<server>/arcgis/rest/services/AssignmentsArchives/FeatureServer/0"
  • Use the where clause to query for the assignments you want to copy. The script defaults to copying all assignments (-where “1=1”).
  • Provide the project-id of your Workforce project.
  • Optionally, you can copy attachments (copy-attachments). Setting this parameter could slow down the script depending on how large your attachments are.

Once you run this script, your assignments will be copied to the new feature layer. After you check to make sure this was successful, you can delete those assignments from your active Workforce project.

 

For more information, see the copy_assignments_to_fs readme.

 

Reset stale workers

The reset_stale_workers script resets workers to the not working status if they haven’t changed their location, status, or contact information after a set date or time. If a worker forgets to update their status before taking a break or leaving for the day, they will still appear to be working on the dispatcher map. The following script keeps your project organized by resetting workers after a date or time that you set:

 

python reset_stale_workers.py -u -p -org https://arcgis.com -project-id -cutoff-date -timezone "US/Eastern"

 

Run this in the terminal or command prompt after editing the username, password, organization, and project-id to match your own credentials.

 

The cutoff-date acts as the threshold for when workers should be reset. Input either a specific date or amount of time (in minutes) to satisfy this parameter. For example: 

 

  • A manager runs this script every Monday morning to make sure each worker begins the week with a status of not working. They run the script to reset workers who haven’t updated their status in the past 24 hours. Their cutoff-date input would be 1440 (the number of minutes in 24 hours).

 

For more information, see the reset stale workers readme. 

 

Report incomplete assignments that have completed work orders

The report_incomplete_assignments_with_work_orders script reports assignments that have a completed work order, yet have an assignment status of unassigned, assigned, or declined. This script gives you the option to cancel assignments that meet this condition. This allows you to clear your project of completed assignments that have an incorrect status in Workforce.  

 

Features in Collector and surveys in Survey123 can be integrated as work orders for Workforce assignments. To learn how to integrate Survey123 and Collector with your Workforce project, see Integrate other apps.

 

In this example, there are four tree inspections that have been assigned to one mobile worker. The Workforce project is integrated with Survey123, so there is a survey (work order) associated with each assignment.

 

While the worker completed three work orders, they only updated one assignment to have a status of completed, as shown in the table below.

 

Work Order ID

Workforce Assignment Status

Survey123 Work Order

1

Assigned

Completed

2

Assigned

Completed

3

Completed

Completed

4

Assigned

Incomplete

 

Run the following script to report the assignments that have completed work orders, but an incomplete status. The script will also cancel these assignments.

 

python report_incomplete_assignments_with_work_orders.py -u username -p password -org https://arcgis.com -project-id -survey-id -field-name work_order_id --cancel-assignments

 

Be sure to edit the following:

  • Your username, password, and organization
  • The project-id for the Workforce project
  • The survey-id – this is the item ID for your survey layer
  • The field-name you used to integrate your Workforce project with either Collector or Survey123. The script defaults to using the work_order_id. This is the field used in the example above.
  • Add the optional --cancel-assignments parameter to cancel any assignments the script reports.

After running the script, it reports the incomplete assignments with completed work orders. In the example above, the script returns assignments 1 and 2 and then cancels them both.

 

For more information, see the report_incomplete_assignments readme.

 

Note: There is also a script available that reports any assignment that have a status of “completed” yet don't have a completed work order. For more information, see the report_complete_assignments_without_work_orders readme.

 

Additional resources

This blog post taught you how to use ArcGIS API for Python to clean and maintain your Workforce projects. See the following blog posts to learn about other ways to automate tasks for Workforce:

Feel free to test out all of the Workforce scripts in the Github repo. To learn more about the Workforce module within the Python API, see Managing Workforce for ArcGIS Projects.