Automatiser et écrire un script Workforce

Attention :

Cette rubrique décrit l’automatisation et la rédaction de scripts pour les projets Classic Workforce qui apparaissent dans Workforce for ArcGIS. Pour plus d’informations sur la manière d’automatiser et d’écrire des projets qui sont activés pour une utilisation hors connexion apparaissant dans ArcGIS Workforce, reportez-vous à la rubrique Automatiser Workforce.

Il s’agit d’une rubrique avancée destinée aux administrateurs et propriétaires de projet qui utilisent les couches d’entités directement, par exemple, par le biais de ArcGIS API for Python ou de l’API REST.

ArcGIS Workforce vous permet de planifier, gérer et réaliser des processus pour tous les types d’activités sur le terrain. Il s’intègre à votre organisation ArcGIS avec une application web qui permet de créer et d’attribuer des tâches et une application mobile pour que les opérateurs de terrain puissent gérer leurs affectations. Une fois que le propriétaire du projet a créé et configuré un projet Workforce, les superviseurs utilisent l’application Web Workforce pour créer et attribuer des tâches. Les opérateurs de terrain consultent et accomplissent les tâches qui leur sont attribuées via Workforce et d’autres applications ArcGIS installées sur leur appareil mobile. L’intégralité du processus est optimisée par le projet Workforce, un ensemble de couches d’entités et de cartes.

L’application Web Workforce est conçue pour permettre au superviseur de créer rapidement et efficacement de nouvelles affectations de travail et de gérer les affectations existantes. Toutefois, il est possible que certaines tâches que vous souhaitez réaliser avec des affectations ne relèvent pas de l’application web. Par exemple, certaines des requêtes les plus courantes reçues pour Workforce ont trait à l’intégration avec d’autres systèmes, notamment des systèmes de gestion de bons de travail, de ressources ou de maintenance tiers, ainsi qu’à la gestion des affectations récurrentes ou répétitives.

L’utilisation de l’automatisation et des scripts avec Workforce vous permet maintenant de bénéficier de ces fonctionnalités. Vous n’êtes pas limité à l’utilisation de l’application Web pour créer des affectations. Workforce fonctionne avec le contenu de la couche d’entités des affectations, quelle que soit la manière dont les enregistrements ont été créés. Le travail peut provenir d’autres systèmes au sein d’une organisation, par exemple d’un système de gestion des ressources ou de maintenance, ou d’un système 311. Workforce peut s’intégrer avec des sources externes pour créer et mettre à jour des affectations. La couche Assignments comprend un champ workOrderId qui peut servir de clé étrangère. Il stocke un identifiant unique qui fait référence à un système externe. Le champ workOrderId est accessible dans les détails de l’affectation sous la forme ID. Les superviseurs peuvent fournir les informations, et les opérateurs de terrain peuvent les consulter.

Il est important de bien comprendre la structure des projets Workforce ainsi que le fonctionnement des champs de date et d’heure du statut de l’affectation avant de se lancer dans l’automatisation et l’écriture de scripts. Bien qu’il soit recommandé d’utiliser ArcGIS API for Python, vous pouvez également automatiser Workforce par le biais de l’API REST pour les couches d’entités. Dans la mesure où les affectations sont créées selon la même structure, Workforce est en mesure de les interpréter.

Vue d’ensemble de la structure

Un projet Workforce se compose de quatre couches d’entités et de quatre domaines de valeurs précodées avec une structure prédéfinie. Le nom de chaque couche d’entités est la combinaison d’un nom, qui décrit l’objectif de la couche d’entités, et du GUID de l’élément de projet Workforce. Par exemple, la couche des opérateurs (Workers) associée au projet avec le GUID 5dd018fcd88c4d33814cf3da9c44061e se nommerait workers_5dd018fcd88c4d33814cf3da9c44061e. Ceci garantit l’unicité de chaque couche d’entités.

Diagramme de la structure de Workforce
Remarque :

Les champs de suivi de l’éditeur sont différents dans ArcGIS Enterprise. À la place de CreationDate, Creator, EditDate et Editor, les champs created_date, created_user, last_edited_dateet last_edited_user sont visibles, respectivement.

