.. _jobs:

Jobs
----

The Job API caters for creating, monitoring and deleting jobs.
Jobs can also be updated through the API as long as they are not
on a mobile device. The job API currently has the following restrictions:

- No support for advanced job state management. Job state management can only happen on mobile devices or through the webapp.
- No support for scheduling recurrent jobs.


.. _list-jobs:

List Jobs
.........

.. http:get:: /job/?start=<start date>&end=<end date>

   Retrieve list of jobs in given time window. Deferred and recurrent
   jobs are also listed and are discriminated by the existence of the
   notificationDelta field. The list can be sorted on scheduled time,
   jobId or state. The list also supports some limited filtering. In
   particular, the list can be filtered on exact match on job lead (by
   uuid), location (by uuid) or state. "state" field is an array of
   length at least one. The first value corresponds to the state and
   the remainder, if any, to the substates.

   The *<start date>* and *<end date>* parameters must be given in ISO 8601
   format, and need to be URL-encoded where appropriate. For example,
   the datetime ``2014-01-31 10:00:00``, must appear in the URL as
   ``2014-01-31+10%3A00%3A00``. The space between the date and time components
   needs to be URL-encoded (as a '+'), and the colons (:) between the hours,
   minutes and seconds must be encoded as well (as %3A00).

   The job list can be sorted on scheduledOn, jobId, and state. The job list
   can be filtered on jobLead, locaton, and state.

   **Sample Request**:

   .. sourcecode:: http

      GET https://api.fieldaware.net/job/?start=2012-09-19T16%3A00&end=2012-09-19T17%3A00&pageSize=3 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Accept: application/json

   **Sample Response**

   .. sourcecode:: http

    HTTP/1.1 200 OK
    Content-Type: application/json
    Link: <https://api.fieldaware.net/job/?start=2012-09-19T16%3A00&end=2012-09-19T17%3A00&page=0&pageSize=3>; rel=first,<https://api.fieldaware.net/job/?start=2012-09-19T16%3A00&end=2012-09-19T17%3A00&page=3&pageSize=3>; rel=last,<https://api.fieldaware.net/job/?start=2012-09-19T16%3A00&end=2012-09-19T17%3A00&page=1&pageSize=3>; rel=next

      {
          "count": 9,
          "pageSize": 3,
          "items": [
              {
                  "startedOn": "2012-09-19T16:57:00+00:00",
                  "state": [
                      "completed"
                  ],
                  "uuid": "99c313e92fb446bea07faeca5d5d392d",
                  "invoice": {
                      "uuid": "0021b917a7b444a697c751f361c22545"
                  },
                  "completedOn": "2012-09-19T17:00:00+00:00",
                  "jobLead": {
                      "uuid": "35e6bfb499e04e0fa7b2f80519a573f9"
                  },
                  "scheduledOn": "2012-09-19T17:00:00+00:00",
                  "createdOn": "2012-09-19T16:57:04+00:00",
                  "location": {
                      "uuid": "f367809ccd224716ad97cd685aafe899"
                  },
                  "jobId": "J598",
                  "link": {
                    "rel": "detail",
                    "url": "https://api.fieldaware.net/job/99c313e92fb446bea07faeca5d5d392d",
                  }
              },
              {
                  "startedOn": "2012-09-12T21:33:00+00:00",
                  "state": [
                      "active"
                  ],
                  "uuid": "5ec7b82dfbbf40e49e01cd46145cf069",
                  "invoice": null,
                  "completedOn": null,
                  "jobLead": {
                      "uuid": "d4d01046ce194da7a5d6fc3df749667d"
                  },
                  "scheduledOn": "2012-09-12T21:33:00+00:00",
                  "createdOn": "2012-09-12T21:33:23+00:00",
                  "location": {
                      "uuid": "2e557478fbc443c08fc4da7d77f4cb21"
                  },
                  "jobId": "J583",
                  "link": {
                    "rel": "detail",
                    "url": "https://api.fieldaware.net/job/5ec7b82dfbbf40e49e01cd46145cf069",
                  }
              },
              {
                  "startedOn": "2012-09-05T15:45:00+00:00",
                  "state": [
                      "active"
                  ],
                  "uuid": "6739f71557c24a5ab16dc8549584ff30",
                  "invoice": null,
                  "completedOn": null,
                  "jobLead": {
                      "uuid": "d4d01046ce194da7a5d6fc3df749667d"
                  },
                  "scheduledOn": "2012-09-11T12:19:00+00:00",
                  "createdOn": "2012-08-29T20:34:26+00:00",
                  "location": {
                      "uuid": "25952d48ee5e486fac57d9c7999bd7db"
                  },
                  "jobId": "J551",
                  "link": {
                    "rel": "detail",
                    "url": "https://api.fieldaware.net/job/6739f71557c24a5ab16dc8549584ff30",
                  }
              }
          ],
          "sortedBy": [
              "-scheduledOn"
          ],
          "page": 0
      }

   :query start: starting date (required)
   :query end: end date (required)
   :query sortedBy: Available sorting criteria: ``scheduledOn``, ``jobLead`` , ``location`` and ``state``
   :query location: filtered by ``location``
   :query jobLead: filtered by ``jobLead``
   :query state: filtered by ``state``

   **Sample invocations**

   .. sourcecode:: http

      /job/?start=2014-01-23&end=2014-01-31&jobLead=9a4b0eb2100a41349a178463c1ea569f
      /job/?start=2014-01-23&end=2014-01-31&state=Completed&sortedBy=-jobId
      /job/?start=2014-01-23&end=2014-01-31&jobLead=9a4b0eb2100a41349a178463c1ea569f&location=b17e350cfd404b068e373ed7661e2b55
      /job/?start=2014-01-23&end=2014-01-31&location=b17e350cfd404b068e373ed7661e2b55&pageSize=200&page=2

   :statuscode 200: no error


