使用 ArcGIS Workforce 进行自动化和脚本设置

警告：

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

注：

Classic 工程的方案与以下所述方案不同。 有关如何自动化和设置 Classic Workforce 工程脚本的信息，请参阅自动化和设置 Workforce 脚本 (Classic)。 要将 Classic 工程迁移至新方案，请参阅迁移 Classic 工程。

有关详细信息，请参阅什么是 Classic 工程。

通过 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，但还可以使用要素图层的 ArcGIS REST API 自动化 Workforce。

方案概览

Workforce 工程由 2 个要素图层、3 个表以及单个要素服务内的 3 个编码值属性域组成。 在创建工程时，系统将自动生成 Workforce 要素服务，以及文件夹、群组、调度员和工作人员 web 地图。 要素服务与 2 个 web 地图具有项目关系，并且位于预定义方案中，如下所示。

注：

某些字段名称在 ArcGIS Enterprise 中有所不同。 不是 OBJECTID、GlobalID、CreationDate、Creator、EditDate 和 Editor，而分别是 objectid、globalid、created_date、created_user、last_edited_date 和 last_edited_user。

Workforce 要素服务

Workforce 要素服务包含以下图层和表格：

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

  警告：

  对于任务的几何，如果任务具有 null 值，则不会在 Workforce 中显示该值。

• Dispatchers 表
  • 该表包含工程中每个调度员的记录。
  • 包括有关调度员（包含其姓名和联系电话）的信息。
  • 调度员的 ArcGIS 组织用户名被存储在 userid 字段中。
  • 该图层可以追踪创建和最后更新每个调度员的用户。
  • 从 GlobalID 到 Assignments.dispatcherid 存在 PK-FK 关系。 将 Dispatchers 表中的 GlobalID 值用作 Assignments.dispatcherid 字段值，以将调度员与其分配的所有任务相关联。
• Assignment Types 表
  • 该表包含工程中每个任务类型的记录。
  • 此表在创建工程时为空。 在工程配置期间，一旦添加了任务类型，该编码值属性域就会包含值。
  • 其中包含添加任务类型时，工程所有者指定的任务类型的说明。
  • 从 GlobalID 到 Assignments.assignmenttype 存在 PK-FK 关系。 使用 Assignment Types 表中的 GlobalID 字段值，以将任务类型与任务相关联。
• Assignment Integrations 表
  • 该表包含工程中每个任务集成的记录。
  • 该表在创建时包含与 ArcGIS Navigator 集成的记录。
  • 除了标准系统定义的属性之外，Assignment Integrations 表还包含以下用户定义的属性：
    • app- 集成应用程序的标识符，将有助于查找在 web 应用程序中填充配置体验所需的集成配置，例如 arcgis-collector 或 https://collector.arcgis.app。
    • assignmenttype- 如果应该仅针对某些任务类型显示集成，则为任务类型的 GlobalID。 值 null 指示集成支持工程中的所有任务类型。
    • prompt- 在移动客户端中显示的提示，例如“导航至任务”。
    • urltemplate- 用于调用集成应用程序的模板 URL。
  • 要查找适用于特定任务的集成，请使用以下 where 子句之一：assignmenttype = null 或 assignmenttype = '<assignment-type-id>'。 这些子句将针对当前任务的类型，查找所有工程级别的集成和所有类型级别的集成。
  • 要查找适用于工程的集成，请使用 where 子句按应用程序进行查询，例如，appid = 'arcgis-collector'。

3 个编码值属性域如下：

• Assign_Status- 存储任务状态的 7 个有效值。 将保留 0-20 的值以供 Workforce 今后使用。 希望在此字段中存储自己的值的客户应从该范围外选择一个值。
• Priority- 存储任务优先级的四个有效值。
• Worker_Status- 存储移动工作人员状态的三个有效值。

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

Web 地图项目关系

Workforce 要素服务以及工作人员和调度员 web 地图之间的项目关系具有以下定义：

• 关系类型 - WorkforceMap2FeatureService
• 源类型 - Web 地图
• 目标类型 - 要素服务
• 规则
  • mustOwnAllItems - 工程所有者将建立关系，并且他们必须拥有相关地图。