Les quatre couches d’entités sont les suivantes :

  1. Opérateurs
    • Une couche d’entités ponctuelles contenant un enregistrement pour chaque opérateur de terrain inclus dans le projet.
    • Inclut des informations sur l’opérateur de terrain, notamment son numéro de contact et son titre de tâche.
    • Le nom d’utilisateur de l’organisation ArcGIS de l’opérateur de terrain est stocké dans le champ userId.
    • La couche effectue le suivi de la personne qui a créé et mis à jour en dernier chaque opérateur de terrain.
    • Il existe une relation clé primaire-clé étrangère (PK-FK) entre OBJECTID etAssignments.workerId. L’utilisation de la valeur OBJECTID de la couche Workers (Opérateurs) comme valeur de champ Assignments.workerId permet d’associer l’opérateur de terrain à toutes ses affectations.
    • La couche dispose des associations de domaines de valeurs précodées suivantes :
      • Le champ de statut est associé au domaine de valeurs précodées Worker_Status pour suivre le statut de l’opérateur de terrain.
  2. Affectations
    • Une couche d’entités ponctuelles contenant un enregistrement pour chaque affectation.
    • Inclut des informations sur l’affectation, notamment son statut, son emplacement et sa description.
    • La couche effectue le suivi de la personne qui a créé et mis à jour en dernier chaque affectation.
    • Les pièces jointes sont activées sur la couche d’entités.
    • La couche contient des clés étrangères pour certains champs, ce qui permet d’associer les valeurs d’une autre couche à cette couche :
      • Assignments.workerId À Workers.OBJECTID.
      • Assignments.dispatcherId À Dispatchers.OBJECTID.
      • Assignments.workOrderId peut servir de clé étrangère pour un système externe, tel qu’un système de gestion des ressources ou de maintenance, en fournissant les valeurs de l’autre système.
    • La couche dispose des associations de domaines de valeurs précodées suivantes :
      • Le champ status est associé au domaine de valeurs précodées Assign_Status pour suivre le statut de l’affectation.
      • Le champ priority est associé au domaine de valeurs précodées Priority pour gérer la priorité des affectations de travail.
      • Le champ assignmentType est associé au domaine de valeurs précodées Assign_Type pour stocker les types d’affectation du projet.
  3. Superviseurs
    • Une couche d’entités ponctuelles contenant un enregistrement pour chaque superviseur au sein du projet.
    • Inclut des informations sur le superviseur, notamment son nom et son numéro de contact.
    • Le nom d’utilisateur de l’organisation ArcGIS du superviseur est stocké dans le champ userId.
    • La couche effectue le suivi de la personne qui a créé et mis à jour en dernier chaque superviseur.
    • Il existe une relation clé primaire-clé étrangère (PK-FK) entre OBJECTID etAssignments.dispatcherId. L’utilisation de la valeur OBJECTID de la couche Dispatchers comme valeur de champ Assignments.dispatcherId permet d’associer le superviseur à toutes les affectations qu’il a attribuées.
  4. Suivi de la localisation
    • Une couche d’entités ponctuelles contenant un enregistrement pour chaque emplacement de point consigné alors que le suivi de l’emplacement est activé.
    • La couche effectue le suivi de la personne qui a créé et mis à jour en dernier chaque suivi d’emplacement.

Les quatre domaines de valeurs précodées sont les suivantes :

  1. Assign_Status- Stocke les six valeurs valides pour le statut d’une affectation.
  2. Priority- Stocke les quatre valeurs valides pour la priorité d’une affectation.
  3. Assign_Type- Stocke les types d’affectation du projet. Ce domaine de valeurs précodées est vide à la création du projet. Elle contient des valeurs une fois les types d’affectation ajoutés au cours de la configuration du projet.
  4. Worker_Status- Stocke les trois valeurs valides pour le statut de l’opérateur de terrain.

Pour les valeurs des domaines de valeurs précodées, consultez le diagramme de la structure de Workforce.

Champs de date et d’heure du statut de l’affectation

Au statut de chaque affectation, défini dans le domaine Assign_Status, correspond un champ de date et d’heure dans la couche d’entités des affectations. Ces champs contiennent les dernières date et heure auxquelles une affectation se trouvait dans l’état correspondant. Lorsqu’un statut est utilisé pour la première fois pour une affectation en particulier, le champ de date et d’heure associé est d’abord renseigné. Lorsqu’une affectation se trouve de nouveau plus tard dans le même état, le champ de date et d’heure est mis à jour avec la nouvelle date et la nouvelle heure. Par exemple, lorsqu’une affectation est d’abord attribuée, sa date d’attribution est la date et l’heure actuelles. Si elle est réattribuée trois heures plus tard, le champ assignedDate est mis à jour avec la nouvelle heure, et l’heure d’attribution d’origine est perdue.

