Automatizar y utilizar scripts en Workforce

Precaución:

En este tema se describe cómo automatizar y utilizar scripts en proyectos de Classic Workforce que aparecen en Workforce for ArcGIS. Para obtener información sobre cómo automatizar y utilizar scripts en proyectos habilitados para el uso sin conexión, y que aparecen en ArcGIS Workforce, consulte Automatizar Workforce.

Se trata de un tema avanzado pensado para administradores y propietarios de proyecto que trabajan con las capas de entidades directamente, por ejemplo, mediante ArcGIS API for Python o la API REST.

ArcGIS Workforce permite planificar, administrar y completar flujos de trabajo para todo tipo de actividades de campo. Se integra en su organización de ArcGIS con una aplicación web que permite crear y asignar trabajo y una aplicación web para que los trabajadores móviles puedan administrar sus asignaciones. Una vez que el propietario del proyecto crea y configura un proyecto de Workforce, los controladores utilizan la aplicación web Workforce para crear y asignar trabajo y los trabajadores móviles consultan y completan el trabajo que se les ha asignado mediante el uso de Workforce y otras aplicaciones de ArcGIS en sus dispositivos móviles. Todo el flujo de trabajo se rige por el proyecto de Workforce, un conjunto de capas y mapas de entidades.

La aplicación web de Workforce está diseñada para que un controlador pueda crear de forma rápida y eficaz asignaciones de trabajo y para que pueda administrar las asignaciones existentes Sin embargo, puede que haya muchas cosas que quiera hacer con las asignaciones que se encuentran fuera del alcance de la aplicación web. Por ejemplo, algunas de las solicitudes más comunes que se reciben en Workforce están relacionadas con la integración con otros sistemas, por ejemplo, sistemas externos de administración de órdenes de trabajo, activos o mantenimiento, así como con gestionar asignaciones recurrentes o repetitivas.

Ahora, al utilizar la automatización o los scripts con Workforce puede conseguir esas capacidades. No debe limitarse a utilizar la aplicación web para crear asignaciones. Workforce funciona con el contenido de la capa de entidades Asignaciones, independientemente de cómo se hayan creado los registros. El trabajo puede crearse en otros sistemas de una organización, por ejemplo, en un sistema de administración de activos o de mantenimiento o en un sistema 311. Workforce se puede integrar con fuentes externas para crear y actualizar asignaciones. La capa Asignaciones tiene un campo workOrderId que puede actuar como una clave externa y almacenar un identificador único que haga referencia a un sistema externo. El campo workOrderId está disponible en los detalles de la Asignación como el Id.. Los controladores pueden proporcionar la información y los trabajadores móviles pueden verla.

Asegúrese de comprender el esquema de los proyectos de Workforce y cómo funcionan loscampos de fecha y hora del estado de la asignación antes de comenzar a utilizar la automatización y los scripts. Aunque se recomienda que utilice ArcGIS API for Python, también puede automatizar Workforce a través de la API REST para capas de entidades. Siempre que las asignaciones se creen con el mismo esquema, Workforce puede interpretarlas.

Descripción general del esquema

Un proyecto de Workforce está formado por cuatro capas de entidades y cuatro dominios de valor codificado con un esquema predefinido. El nombre de cada capa de entidades es una combinación de un moniker, que describe la finalidad de la capa de entidades y el GUID del elemento del proyecto de Workforce. Por ejemplo, la capa de Trabajadores asociada a un proyecto con el GUID 5dd018fcd88c4d33814cf3da9c44061e se llamaría workers_5dd018fcd88c4d33814cf3da9c44061e. Esto garantiza la unicidad de cada capa de entidades.

Nota:

Los campos de rastreo del editor son distintos en ArcGIS Enterprise. En lugar de CreationDate, Creator, EditDate y Editor, se trata de created_date, created_user, last_edited_date y last_edited_user, respectivamente.

Las cuatro capas de entidades son las siguientes:

