Automatización y creación de scripts con ArcGIS Workforce

Precaución:

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 API REST de ArcGIS.

Nota:

Los proyectos Classic tienen un esquema diferente al que se describe a continuación. Para obtener información sobre cómo automatizar y crear scripts de proyectos Classic de Workforce, consulte Automatizar y utilizar scripts en Workforce (Classic). Para migrar proyectos Classic al nuevo esquema, consulte Migrar proyectos Classic.

Para obtener más información, consulte ¿Qué es un proyecto Classic?.

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 Workforce permite a un controlador crear de forma rápida y eficaz asignaciones de trabajo y 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 la gestión de asignaciones recurrentes o repetitivas.

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 incluye 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 empleando API REST de ArcGIS para capas de entidades.

Descripción general del esquema

Un proyecto de Workforce se compone de dos capas de entidades, tres tablas y tres dominios de valor codificado dentro de un solo servicio de entidades. El servicio de entidades de Workforce se genera automáticamente en el momento en que se crea el proyecto, junto con una carpeta, un grupo y los mapas web del controlador y el trabajador. El servicio de entidades tiene una relación de elemento con los dos mapas web y está en un esquema predefinido, que se muestra a continuación.

Nota:

Ciertos nombres de campo son diferentes en ArcGIS Enterprise. En lugar de OBJECTID, GlobalID, CreationDate, Creator, EditDate y Editor, se trata de objectid, globalid, created_date, created_user, last_edited_date y last_edited_user, respectivamente.

Servicio de entidades de Workforce

El servicio de entidades de Workforce contiene las siguientes capas y tablas:

• Capa 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 GlobalID aAssignments.workerid. Al utilizar el valor de GlobalID 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 status está asociado al dominio de valor codificadoWorker_Status para realizar el seguimiento del estado del trabajador móvil.
• Capa 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.GlobalID.
    • Assignments.dispatcherid aDispatchers.GlobalID.
    • 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.
    • Existe una relación PK-FK de GlobalID aAssignment.assignmenttype. Al utilizar el valor de GlobalID de la capa Asignaciones como valor del campoAssignments.assignmenttype , se asocia la asignación al tipo de asignación.
  • 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.

  Precaución:

  Si una asignación tiene un valor null para su geometría, no aparecerá en Workforce.

• Tabla Controladores
  • Una tabla que contiene un registro de cada controlador del 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 GlobalID a Assignments.dispatcherid. Al utilizar el valor GlobalID de la tabla Controladores como valor del campo Assignments.dispatcherid , se asocia al controlador con todas las asignaciones que ha asignado.
• Tabla Tipos de asignación
  • Una tabla que contiene un registro de cada tipo de asignación del proyecto.
  • Esta tabla está vacía al crear el proyecto. Contendrá valores una vez que se agreguen tipos de asignación durante la configuración del proyecto.
  • Incluye las descripciones de los tipos de asignación especificados por el propietario del proyecto cuando se agregaron los tipos de asignación.
  • Existe una relación PK-FK de GlobalID a Assignments.assignmenttype. El uso del valor del campo GlobalID de la tabla Tipos de asignación asocia el tipo de asignación con asignaciones.
• Tabla Integraciones de asignaciones
  • Una tabla que contiene un registro de cada integración de asignaciones del proyecto.
  • Esta tabla contiene un registro para la integración con ArcGIS Navigator cuando se crea.
  • La tabla Integraciones de asignaciones contiene los siguientes atributos definidos por el usuario, además de los atributos estándar definidos por el sistema:
    • app— Un identificador para la aplicación integrada que ayudará a encontrar las configuraciones de integración necesarias para completar la experiencia de configuración en la aplicación web, por ejemplo, arcgis-collector o https://collector.arcgis.app.
    • assignmenttype— El GlobalID de un tipo de asignación si la integración solo se debe mostrar para ciertos tipos de asignación. Un valor de null indica que la integración admite todos los tipos de asignación del proyecto.
    • prompt— El mensaje mostrado en el cliente móvil, por ejemplo, Navegar a la asignación.
    • urltemplate— La URL de la plantilla que se utiliza para invocar la aplicación integrada.
  • Para encontrar las integraciones que se aplican a una asignación en particular, utilice una de las siguientes cláusulas WHERE: assignmenttype = null o assignmenttype = '<assignment-type-id>'. Estas encuentran todas las integraciones a nivel de proyecto y todas las integraciones a nivel de tipo para el tipo de asignación actual.
  • Para encontrar las integraciones aplicables a un proyecto, consulte la aplicación utilizando una cláusula WHERE, por ejemplo, appid = 'arcgis-collector'.

Los tres dominios de valor codificado son los siguientes:

• Assign_Status— Almacena los siete valores válidos para el estado de una asignación. Los valores del 0 al 20 están reservados para su uso futuro por Workforce. Los clientes que deseen almacenar sus propios valores en este campo deben elegir un valor fuera de ese rango.
• Priority— Almacena los cuatro valores válidos para la prioridad de una asignación.
• 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.

Relación de elemento del mapa web

La relación de elemento entre el servicio de entidades de Workforce y los mapas web del trabajador y el controlador tiene la siguiente definición:

• Tipo de relación: WorkforceMap2FeatureService
• Tipo de origen: mapa web
• Tipo de destino: servicio de entidades
• Reglas
  • mustOwnAllItems: el propietario de proyecto determina la relación y el mapa relacionado debe ser de su propiedad.

Cuando un mapa web tiene una relación de elemento con el servicio de entidades de Workforce, se agrega la siguiente información a sus metadatos:

• title: el título del proyecto.
• snippet: una breve descripción del proyecto.
• thumbnail: la vista en miniatura del proyecto.
• typeKeywords: Workforce Worker se agrega al Mapa del trabajador y Workforce Dispatcher se agrega al Mapa del controlador.

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 en 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. 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 elimina.

Si los campos inprogressdate, declineddate o pauseddate se rellenan al reasignar una asignación, se establecen en null.

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 Rastreo del editor de editdate 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. El valor de declineddate es ahora null.
• 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 valor de inProgressDatesigue 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 valor de pauseddate sigue siendo t3.
• Reasignar trabajo en pausa
  • 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 valor de inprogressdatesigue siendo t2.
  • Asigna la asignación a otro trabajador móvil a la hora t4, por lo tanto, el valor de assigneddate es t4. Los valores de inprogressDate y pauseddate son ahora null.

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 el repositorio de scripts deWorkforce 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 la Administración ArcGIS Workforce de proyectos Jupyter notebook para ver operaciones típicas. Para comenzar con el módulo de Workforce, primero debe instalar y configurar ArcGIS API for Python.

Nota:

Para automatizar proyectos de Workforce, debe usar ArcGIS API for Python 1.8.3 o posterior.

Introducción al módulo de Workforce

El módulo de Workforce permite crear proyectos Classic y proyectos habilitados para el uso sin conexión. Cree proyectos con el módulo de Workforce siguiendo estos pasos:

1. Inicie sesión en ArcGIS Online ejecutando el siguiente comando en un script de Python o en una consola de Python:
   gis = arcgis.gis.GIS("https://arcgis.com", "<username>", "<password>")

2. Cree un proyecto Classic o un proyecto que esté habilitado para el uso sin conexión ejecutando uno de los siguientes comandos:

   Crear un proyecto Classic

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

   Crear un proyecto habilitado para el uso sin conexión

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

Para obtener información sobre cómo utilizar el módulo de Workforce para modificar asignaciones, tipos de asignaciones, trabajadores, controladores e integraciones de aplicaciones, consulte la documentación de ArcGIS API for Python correspondiente al módulo de Workforce.

Utilizar API REST de ArcGIS para capas de entidades

Precaución:

Se recomienda utilizar ArcGIS API for Python. Incluye varios métodos de protección que salvaguardan la integridad de su proyecto de Workforce.

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

Crear una asignación con API REST de ArcGIS

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 API REST de ArcGIS, 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 API REST de ArcGIS, utilice el comando Agregar entidades. Algunos campos requieren valores, puede proporcionar valores para otros campos si su asignación los requiere y algunos campos no pueden contener valores.

Los campos descritos en la siguiente tabla requieren valores:

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 a partir de los valores del dominio assign_status.	0 (No asignada): cree un trabajo sin asignar. 1 (Asignada): asigne el trabajo como parte de su creación. Precaución: Si va a asignar el trabajo, debe incluir valores para los campos workerid y assigneddate , descritos a continuación.
assignmenttype	El tipo de asignación, obtenido a partir de los valores de GlobalID en la tabla Tipos de asignación.	Un valor de GlobalID válido de la tabla Tipos de asignación.
location	Descripción de texto de la ubicación del punto de la asignación.	Una dirección, un par de coordenadas x,y o cualquier texto descriptivo.
dispatcherid	El Id. del controlador que crea la asignación, obtenido a partir de los valores de GlobalID de la tabla Controladores.	Un valor de GlobalID válido para un controlador en particular asociado con el proyecto.

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

Campo	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 Priority.
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.

Para 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, obtenido de los valores de GlobalID en la capa Trabajadores.	Un valor de GlobalID válido del trabajador móvil que está asignando.
assigneddate	Fecha y hora en que se realizó la asignación.	La fecha y hora actuales, proporcionadas como hora UTC en segundos de la última época.

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

Realizar asignaciones con API REST de ArcGIS

En la sección anterior, aprendió a crear una asignación asignada. Ahora, aprenderá a asignar una asignación existente. Utilice el comando API REST de ArcGIS Actualizar entidades y transfiera el conjunto de entidades que se va a actualizar. Para cada entidad, debe 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 a partir 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, obtenido de los valores de GlobalID en la capa Trabajadores.	El valor de GlobalID del trabajador móvil que está asignando.
assigneddate	Fecha y hora en que se realizó la asignación.	La fecha y hora actuales, proporcionadas como hora UTC en segundos de la última época.
dispatcherid	El Id. del controlador que realiza la asignación, obtenido a partir de los valores de GlobalID de la tabla Controladores.	Un valor de GlobalID válido para un controlador en particular asociado con el proyecto.