Enregistrement des activités

L'enregistrement des activités constitue le principal flux entrant de données de l'API Mobilic.

Nous allons détailler ici les différentes opérations qui permettent de réaliser ces enregistrements.

Prérequis

Toutes les opérations explicitées ci-après nécessitent l'authentification d'un compte "activé" :

à la suite de l'inscription, l'utilisateur doit confirmer son adresse email pour activer son compte
tant que son compte n'est pas actif, les opérations ci-dessous ne seront pas disponibles

Pour en savoir plus sur le parcours utilisateur, vous pouvez consulter les notices d'utilisation des travailleurs mobiles et des gestionnaires

Pour savoir si un compte utilisateur est actif, l'opération suivante permet de récupérer les paramètres hasActivatedEmail et hasConfirmedEmail :

query user {
  user(id: XXXXX) {
    hasConfirmedEmail
    hasActivatedEmail
  }
}

Ceux-ci doivent correspondre à true.

Opérations

Récupérer les entreprises sur lesquelles un salarié peut créer une mission

Pour pouvoir récupérer les id des entreprises sur lesquelles un salarié peut renseigner du temps de travail, l'opération suivante peut être utilisée :

query user {
  user(id: XXXXX) {
    currentEmployments {
      company {
        name
        id
      }
    }
  }
}

Création d'une nouvelle mission

Avant d'enregistrer les activités il est indispensable de créer une mission à laquelle seront rattachées les activités.

L'opération de création de la mission est la suivante :

mutation {
    activities {
        createMission(name: "XXX", "companyId: YYY) {
            id
            name
        }
    }
}

Il y a deux variables, optionnelles toutes les deux :

name
companyId, qui permet de préciser l'entreprise associée à la mission dans le cas où l'auteur est rattaché à plusieurs entreprises.

Si une entreprise est donnée via companyId il faut que l'auteur y soit rattaché, soit en tant que gestionnaire soit en tant que travailleur. Dans le cas où aucune entreprise n'est précisée la mission est associée à l'entreprise de rattachement principale de l'auteur.

La création de la mission ne déclenche pas le démarrage du chrono de temps de travail : les deux moments sont séparés. Cela permet par exemple à l'exploitant de planifier et de créer à l'avance les missions dans son logiciel métier, qui pourrait ensuite les enregistrer dans l'interface dédiée aux travailleurs mobiles pour leur permettre de renseigner le temps de travail de chaque mission le moment venu.

Enregistrement d'une activité

L'enegistrement d'une activité se fait au moyen de l'opération logActivity.

C'est l'opération principale.

mutation(
  $type: ActivityTypeEnum!
  $startTime: TimeStamp!
  $endTime: TimeStamp
  $switch: Boolean
  $userId: Int
  $context: GenericScalar
  $missionId: Int!
) {
  activities {
    logActivity(
      type: $type
      startTime: $startTime
      missionId: $missionId
      endTime: $endTime
      switch: $switch
      context: $context
      userId: $userId
    ) {
      id
      type
      startTime
    }
  }
}

Elle prend en arguments :

type, la nature de la nouvelle activité (déplacement, travail, accompagnement)
startTime, l'heure de début d'activité
missionId, la mission pour laquelle est effectuée l'activité
endTime, l'heure de fin d'activité (optionnelle)
switch, indique si le mode d'enregistrement tachygraphe est activé (optionnel, par défaut oui)
userId, le travailleur mobile pour lequel enregistrer l'activité (optionnel, par défaut c'est l'utilisateur authentifié)
context, des données libres qui seront rattachées à l'activité

Par défaut l'activité est enregistrée pour l'utilisateur qui effectue l'opération (l'utilisateur authentifié avec le jeton). Afin de faciliter l'usage de l'API il est possible d'enregistrer des activités pour un autre utilisateur, en utilisant le champ userId.

Mode d'enregistrement tachygraphe

L'API Mobilic privilègie une saisie en temps réel des activités, dans laquelle les évènements de changement d'activité sont transmis à l'API. L'heure de fin d'une activité n'est déterminée qu'au moment du changement d'activité suivant.

En conséquence l'opération logActivity a deux modes de fonctionnement :

le mode "tachygraphe", correspondant au principe ci-dessus (switch: true). L'API enregistre les changements d'activité.
un mode plus classique où les activités sont saisies a posteriori avec leur heure de fin éventuelle (switch: false). L'API enregistre directement les activités.

Plus précisément le mode "tachygraphe" fonctionne de la manière suivante :

la variable startTime correspond à l'heure de changement d'activité. Au moment de l'opération l'utilisateur ne peut pas avoir d'activité enregistrée après cette heure. En d'autres termes le changement d'activité n'est possible que pendant ou après la dernière activité.
l'opération n'accepte pas d'heure de fin (endTime)
si la dernière activité de l'utilisateur n'est pas terminée l'opération met fin à la dernière activité à l'heure startTime.
l'opération crée une nouvelle activité démarrant à startTime et sans date de fin.