1. Trabajadores
   • Una capa de entidades de puntos que contiene un registro de cada trabajador móvil incluido en el proyecto.
   • Contiene información acerca del trabajador móvil, incluido su número de contacto y el cargo que ocupa.
   • El nombre de usuario de la organización de ArcGIS del trabajador móvil se almacena en el campo userId.
   • La capa realiza un seguimiento de quién ha creado y actualizado por última vez cada trabajador móvil.
   • Existe una relación entre la clave principal y la clave externa (PK-FK) de OBJECTID aAssignments.workerId. Al utilizar el valor de OBJECTID de la capa Trabajadores como valor del campo Assignments.workerId se asocia al trabajador móvil con todas sus asignaciones.
   • La capa tiene las siguientes asociaciones de dominio de valor codificado:
     • El campo de estado está asociado al dominio de valor codificado Worker_Status para realizar el seguimiento del estado del trabajador móvil.
2. Asignaciones
   • Una capa de entidades de puntos que contiene un registro de cada asignación.
   • Contiene información sobre la asignación, incluido el estado, la ubicación o la descripción, entre otros.
   • La capa realiza un seguimiento de quién ha creado y actualizado por última vez cada asignación.
   • Los adjuntos están habilitados en la capa de entidades.
   • La capa contiene claves externas para algunos campos, asociando valores de otra capa a esta capa:
     • Assignments.workerId a Workers.OBJECTID.
     • Assignments.dispatcherId aDispatchers.OBJECTID.
     • Assignments.workOrderId se puede utilizar como una clave externa en un sistema externo, por ejemplo, un sistema de administración de activos o de mantenimiento, proporcionando valores del otro sistema.
   • La capa tiene las siguientes asociaciones de dominio de valor codificado:
     • El campo status está asociado al dominio de valor codificado Assign_Status para realizar el seguimiento del estado de la asignación.
     • El campo priority está asociado al dominio de valor codificado Priority para administrar la prioridad de las asignaciones de trabajo.
     • El campo assignmentType está asociado al dominio de valor codificado Assign_Type para almacenar los tipos de asignación del proyecto.
3. Controladores
   • Una capa de entidades de puntos que contiene un registro de cada controlador incluido en el proyecto.
   • Contiene información acerca del controlador, incluido su nombre y número de contacto.
   • El nombre de usuario de la organización de ArcGIS del controlador se almacena en el campo userId.
   • La capa realiza un seguimiento de quién ha creado y actualizado por última vez cada controlador.
   • Existe una relación PK-FK de OBJECTID a Assignments.dispatcherId. Al utilizar el valor OBJECTID de la tabla Controladores como valor del campo Assignments.dispatcherId, se asocia al controlador con todas las asignaciones que ha asignado.
4. Rastreo de ubicación
   • Una capa de entidades de puntos que contiene un registro de cada ubicación de punto registrada con la función de seguimiento de ubicaciones habilitada.
   • La capa realiza un seguimiento de quién ha creado y actualizado por última vez cada rastreo de la ubicación.

Los cuatro dominios de valor codificado son los siguientes:

1. Assign_Status— Almacena los seis valores válidos para el estado de una asignación.
2. Priority— Almacena los cuatro valores válidos para la prioridad de una asignación.
3. Assign_Type— Almacena los tipos de asignación para el proyecto. Este dominio de valor codificado está vacío cuando se crea el proyecto. Contendrá valores una vez que se agreguen tipos de asignación durante la configuración del proyecto.
4. Worker_Status— Almacena los tres valores válidos para el estado del trabajador móvil.

Para ver los valores de los dominios de valor codificado, consulte el diagrama del esquema de Workforce.

Campos de estado, fecha y hora de la asignación

Cada estado de la asignación definido en el dominio Assign_Status tiene un campo de fecha y hora correspondiente en la capa de entidades Asignaciones. Estos campos contienen la última fecha y hora en que una asignación estuvo el estado correspondiente. Cuando se utiliza un estado por primera vez para una determinada asignación, el campo de fecha y hora asociado se rellena en primer lugar. Cuando una asignación vuelve a estar en el mismo estado más tarde, el campo de fecha y hora se actualiza con la nueva fecha y hora. Por ejemplo, cuando se asigna por primera vez una asignación, su fecha asignada es la fecha y hora actuales. Si se reasigna tres horas más tarde, el campo assignedDate se actualiza con la hora nueva y la hora original de la asignación se pierde.

