Search Task

Problem

Ability to retrieve a list of tasks that match specific criteria.

Examples:

My tasks for the next 4 days
Latest tasks created this week
Tasks assigned to [email protected]
...

Thank to this API you can build your own dashboard.

Query Parameters

info

Query parameters must be encoded**

taskAssignees: [email protected],[email protected] → KO
taskAssignees : ana.alvarez%40mobility-work.com%2Claurent.desechalliers%40mobility-work.com → OK

Your API implements the classic trio: Pagination, Sorting, and Filtering.

Pagination

We use the Pagesize system

Sorting

You can sort (Asc/Desc) on 3 dates properties : creation/completion/scheduling

Filtering

Assignation
States & properties
Tags
Equipments
Tasks Scheduling

Response

About Pagination

The response to a request may contain several hundred or even thousands of tasks.
We obviously can't return all the tasks in a single response.
Therefore, we use pagination (Page, Limit).

{
  "_links": [
    {
      "href": "https://api.mobility-work.com/partners/v1/tasks/search?page=5&size=5&taskTags=toto,regulatory&taskTagsOperator=or",
      "rel": "self"
    },
    {
      "href": "https://api.mobility-work.com/partners/v1/tasks/search?page=6&size=5&taskTags=toto,regulatory&taskTagsOperator=or",
      "rel": "next"
    },
    {
      "href": "https://api.mobility-work.com/partners/v1/tasks/search?page=4&size=5&taskTags=toto,regulatory&taskTagsOperator=or",
      "rel": "prev"
    }
  ],
  
  
  "_items": [
    {
      ...
    },
    {
      ...
    }
    ...
  ],
  
  
  "_pagination": {
    "totalItemCount": 435,
    "totalPageCount": 87,
    "itemCountPerPage": 5,
    "currentPage": 5,
    "currentItemCount": 5
  }
}

_links contain URL for pagination navigation
_pagination contain information for pagination
_items contain all tasks for a given page

Query parameters details

No parameters are mandatory, so you can enter only the criteria corresponding to the query you need.

Pagination & sorting

alt text

page: current pagination page
size: number of tasks returned by the API (for the given page)
sort: sort field / ascending or descending order
- createdAt.desc
- completedAt.desc
- scheduledAt.desc
- createdAt.asc
- completedAt.asc
- scheduledAt.asc

Assignation

alt text

taskAssignees: [Array] List of assignees
taskAssigneesOperator:
- If AND, returns only the tasks to which all assignees are assigned
- If OR, returns all tasks where at least one of the assignees is assigned
- Default: OR

States & properties

alt text

tasksPartOfMaintenancePlan : filter if tasks is part of a maintenance plan or not
- 2 value yes/no
taskStates
- You can apply more than one state (OR implicit)
  - API return all task who match with one of selected states
- Task states :
  - planned
  - ongoing
  - completed
  - canceled

Equipments

alt text

equipments: [Array] Use this filter to get tasks related to the specified equipment external references.

Tasks Scheduling

alt text

scheduledFrom:
- Use this filter alone to get tasks whose scheduled date (start date) is on or after the specified date.
- Use it with the scheduledTo filter to get tasks scheduled between scheduledFrom and scheduledTo dates.
- (example) scheduledFrom: 2024-08-08T08:00:00+00:00
- UTC +0 only
scheduledTo:
- Use this filter alone to get tasks whose scheduled date (start date) is on or before the specified date.
- Use it with the scheduledFrom filter to get tasks scheduled between scheduledFrom and scheduledTo dates.
- (example) scheduledTo: 2024-08-08T08:00:00+00:00
- UTC +0 only

Detailed answers

_links

_links contains URLs for pagination navigation

Current page URL
- Pages start at 1 (not 0)
Previous page URL
- Same as current page URL if the current page is page 1
Next page URL
- Same as current page URL if the current page is the last page

_paginations

_pagination contains information for pagination

totalItemCount: number of tasks matching the request
totalPageCount: number of pages needed to browse all tasks
itemCountPerPage: number of tasks per page (defined by the limit parameter)
currentPage: current page returned by the API
currentItemCount: number of tasks on the current page (equal to limit, except for the last page, which may be lower)

_items

_items contains all tasks for a given page

