Activity recording

Activity recording is the main incoming data stream of the Mobilic API.

We will detail here the different operations that allow these records to be made.

Prerequisite

All operations below requires to be authenticated with an "activated" account :

• after signing in, the user needs to confirm the email address to activate the account

• while the user account is not actived, the operations won't be available

To know if the user account is activated, you can retrieve hasActivatedEmail and hasConfirmedEmail with this operation :

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

They must be equal totrue.

Operations

Creation of a new mission

Before recording the activities, it is necessary to create a mission to which the activities will be attached. The operation for creating the mission is as follows :

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

There are two variables, both optional:

• name

• companyId, which makes it possible to specify the company associated with the assignment in the case where the author is attached to several companies.

If a company is given via companyId, the author must be attached to it, either as a manager or as a worker. If no company is specified, the mission is associated with the author's main company.

The creation of the mission does not trigger the start of the working time clock : the two moments are separated. This allows the operator, for example, to plan and create missions in advance in their business software, which could then be recorded in the mobile worker interface to allow them to enter the working time for each mission at the appropriate time.

Recording an activity

The registration of an activity is done by means of the operation logActivity.

This is the main operation.

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
    }
  }
}

It takes into arguments :

• type, the nature of the new activity (travelling, working, accompanying)

• startTime, the start time of the activity

• missionId, the mission for which the activity is carried out

• endTime, the end time of the activity (optional)

• switch, indicates whether the tachograph recording mode is activated (optional, default is yes)

• userId, the mobile worker for whom to record the activity (optional, default is the authenticated user)

• context, free data that will be linked to the activity

By default the activity is recorded for the user who performs the operation (the user authenticated with the token). In order to facilitate the use of the API it is possible to record activities for another user, using the userId field.

Tachograph recording mode

The Mobilic API favours a real-time input of activities, in which activity change events are transmitted to the API. The end time of an activity is not determined until the next activity change.

Consequently, the logActivity operation has two modes of operation:

• the "tachograph" mode, corresponding to the above principle (switch: true). The API records activity changes.

• a more classical mode where activities are entered after the action with their possible end time (switch: false). The API records the activities directly.

More precisely, the "tachograph" mode works as follows :

• the startTime variable corresponds to the time of the activity change. At the time of the operation the user cannot have any activity recorded after this time. In other words, the change of activity is only possible during or after the last activity.

• the operation does not accept an end time (endTime)

• if the user's last activity is not finished the operation terminates the last activity at the startTime.

• the operation creates a new activity starting at startTime and without an end time.

In contrast, the classic recording mode simply creates a new period of activity for the user, checking only that there is no overlap with their history. In particular, it can be used to insert a new activity among past activities (which the tachograph mode does not allow).

Updating an activity

The operation to correct or modify an activity is editActivity. Only the time period of an activity can be modified (not the type of work, nor the mission nor the worker concerned).

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
    }
  }
}

It takes into argument :

• activityId, the identifier of the activity to be modified

• startTime, the new start time (optional, if it has been changed)

• endTime, the new end time (optional, if it has been changed)e)

• removeEndTime, indicates whether the end of the activity should be cancelled (optional and incompatible with endTime). Useful if the activity was terminated by mistake.

• context, free data that will be attached to the modification event.

Cancelling an activity

The operation to cancel an activity is cancelActivity. It removes the activity from the user's history.

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

End of mission

The operation signals the end of the mission for the mobile worker.

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

The arguments of the operation have the same function as for recording an activity. In case the last user activity is not completed the operation terminates it at the endTime.

Examples

We will illustrate the use and role of the above operations through the example of a typical working day.

Start of the day

The first action to perform is to create a mission.

mutation {
  activities {
    createMission(name: "test day", companyId: 1, vehicleRegistrationNumber: "ER-1844-SV") {
      id
      name
    }
  }
}

Response

{
  "data": {
    "activities": {
      "createMission": {
        "id": 18,
        "name": "test day"
      }
    }
  }
}

Start Location

Once the mission is created and the vehicle specified, you can log the location of the start of the mission, and the vehicle mileage.

These information are mandatory.

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

See page below for more information about logging a location

pageLocation recording

First activity

The start of the first activity of the mission can then be recorded.

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

Response

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

In tachograph mode the activity does not have an end time when it is recorded. As long as the API does not receive a new activity change or end event the stopwatch continues to run.

Second activity

The recording of the change of activity is done in the same way as the previous recording, i.e. in tachograph mode.

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

Response

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

The change of activity created a new activity starting at 11:00 (and with no end time) and ended the previous activity at the same time.

Break

To indicate the end of an activity without the immediate start of another activity, simply edit the end date of the activity.

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

Response

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

End of the day

Third activity

Once the pause is over, the recording of activities can be resumed, still in tachograph mode.

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
      }
    }
  }
}

When counting working time over the day, the gaps between two activities will automatically be counted as break time.

Fourth activity

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

Response

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

End location

Before ending a mission, you must specify the end location, and the updated mileage.

These information are mandatory

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

See page below for more information about logging a location

pageLocation recording

End of mission

To end the mission, simply perform the endMission operation by passing the end date of the current activity.

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

Response

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

Possible corrections

The mobile worker notices some errors and omissions in his initial input.

Forgot to restart after the break

The real time of the restart after the lunch break is 1.30 p.m., but the user did not register the restart until 2 p.m. To correct this, the user simply indicates that the restart activity actually started half an hour earlier.

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

Response

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

Correcting the end of an activity

The mobile worker has reported the end of the assignment too early. He wants to shift the end date from 5pm to 5:30pm.

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

Response

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

Adding an activity after the event

The mobile worker wants to add an activity that took place between 8am and 9am. All he has to do is record an activity in classic mode.

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

Response

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