Estado de asignación	Campo de fecha y hora correspondiente
No asignado	CreationDate
Asignada	assignedDate
En curso	inProgressDate
Completada	completedDate
Rechazada	declinedDate
En pausa	pausedDate

Nota:

El estado Cancelado no tiene un campo de fecha y hora asociado. El campo EditDate del Rastreo del editor se puede utilizar para determinar la fecha y hora en que se canceló una asignación, siempre que no se hayan realizado ediciones desde que se canceló.

Para comprender mejor los valores y cuándo se definen, considere estos escenarios:

• Reasignar trabajo asignado previamente
  • Realizó una asignación a la hora t1, por lo tanto, el valor de assignedDate es t1.
  • Más tarde, a la hora t2, la asignación se reasigna a otro trabajador móvil, por lo que el valor de assignedDate es t2.
• Reasignar trabajo rechazado
  • Realizó una asignación a la hora t1, por lo tanto, el valor de assignedDate es t1.
  • El trabajador móvil rechaza la asignación a la hora t2, por lo tanto, el valor de declinedDate es t2. El valor de assignedDate sigue siendo t1.
  • Asigna la asignación a otro trabajador móvil a la hora t3, por lo tanto, el valor de assignedDate es t3.
• Poner trabajo en pausa y reanudarlo
  • Realizó una asignación a la hora t1, por lo tanto, el valor de assignedDate es t1.
  • El trabajador móvil empieza la asignación a la hora t2, por lo tanto, el valor de inProgressDate es t2. El valor de assignedDate sigue siendo t1.
  • El trabajador móvil pone en pausa la asignación a la hora t3, por lo tanto, el valor de pausedDate es t3. El valor de assignedDate sigue siendo t1 y el de inProgressDate sigue siendo t2.
  • El trabajador móvil reinicia la asignación a la hora t4, por lo tanto, el valor de inProgressDate es t4. El valor de assignedDate sigue siendo t1 y el de pausedDate sigue siendo t3.

Utilizar ArcGIS API for Python (recomendado)

Utilice ArcGIS API for Python y su módulo Workforce para automatizar y utilizar scripts en Workforce. Las asignaciones creadas con el módulo Workforce pueden ser interpretadas por Workforce, ya que siguen el mismo esquema. Para obtener ejemplos y prácticas recomendadas, consulte los scripts de muestra disponibles en GitHub. Los scripts muestran cómo utilizar Python para completar muchas tareas, por ejemplo, cargar asignaciones mediante programación desde fuentes de datos externas, importar y administrar trabajadores, eliminar asignaciones completadas y más. También puede utilizar este notebook de Jupyter para ver más operaciones típicas.

El módulo de Workforce se introdujo con ArcGIS API for Python 1.4.1. Aunque podía utilizar Python antes de que este módulo se introdujese, simplifica la automatización de tareas en Workforce. El módulo de Workforce encapsula las reglas y el esquema de proyecto de Workforce. También incluye métodos de protección, lo cual protege la integridad de su proyecto de Workforce.

Nota:

¿Tiene comentarios u opiniones sobre uno de los scripts? ¿O una idea sobre otro script que le gustaría que se ofreciese? Compártalos en GitHub.

Utilizar la API REST para capas de entidades

Precaución:

Se recomienda utilizar ArcGIS API for Python. Tiene implementados varios métodos de protección que protegen la integridad del proyecto de Workforce.

Puede automatizar Workforce mediante la API REST para capas de entidades. Cuando utilice la API REST, deberá utilizar el formato de Objeto de entidad para crear y actualizar asignaciones. Consulte las siguientes secciones para obtener más información sobre cómo crear y actualizar asignaciones, además de cómo asignarlas, mediante la API REST.

Crear una asignación mediante la API REST

Workforce funciona con el contenido de la capa de entidades Asignaciones, independientemente de cómo se hayan creado los registros. No hay ningún requisito para crear asignaciones mediante la aplicación web Workforce. Si se ha creado correctamente un registro en la capa de entidades Asignaciones con la API REST, Workforce lo reconoce como una asignación válida tanto en la aplicación web como en la aplicación móvil.