Get Job
.......

.. http:get:: /job/(job_ref)

   Retrieve all information on a particular job.

   **Sample request**:

   .. sourcecode:: http

      GET /job/99c313e92fb446bea07faeca5d5d392d HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
          "tasks": [
              {
                  "note": "Test",
                  "task": {
                      "uuid": "61b8a942d4e2487290c1b49618252305",
                      "name": "HEPA filter install",
                      "description": "Install of HEPA filter"
                  },
                  "done": true,
                  "uuid": "c66de447e19744409c07bf88f7fe4043",
                  "asset": {
                      "uuid": "a4d28061ee5311e49c3180e65008eae2"
                  },
                  "items": [
                      {
                          "item": {
                              "uuid": "f81eab99da674809a2841251cd327fca",
                              "name": "Labor",
                              "description": "Labor description"
                          },
                          "unitCost": 10,
                          "unitPrice": 10,
                          "uuid": "222a8990c2954b64a5382818b59592eb",
                          "quantity": 8
                      },
                      {
                          "item": {
                              "uuid": "c550698e989447b6bef17f9121d95b39",
                              "name": "Air Conditioner",
                              "description": "Install & supply A/C unit"
                          },
                          "unitCost": 0,
                          "unitPrice": 5000,
                          "uuid": "80f80f2016374630bbf6b77e45a5b1fd",
                          "quantity": 1
                      }
                  ],
                  "unitPrice": 0,
                  "unitCost": 0,
                  "customFields": {},
                  "attachments": []
              }
          ],
          "revenue": 5080,
          "scheduledDuration": 120,
          "jobId": "J598",
          "invoice": {
              "link": {
                  "url": "https://api.fieldaware.net/invoice/0021b917a7b444a697c751f361c22545",
                  "rel": "detail"
              },
              "uuid": "0021b917a7b444a697c751f361c22545"
          },
          "jobLead": {
              "emailAddress": "jmartin@gmailus.com",
              "telno": "9725551212",
              "surname": "Martin",
              "uuid": "35e6bfb499e04e0fa7b2f80519a573f9",
              "name": "Jack"
          },
          "jobType": {
              "uuid": "46e6bfb487e04e0fa7b2f81617b573e4",
              "name": "Install"
          },
          "scheduledOn": "2012-09-19T17:00:00+00:00",
          "labor": [],
          "uuid": "99c313e92fb446bea07faeca5d5d392d",
          "crew": [
              {
                  "workedHours": [
                      {
                          "start": "2012-09-19T16:57:00+00:00",
                          "inTransit": false,
                          "end": "2012-09-19T16:59:14+00:00",
                          "startLocation": {
                                "lat": 41.40338,
                                "lng": 2.17403
                          },
                          "endLocation": {
                                "lat": 41.40338,
                                "lng": 2.17403
                          },
                          "pauseReason": "lunch"
                      },
                      {
                          "start": "2012-09-19T16:59:44+00:00",
                          "inTransit": false,
                          "end": "2012-09-19T17:00:00+00:00",
                          "startLocation": {
                                "lat": 41.40338,
                                "lng": 2.17403
                          },
                          "endLocation": {
                                "lat": 41.40338,
                                "lng": 2.17403
                          },
                          "pauseReason": "break"
                      }
                  ],
                  "pauseReason": "break",
                  "state": "completed",
                  "uuid": "35e6bfb499e04e0fa7b2f80519a573f9"
              }
          ],
          "state": [
              "completed"
          ],
          "scheduledState": "dispatched",
          "location": {
              "uuid": "f367809ccd224716ad97cd685aafe899",
              "locality": "Plano",
              "country": null,
              "region": "TX",
              "postcode": "75098",
              "streetName": "665544 Preston Road",
              "name": null
          },
          "completedOn": "2012-09-19T17:00:00+00:00",
          "customFields": {},
          "asset": null,
          "startedOn": "2012-09-19T16:57:00+00:00",
          "description": "Install new service",
          "estDuration": 180,
          "pre_signature": {
              "url": "http://fieldaware.s3.amazonaws.com/db84ba3e8e4845ecad61bae0831b3e6e.png",
              "terms_accepted": false,
              "is_shown": false,
              "name": null
          },
          "customer": {
              "uuid": "88e1aeee54c4431e99d1a126b8ea300d",
              "name": "Jimmy Smith",
              "customerId": 34
          },
          "createdOn": "2012-09-19T16:57:04+00:00",
          "contact": null,
          "signature": {
              "url": "http://fieldaware.s3.amazonaws.com/84ed671888254fa3932c119a3eabed77.png",
              "terms_accepted": false,
              "is_shown": false,
              "name": null
          },
          "timeSlots": [
              {
                  "duration": 20,
                  "scheduledOn": "2018-12-06T13:53:00+00:00",
                  "uuid": "6084b55362bc45c59c27464a3feea5e8",
                  "crew": ["35e6bfb499e04e0fa7b2f80519a573f9",
                           "79yt890b7194412189c5019b85794444"]
              }
          ],
          "plannedEffort": 40
      }


   If retrieving a deferred job that has already been dispatched, the
   service returns a ``HTTP 307`` redirection status with the URL of
   the newly dispatched job in the response's ``Location``
   header. This value can then be used in a second request to obtain
   the desired information about the dispatched job.
   For example, if requesting a deferred job that has already been dispatched.

   .. sourcecode:: http

      GET /job/86082ca89a444a3fb1aaf39049423815 HTTP/1.1
      Host: api.fieldaware.net
      Accept: application/json
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18

   The response will have the ``Location`` header set and an empty body.

   .. sourcecode:: http

      HTTP/1.1 307 TEMPORARY REDIRECT
      Location: https://api.fieldaware.net/job/4ce32c5a0d03407a8a572d0300ac0d69

   :statuscode 200: no error
   :statuscode 307: redirection due to dispatch
   :statuscode 404: resource not found

