.. _attachments:

Attachments
-----------

File can be attached to few entities like assets and tasks assigned to a job.



Asset
.....


The following procedure describes how to attach files
to an asset. A caption (description) can be defined as well.

In order to add an attachment, a ``POST`` using the ``Content-Type multipart/form-data`` (according to RFC 2388) must be issued.
For instance to add a file ``catalog.html``:

  .. sourcecode:: bash

    curl -v \
      -H "Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5" \
      https://api.fieldaware.net/asset/fe1ffcc1f3554f9fa6f1efe743a0aacb/attachment/ \
      -F name=@catalog.html

      > POST /asset/fe1ffcc1f3554f9fa6f1efe743a0aacb/attachment/ HTTP/1.1
      > User-Agent: curl/7.30.0
      > Host: api.fieldaware.net
      > Accept: application/json
      > Authorization: Token 687fe20baeef448bb30db579139dad33
      > Content-Type: multipart/form-data; boundary=----------------------------8e28fb81d96d

Returning the following

.. sourcecode:: javascript

   [
     {
       "mimetype": "text/html",
       "caption": null,
       "createdDate": "2014-10-08T18:05:04.836000+00:00",
       "uuid": "16af620bd7b66c76c284cf283b31833e",
       "name": "catalog.html"
     }
   ]

The ``mimetype`` is guessed by the file extension. Other possibilities are ``application/pdf``, ``text/plain``,
``text/html`` and ``application/octet-stream`` for not recognized file extension.

Many files can be uploaded at once. For instance

 .. sourcecode:: bash

    curl \
      -H "Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5" \
      https://api.fieldaware.net/asset/fe1ffcc1f3554f9fa6f1efe743a0aacb/attachment/ \
      -F name=@foo.txt \
      -F name=@foo


Once the file has been attached, it's possible to specify a caption on a per attachment basis. This is done updating
the attachment url using the suitable ``caption`` field. For instance

.. sourcecode:: bash

   curl -X PUT \
     -H "Content-Type: application/json" \
     -H "Authorization: Token 687fe20baeef448bb30db579139dad33" \
     https://api.fieldaware.net/asset/fe1ffcc1f3554f9fa6f1efe743a0aacb/attachment/16af620bd7b66c76c284cf283b31833e \
     --data-binary '{"caption": "the catalog"}'


All attachments metadata can be retrieved at once


.. sourcecode:: bash

   curl \
     -H "Accept-Type: application/json" \
     -H "Authorization: Token 687fe20baeef448bb30db579139dad33" \
     https://api.fieldaware.net/asset/fe1ffcc1f3554f9fa6f1efe743a0aacb/attachment/

returning

.. sourcecode:: javascript

   [
     {
       "mimetype": "text/html",
       "caption": "the catalog",
       "createdDate": "2014-10-08T18:05:04.836000+00:00",
       "uuid": "16af620bd7b66c76c284cf283b31833e",
       "name": "catalog.html"
     },
     {
       "mimetype": "application/octet-stream",
       "caption": null,
       "createdDate": "2014-10-08T18:29:51.951750+00:00",
       "uuid": "55cf17c7e8cb4911ad0310cb420d8dbd",
       "name": "foo"
     },
     {
       "mimetype": "text/plain",
       "caption": null,
       "createdDate": "2014-10-08T14:29:16.184107+00:00",
       "uuid": "ba8a58a37007372d5177bff39f24d4c7",
       "name": "foo.txt"
     }
   ]


Attachment can be retrieved (GET) or deleted (DELETE) referring the specific url

.. sourcecode:: bash

   curl \
     -H "Accept-Type: application/json" \
     -H "Authorization: Token 687fe20baeef448bb30db579139dad33" \
     https://api.fieldaware.net/asset/fe1ffcc1f3554f9fa6f1efe743a0aacb/attachment/16af620bd7b66c76c284cf283b31833e


   curl -X DELETE \
     -H "Authorization: Token 687fe20baeef448bb30db579139dad33" \
     https://api.fieldaware.net/asset/fe1ffcc1f3554f9fa6f1efe743a0aacb/attachment/16af620bd7b66c76c284cf283b31833e


See as well Asset reference :ref:`here <assets>`


.. _attachmentsjob:

Jobs
....


The following procedure describes how to attach files
to a task associated to a job. A caption (description) can be defined as well for each attachment.


