自动化和设置 Workforce 的脚本

警告：

本主题将介绍如何自动化和设置在 Workforce for ArcGIS 中显示的 Classic Workforce 工程的脚本。 有关如何自动化和设置启用离线使用功能的工程以及显示在 ArcGIS Workforce 中的工程的脚本的信息，请参阅自动化 Workforce。

这一高级主题面向通过 ArcGIS API for Python 或 REST API 等途径直接使用要素图层的管理员和工程所有者。

通过 ArcGIS Workforce 可以计划、管理和完成所有类型的外业活动的工作流。 它将一个用于创建和分配工作的 web 应用程序与一个可供移动工作人员管理其任务的移动应用程序整合到您的 ArcGIS 组织中。 工程所有者创建和配置 Workforce 工程后，调度员便会使用 Workforce web 应用程序创建和分配工作，而移动工作人员会在他们的移动设备上使用 Workforce 和其他 ArcGIS 应用程序查看并完成分配给他们的工作。 整个工作流由 Workforce 工程（要素图层和地图的集合）驱动。

Workforce web 应用程序可供调度员快速有效地创建工作任务和管理现有任务。 但是，您可能想要对 web 应用程序范围之外的任务执行一些操作。 例如，针对 Workforce 收到的一些最常见的请求是关于与其他系统集成的请求，例如第三方工作指令、资产或维护管理系统以及处理循环或重复任务。

对 Workforce 进行自动化和脚本设置可即时实现这些功能。 您并不局限于使用 web 应用程序创建任务。无论记录的创建方式如何，Workforce 都使用 Assignments 要素图层的内容。 也可以通过组织中的其他系统（例如，资产或维护管理系统或者 311 系统等）生成工作。Workforce 可通过与外部源集成来创建和更新任务。 Assignments 图层具有 workOrderId 字段，您可将该字段作为外键来存储引用外部系统的唯一标识符。 workOrderId 字段可在任务详细信息中用作 ID - 调度员可提供信息，而移动工作人员可查看这些信息。

在进行自动化和脚本设置之前，确保您了解 Workforce 工程的方案以及任务状态日期和时间字段的操作方式。 虽然建议您使用 ArcGIS API for Python，但是您还可以通过要素图层的 REST API 自动化 Workforce。 只要任务使用同一方案创建，Workforce 就可以解释它们。

方案概述

在预定义方案中，Workforce 工程由四个要素图层和四个编码值属性域组成。 每个要素图层的名称是用于描述要素图层目的的名字与后面所追加的 Workforce 工程项目 GUID 的组合。 例如，与 GUID 为 5dd018fcd88c4d33814cf3da9c44061e 的工程相关联的工作人员图层将命名为 workers_5dd018fcd88c4d33814cf3da9c44061e。 这保证了每个要素图层的唯一性。

注：

ArcGIS Enterprise 中编辑者追踪字段是不同的。 不是 CreationDate、Creator、EditDate 和 Editor，而分别是 created_date、created_user、last_edited_date 和 last_edited_user。

四个要素图层如下：

1. 工作人员
   • 包含工程中每个移动工作人员的记录的点要素图层。
   • 包括有关移动工作人员（包含其联系电话和作业标题）的信息。
   • 移动工作人员的 ArcGIS 组织用户名存储在 userId 字段中。
   • 该图层可以追踪创建和最后更新每个移动工作人员的用户。
   • 从 OBJECTID 到 Assignments.workerId 存在主键-外键 (PK-FK) 关系。 将工作人员图层中的 OBJECTID 值用作 Assignments.workerId 字段值，以将移动工作人员与其所有任务相关联。
   • 该图层具有以下编码值属性域关联：
     • 状态字段与 Worker_Status 编码值属性域关联以追踪移动工作人员状态。
2. 分配
   • 包含每个任务的记录的点要素图层。
   • 包括有关任务（包含其状态、位置和描述等）的信息。
   • 该图层可以追踪创建和最后更新每个任务的用户。
   • 在要素图层上启用附件。
   • 该图层包含某些字段的外键，这些外键将另一个图层的值与该图层关联：
     • Assignments.workerId 到 Workers.OBJECTID。
     • Assignments.dispatcherId 到 Dispatchers.OBJECTID。
     • Assignments.workOrderId 可通过从其他系统提供值来用作外部系统（如资产或维护管理系统）的外键。
   • 该图层具有以下编码值属性域关联：
     • 将 status 字段与 Assign_Status 编码值属性域关联以追踪任务的状态。
     • 将 priority 字段与 Priority 编码值属性域关联以管理工作任务的优先级。
     • assignmentType 字段与 Assign_Type 编码值属性域关联以存储工程的任务类型。