.. note:: ``timeSlots`` data is read-only via the API. Time slots can only be modified in the webapp.
 The duration of each ``timeSlots`` entry is expressed in **minutes**.

 The value for ``plannedEffort`` is a calculated field based on the number of time slots, their duration,
 and the number of assignees per time slot. The units for planned effort are **minutes**. This field is read-only.

 The value for ``scheduledDuration`` is a calculated field based on the time taken between the start of the first
 time slot and the end of the last time slot. The units for scheduled duration are **minutes**. This field is read-only.

 ``pauseReason`, ``startLocation`` and ``endLocation`` for ``crew`` ``workedHours`` cannot be set via the API. This field is read-only.
 The ``pauseReason`` for ``workedHours`` is the last ``pauseReason`` of the ``crew`` array.

 ``scheduledState`` can not be set directly via the API presently, only via Planning Mode in the web application.
 ``scheduledState`` on an unassigned job will be updated indirectly from ``tentative`` or ``confirmed`` to ``dispatched`` if a job lead is set via the API.
 A job created without a job lead will return with a ``scheduledState`` of ``tentative``.


.. _create-job:

Create Job
..........

All fields are optional unless stated otherwise.

.. http:post:: /job/

   Create a new job.


   **Sample minimal request**

   .. sourcecode:: http

      POST /job/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Accept: application/json

      {
        "scheduledOn": "2015-11-11T14:30:00",
        "location": {
          "uuid": "067e238dd9354ea09073babbcbefa053"
        }
      }


   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: https://api.fieldaware.net/job/21cbeb8f0606469899cc22c96ddb778d


      {
        "link": {
          "url": "https://api.fieldaware.net/job/21cbeb8f0606469899cc22c96ddb778d",
          "rel": "detail"
        },
        "tasks": [],
        "revenue": 0,
        "jobId": "J2225",
        "invoice": null,
        "jobLead": null,
        "scheduledOn": "2014-09-27T00:00:00+00:00",
        "labor": [],
        "uuid": "f4e4341f7dc7416cadf64e7e99bb207f",
        "crew": [],
        "state": [
            "scheduled"
        ],
        "scheduledState": "tentative",
        "location": {
              "uuid": "f367809ccd224716ad97cd685aafe899",
              "locality": "Plano",
              "country": null,
              "region": "TX",
              "postcode": "75098",
              "streetName": "665544 Preston Road",
              "name": null
        },
        "completedOn": null,
        "customFields": {},
        "asset": null,
        "startedOn": null,
        "description": "",
        "estDuration": null,
        "pre_signature": null,
        "customer": {
            "uuid": "7b4d6ecf8a094937a1afae4479485d49",
            "name": "ABC Company",
            "customerId": 30
        },
        "createdOn": "2014-09-28T16:31:49+00:00",
        "contact": null,
        "signature": null,
        "timeSlots": {
            "duration": 0,
            "scheduledOn": "2014-09-27T00:00:00+00:00",
            "uuid": "5ab2e3f511a142908dda8db647c86ab8",
            "crew": []
        },
        "plannedEffort": 0
      }


   **Sample request**:

   .. sourcecode:: http

      POST /job/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Accept: application/json

      {
        "scheduledOn": "2014-12-11T09:00:00",
        "notificationDelta": 2,
        "description": "collecting items",
        "estDuration": 180,
        "location": {
          "uuid": "38be890b7194412189c5019b85790zzz"
        },
        "contact": {
          "uuid": "11as890b7194412189c5019b85790293"
        },
        "asset": {
          "uuid": "41xs890b7194412189c5019b85791113"
        },
        "jobType": {
          "uuid": "81ds910g8144337187d6023j88792229"
        },
        "jobLead": {
          "uuid": "96vb890b7194412189c5019b85790999"
        },
        "crew": [
          {
            "uuid": "79yt890b7194412189c5019b85794444"
          }
        ],
        "tasks": [
          {
            "task": {
              "uuid": "bg56890b7194412189c5019b85790293"
            },
            "asset": {
              "uuid": "511ffeefddf34d0190524e738fe12303"
            },
            "assignee": {
              "uuid": "79yt890b7194412189c5019b85794444",
              "emailAddress": "bthompson@gmailus.com"
            },
            "note": "note for this task",
            "unitCost": 10.23,
            "unitPrice": 10.23,
            "done": true,
            "customFields": {
              "f713aba8bd2b11e6b6b7f45c89b2e1d5": "my sample string task custom field value",
              "23daaec2bd2c11e6bdc3f45c89b2e1d5": false
            },
            "items": [
              {
                "item": {
                  "uuid": "56uy890b7194412189c5019b85790293"
                },
                "quantity": 2.0,
                "unitCost": 23.30,
                "unitPrice": 34.12
              }
            ]
          }
        ],
        "customFields": {
          "67as890b7194412189c5019b85790293": true,
          "my_custom_reference_key": "my sample text"
        },
        "labor": [
          {
            "user": {
              "uuid": "98de890b7194412189c5019b85790293"
            },
            "quantity": 3,
            "rate": {
                "name": "Overtime",
                "rate": 200.00,
                "cost": 120.00,
                "taxable": true,
                "taxes": [
                  {
                    "name": "Standard",
                    "group": "Taxes"
                  }
                ],
                "glAccount": "GL-40130"
            }
          }
        ]
      }


   :<json datetime scheduledOn: When the job is scheduled (required).
   :<json integer notificationDelta: When present, a deferred job is created and will be dispatched at time (scheduledOn - notificationDelta)
   :<json string description: Textual description of the job.
   :<json integer estDuration: The estimated duration of the work in minutes.
   :<json obj location: JSON object representing the location for the job.
   :<json obj contact: JSON object representing the contact person for the job.
   :<json obj asset: JSON object representing what asset is needed, if any.
   :<json obj jobLead: Who is the lead member for this job.
   :<json array crew: A list of JSON objects representing crew members.
   :<json array tasks: A list of JSON objects representing tasks.
   :<json obj task: Each object in tasks array has this form
   :<json obj task.task: JSON object defining the uuid of a task
   :<json string task.note: A note
   :<json obj task.assignee: JSON object defining the uuid of the task assignee. Must be an existing crew member.
   :<json number task.unitCost: The unitary cost of the task
   :<json number task.unitPrice: The unitary price of the task
   :<json obj task.customFields: Mapping of declaration keys to values (see note below)
   :<json boolean done: The status of the task
   :<json array items: An array of item
   :<json object item: Each object in items array has this form
   :<json obj item.item: JSON object defining the uuid of an item
   :<json integer item.quantity: Quantity needed of a specific item
   :<json number item.unitCost: The unitary cost of the item
   :<json number item.unitPrice: The unitary price of the item
   :<json obj customFields: A JSON objects representing custom fields, see :ref:`Custom Fields <custom-fields>`
   :<json array labor: A list of JSON labor objects
   :<json object labor: Each object in labor array has this form
   :<json obj labor.user: JSON object representing a user
   :<json integer labor.quantity: How many minutes spent on the job.
   :<json object labor.rate: a rate object (Details below)
   :<json string labor.rate.name: A descriptive name for the rate, used for displaying (required)
   :<json number labor.rate.rate:  Price per hour to be charged (required)
   :<json number labor.rate.cost: Internal cost associated with unit (defaults to 0)
   :<json number labor.rate.taxable: Whether tax is to be applied to this on invoice generation (defaults to False)
   :<json array labor.rate.taxes: an array of tax objects
   :<json string glAccount: General Ledger account identifier



.. note:: Job lead is automatically added to the crew.

.. note:: Task assignee field is only available to True-Crew enabled customers.

.. note:: Labor can be specified either by an existing rate from the
            Company settings (that is applicable to the specified
            user), or, by an ad-hoc rate for this labor entity (as in the previous example).
            In the former case, the rate is specified by UUID, in the latter
            case, there is no UUID but a number of fields need to be
            provided. If those value fields are present, a UUID, even
            if provided, is ignored.


   **Alternative rate specification**

     .. sourcecode:: http

        POST /job/ HTTP/1.1
        Host: api.fieldaware.net
        Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
        Accept: application/json

        {
          "scheduledOn": "2014-12-11T09:00:00",
          "location": {
            "uuid": "38be890b7194412189c5019b85790zzz"
          },
          "labor": [
            {
              "user": {
                "uuid": "98de890b7194412189c5019b85790293"
              },
              "quantity": 3,
              "rate": {
                  "uuid": "091a93d117b34958acd9ab3234016550"
              }
            }
          ]
        }

     :<json string labor.rate.uuid: UUID referring to a specific rate


.. note::

    To map a :ref:`Custom Field <custom-fields>` to a job task, the declaration
    must have an ``entityClass`` of ``Task`` **and** have ``availableOnJob``
    set to ``true``.  Attempting to map a declaration not having these values
    will be silently ignored.

    These mappings support typical CRUD operations: adding, retrieving,
    updating and removing. Passed custom field keys that do not correspond to
    any of existing Task custom field declaration are silently ignored.  The
    update semantics of these mappings can be summarized as "last write
    overwrites previous mapping".  Thus, for example, sending an empty mapping
    (`{}`) will remove all custom fields values associated with a job task.


Update Job
..........

.. http:post:: /job/(job_ref)

   Update a given job.

   **JSON request body**: Same as `Create Job`_, with all properties being optional.

   .. warning:: It is not possible to add, delete or update individual tasks or
    items using this endpoint (see below how to manage an individual task).
    It is only possible to specify the whole list of tasks
    on an update. When UUIDs of existing tasks on the job are listed, they are re-used,
    if only the UUID of the task to be added to the job is listed, a new task is
    added, for which the attributes ``note``, ``unitCost``, ``unitPrice``, and
    ``done`` can be specified. Passing an empty array effectively deletes all tasks
    (and associated items) from the job.

   .. note:: The job crew can only be updated when the job is in the 'Scheduled' state.
    For jobs that are in any other state, such as 'Active' or 'Completed', attempts
    to update the crew will result in a Conflict Error. Also, attempt to remove the
    job lead from the crew will result in a Conflict Error.

   .. note:: It is currently not possible to update the labor section of a job.

   If updating a deferred job that has already been dispatched, the
   service returns a ``HTTP 307`` redirection status with the URL of
   the newly dispatched job in the response's ``Location`` header.

   :statuscode 204: job updated successfully
   :statuscode 307: redirection due to dispatch
   :statuscode 404: resource not found
   :statuscode 409: request could not be full filled because state of resource does not allow payload to be applied


Delete Job
..........

.. http:delete:: /job/(job_ref)

   Delete a given job.

   If deleting a deferred job that has already been dispatched, the
   service returns a ``HTTP 307`` redirection status with the URL of
   the newly dispatched job in the response's ``Location`` header.

   **Sample request**:

   .. sourcecode:: http

      DELETE /job/3b6d8b52006c46abbde3275f10fe9108 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5

   **Sample response**

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT

   :statuscode 204: job deleted successfully
   :statuscode 307: redirection due to dispatch
   :statuscode 404: resource not found


Dispatch a Deferred Job
.......................

.. http:post:: /job/(job_ref)/dispatch

   Dispatch a deferred job.

   When dispatching a job, the service returns a
   ``HTTP 303`` redirection status with the URL of the newly
   dispatched job in the response's ``Location`` header.

   **Sample request**:

   .. sourcecode:: http

      POST /job/3b6d8b52006c46abbde3275f10fe9108/dispatch HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Accept: application/json

   **Sample response**

   .. sourcecode:: http

      HTTP/1.1 303 SEE OTHER
      Location: https://api.fieldaware.net/job/d43f849cf8b146babc740cb3e4ec705f


   :statuscode 303: dispatch successful, dispatched job uuid can be found in the response's Location header
   :statuscode 404: resource not found
   :statuscode 409: cannot dispatch an already dispatched job


Managing a Job Task
...................

.. http:post:: /job/(job_ref)/task/

    Create a new job ``Task`` by appending it to the end of ``tasks`` array.
    The payload is the same used for task in the Job payload

    .. sourcecode:: http

       POST /job/f4e4341f7dc7416cadf64e7e99bb207f/task/ HTTP/1.1
       Host: api.fieldaware.net
       Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
       Accept: application/json
         {
           "task": {
             "uuid": "bg56890b7194412189c5019b85790293"
           },
           "asset": {
             "uuid": "511ffeefddf34d0190524e738fe12303"
           },
           "assignee": {
             "uuid": "79yt890b7194412189c5019b85794444"
           },
           "note": "note for this task",
           "unitCost": 10.23,
           "unitPrice": 10.23,
           "done": true,
           "items": [
             {
               "item": {
                 "uuid": "56uy890b7194412189c5019b85790293"
               },
               "quantity": 2.0,
               "unitCost": 23.30,
               "unitPrice": 34.12
             }
           ]
         }


    .. sourcecode:: http

       HTTP/1.1 201 CREATED
       Content-Type: application/json
       Location: https://api.fieldaware.net/job/f4e4341f7dc7416cadf64e7e99bb207f/task/2189c5019b8579029356uy890b719441
           {
             "uuid: "2189c5019b8579029356uy890b719441",
             "task": {
               "uuid": "bg56890b7194412189c5019b85790293"
             },
             "asset": {
               "uuid": "511ffeefddf34d0190524e738fe12303"
             },
             "assignee": {
               "uuid": "79yt890b7194412189c5019b85794444"
             },
             "note": "note for this task",
             "unitCost": 10.23,
             "unitPrice": 10.23,
             "done": true,
             "items": [
               {
                 "item": {
                   "uuid": "56uy890b7194412189c5019b85790293"
                 },
                 "quantity": 2.0,
                 "unitCost": 23.30,
                 "unitPrice": 34.12
               }
             ]
           }


.. http:get:: /job/(job_ref)/task/(task_ref)

    Get a single Task

.. http:put:: /job/(job_ref)/task/(task_ref)

    Update a `Task`. The payload is the same used for updating a task in the Job payload. There is no
    need to specify the "uuid" field though.

.. http:delete:: /job/(job_ref)/task/(task_ref)

    Delete a  `Task`.


Upload Attachment to Job Task
.............................

A detailed guide about attachments is :ref:`here <attachmentsjob>`

.. http:post:: /job/(job_ref)/task/(task_ref_or_index)/attachment/

   Upload one or more files and attach them to a given job task.

   The task can be specified either by its UUID (if it is unique for this job)
   or its index (0-based) in the "tasks" array, as returned by `Get Job`_.

   The file(s) to be uploaded must be encoded as a "multipart/form-data" content
   type.

   If adding an attachment to a task belonging to a deferred job that
   has already been dispatched, the service returns a ``HTTP 307``
   redirection status with the URL of the newly dispatched job in the
   response's ``Location`` header.

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json

      [
        {
          "mimetype": "text/plain",
          "name": "requirements.txt",
          "uuid": "36e4a048a9354e7d9dd7caee7563bb9e"
        },
        {
          "mimetype": "application/msword",
          "name": "Summary.doc",
          "uuid": "67e02c4a4a2d464bb3f1dcdd2e736372"
        }
      ]

   :statuscode 201: successful upload
   :statuscode 307: redirection due to dispatch
   :statuscode 400: attachment too large
   :statuscode 404: resource not found


List Attachments of Job Task
............................

.. http:get:: /job/(job_ref)/task/(task_ref_or_index)/attachment/

   **Sample request**:

   .. sourcecode:: http

      GET /job/3b6d8b52006c46abbde3275f10fe9108/task/61b8a942d4e2487290c1b49618252305/attachment/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      [
        {
          "mimetype": "image/png",
          "createdDate": "2013-08-11T14:00:00+00:00",
          "uuid": "a3aa9575739c43989bfec0fca014d3d0",
          "caption": "file description",
          "name": "pict.png"
        },
        {
          "mimetype": "image/png",
          "createdDate": "2013-08-11T15:00:00+00:00",
          "uuid": "c0fca014d3d0a3aa9575739c43989bfe",
          "caption": "file description",
          "name": "picture.png"
        }
      ]

Download Attachment of Job Task
...............................

.. http:get:: /job/(job_ref)/task/(task_ref_or_index)/attachment/(attachment_ref)

   Download a given file attached to a given job task.

   The task can be specified either by its UUID (if it is unique for this job)
   or its index (0-based) in the "tasks" array, as returned by `Get Job`_. The
   attachment is specified by its UUID, as returned by `Upload Attachment to Job Task`_.

   If downloading an attachment from a job task belonging to a
   deferred job that has already been dispatched, the service returns
   a ``HTTP 307`` redirection status with the URL of the newly
   dispatched job in the response's ``Location`` header.

  :statuscode 307: redirection due to dispatch
  :statuscode 404: resource not found


Update Attachment caption
.........................

.. http:put:: /job/(job_ref)/task/(task_ref_or_index)/attachment/(attachment_ref)

    You can update the attachment caption

   **Sample request**:

   .. sourcecode:: http

      PUT /job/3b6d8b52006c46abbde3275f10fe9108/task/61b8a942d4e2487290c1b49618252305/attachment/c0fca014d3d0a3aa9575739c43989bfe HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Accept: application/json

      {
        "caption": "caption text"
      }

   **Sample response**:

   .. sourcecode:: http

    HTTP/1.1 204 No Content


Delete Attachment from Job Task
...............................

.. http:delete:: /job/(job_ref)/task/(task_ref_or_index)/attachment/(attachment_ref)

   Delete a given file attached to a given job task.

   The task can be specified either by its UUID (if it is unique for this job)
   or its index (0-based) in the "tasks" array, as returned by `Get Job`_. The
   attachment is specified by its UUID, as returned by `Upload Attachment to Job Task`_.

   If deleting an attachment belonging to a deferred job that has
   already been dispatched, the service returns a ``HTTP 307``
   redirection status with the URL of the newly dispatched job in the
   response's ``Location`` header.

   **Sample request**:

   .. sourcecode:: http

      DELETE /job/3b6d8b52006c46abbde3275f10fe9108/task/61b8a942d4e2487290c1b49618252305/attachment/c0fca014d3d0a3aa9575739c43989bfe HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT

   :statuscode 204: attachment deleted successfully
   :statuscode 307: redirection due to dispatch
   :statuscode 404: resource not found


Job dependencies
................

In order to define a explicit order for the execution of jobs, the API supports the definition
of predecessor and successor jobs for a given one. These must be set under the ``dependencies`` attribute.

.. http:post:: /job/

  **Sample minimal request**

   .. sourcecode:: http

      POST /job/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Accept: application/json

      {
          "scheduledOn": "2013-08-21T14:30:00",
          "location": {
              "uuid": "f367809ccd224716ad97cd685aafe899",
          },
          "dependencies": {
            "predecessor": {
                "uuid": "c1ae96d5cc8a4f03b7af6882697bd382"
            },
            "successor": {
                "uuid": "3b6d8b52006c46abbde3275f10fe9108"
            }
          }
      }

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: https://api.fieldaware.net/job/21cbeb8f0606469899cc22c96ddb778d


      {
        "link": {
          "url": "https://api.fieldaware.net/job/21cbeb8f0606469899cc22c96ddb778d",
          "rel": "detail"
        },
        "tasks": [],
        "revenue": 0,
        "jobId": "J2225",
        "invoice": null,
        "jobLead": null,
        "scheduledOn": "2014-09-27T00:00:00+00:00",
        "labor": [],
        "uuid": "21cbeb8f0606469899cc22c96ddb778d",
        "crew": [],
        "state": [
            "scheduled"
        ],
        "location": {
              "uuid": "f367809ccd224716ad97cd685aafe899",
              "locality": "Plano",
              "country": null,
              "region": "TX",
              "postcode": "75098",
              "streetName": "665544 Preston Road",
              "name": null
        },
        "completedOn": null,
        "customFields": {},
        "asset": null,
        "startedOn": null,
        "description": "",
        "estDuration": null,
        "pre_signature": null,
        "customer": {
            "uuid": "7b4d6ecf8a094937a1afae4479485d49",
            "name": "ABC Company",
            "customerId": 30
        },
        "createdOn": "2014-09-28T16:31:49+00:00",
        "contact": null,
        "signature": null,
        "dependencies": {
            "predecessor": {
                "uuid": "c1ae96d5cc8a4f03b7af6882697bd382",
                "link": {
                  "url": "https://api.fieldaware.net/job/c1ae96d5cc8a4f03b7af6882697bd382",
                  "rel": "detail"
            },
            "successor": {
                "uuid": "3b6d8b52006c46abbde3275f10fe9108",
                "link": {
                  "url": "https://api.fieldaware.net/job/3b6d8b52006c46abbde3275f10fe9108",
                  "rel": "detail"
                }
            }
        }
      }


Job time windows
................

It is possible to set a "time window" on a job. This will indicate the earliest time when work for
that job should start, and a deadline for when that job should be finished by or before. The values
for these times should be nested under the ``timeWindow`` attribute


.. http:post:: /job/

  **Sample minimal request**

   .. sourcecode:: http

      POST /job/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Accept: application/json

      {
          "scheduledOn": "2013-08-21T14:30:00",
          "location": {
              "uuid": "f367809ccd224716ad97cd685aafe899",
          },
          "timeWindow": {
            "startAfter": "2014-12-01T00:00:00",
            "deadline": "2014-12-05T00:00:00"
          }
      }

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: https://api.fieldaware.net/job/21cbeb8f0606469899cc22c96ddb778d


      {
        "link": {
          "url": "https://api.fieldaware.net/job/21cbeb8f0606469899cc22c96ddb778d",
          "rel": "detail"
        },
        "tasks": [],
        "revenue": 0,
        "jobId": "J2225",
        "invoice": null,
        "jobLead": null,
        "scheduledOn": "2014-09-27T00:00:00+00:00",
        "labor": [],
        "uuid": "21cbeb8f0606469899cc22c96ddb778d",
        "crew": [],
        "state": [
            "scheduled"
        ],
        "location": {
              "uuid": "f367809ccd224716ad97cd685aafe899",
              "locality": "Plano",
              "country": null,
              "region": "TX",
              "postcode": "75098",
              "streetName": "665544 Preston Road",
              "name": null
        },
        "completedOn": null,
        "customFields": {},
        "asset": null,
        "startedOn": null,
        "description": "",
        "estDuration": null,
        "pre_signature": null,
        "customer": {
            "uuid": "7b4d6ecf8a094937a1afae4479485d49",
            "name": "ABC Company",
            "customerId": 30
        },
        "createdOn": "2014-09-28T16:31:49+00:00",
        "contact": null,
        "signature": null,
        "timeWindow": {
            "startAfter": "2014-12-01T00:00:00",
            "deadline": "2014-12-05T00:00:00"
        }
      }


.. warning::
  Job time windows and job dependencies are not compatible at the moment. Setting up
  job dependencies to a job with a time window will result in the removal of the
  ``startAfter`` and ``deadline`` values.
  Trying to set up a job time window on a job already having dependencies set up will
  result in a conflict error (status code 409).


.. _jobs-enterprise-updates:

Enterprise Job Updates
......................

.. warning::
  The following changes are only visible if the organisation using the API is Enterprise-enabled.

An additional attribute ``group`` has been added to jobs when enterprise mode is
enabled for a company using the API. This attribute specifies the group which is
in charge of fulfilling the job.


.. http:get:: /job/(job_ref)

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
          "tasks": [],
          "revenue": 5080,
          "jobId": "J598",
          "invoice": null,
          "jobLead": {
              "emailAddress": "jmartin@gmailus.com",
              "telno": "9725551212",
              "surname": "Martin",
              "uuid": "35e6bfb499e04e0fa7b2f80519a573f9",
              "name": "Jack"
          },
          "jobType": {
              "uuid": "46e6bfb487e04e0fa7b2f81617b573e4",
              "name": "Install"
          },
          "scheduledOn": "2012-09-19T17:00:00+00:00",
          "labor": [],
          "uuid": "99c313e92fb446bea07faeca5d5d392d",
          "crew": [],
          "state": [
              "completed"
          ],
          "location": {
              "uuid": "f367809ccd224716ad97cd685aafe899",
              "locality": "Plano",
              "country": null,
              "region": "TX",
              "postcode": "75098",
              "streetName": "665544 Preston Road",
              "name": null
          },
          "completedOn": "2012-09-19T17:00:00+00:00",
          "customFields": {},
          "asset": null,
          "startedOn": "2012-09-19T16:57:00+00:00",
          "description": "Install new service",
          "estDuration": 180,
          "pre_signature": null,
          "customer": {
              "uuid": "88e1aeee54c4431e99d1a126b8ea300d",
              "name": "Jimmy Smith",
              "customerId": 34
          },
          "createdOn": "2012-09-19T16:57:04+00:00",
          "contact": null,
          "signature": null,
          "group": {
              "uuid": "c1ae96d5cc8a4f03b7af6882697bd382",
              "name": "Plano Branch"
          }
      }


   :<json obj group: Indicates the uuid and name of the group or branch in charge of the job.


This ``group`` attribute is also required on the creating payload for new jobs when enterprise is
enabled:

.. http:post:: /job/

  **Sample minimal request**

   .. sourcecode:: http

      POST /job/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
      Accept: application/json

      {
          "scheduledOn": "2013-08-21T14:30:00",
          "location": {
              "uuid": "f367809ccd224716ad97cd685aafe899",
          },
          "group": {
              "uuid": "c1ae96d5cc8a4f03b7af6882697bd382"
          }
      }

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: https://api.fieldaware.net/job/21cbeb8f0606469899cc22c96ddb778d


      {
        "link": {
          "url": "https://api.fieldaware.net/job/21cbeb8f0606469899cc22c96ddb778d",
          "rel": "detail"
        },
        "tasks": [],
        "revenue": 0,
        "jobId": "J2225",
        "invoice": null,
        "jobLead": null,
        "scheduledOn": "2014-09-27T00:00:00+00:00",
        "labor": [],
        "uuid": "21cbeb8f0606469899cc22c96ddb778d",
        "crew": [],
        "state": [
            "scheduled"
        ],
        "location": {
              "uuid": "f367809ccd224716ad97cd685aafe899",
              "locality": "Plano",
              "country": null,
              "region": "TX",
              "postcode": "75098",
              "streetName": "665544 Preston Road",
              "name": null
        },
        "completedOn": null,
        "customFields": {},
        "asset": null,
        "startedOn": null,
        "description": "",
        "estDuration": null,
        "pre_signature": null,
        "customer": {
            "uuid": "7b4d6ecf8a094937a1afae4479485d49",
            "name": "ABC Company",
            "customerId": 30
        },
        "createdOn": "2014-09-28T16:31:49+00:00",
        "contact": null,
        "signature": null,
        "group": {
            "uuid": "c1ae96d5cc8a4f03b7af6882697bd382",
            "name": "Plano Branch"
        }
      }