当 web 地图与 Workforce 要素服务具有项目关系时，系统会将以下信息添加到其元数据中：

• title - 工程的标题。
• snippet - 工程的简短描述。
• thumbnail - 工程的缩略图。
• typeKeywords - Workforce Worker 将被添加至 Worker 地图，Workforce Dispatcher 将被添加至 Dispatcher 地图。

任务状态日期和时间字段

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

如果在重新分配任务时填充 inprogressdate、declineddate 或 pauseddate 字段，则其将被设置为 null。

任务状态	相应的日期和时间字段
未分配	creationdate
已分配	assigneddate
进行中	inprogressdate
已完成	completeddate
已拒绝	declineddate
已暂停	pauseddate

注：

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

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

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

使用 ArcGIS API for Python（推荐）

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

注：

要自动化 Workforce 工程，必须使用 ArcGIS API for Python 1.8.3 或更高版本。

Workforce 模块入门

Workforce 模块可用于创建 Classic 工程以及启用离线使用功能的工程。 要使用 Workforce 模块创建工程，请完成以下步骤：

1. 可以通过在 Python 脚本或 Python 控制台中运行以下命令登录到 ArcGIS Online：
   gis = arcgis.gis.GIS("https://arcgis.com", "<username>", "<password>")

2. 通过运行以下命令之一，创建 Classic 工程或启用离线使用功能的工程：

   创建 Classic 工程

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

   创建启用离线使用功能的工程

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

有关如何使用 Workforce 模块来修改任务、任务类型、工作人员、调度员和应用程序集成的信息，请参阅 Workforce 模块的 ArcGIS API for Python 文档。

使用要素图层的 ArcGIS REST API

警告：

建议使用 ArcGIS API for Python。 其中包含多项防护措施，可用于保护 Workforce 工程的完整性。

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

使用 ArcGIS REST API 创建任务

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

创建任务时，请使用 ArcGIS REST API 添加要素命令。 有些字段需要值，如果您的任务需要这些字段，则可以为其提供值，而有些字段则不能包含值。

下表中介绍的字段需要值：

字段	定义	要提供的值
SHAPE	任务的点位置。	x,y 坐标对。
status	任务状态，派生自 assign_status 属性域中的值。	0（未分配）- 创建未分配的工作。 1（已分配）- 在工作的创建过程中对其进行分配。 警告： 如果要分配工作，则必须包含 workerid 和 assigneddate 字段的值，如下所述。
assignmenttype	任务类型，派生自任务类型表中的 GlobalID 值。	任务类型表中的有效 GlobalID 值。
location	任务的点位置的文本描述。	地址、x,y 坐标对或任意描述性文本。
dispatcherid	创建任务的调度员的 ID，派生自 Dispatchers 表中的 GlobalID 值。	与工程相关联的特定调度员的有效 GlobalID 值。

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

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

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

字段	定义	要提供的值
workerid	被分配任务的移动工作人员的 ID，派生自 Workers 图层中的 GlobalID 值。	您正在分配的移动工作人员的有效 GlobalID 值。
assigneddate	分配了任务的日期和时间。	从上一个纪元以秒为单位作为 UTC 时间提供的当前日期和时间。

Assignments 图层中的其他字段由 ArcGIS 平台管理，包括方案图中被标记为 ArcGIS 或编辑者追踪字段的一部分的字段。 请勿提供或修改这些值。

使用 ArcGIS REST API 分配任务

在上一部分中，您已学习了如何创建已分配的任务。 现在，您将学习如何分配现有任务。 使用 ArcGIS REST API 更新要素命令，传入要更新的要素数组。 对于每个要素，必须提供以下 3 个字段来分配或重新分配任务：

字段	定义	要提供的值
status	任务状态，派生自 Assign_Status 属性域中的值。	1（已分配）
workerid	被分配任务的移动工作人员的 ID，派生自 Workers 图层中的 GlobalID 值。	您正在分配的移动工作人员的 GlobalID 值。
assigneddate	分配了任务的日期和时间。	从上一个纪元以秒为单位作为 UTC 时间提供的当前日期和时间。
dispatcherid	分配任务的调度员的 ID，派生自 Dispatchers 表中的 GlobalID 值。	与工程相关联的特定调度员的有效 GlobalID 值。