Al crear asignaciones con la API REST, utilice el comando Agregar entidades. Hay algunos campos para los que debe proporcionar valores, otros para los que puede proporcionar valores si son necesarios para la asignación y otros para los que no debe proporcionar valores.

Debe proporcionar valores para los campos siguientes:

Campo	Definición	Valor que se debe proporcionar
SHAPE	La ubicación del punto de la asignación	Cualquier par de coordenadas x,y
status	El estado de la asignación, obtenido de los valores del dominio Assign_Status.	0 (Sin asignar) para crear un trabajo sin asignar 1 (Asignado) si va a asignar el trabajo como parte de su creación Precaución: Si va a asignar el trabajo, también debe incluir valores para los campos workerId y assignedDate, que se describen más adelante en una tabla.
assignmentType	El tipo de asignación, a partir de los valores del dominio Assign_Type	Un valor válido del dominio Assign_Type
location	Descripción de texto de la ubicación del punto de la asignación	Cualquier dirección; un par de coordenadas x,y o cualquier texto descriptivo
assignmentRead	Especifica si el trabajador móvil ha visto la asignación	0 porque la asignación aparece como no leída
dispatcherId	El Id. del controlador que crea la asignación (dispatchers.OBJECTID de la capa de Controladores)	Puede ser el Id. de controlador del usuario de la organización de ArcGIS con el que está conectado o el Id. de un determinado controlador asociado al proyecto

También puede incluir valores para los siguientes campos opcionales:

Campo opcional	Definición	Valor que se debe proporcionar
description	Información sobre la asignación para el trabajador móvil	Texto para el trabajador móvil. El espacio en blanco se gestiona con el valor de línea anterior.
priority	La prioridad de la asignación	Un valor válido del dominio Prioridad.
workOrderId	Clave externa que hace referencia a una orden de trabajo de un sistema externo o de terceros	Un valor del sistema externo.
dueDate	Fecha y hora en que debe completarse la asignación	Una fecha y hora válidas, proporcionadas como tiempo en UTC en segundos de la última época. Nota: Para proporcionar una fecha de vencimiento sin una hora, especifique la fecha y utilice 11:59:59 PM como tiempo.

Si desea asignar el trabajo como parte de su creación, utilice el estado 1 (tal y como se mencionó anteriormente) y proporcione también los campos siguientes:

Campo	Definición	Valor que se debe proporcionar
workerId	El Id. del trabajador móvil al que se va a asignar la asignación (workers.OBJECTID de la capa de Trabajadores)	OBJECTID del trabajador móvil que está asignando
assignedDate	Fecha y hora en que se asignó la asignación	La fecha y hora actuales, proporcionadas como tiempo de UTC en segundos de la última época

El resto de campos de la capa Asignaciones se administran mediante la plataforma de ArcGIS, incluidos los campos que están marcados como parte de los campos de ArcGIS o del Rastreo del editor en el diagrama del esquema. No debe proporcionar ni modificar sus valores.

Asignar asignaciones mediante la API REST

En la sección anterior, vio cómo crear una asignación asignada. Aquí verá cómo asignar una asignación existente. Utilice el comando Actualizar entidades de la API REST y transfiera el conjunto de entidades que se va a actualizar. Para cada entidad, deberá proporcionar estos tres campos para asignar o reasignar una asignación:

Campo	Definición	Valor que se debe proporcionar
status	El estado de la asignación, obtenido de los valores del dominio Assign_Status.	1 (Asignada)
workerId	El Id. del trabajador móvil al que se va a asignar la asignación (workers.OBJECTID de la capa de Trabajadores)	OBJECTID del trabajador móvil que está asignando
assignedDate	Fecha y hora en que se asignó la asignación	La fecha y hora actuales, proporcionadas como tiempo de UTC en segundos de la última época
dispatcherId	El Id. del controlador que asigna la asignación, si es diferente del controlador que la ha creado (dispatchers.OBJECTID de la capa de Controladores)	Puede ser el Id. de controlador del usuario de la organización de ArcGIS con el que está conectado o el Id. de un determinado controlador asociado al proyecto