Par opposition le mode d'enregistrement classique se contente de créer une nouvelle période d'activité pour l'utilisateur, en vérifiant simplement qu'il n'y a pas de chevauchement avec son historique. Il peut notamment être utilisé pour intercaler une nouvelle activité parmi les activités passées (ce que le mode tachygraphe ne permet pas de faire).

Mise à jour d'une activité

L'opération de correction ou de modification d'une activité est editActivity. Seule la période d'une activité est modifiable (pas le type de travail, ni la mission ni le travailleur concernés)

mutation(
  $activityId: Int!
  $startTime: TimeStamp
  $endTime: TimeStamp
  $removeEndTime: Boolean
  $context
) {
  activities {
    editActivity(
      activityId: $activityId
      startTime: $startTime
      endTime: $endTime
      removeEndTime: $removeEndTime
      context: $context
    ) {
      id
      type
      startTime
    }
  }
}

Elle prend en arguments :

activityId, l'identifiant de l'activité à modifier
startTime, la nouvelle heure de début (optionnelle, si elle a été modifiée)
endTime, la nouvelle heure de fin (optionnelle, si elle a été modifiée)
removeEndTime, indique si la fin de l'activité doit être annulée (optionnel et incompatible avec endTime). Utile si l'activité a été terminée par erreur.
context, des données libres qui seront rattachées à l'évènement de modification.

Annulation d'une activité

L'opération d'annulation d'une activité est cancelActivity. Elle permet de supprimer l'activité de l'historique de l'utilisateur.

mutation(
  $activityId: Int!
  $context
) {
  activities {
    cancelActivity(
      activityId: $activityId
      context: $context
    ) {
       success
    }
  }
}

Fin de mission

L'opération signale la fin de la mission pour le travailleur mobile.

mutation(
  $missionId: Int!
  $endTime: TimeStamp!
  $userId: Int
  $context: GenericScalar
) {
  activities {
    endMission(
      missionId: $missionId
      endTime: $endTime
      userId: $userId
      context: $context
    ) {
      id
      name
    }
  }
}

Les arguments de l'opération ont la même fonction que pour l'enregistrement d'une activité. Dans le cas où la dernière activité de l'utilisateur n'est pas terminée l'opération y met fin à l'heure endTime.

Création d'une absence

La création d'une absence est plus simple grace à l'opération logHoliday. Elle permet de créer une mission avec une activité de type OFF et de la valider en un seul appel.

mutation (
    $companyId: Int!
    $userId: Int
    $startTime: TimeStamp!
    $endTime: TimeStamp!
    $title: String!
) {
    activities{
        logHoliday(
            companyId: $companyId
            userId: $userId
            startTime: $startTime
            endTime: $endTime
            title: $title
        ) {
            id
        }
    }
}

Elle prend en arguments :