Etat de l’affectationChamp de date et d’heure correspondant

Non attribué

CreationDate

Attribué

assignedDate

En cours

inProgressDate

Terminées

completedDate

Refusée

declinedDate

Interrompue

pausedDate

Remarque :

Aucun champ de date et d’heure n’est associé au statut Annulé. Le champ de suivi de l’éditeur EditDate permet de déterminer la date et l’heure auxquelles une affectation a été annulée, dès lors qu’aucune autre mise à jour n’a été apportée depuis l’annulation.

Pour mieux comprendre les valeurs et le moment où elles sont définies, examinez les scénarios suivants :

  • Réattribution d’une tâche déjà attribuée
    • Vous avez attribué une affectation à l’heure t1, donc la valeur de assignedDate est t1.
    • Ensuite, à l’heure t2, l’affectation a été réattribuée à un autre opérateur de terrain, donc la valeur de assignedDate est t2.
  • Réattribution d’une tâche refusée
    • Vous avez attribué une affectation à l’heure t1, donc la valeur de assignedDate est t1.
    • l’opérateur de terrain refuse l’affectation à l’heure t2, donc la valeur de declinedDate est t2. La valeur de assignedDate demeure t1.
    • Vous attribuez l’affectation à un autre opérateur de terrain à l’heure t3, donc la valeur de assignedDate est t3.
  • Interruption et reprise d’une tâche
    • Vous avez attribué une affectation à l’heure t1, donc la valeur de assignedDate est t1.
    • L’opérateur de terrain commence l’affectation à l’heure t2, donc la valeur de inProgressDate est t2. La valeur de assignedDate demeure t1.
    • l’opérateur de terrain met en pause l’affectation à l’heure t3, donc la valeur de pausedDate est t3. La valeur de assignedDate demeure t1, et la valeur de inProgressDate demeure t2.
    • L’opérateur de terrain reprend l’affectation à l’heure t4, donc la valeur de inProgressDate est t4. La valeur de assignedDate demeure t1, , et la valeur de pausedDate demeure t3.

Utiliser ArcGIS API for Python (recommandé)

Utilisez ArcGIS API for Python et son module Workforce pour automatiser Workforce et y écrire des scripts. Workforce peut interpréter les affectations créées avec le module Workforce étant donné qu’elles suivent la même structure. Pour obtenir des exemples et connaître les pratiques conseillées, consultez les exemples de scripts disponibles sur GitHub. Les scripts indiquent comment utiliser Python pour effectuer de nombreuses tâches, notamment charger des affectations par programmation à partir de sources de données externes, importer et gérer des opérateurs, supprimer des affectations terminées, etc. Vous pouvez par ailleurs utiliser cet environnement Jupyter Notebook pour voir certaines opérations typiques.

Le module Workforce est apparu dans la version ArcGIS API for Python 1.4.1. Il était possible d’utiliser Python avant l’introduction de ce module, mais ce dernier simplifie l’automatisation des tâches Workforce. Le module Workforce encapsule la structure du projet Workforce et les règles. Il comprend également des mesures de protection qui assurent l’intégrité de votre projet Workforce.

Remarque :

Vous avez des commentaires sur l’un des scripts ? Ou une idée sur un autre script dont vous souhaiteriez bénéficier ? Partagez-les sur GitHub.

Utiliser l’API REST pour les couches d’entités

Attention :

Il est recommandé d’utiliser ArcGIS API for Python. Il met en œuvre plusieurs mesures de protection qui assurent l’intégrité du projet Workforce.

Vous pouvez automatiser Workforce via l’API REST pour les couches d’entités. Lorsque vous utilisez l’API REST, vous devez utiliser le format Feature object (Objet entité) pour créer et mettre à jour les affectations. Reportez-vous aux sections suivantes pour plus d’informations sur la création et la mise à jour, ainsi que l’attribution, d’affectations via l’API REST.

Créer une affectation via l’API REST

Workforce fonctionne avec le contenu de la couche d’entités des affectations, quelle que soit la manière dont les enregistrements ont été créés. Il n’est pas nécessaire de créer des affectations via l’application Web Workforce. Si un enregistrement est créé dans la couche d’entités des affectations, Assignments, avec l’API REST, Workforce le reconnaît comme une affectation valide dans l’application Web et l’application mobile.