taskIk: task ID
taskShortId: task short ID (we use two different ID systems on Mobility Works)
description: task description
taskState: task status / 4 available statuses
- pending
- in_progress
- completed
- canceled
regulatory: indicates whether the task was generated by a regulatory maintenance plan
- values: true / false
createdAt: ISO 8601 task creation date
- example: 2024-07-08T10:52:31+00:00
completedAt: ISO 8601 task completion date
- example: 2024-07-08T10:52:31+00:00
- null if the task is not completed
estimateDurationInMinutes:
- example: 60
- null if no value
plannedMaintenanceTimeInMinutes:
- example: 60
- null if no value
plannedStoppedTimeInMinutes:
- example: 60
- null if no value
networkId: your network UUID
- example: 8b2b640a-ef8a-4dc6-83e3-fbcdfc568f7c
schedule: ISO 8601 scheduled dates
- example:
  - from: 2024-08-08T08:00:00+00:00
  - to: 2024-08-10T09:00:00+00:00
associatedTo: details of task-related equipment
maintenancePlan: maintenance plan details
- null if the task is not associated with a maintenance plan
tags: [Array] tags associated with the task
- empty array if no tags are associated with the task
- for each tag:
  - name and code
  - group name and code name if the tag is associated with a tag group
assignees: [Array] details of those assigned to the task
sparePartRequirements: [Array] details of spare parts required for the job
- empty array if no spare parts are associated with the task
_links: link (webApp) to the task
- we use an array to allow for future links
- the link to the task uses relation = canonical

Python Exemple

import http.client
import urllib.parse
import json

def search_tasks(
    api_key,
    taskAssignees=None,
    taskAssigneesOperator=None,
    page=None,
    size=None,
    taskTags=None,
    taskTagsOperator=None
):
    # Dynamic parameter construction
    params = {}

    if taskAssignees:
        # Correct format: email encoding
        params['taskAssignees'] = ','.join(taskAssignees)
    if taskAssigneesOperator:
        params['taskAssigneesOperator'] = taskAssigneesOperator
    if page:
        params['page'] = str(page)
    if size:
        params['size'] = str(size)
    if taskTags:
        params['taskTags'] = ','.join(taskTags)
    if taskTagsOperator:
        params['taskTagsOperator'] = taskTagsOperator

    # URL encoding of parameters
    query_string = urllib.parse.urlencode(params, safe=',')  # garder les virgules non encodées
    endpoint = f"/partners/v1/tasks/search?{query_string}" if query_string else "/partners/v1/tasks/search"

    # HTTPS connection
    conn = http.client.HTTPSConnection("api.mobility-work.com")
    headers = {
        'Accept': 'application/json',
        'Api-Key': api_key
    }

    # Apple GET
    conn.request("GET", endpoint, headers=headers)
    res = conn.getresponse()
    data = res.read()

    # Parsing JSON
    try:
        json_obj = json.loads(data)
        pretty_str = json.dumps(json_obj, indent=4)
        print(pretty_str)
        return json_obj
    except json.JSONDecodeError:
        print("Erreur de parsing JSON. Réponse brute :")
        print(data.decode())
        return None

# Sample call
if __name__ == "__main__":
    API_KEY = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

    search_tasks(
        api_key=API_KEY,
        taskAssignees=["[email protected]", "laurent.fs@@email.com"],
        taskAssigneesOperator="or",
        page=1,
        size=5,
        taskTags=["pneumatic"],
        taskTagsOperator="and"
    )

Response

