Automatisation et écriture de scripts avec ArcGIS Workforce

Attention :

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, via ArcGIS API for Python ou ArcGIS REST API.

Remarque :

Les projets Classic présentent une structure différente de celle décrite ci-après. Pour savoir comment automatiser des projets Workforce Classic et y écrire des scripts, reportez-vous à la rubrique Automatiser Workforce et y créer des scripts (Classic). Pour migrer des projets Classic vers une nouvelle structure, reportez-vous à la sous-rubrique Migrer des projets Classic.

Pour plus d’informations, reportez-vous à la rubrique Qu’est-ce qu’un projet Classic ?.

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 à l’aide de 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 permet à un superviseur de créer des affectations de travail, et de gérer les affectations existantes, rapidement et efficacement. 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 portent sur l’intégration avec d’autres systèmes, notamment des systèmes de gestion de bons de travail, de ressources ou de maintenance tiers, et sur la gestion des affectations récurrentes ou répétitives.

L’utilisation de l’automatisation et des scripts avec Workforce vous permet 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 avec ArcGIS REST API pour les couches d’entités.

Vue d’ensemble de la structure

Un projet Workforce se compose de deux couches d’entités, de trois tables et de trois domaines de valeurs précodées, au sein d’un seul service d’entités. Le service d’entités Workforce est généré automatiquement au moment où le projet est créé avec un dossier, un groupe, ainsi que les cartes Web des superviseurs et des opérateurs. Le service d’entités présente une relation avec des éléments des deux cartes Web et figure dans une structure prédéfinie illustrée ci-dessous.

Remarque :

Certains noms de champ sont différents dans ArcGIS Enterprise. À la place de OBJECTID, GlobalID, CreationDate, Creator, EditDateet Editor, il s’agit de objectid, globalid, created_date, created_user, last_edited_dateet last_edited_user, respectivement.

Service d’entités Workforce

Le service d’entités Workforce comporte les couches et les tables suivantes :

• Couche Workers
  • 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 GlobalID etAssignments.workerid. L’utilisation de la valeur GlobalID 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 status est associé au domaine de valeurs précodéesWorker_Status pour suivre le statut de l’opérateur de terrain.
• Couche Assignments
  • 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.GlobalID.
    • Assignments.dispatcherid À Dispatchers.GlobalID.
    • 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.
    • Il existe une relation clé primaire-clé étrangère (PK-FK) entre GlobalID etAssignment.assignmenttype. L’utilisation de la valeur GlobalID de la couche Assignments comme valeur de champ Assignments.assignmenttype permet d’associer l’affectation au type d’affectation.
  • 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.

  Attention :

  Si la géométrie d’une affectation comporte une valeur null, elle n’apparaît pas dans Workforce.

• Table Dispatchers
  • Une table contenant un enregistrement pour chaque superviseur 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 GlobalID etAssignments.dispatcherid. L’utilisation de la valeur GlobalID de la table Dispatchers comme valeur de champ Assignments.dispatcherid permet d’associer le superviseur à toutes les affectations qu’il a attribuées.
• Table Assignment Types
  • Une table contenant un enregistrement pour chaque type d’affectation du projet.
  • Cette table est vide lorsque le projet est créé. Elle contient des valeurs une fois les types d’affectation ajoutés au cours de la configuration du projet.
  • Elle inclut les descriptions des types d’affectation spécifiés par le propriétaire de projet lors de l’ajout des types d’affectation.
  • Il existe une relation clé primaire-clé étrangère (PK-FK) entre GlobalID et Assignments.assignmenttype. L’utilisation de la valeur de champ GlobalID de la table Assignment Types permet d’associer le type d’affectation aux affectations.