Let's assume we have a job with a list of tasks. For instance

  .. sourcecode:: bash

    curl \
      -H "Accept-Type: application/json" \
      -H "Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5" \
      https://api.fieldaware.net/job/91085af6e6e14ff1b01c348aea2ff90d

  .. sourcecode:: javascript

    {
      "customer": {
        "uuid": "ad75feede7334c0bb024835921226221",
        "name": "Omni Hotels",
        "customerId": 21
      },
      "startedOn": null,
      "tasks": [
        {
          "note": "",
          "attachments": [],
          "done": false,
          "uuid": "5012fb628f1c43bab18a72ba5653343c",
          "items": [],
          "unitPrice": 0,
          "unitCost": 0,
          "name": "Restaurant Cleaning"
        }
      ],
      "uuid": "91085af6e6e14ff1b01c348aea2ff90d",
      "revenue": 0,
      "signature": null,
      "crew": [
        {
          "state": "scheduled",
          "uuid": "f260bfef377a4688bac336ec0ceb1429"
        }
      ],
      "jobId": "J21.2",
      "pre_signature": null,
      "state": [
        "scheduled"
      ],
      "contact": null,
      "labor": [],
      "location": {
        "uuid": "c486302ad75640eab554c56c6cfb14c3",
        "locality": "Dallas",
        "country": null,
        "region": "Texas",
        "postcode": "75202",
        "streetName": "555 S. Lamar",
        "name": "Dallas - Downtown"
      },
      "invoice": null,
      "completedOn": null,
      "jobLead": {
        "emailAddress": "andy.murphy@fieldaware.com",
        "telno": "",
        "surname": "Murphy",
        "uuid": "f260bfef377a4688bac336ec0ceb1429",
        "name": "Andy"
      },
      "scheduledOn": "2014-06-01T15:30:00+00:00",
      "asset": null,
      "estDuration": 15,
      "customFields": {
        "2d317c1902f645d6ae5b7fd7fb704667": "Routine"
      },
      "description": "Routing:\n1 a month or 2 a month, scheduled work, no way to currently catch completed work"
    }

In order to add a file to a task, a ``POST`` using the ``Content-Type multipart/form-data`` (according to RFC 2388) must be issued.
For instance to add a file ``picture.jpg``:

 .. sourcecode:: bash

    curl -v \
      -H "Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5" \
      https://api.fieldaware.net/job/91085af6e6e14ff1b01c348aea2ff90d/task/5012fb628f1c43bab18a72ba5653343c/attachment/ \
      -F name=@picture.jpg

      > POST /job/91085af6e6e14ff1b01c348aea2ff90d/task/5012fb628f1c43bab18a72ba5653343c/attachment/ HTTP/1.1
      > User-Agent: curl/7.30.0
      > Host: api.fieldaware.net
      > Accept: application/json
      > Authorization: Token 687fe20baeef448bb30db579139dad33
      > Content-Type: multipart/form-data; boundary=----------------------------b81d96d8e28f

Returning the following

.. sourcecode:: javascript

    [
      {
        "mimetype": "image/jpeg",
        "caption": null,
        "createdDate": "2014-10-08T13:49:04.271791+00:00",
        "uuid": "05e190f276714af6b065997fb7679b51",
        "name": "picture.jpg"
      }
    ]

Many files can be uploaded at once:

 .. sourcecode:: bash

    curl \
      -H "Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5" \
      https://api.fieldaware.net/job/91085af6e6e14ff1b01c348aea2ff90d/task/5012fb628f1c43bab18a72ba5653343c/attachment/ \
      -F name=@foo.txt \
      -F name=@foo

Once the file has been attached, it's possible to specify a caption on a per attachment basis. This is done updating
the attachment url using the suitable ``caption`` field. For instance

.. sourcecode:: bash

   curl -X PUT \
     -H "Content-Type: application/json" \
     -H "Authorization: Token 687fe20baeef448bb30db579139dad33" \
     https://api.fieldaware.net/job/91085af6e6e14ff1b01c348aea2ff90d/task/5012fb628f1c43bab18a72ba5653343c/attachment/05e190f276714af6b065997fb7679b51 \
     --data-binary '{"caption": "description text"}'


All attachments metadata can be retrieved at once

.. sourcecode:: bash

   curl \
     -H "Accept-Type: application/json" \
     -H "Authorization: Token 687fe20baeef448bb30db579139dad33" \
     https://api.fieldaware.net/job/91085af6e6e14ff1b01c348aea2ff90d/task/5012fb628f1c43bab18a72ba5653343c/attachment/

returning

.. sourcecode:: javascript

    [
      {
        "mimetype": "application/octet-stream",
        "caption": null,
        "createdDate": "2014-10-08T14:29:15.951750+00:00",
        "uuid": "4911ad0310cb420d8dbd55cf17c7e8cb",
        "name": "foo"
      },
      {
        "mimetype": "text/plain",
        "caption": null,
        "createdDate": "2014-10-08T14:29:16.184107+00:00",
        "uuid": "177bff39f24d4c7ba8a58a37007372d5",
        "name": "foo.txt"
      },
      {
        "mimetype": "image/jpeg",
        "caption": "description text",
        "createdDate": "2014-10-08T13:49:04.271791+00:00",
        "uuid": "05e190f276714af6b065997fb7679b51",
        "name": "picture.jpg"
      }
    ]

Individual attachment can be retrieved (GET) or deleted (DELETE) referring the specific url


.. sourcecode:: bash

   curl \
     -H "Accept-Type: application/json" \
     -H "Authorization: Token 687fe20baeef448bb30db579139dad33" \
     https://api.fieldaware.net/job/91085af6e6e14ff1b01c348aea2ff90d/task/5012fb628f1c43bab18a72ba5653343c/attachment/05e190f276714af6b065997fb7679b51

   curl -X DELETE \
     -H "Authorization: Token 687fe20baeef448bb30db579139dad33" \
     https://api.fieldaware.net/job/91085af6e6e14ff1b01c348aea2ff90d/task/5012fb628f1c43bab18a72ba5653343c/attachment/05e190f276714af6b065997fb7679b51

See as well Job documemtation :ref:`here <jobs>`