comment, le motif de l'absence (optionel)
companyId, l'identifiant de l'entreprise pour laquelle l'absence est enregistrée
endTime, l'heure de fin de l'absence
startTime, l'heure de début de l'absence
title, l'intitulé de l'absence
userId, l'identifiant du salarié concerné par l'absence (optionnel, par défaut c'est l'auteur de l'opération)

Exemples

Nous allons illustrer l'utilisation et le rôle des opérations précédentes à travers l'exemple d'une journée de travail classique.

Début de journée

La première action à effectuer consiste à créer une mission.

mutation {
  activities {
    createMission(name: "Journée test", companyId: 1) {
      id
      name
    }
  }
}

Réponse

{
  "data": {
    "activities": {
      "createMission": {
        "id": 18,
        "name": "Journée test"
      }
    }
  }
}

Lieu de début de mission

Une fois la mission créée, on peut renseigner le lieu de début de mission, et le kilométrage du véhicule.

Ces informations sont obligatoires.

mutation {
  activities {
    logLocation(missionId: 18, type: "mission_start_location", manualAddress: "10 avenue de la République 75011", kilometerReading: 5500) {
      id
      name
    }
  }
}

Pour plus d'information sur le renseignement des lieux d'une mission, se référer à la page suivante :

pageEnregistrement des lieux de début et de fin de mission

Première activité

On peut ensuite enregistrer le démarrage de la première activité de la mission.

mutation {
  activities {
    # 9h00
    logActivity(missionId: 18, type: "drive", startTime: 1577869200) {
      id
      type
      startTime
      endTime
    }
  }
}

Réponse

{
  "data": {
    "activities": {
      "logActivity": {
        "id": 193,
        "type": "drive",
        "startTime": 1577869200,
        "endTime": null
      }
    }
  }
}

En mode tachygraphe l'activité n'a pas d'heure de fin au moment de son enregistrement. Tant que l'API ne reçoit pas un nouvel évènement de changement ou de fin d'activité le chronomètre continue de tourner.

Deuxième activité

L'enregistrement du changement d'activité se fait de manière identique à l'enregistrement précédent, c'est-à-dire en mode tachygraphe.

mutation {
  activities {
    # 11h00
    logActivity(missionId: 18, type: "work", startTime: 1577876400) {
      id
      type
      startTime
      endTime
    }
  }
}

Réponse

{
  "data": {
    "activities": {
      "logActivity": {
        "id": 194,
        "type": "work",
        "startTime": 1577876400,
        "endTime": null
      }
    }
  }
}

Le changement d'activité a créé une nouvelle activité débutant à 11h (et sans heure de fin) et a mis fin à l'activité précédente à cette même heure.

Pause

Pour indiquer la fin d'une activité sans démarrage immédiat d'une autre activité, il suffit d'éditer la date de fin de l'activité.

mutation {
  activities {
    # 12h30
    editActivity(activityId: 194, endTime: 1577881800) {
      id
      type
      startTime
      endTime
    }
  }
}

Réponse

{
  "data": {
    "activities": {
      "editActivity": {
        "id": 194,
        "type": "work",
        "startTime": 1577876400,
        "endTime": 1577881800
      }
    }
  }
}

Fin de journée

Troisième activité

Une fois la pause terminée l'enregistrement des activités peut reprendre, toujours en mode tachygraphe.

mutation {
  activities {
    # 14h00
    logActivity(missionId: 18, type: "work", startTime: 1577887200) {
      id
      type
      startTime
      endTime
    }
  }
}

Réponse

{
  "data": {
    "activities": {
      "logActivity": {
        "id": 195,
        "type": "work",
        "startTime": 1577887200,
        "endTime": null
      }
    }
  }
}

Lors du décompte du temps de travail sur la journée, les périodes de creux entre deux activités seront automatiquement décomptées comme du temps de pause.

Quatrième activité

mutation {
  activities {
    # 15h30
    logActivity(missionId: 18, type: "drive", startTime: 1577892600) {
      id
      type
      startTime
      endTime
    }
  }
}

Réponse

{
  "data": {
    "activities": {
      "logActivity": {
        "id": 196,
        "type": "drive",
        "startTime": 1577892600,
        "endTime": null
      }
    }
  }
}

Lieu de fin de mission

On termine la journée en renseignant le lieu de fin de mission, et le nouveau kilométrage du véhicule.

Ces informations sont obligatoires.

mutation {
  activities {
    logLocation(missionId: 18, type: "mission_end_location", manualAddress: "25 avenue de la République 75011", kilometerReading: 5550) {
      id
      name
    }
  }
}

Pour plus d'information sur le renseignement des lieux d'une mission, se référer à la page suivante :

pageEnregistrement des lieux de début et de fin de mission

Fin de mission

Pour terminer la mission il suffit d'effectuer l'opération endMission en passant la date de fin de l'activité en cours.

mutation {
  activities {
    # 17h
    endMission(missionId: 18, endTime: 1577898000) {
      id
    }
  }
}

Réponse

{
  "data": {
    "activities": {
      "endMission": {
        "id": 18
      }
    }
  }
}

Corrections éventuelles

Le travailleur mobile s'aperçoit de quelques erreurs et oublis dans sa saisie intiale.

Oubli de redémarrer après la pause

La vraie heure de reprise d'activité après la pause du midi est 13h30 mais l'utilisateur n'a enregistré la reprise qu'à 14h. Pour corriger cela il lui suffit d'indiquer que l'activité de reprise a en fait démarré une demi-heure plus tôt.

mutation {
  activities {
    # 13h30
    editActivity(activityId: 195, startTime: 1577885400) {
      id
      type
      startTime
      endTime
    }
  }
}

Réponse

{
  "data": {
    "activities": {
      "editActivity": {
        "id": 195,
        "type": "work",
        "startTime": 1577885400,
        "endTime": 1577892600
      }
    }
  }
}

Correction de la fin d'une activité

Le travailleur mobile a signalé trop tôt la fin de mission. Il souhaite décaler la date de fin de 17h à 17h30.

mutation {
  activities {
    # 17h30
    editActivity(activityId: 196, endTime: 1577899800) {
      id
      type
      startTime
      endTime
    }
  }
}

Réponse

{
  "data": {
    "activities": {
      "editActivity": {
        "id": 196,
        "type": "work",
        "startTime": 1577892600,
        "endTime": 1577899800
      }
    }
  }
}

Rajout d'une activité a posteriori

Le travailleur mobile souhaite ajouter une activité qui s'est déroulée de 8h à 9h. Il lui suffit d'enregistrer une activité en mode classique.

mutation {
  activities {
    # 8h - 9h
    logActivity(
      missionId: 18
      type: "work"
      startTime: 1577865600
      endTime: 1577869200
      switch: false
    ) {
      id
      type
      startTime
      endTime
    }
  }
}

Réponse

{
  "data": {
    "activities": {
      "logActivity": {
        "id": 197,
        "type": "work",
        "startTime": 1577865600,
        "endTime": 1577869200
      }
    }
  }
}

Validation de la mission

Pour valider la mission il suffit d'effectuer l'opération validateMission.

mutation {
  activities {
    validateMission(missionId: 18, usersIds: [1577898000]) {
      id
    }
  }
}

Réponse

{
  "data": {
    "activities": {
      "validateMission": {
        "id": 18
      }
    }
  }
}

PrécédentUtiliser la console SuivantEnregistrement des lieux de début et de fin de mission

Dernière mise à jour il y a 1 mois