{
    "_links": [
        {
            "href": "https://api.mobility-work.com/partners/v1/tasks/[email protected],[email protected]&taskAssigneesOperator=or&page=1&size=5&taskTags=pneumatic&taskTagsOperator=and",
            "rel": "self"
        },
        {
            "href": "https://api.mobility-work.com/partners/v1/tasks/[email protected],[email protected]&taskAssigneesOperator=or&page=1&size=5&taskTags=pneumatic&taskTagsOperator=and",
            "rel": "next"
        },
        {
            "href": "https://api.mobility-work.com/partners/v1/tasks/[email protected],[email protected]&taskAssigneesOperator=or&page=1&size=5&taskTags=pneumatic&taskTagsOperator=and",
            "rel": "prev"
        }
    ],
    "_items": [
        {
            "taskId": "DcrBEQAhCASwinBAYJVyQKX_Eu7yjjcrkEalx8iBRyW-KaX6QQ23Yrhxaq6kuxeTld8_HZCENOK0g2NMHYK1ERPMHw",
            "taskShortId": "809ad889",
            "description": "sqdfsf",
            "taskState": "pending",
            "regulatory": false,
            "createdAt": "2022-10-10T06:26:09+00:00",
            "completedAt": null,
            "estimateDurationInMinutes": 120,
            "plannedMaintenanceTimeInMinutes": 120,
            "plannedStoppedTimeInMinutes": null,
            "networkId": "8b2b640a-ef8a-4dc6-83e3-fbcdfc568f7c",
            "schedule": {
                "from": "2023-03-13T07:30:00+00:00",
                "to": "2023-03-13T09:30:00+00:00",
                "allDay": false
            },
            "associatedTo": {
                "name": "Industrial building - Facility FR12GH",
                "costCenter": "FR12GH",
                "externalReference": null,
                "tags": []
            },
            "maintenancePlan": {
                "id": "540a3a7a-d870-4b5d-b1c6-191f69cf5609",
                "description": "sqdfsf",
                "state": "in_progress",
                "tags": [
                    {
                        "code": "11",
                        "name": "11",
                        "groupId": null,
                        "groupName": null
                    }
                ]
            },
            "tags": [
                {
                    "code": "niveau-1",
                    "name": "Niveau 1",
                    "groupId": 3602,
                    "groupName": "Niveau de maintenance"
                },
                {
                    "code": "11",
                    "name": "11",
                    "groupId": null,
                    "groupName": null
                },
                {
                    "code": "pneumatic",
                    "name": "Pneumatic",
                    "groupId": null,
                    "groupName": null
                },
                {
                    "code": "intervention-immediate",
                    "name": "Intervention imm\u00e9diate",
                    "groupId": 2534,
                    "groupName": "Urgence intervention"
                },
                {
                    "code": "level-1",
                    "name": "Level 1",
                    "groupId": 3601,
                    "groupName": "Maintenance Level"
                },
                {
                    "code": "01-defaillance-structurelle",
                    "name": "01 D\u00e9faillance structurelle",
                    "groupId": 3230,
                    "groupName": "D\u00e9faillance"
                },
                {
                    "code": "$corrective",
                    "name": "Correctifs",
                    "groupId": 1581,
                    "groupName": "Type de maintenance"
                }
            ],
            "assignees": {
                "individuals": [
                    {
                        "firstName": "laurent",
                        "lastName": "desechalliers",
                        "email": "[email protected]"
                    },
                    {
                        "firstName": "Ana",
                        "lastName": "Alvarez",
                        "email": "[email protected]"
                    }
                ],
                "teams": []
            },
            "sparePartRequirements": [],
            "_links": [
                {
                    "href": "https://api.mobility-work.com/work-orders/tasks/detail/DcrBEQAhCASwinBAYJVyQKX_Eu7yjjcrkEalx8iBRyW-KaX6QQ23Yrhxaq6kuxeTld8_HZCENOK0g2NMHYK1ERPMHw",
                    "rel": "canonical"
                }
            ]
        }
    ],
    "_pagination": {
        "totalItemCount": 1,
        "totalPageCount": 1,
        "itemCountPerPage": 5,
        "currentPage": 1,
        "currentItemCount": 1
    }
}

Curl Exemple

curl -X GET "https://api.mobility-work.com/partners/v1/tasks/search?taskAssignees=laurent.d%40email.com,laurent.fs%40email.com&taskAssigneesOperator=or&page=1&size=5&taskTags=pneumatic&taskTagsOperator=and" \
  -H "Accept: application/json" \
  -H "Api-Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" | jq

Problem​

Query Parameters​

Response​

Query parameters details​

Pagination & sorting​

Assignation​

States & properties​

Tags​

Equipments​

Tasks Scheduling​

Detailed answers​

_links​

_paginations​

_items​

Python Exemple​

Curl Exemple​

Problem

Query Parameters

Response

Query parameters details

Pagination & sorting

Assignation

States & properties

Tags

Equipments

Tasks Scheduling

Detailed answers

_links

_paginations

_items

Python Exemple

Curl Exemple