Lorsque vous créez des affectations avec l’API REST, utilisez la commande Add features (Ajouter des entités). Pour certains champs, vous devez fournir des valeurs, pour d’autres, vous pouvez être amené à fournir des valeurs si votre affectation le demande et pour d’autres encore, vous ne devez fournir aucune valeur.

Vous devez fournir des valeurs pour les champs suivants :

TerrainDéfinitionValeur à fournir

SHAPE

L’emplacement de point de l’affectation

Une paire de coordonnées x,y

status

Statut de l’affectation, à partir des valeurs du domaine Assign_Status

  • 0 (Non attribuée) pour créer une tâche non attribuée
  • 1 (Attribuée) si vous allez attribuer la tâche dans le cadre de sa création
Attention :

Si vous allez attribuer la tâche, vous devez également inclure des valeurs pour les champs workerId et assignedDate, décrits dans un tableau ultérieur.

assignmentType

Le type d’affectation, à partir des valeurs du domaine Assign_Type

Toute valeur valide provenant du domaine Assign_Type

location

Description textuelle de l’emplacement de point de l’affectation

Une adresse, une paire de coordonnées x,y ou un texte descriptif

assignmentRead

Indique si l’opérateur de terrain a consulté l’affectation

0 car l’affectation n’est pas lue

dispatcherId

ID du superviseur qui crée l’affectation (dispatchers.OBJECTID à partir de la couche des superviseurs)

Il peut s’agir de l’ID de superviseur associé à l’utilisateur de l’organisation ArcGIS sous le nom duquel vous êtes connecté, ou de l’ID d’un superviseur en particulier associé au projet

Vous pouvez également inclure des valeurs pour les champs facultatifs suivants :

Champ facultatifDéfinitionValeur à fournir

description

Informations destinées au à l’opérateur de terrain concernant l’affectation

Texte pour l’opérateur de terrain. L’espace (whitespace) est traité avec la valeur pre-line.

priority

La priorité de l’affectation

Une valeur valide issue du domaine Priority.

workOrderId

Une clé étrangère référençant une commande de travail émanant d’un système externe ou tiers

Une valeur issue de votre système externe.

dueDate

La date et l’heure auxquelles l’affectation doit être terminée

Une date et une heure valides, au format de temps en secondes UTC de la dernière ère.

Remarque :

Pour indiquer une date d’échéance sans préciser d’heure, spécifiez la date et utilisez 11:59:59 PM comme heure.

Si vous souhaitez attribuer le travail dès sa création, utilisez le statut 1 (comme indiqué ci-dessus) et fournissez également les champs suivants :

TerrainDéfinitionValeur à fournir

workerId

ID de l’opérateur de terrain auquel l’affectation est attribuée (workers.OBJECTID à partir de la couche des opérateurs de terrain)

OBJECTID de l’opérateur de terrain auquel vous attribuez la tâche

assignedDate

La date et l’heure d’attribution de l’affectation

La date et l’heure actuelles, au format de temps en secondes UTC de la dernière ère

Les autres champs de la couche des affectations sont gérés par la plateforme ArcGIS, notamment ceux qui sont signalés comme faisant partie des champs ArcGIS ou Editor Tracking (Suivi de l’éditeur) dans le diagramme de la structure. Vous ne devez pas fournir ou modifier leurs valeurs.

Attribuer des affectations via l’API REST

Dans la section précédente, vous avez vu comment créer une affectation attribuée. Dans celle-ci, vous allez voir comment attribuer une affectation existante. Utilisez la commande Mettre à jour les entités de l’API REST, en transmettant le tableau d’entités à mettre à jour. Pour chaque entité, vous devez indiquer ces trois champs pour attribuer ou réattribuer une affectation :

TerrainDéfinitionValeur à fournir

status

Statut de l’affectation, à partir des valeurs du domaine Assign_Status

  • 1 (Attribuée)

workerId

ID de l’opérateur de terrain auquel l’affectation est attribuée (workers.OBJECTID à partir de la couche des opérateurs de terrain)

OBJECTID de l’opérateur de terrain auquel vous attribuez la tâche

assignedDate

La date et l’heure d’attribution de l’affectation

La date et l’heure actuelles, au format de temps en secondes UTC de la dernière ère

dispatcherId

ID du superviseur qui attribue l’affectation, s’il est différent du superviseur qui l’a créé (dispatchers.OBJECTID à partir de la couche des superviseurs)

Il peut s’agir de l’ID de superviseur associé à l’utilisateur de l’organisation ArcGIS sous le nom duquel vous êtes connecté, ou de l’ID d’un superviseur en particulier associé au projet