3. 调度员
   • 包含工程中每个调度员的记录的点要素图层。
   • 包括有关调度员（包含其姓名和联系电话）的信息。
   • 调度员的 ArcGIS 组织用户名被存储在 userId 字段中。
   • 该图层可以追踪创建和最后更新每个调度员的用户。
   • 从 OBJECTID 到 Assignments.dispatcherId 存在 PK-FK 关系。 将 Dispatchers 图层中的 OBJECTID 值用作 Assignments.dispatcherId 字段值，以将调度员与其分配的所有任务相关联。
4. 位置追踪
   • 包含在启用位置追踪时登录的每个点位置的记录的点要素图层。
   • 该图层可以追踪创建和最后更新每个位置轨迹的用户。

四个编码值属性域如下：

1. Assign_Status- 存储任务状态的 6 个有效值。
2. Priority- 存储任务优先级的四个有效值。
3. Assign_Type- 存储工程的任务类型。 该编码值属性域在创建工程时为空。 在工程配置期间，一旦添加了任务类型，该编码值属性域就会包含值。
4. Worker_Status- 存储移动工作人员状态的三个有效值。

有关编码值属性域的值，请参阅 Workforce 方案图。

任务状态日期和时间字段

在 Assign_Status 属性域中定义的每个任务状态在任务要素图层中都具有相应的日期和时间字段。 这些字段包含任务处于相应状态的最后日期和时间。 当状态第一次用于特定任务时，会首先填充相关联的日期和时间字段。 当任务稍后再次处于相同状态时，日期和时间字段会更新为新的日期和时间。 例如，在第一次分配任务时，其分配日期即当前日期和时间。 如果三小时后重新分配任务，则 assignedDate 字段会更新为新时间，而原始任务时间丢失。

任务状态	相应的日期和时间字段
未分配	CreationDate
已分配	assignedDate
进行中	inProgressDate
已完成	completedDate
已拒绝	declinedDate
已暂停	pausedDate

注：

已取消的状态没有关联的日期和时间字段。 EditDate 编辑者追踪字段可用于确定取消任务的日期和时间（只要在取消后未进行任何其他编辑）。

为了更好地了解这些值以及何时设置这些值，请参考以下情景：

• 重新分配之前分配过的工作
  • 您在时间 t1 时分配了一个任务，因此 assignedDate 为 t1。
  • 稍后，在时间 t2 时，将该任务重新分配给另一个移动工作人员，因此 assignedDate 为 t2。
• 重新分配被拒绝的工作
  • 您在时间 t1 时分配了一个任务，因此 assignedDate 为 t1。
  • 移动工作人员在时间 t2 时拒绝了该任务，因此 declinedDate 为 t2。 assignedDate 仍为 t1。
  • 您在时间 t3 时将任务分配给另一个移动工作人员，因此 assignedDate 为 t3。
• 暂停和继续工作
  • 您在时间 t1 时分配了一个任务，因此 assignedDate 为 t1。
  • 移动工作人员在时间 t2 时开始任务，因此 inProgressDate 为 t2。 assignedDate 仍为 t1。
  • 移动工作人员在时间 t3 时暂停任务，因此 pausedDate 为 t3。 assignedDate 仍为 t1 且 inProgressDate 仍为 t2。
  • 移动工作人员在时间 t4 时重新开始任务，因此 inProgressDate 为 t4。 assignedDate 仍为 t1 且 pausedDate 仍为 t3。

使用 ArcGIS API for Python（推荐）

使用 ArcGIS API for Python 及其 Workforce 模块来自动化 Workforce 并设置其脚本。 由于遵循相同的方案，因此使用 Workforce 模块创建的任务可由 Workforce 进行解释。 有关示例和最佳做法，请参阅 GitHub 中的示例脚本。 脚本显示如何使用 Python 完成大量任务，例如通过编程的方式从外部数据源加载任务、导入和管理工作人员以及移除完成的任务等。 您还可以使用此 Jupyter notebook 来查看一些典型操作。