• Table Assignment Integrations
  • Une table contenant un enregistrement pour chaque intégration d’affectation du projet.
  • Cette table comprend un enregistrement pour l’intégration avec ArcGIS Navigator au moment de sa création.
  • La table Assignment Integrations contient les attributs définis par l’utilisateur suivants, qui viennent s’ajouter aux attributs standard définis par l’utilisateur :
    • app- Identifiant pour l’application intégrée. Il est utile pour rechercher les configurations des intégrations nécessaires pour renseigner l’expérience de configuration dans l’application Web (par exemple, arcgis-collector ou https://collector.arcgis.app)
    • assignmenttypeGlobalID d’un type d’affectation si l’intégration doit être affichée uniquement pour certains types d’affectation. La valeur null indique que l’intégration prend en charge tous les types d’affectation du projet.
    • prompt- Invite affichée sur l’appareil du client mobile (par exemple, Accéder à l’affectation).
    • urltemplate- URL de modèle utilisée pour appeler l’application intégrée.
  • Pour rechercher les intégrations qui s’appliquent à une affectation particulière, utilisez l’une des clauses where suivantes : assignmenttype = null ou assignmenttype = '<assignment-type-id>'. Ces clauses permettent de trouver toutes les intégrations au niveau du projet et au niveau du type, pour le type de l’affectation actuelle.
  • Pour rechercher les intégrations qui s’appliquent à un projet, lancez une requête selon l’application à l’aide d’une clause where telle que appid = 'arcgis-collector'.

Les trois domaines de valeurs précodées sont les suivants :

• Assign_Status- Stocke les sept valeurs valides pour le statut d’une affectation. Les valeurs comprises entre 0 et 20 sont réservées à une utilisation ultérieure par Workforce. Les clients qui souhaitent stocker leurs valeurs dans ce champ doivent opter pour une valeur comprise en dehors de cette plage.
• Priority- Stocke les quatre valeurs valides pour la priorité d’une affectation.
• 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.

Relation des éléments des cartes Web

La relation des éléments entre le service d’entités Workforce et les cartes Web des superviseurs et opérateurs de terrain se définit comme suit :

• Type de relation - WorkforceMap2FeatureService
• Type d’origine - Carte Web
• Type de destination - Service d’entités
• Règles
  • mustOwnAllItems - Le propriétaire de projet établit la relation et doit détenir la carte associée.

Lorsqu’il existe une relation entre les éléments d’une carte Web et le service d’entités Workforce, les informations suivantes sont ajoutées aux métadonnées de la carte :

• title - Intitulé du projet.
• snippet - Brève description du projet.
• thumbnail - Miniature du projet.
• typeKeywords - Workforce Worker est ajouté à la carte des opérateurs et Workforce Dispatcher à la carte des superviseurs.

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 particulière, le champ de date et d’heure associé est renseigné. Lorsqu’une affectation présente plus tard le même statut, 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 supprimée.

Si le champ inprogressdate, declineddate ou pauseddate est renseigné lorsque l’affectation est réattribuée, il est défini sur null.

Etat de l’affectation	Champ 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 editdate de suivi de l’éditeur 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. La valeur de declineddate est maintenant null.
• 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.
• Réattribution d’une tâche interrompue
  • 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.
  • Vous attribuez l’affectation à un autre opérateur de terrain à l’heure t4, donc la valeur de assigneddate est t4. Les valeurs de inprogressDate et de pauseddate sont à présent null.

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 script du référentiel de scripts de Workforce 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 également consulter le notebook Jupyter Managing ArcGIS Workforce projects pour voir certaines opérations typiques. Pour prendre en main le module Workforce, vous devez d’abord installer et configurer ArcGIS API for Python.

Remarque :

Pour automatiser des projets Workforce, vous devez utiliser ArcGIS API for Python 1.8.3 ou version ultérieure.

Prendre en main le module Workforce

Le module Workforce vous permet de créer des projets Classic ainsi que des projets utilisables en mode hors connexion. Pour créer des projets avec le module Workforce, procédez comme suit :

1. Connectez-vous à ArcGIS Online en exécutant la commande suivante dans un script Python ou depuis une console Python :
   gis = arcgis.gis.GIS("https://arcgis.com", "<username>", "<password>")

2. Pour créer un projet Classic ou un projet utilisable en mode hors connexion, exécutez l’une des commandes suivantes :

   Créer un projet Classic

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

   Créer un projet utilisable en mode hors connexion

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

Pour plus d’informations sur l’utilisation du module WorkforceWorkforce afin de modifier des affectations, des types d’affectation, des opérateurs, des superviseurs et des intégrations d’applications, consultez la documentation ArcGIS API for Python du module Workforce.

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

Attention :

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

Vous pouvez automatiser Workforce en utilisant ArcGIS REST API pour les couches d’entités. Avec ArcGIS REST API, vous devez utiliser le format Objet entité pour créer et mettre à jour les affectations. Reportez-vous aux sections ci-après pour plus d’informations sur la création et la mise à jour et l’attribution d’affectations à l’aide de ArcGIS REST API.

Créer une affectation avec ArcGIS REST API

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 ArcGIS REST API, Workforce le reconnaît comme une affectation valide dans l’application Web et dans l’application mobile.

Lorsque vous créez des affectations avec ArcGIS REST API, utilisez la commande Add Features (Ajouter des entités). Pour certains champs, vous devez indiquer des valeurs. Pour d’autres, vous pouvez indiquer des valeurs s’il s’agit d’une condition de votre affectation. Certains champs ne doivent contenir aucune valeur.

Les champs décrits dans le tableau suivant doivent impérativement contenir des valeurs :

Terrain	Définition	Valeur à fournir
SHAPE	Emplacement de point de l’affectation.	Paire de coordonnées x,y.
status	Statut de l’affectation, obtenu à partir des valeurs du domaine assign_status.	0 (Non attribuée) - Créer une tâche non attribuée. 1 (Attribuée) - Attribuer la tâche dans le cadre de sa création. Attention : Si vous attribuez la tâche, vous devez inclure des valeurs pour les champs workerid et assigneddate, décrits ci-après.
assignmenttype	Type de l’affectation, obtenu à partir des valeurs du champ GlobalID de la table des types d’affectation.	Valeur GlobalID valide provenant de la table des types d’affectation.
location	Description textuelle de l’emplacement de point de l’affectation.	Adresse, paire de coordonnées x,y ou texte descriptif.
dispatcherid	ID du superviseur qui crée l’affectation, obtenu à partir des valeurs du champ GlobalID de la table des superviseurs.	Valeur GlobalID valide pour un superviseur spécifique associé au projet.

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

Terrain	Définition	Valeur à fournir
description	Informations concernant l’affectation, destinées à l’opérateur de terrain.	Texte pour l’opérateur de terrain. L’espace (whitespace) est traité avec la valeur pre-line.
priority	Priorité de l’affectation.	Valeur valide provenant du domaine Priority.
workorderid	Clé étrangère référençant un bon de travail provenant d’un système externe ou tiers.	Une valeur issue de votre système externe.
duedate	Date et 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.

Pour attribuer la tâche dès sa création, utilisez le statut 1 (comme indiqué ci-dessus) et renseignez également les champs suivants :

Terrain	Définition	Valeur à fournir
workerid	ID de l’opérateur de terrain auquel l’affectation est attribuée, obtenu à partir des valeurs du champ GlobalID de la table des opérateurs.	Valeur GlobalID valide de l’opérateur de terrain auquel vous attribuez la tâche.
assigneddate	Date et heure d’attribution de l’affectation.	Date et heure actuelles, au format de temps en secondes UTC de la dernière ère.

Les autres champs de la couche Assignments 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. Veillez à ne pas indiquer ni modifier ces valeurs.

Attribuer des affectations avec ArcGIS REST API

Dans la section précédente, vous avez appris à créer une affectation attribuée. À présent, vous allez apprendre à attribuer une affectation existante. Utilisez la commande ArcGIS REST API Update Features (Mettre à jour les entités), en transmettant la matrice des entités à mettre à jour. Pour chaque entité, vous devez renseigner ces trois champs pour attribuer ou réattribuer une affectation :

Terrain	Définition	Valeur à fournir
status	Statut de l’affectation, obtenu à partir des valeurs du domaine Assign_Status.	1 (Attribuée)
workerid	ID de l’opérateur de terrain auquel l’affectation est attribuée, obtenu à partir des valeurs du champ GlobalID de la table des opérateurs.	Valeur GlobalID valide de l’opérateur de terrain auquel vous attribuez la tâche.
assigneddate	Date et heure d’attribution de l’affectation.	Date et heure actuelles, au format de temps en secondes UTC de la dernière ère.
dispatcherid	ID du superviseur qui attribue l’affectation, obtenu à partir des valeurs du champ GlobalID de la table Dispatchers.	Valeur GlobalID valide pour un superviseur spécifique associé au projet.