ArcGIS API for Python 1.4.1 引入了 Workforce 模块。 虽然在引入这一模块前您可以使用 Python,但这一模块简化了 Workforce 任务的自动化过程。 Workforce 模块封装 Workforce 工程方案和规则。 其中也包括防护措施，以保护 Workforce 工程的完整性。

注：

想要对其中一个脚本提供意见和反馈？ 或者想要对另一个脚本提供看法？ 在 GitHub 上共享。

使用要素图层的 REST API。

警告：

建议使用 ArcGIS API for Python。 其中采取了多种防护措施，可保护 Workforce 工程的完整性。

可通过要素图层的 REST API 自动化 Workforce。 使用 REST API 时，您需要使用要素对象格式来创建和更新任务。 有关通过 REST API 创建和更新，以及分配任务的详细信息，请参阅以下部分。

通过 REST API 创建任务

Workforce 使用任务要素图层的内容，而与记录的创建方式无关。 无需通过 Workforce web 应用程序创建任务。如果通过 REST API 在任务要素图层中正确创建了记录，则 Workforce 会将其识别为 web 和移动应用程序中的有效任务。

使用 REST API 创建任务时，请使用添加要素命令。 一些字段需要您提供值（如果您的任务需要，您可以为一些字段提供值），而其他一些字段则不需要您提供值。

您需要为以下字段提供值：

字段	定义	要提供的值
SHAPE	任务的点位置	x,y 坐标对
status	任务状态，来自 Assign_Status 属性域中的值。	0（未分配），表示要创建未分配的工作 1（已分配），表示要在工作的创建过程中对其进行分配 警告： 如果要分配工作，您还需要包含 workerId 和 assignedDate 字段（在后面的表中有所描述）的值。
assignmentType	任务类型，Assign_Type 属性域中的值	Assign_Type 属性域中的有效值
location	任务的点位置的文本描述	地址；x,y 坐标对；或任意描述性文本
assignmentRead	指定移动工作人员是否已查看任务	0 表示任务未读
dispatcherId	创建任务的调度员的 ID（Dispatchers 图层中的 dispatchers.OBJECTID）	可以是您以用户身份连接 ArcGIS 组织时的调度员 ID，也可以是与工程关联的特定调度员的 ID。

还可以包括以下可选字段的值：

可选字段	定义	要提供的值
description	移动工作人员关于任务的信息	移动工作人员的文本。 通过 pre-line 值处理空白字符。
priority	任务的优先级	Priority 属性域中的有效值。
workOrderId	从外部或第三方系统引用工单的外键	外部系统中的值。
dueDate	需要完成任务的日期和时间	从上一个纪元以秒为单位作为 UTC 时间提供的有效日期和时间。 注： 要提供一个不含时间的截止日期，请指定日期并使用 11:59:59 PM 作为时间。

如果要在创建工作的过程中对其进行分配，请使用状态 1（如上所述）并同时提供以下字段：

字段	定义	要提供的值
workerId	被分配任务的移动工作人员的 ID（工作人员图层中的 workers.OBJECTID）	OBJECTID 您正在分配的移动工作人员的
assignedDate	分配任务的日期和时间	从上一个纪元以秒为单位作为 UTC 时间提供的当前日期和时间

任务图层上的其他字段由 ArcGIS 平台管理，包括方案图中被标记为 ArcGIS 或编辑者追踪字段的一部分的字段。 不应提供或修改它们的值。

通过 REST API 分配任务

在上一部分中您已了解了如何创建已分配的任务。 在此，您将了解如何分配现有任务。 使用 REST API 更新要素命令，传入要更新的要素数组。 对于每个要素，都需要提供这三个字段来分配或重新分配任务：

字段	定义	要提供的值
status	任务状态，来自 Assign_Status 属性域中的值。	1（已分配）
workerId	被分配任务的移动工作人员的 ID（工作人员图层中的 workers.OBJECTID）	OBJECTID 您正在分配的移动工作人员的
assignedDate	分配任务的日期和时间	从上一个纪元以秒为单位作为 UTC 时间提供的当前日期和时间
dispatcherId	分配任务的调度员（如果与创建任务的调度员不同）的 ID（调度员图层中的 dispatchers.OBJECTID）	可以是您以用户身份连接 ArcGIS 组织时的调度员 ID，也可以是与工程关联的特定调度员的 ID。