.. _custom-fields:

Custom Fields
=============

Introduction
------------

The system supports *custom fields* on a number of entity types, including: ``Jobs``, ``Invoices``, ``Assets``,
``Customers``, ``Contacts``, ``Locations``, ``Tasks``, and ``Items``. Custom fields in FieldAware apply at
the individual entity level, although they need to be declared per entity type. This allows, for example,
maintenance-related custom fields to be only added to maintenance jobs, or account-related custom fields
only to be applied to customers that have service-level agreement, etc.

A custom field needs to be *declared* before it can be used on an entity. Managing custom field declarations
can be done through the API using the normal ``CREATE``, ``READ``, ``UPDATE``, ``DELETE`` primitives that
are on offer for all resources. Custom field declarations embody the meta-data shared between a number
of custom field values. This means that changes made to the declaration apply to all the corresponding values.
Declarations have a number of properties: display name, position (indicating the order in which it is to be
displayed on a UI), a *type* (one of ``Text``, ``Number``, ``CheckBox``, ``Dropdown``, ``Date``, or ``Time``),
and an optional default value. For ``Asset`` and ``Job`` custom field declarations, there are additional
properties, such as whether the instances are synced down to the mobiles, whether they can be updated on the mobile etc.

    .. code-block:: javascript

      {
        "entityClass": "Job",
        "uuid": "00769539cf7242f799b730cb29b81387",
        "key": "svc_det"
        "name": "Service Detail",
        "type": "Dropdown",
        "options": [
          "Maintenance",
          "Installation",
          "Repair"
        ],
        "defaultValue": [
          "Maintenance"
        ],
        "position": 2,
        "displayOnInvoice": false,
        "readonlyOnDevice": false,
        "barcodeScannable": false,
        "syncable": true,
        "displayOnPdf": true
      }

Custom field values are specified in a substructure which is a mapping from custom field declaration
*key* (used as identifier) to values (which naturally must correspond to the *types* set in the declarations).
Value of the key to be used as identifier can be specified by the user. Otherwise, on creating a *custom field declaration*
an identifier is minted (UUID) and its value is assigned to the key to identify custom field on an entity.


    .. code-block:: javascript

      {
        ...
        "customFields": {
          "svc_det": "Installation",
          ...
        }
      }

Only *custom fields* that have been explicitly assigned a value will show up in this mapping, irrespective of
whether a default value has been specified on the declaration. Default values are only used on the UI as
a convenience to minimize key strokes. This means that for custom fields there is a *difference* between
a custom field that is *not set*, and a custom field that is *set* to the value *null*.
The latter implies that the custom field is applicable to the particular entity and will show up by default
on the different UIs, while the former would mean that user intervention is needed to add the custom field to the entity.

This leads to a very flexible model. For example, on scheduling a job, the *service detail* custom field
could be added to the job and set to *null*. This would make a dropdown appear on the mobile device's screen,
labelled "Service Detail", with options "Maintenance", "Installation", "Repair", but none of them would be selected.
The field technician would have to tap the dropdown and select an option to set it to a particular value.
Alternatively, if the *service detail* custom field would be added with the value "Installation",
then that drop down would also appear on the mobile device but the dropdown would have the "Installation"
option pre-selected. The field technician would not have to tap the dropdown to set a value, but of course this
may mean that if it is overlooked the wrong value may be stored. On the other hand, if the custom field is not listed
on the job, it will not show up on the UI at all. This means that the UI is not cluttered with custom fields that have
no bearing on the entity. The field technician can still add it to the job though but it may require a few more taps.
If a default value is specified on the declaration, adding a custom field on the mobile device or the WebApp to an entity,
sets this value without further clicks needed.

Attempts to specify an undeclared *custom field* on an entity result in an **APIValidationError**.
Similarly, attempts to specify a value of a type other than the one specified in the declaration result in
an **APIValidationError**. The error message should accurately specify the nature of the problem in these cases.

Attempts to set a *custom field* as *barcodeScannable* without a *type* of *Text* will result in an **APIValidationError**.

Custom Field Declaration
------------------------


How to retrieve existing custom fields
......................................

.. http:get:: /settings/customfields/

   Retrieve general information about user's custom fields

   **Sample request**:

   .. sourcecode:: http

      GET /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

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

      {
        "count": 23,
        "pageSize": 20,
        "items": [
          {
            "displayOnInvoice": false,
            "entityClass": "Job",
            "name": "Priority",
            "defaultValue": "Select One",
            "readonlyOnDevice": false,
            "barcodeScannable": false,
            "displayOnPdf": false,
            "syncable": false,
            "key": "4c346afb78bd48588ed8e313c6ab7c5d",
            "position": 1,
            "type": "Dropdown",
            "options": [
              "Select One",
              "Draw",
              "Opt 2",
              "Opt 3"
            ],
            "uuid": "4c346afb78bd48588ed8e313c6ab7c5d"
          },
          {
            "displayOnInvoice": false,
            "entityClass": "Job",
            "name": "Check",
            "defaultValue": false,
            "readonlyOnDevice": false,
            "displayOnPdf": false,
            "syncable": false,
            "key": "9814cdab747c42309f641a716016dca4",
            "position": 2,
            "type": "CheckBox",
            "uuid": "9814cdab747c42309f641a716016dca4",
            "barcodeScannable": false
           },
          {
            "displayOnInvoice": true,
            "entityClass": "Job",
            "name": "Test",
            "defaultValue": "0",
            "readonlyOnDevice": false,
            "displayOnPdf": false,
            "syncable": true,
            "key": "f30e7c56fafd4c8aa5317168de70cd8b",
            "position": 0,
            "type": "Text",
            "uuid": "f30e7c56fafd4c8aa5317168de70cd8b"
            "barcodeScannable": true
          }
        ],
        "sortedBy": [],
        "page": 0
      }

   :>json int number: Total number of declared custom fields
   :>json int pageSize: How many items should be displayed per page
   :>json array items: JSON objects representing custom fields
   :>json array sortedBy: An array of strings
   :>json int page: Page number


How to retrieve existing custom field
.....................................

In order to retrieve a custom field user has to send GET request
with specified custom filed UUID number (custom field reference number).

.. http:get:: /settings/customfields/(customfield_ref)

   Retrieve general information about given custom field.

   **Sample request**:

   .. sourcecode:: http

      GET /settings/customfields/4c346afb78bd48588ed8e313c6ab7c5d HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

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

      {
        "displayOnInvoice": false,
        "entityClass": "Job",
        "name": "Priority",
        "defaultValue": "Select One",
        "readonlyOnDevice": false,
        "barcodeScannable": false,
        "displayOnPdf": false,
        "syncable": false,
        "key": "4c346afb78bd48588ed8e313c6ab7c5d",
        "position": 1,
        "type": "Dropdown",
        "options": [
          "Select One",
          "Draw",
          "Opt 2",
          "Opt 3",
          "Choice5",
          "Choice6"
        ],
        "uuid": "4c346afb78bd48588ed8e313c6ab7c5d"
      }


How to update a custom field
............................

In order to update a given custom field user has to send a PUT request
with a UUID of the custom field (reference number) and a request body.
Below are examples of updating custom fields of different types.

.. http:get:: /settings/customfields/(customfield_ref)

   Custom field type ``dropdown`` before an update.

   **Request**:

   .. sourcecode:: http

      GET /settings/customfields/4c346afb78bd48588ed8e313c6ab7c5d HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

   **Response**:

   .. sourcecode:: http

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

      {
        "displayOnInvoice": false,
        "entityClass": "Job",
        "name": "Priority",
        "defaultValue": "Select One",
        "readonlyOnDevice": false,
        "displayOnPdf": false,
        "syncable": false,
        "key": "4c346afb78bd48588ed8e313c6ab7c5d",
        "barcodeScannable": false,
        "position": 1,
        "type": "Dropdown",
        "options": [
          "Select One",
          "Draw",
          "Opt 2",
          "Opt 3",
          "Choice5",
          "Choice6",
          "Last Option"
        ],
        "uuid": "4c346afb78bd48588ed8e313c6ab7c5d"
      }

.. http:put:: /settings/customfields/(customfield_ref)

   Add new drop down options and change custom field position.

   **Sample request**:

   .. sourcecode:: http

      PUT /settings/customfields/4c346afb78bd48588ed8e313c6ab7c5d HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "displayOnInvoice": false,
        "entityClass": "Job",
        "name": "Priority",
        "defaultValue": "Select One",
        "readonlyOnDevice": false,
        "barcodeScannable": false,
        "displayOnPdf": false,
        "syncable": false,
        "key": "4c346afb78bd48588ed8e313c6ab7c5d",
        "position": 10,
        "type": "Dropdown",
        "options": [
          "Select One",
          "Draw",
          "Opt 2",
          "Opt 3",
          "Choice5",
          "Choice6",
          "Last Option",
          "OptionX",
          "OptionY"
        ],
        "uuid": "4c346afb78bd48588ed8e313c6ab7c5d"
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT


.. http:get:: /settings/customfields/(customfield_ref)

   Custom field type ``text`` before an update.

   **Sample request**:

   .. sourcecode:: http

      GET /settings/customfields/f54facbfe3da48e6b57a216d9deb1003 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

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

      {
        "entityClass": "Asset",
        "name": "Asset Name",
        "defaultValue": "0",
        "readonlyOnDevice": false,
        "barcodeScannable": false,
        "displayOnPdf": false,
        "syncable": true,
        "key": "f54facbfe3da48e6b57a216d9deb1003",
        "position": 2,
        "type": "Text",
        "uuid": "f54facbfe3da48e6b57a216d9deb1003"
      }

.. http:put:: /settings/customfields/(customfield_ref)

   Update custom field type ``text``: ``defaultValue``, ``position``, ``displayOnInvoice``

   **Sample request**:

   .. sourcecode:: http

      GET /settings/customfields/f54facbfe3da48e6b57a216d9deb1003 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "entityClass": "Asset",
        "name": "Asset Name",
        "defaultValue": "TestValue",
        "readonlyOnDevice": false,
        "barcodeScannable": false,
        "displayOnPdf": false,
        "syncable": true,
        "key": "f54facbfe3da48e6b57a216d9deb1003",
        "position": 5,
        "type": "Text",
        "uuid": "f54facbfe3da48e6b57a216d9deb1003"
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT


How to create custom fields
...........................


.. http:post:: /settings/customfields/

   Create custom field entity class ``Customer``, type ``Text``

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "entityClass": "Customer",
        "name": "TestCustomField",
        "type": "Text"
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://api.fieldaware.net/settings/customfields/58efd6c369f74a88a2f0537a566d37da"

      {
        "link": {
          "url": "/settings/customfields/58efd6c369f74a88a2f0537a566d37da",
          "rel": "detail"
        },
        "uuid": "58efd6c369f74a88a2f0537a566d37da"
      }


.. http:post:: /settings/customfields/

   Create custom field entity class ``Task``, type ``Dropdown`` with a custom ``key`` attribute.

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "key": "azs-21",
        "entityClass": "Task",
        "name": "Task Type",
        "type": "Dropdown",
        "options": [
          "Simple",
          "Moderate",
          "Hard"
        ],
        "defaultValue": "Moderate"
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://api.fieldaware.net/settings/customfields/6f8e04dc5416408aad4e3d562a33b40f"

      {
        "link": {
          "url": "/settings/customfields/6f8e04dc5416408aad4e3d562a33b40f",
          "rel": "detail"
        },
        "uuid": "6f8e04dc5416408aad4e3d562a33b40f"
      }


.. http:post:: /settings/customfields/

   Create custom field entity class ``Activity Job``, type ``CheckBox``

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "entityClass": "Job",
        "name": "Require permit?",
        "type": "CheckBox",
        "defaultValue": true,
        "readonlyOnDevice": false,
        "barcodeScannable": false,
        "syncable": false
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://api.fieldaware.net/settings/customfields/ed523838daf74d70ab46389c466ea6e0"

      {
        "link": {
          "url": "/settings/customfields/ed523838daf74d70ab46389c466ea6e0",
          "rel": "detail"
        },
        "uuid": "ed523838daf74d70ab46389c466ea6e0"
      }


.. http:post:: /settings/customfields/

   Create custom field entity class ``Activity Item``, type ``Date``

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "entityClass": "Item",
        "name": "Quote Expire on:",
        "type": "Date",
        "defaultValue": "2015-02-09"
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://apiqa2.fieldaware.net/settings/customfields/a35220f65dd640b5819d4e0569c6f23a"

      {
        "link": {
          "url": "/settings/customfields/a35220f65dd640b5819d4e0569c6f23a",
          "rel": "detail"
        },
        "uuid": "a35220f65dd640b5819d4e0569c6f23a"
      }


.. http:post:: /settings/customfields/

   Create custom field entity class ``Asset``, type ``Time``

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "entityClass": "Asset",
        "name": "Asset Time",
        "defaultValue": "21:00:15",
        "readonlyOnDevice": false,
        "syncable": false,
        "displayOnPdf": false,
        "barcodeScannable": false,
        "type": "Time"
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://api.fieldaware.net/settings/customfields/e7d0be973a99406b9ddb179cfb254ce8"

      {
        "link": {
          "url": "/settings/customfields/e7d0be973a99406b9ddb179cfb254ce8",
          "rel": "detail"
        },
        "uuid": "e7d0be973a99406b9ddb179cfb254ce8"
      }


.. http:post:: /settings/customfields/

   Create custom field entity class ``Invoice``, type ``Text``

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "entityClass": "Invoice",
        "name": "Invoice param",
        "type": "Text",
        "defaultValue": "ACD-12-34"
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://apiqa2.fieldaware.net/settings/customfields/b648e8828f0644aba49e2b5563113608"

      {
        "link": {
          "url": "/settings/customfields/b648e8828f0644aba49e2b5563113608",
          "rel": "detail"
        },
        "uuid": "b648e8828f0644aba49e2b5563113608"
      }


.. http:post:: /settings/customfields/

   Create custom field entity class ``Supplier``, type ``Dropdown``

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "entityClass": "Supplier",
        "name": "MarkSupp Ltd.",
        "defaultValue": "Makita",
        "type": "Dropdown",
        "options": [
          "Bosh",
          "Makita",
          "JCB",
          "BlackDecker",
          "Polkita",
        ]
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://apiqa2.fieldaware.net/settings/customfields/b648e8828f0644aba49e2b5563113608"

      {
        "link": {
          "url": "/settings/customfields/b648e8828f0644aba49e2b5563113608",
          "rel": "detail"
        },
        "uuid": "b648e8828f0644aba49e2b5563113608"
      }


.. http:post:: /settings/customfields/

   Create custom field entity class ``Location``, type ``Number``

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "entityClass": "Location",
        "name": "Accessed: ",
        "type": "Number",
        "defaultValue": 0
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://api.fieldaware.net/settings/customfields/b475bf7611c84df2a56a10b138ff8973"

      {
        "link": {
          "url": "/settings/customfields/b475bf7611c84df2a56a10b138ff8973",
          "rel": "detail"
        },
        "uuid": "b475bf7611c84df2a56a10b138ff8973"
      }


.. http:post:: /settings/customfields/

   Create custom field entity class ``Contact``, type ``CheckBox``

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "entityClass": "Contact",
        "name": "Vip:",
        "type": "CheckBox",
        "defaultValue": false
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://api.fieldaware.net/settings/customfields/31977dc286ae4ef8866f187b089fa160"

      {
        "link": {
          "url": "/settings/customfields/31977dc286ae4ef8866f187b089fa160",
          "rel": "detail"
        },
        "uuid": "31977dc286ae4ef8866f187b089fa160"
      }


.. http:post:: /settings/customfields/

   Create custom field entity class ``User``, type ``Time``

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "entityClass": "User",
        "name": "Start fl",
        "type": "Time"
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://api.fieldaware.net/settings/customfields/ccd79e75d2b44e0bb128caa0176e1bb2"

      {
        "link": {
          "url": "/settings/customfields/ccd79e75d2b44e0bb128caa0176e1bb2",
          "rel": "detail"
        },
        "uuid": "ccd79e75d2b44e0bb128caa0176e1bb2"
      }


How to update custom fields
...........................

In order to update a custom field the user has to send a PUT request with a json
body consisting of all elements (the same payload as the POST request) or
only elements that will be updated.

HTTP requests to create, update and retrieve the resource:

1. Create resource
2. Update resource (full JSON body)
3. Update resource (only fields that have to be updated)
4. Retrieve (and verify) that the resource is updated

.. http:post:: /settings/customfields/

   Create a new custom field

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "entityClass": "Asset",
        "name": "Asset Name",
        "defaultValue": "TestValue",
        "readonlyOnDevice": false,
        "barcodeScannable": false,
        "displayOnPdf": false,
        "syncable": true,
        "key": "f54facbfe3da48e6b57a216d9deb1003",
        "position": 2,
        "type": "Text",
        "uuid": "f54facbfe3da48e6b57a216d9deb1003"
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://api.fieldaware.net/settings/customfields/4c346afb78bd48588ed8e313c6ab7c5d"

      {
        "link": {
          "url": "/settings/customfields/4c346afb78bd48588ed8e313c6ab7c5d",
          "rel": "detail"
        },
        "uuid": "4c346afb78bd48588ed8e313c6ab7c5d"
      }

.. http:put:: /settings/customfields/(customfield_ref)

   Update the custom filed by sending full JSON payload with updated fields.
   Updated fileds: ``defaultValue``, ``syncable``

   **Sample request**:

   .. sourcecode:: http

      PUT /settings/customfields/4c346afb78bd48588ed8e313c6ab7c5d HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "entityClass": "Asset",
        "name": "Asset Name",
        "defaultValue": "ChangedDefaultValue",
        "readonlyOnDevice": false,
        "barcodeScannable": false,
        "displayOnPdf": false,
        "syncable": false,
        "key": "f54facbfe3da48e6b57a216d9deb1003",
        "position": 2,
        "type": "Text",
        "uuid": "f54facbfe3da48e6b57a216d9deb1003"
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT
      Content-Type: application/json


.. http:put:: /settings/customfields/(customfield_ref)

   Update the custom filed by sending JSON payload that consist of fields that user
   wants to update.
   Updated fields: ``displayOnInvoice``, ``name``, ``defaultValue``

   **Sample request**:

   .. sourcecode:: http

      PUT /settings/customfields/4c346afb78bd48588ed8e313c6ab7c5d HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "displayOnPdf": true,
        "name": "Asset Name Updated",
        "defaultValue": "ChangedDefaultValue"
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT
      Content-Type: application/json


.. http:get:: /settings/customfields/(customfield_ref)

   Verify that the custom field is updated.

   **Sample request**:

   .. sourcecode:: http

      GET /settings/customfields/4c346afb78bd48588ed8e313c6ab7c5d HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

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

      {
        "entityClass": "Asset",
        "name": "Asset Name Updated",
        "defaultValue": "ChangedDefaultValue",
        "readonlyOnDevice": false,
        "barcodeScannable": false,
        "displayOnPdf": true,
        "syncable": false,
        "key": "f54facbfe3da48e6b57a216d9deb1003",
        "position": 2,
        "type": "Text",
        "uuid": "f54facbfe3da48e6b57a216d9deb1003"
      }


How to delete custom fields
...........................

User can delete the custom field by sending DELETE request with
the custom field UUID identifier (customfiled_ref).

.. http:delete:: /settings/customfields/(customfield_ref)

   Delete custom field with given UUID (reference number)

   **Sample request**:

   .. sourcecode:: http

      DELETE /settings/customfields/f54facbfe3da48e6b57a216d9deb1003 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT


Creating Entities with Custom Fields
------------------------------------

In order to create an entity with custom fields user has to:

1. create custom fields of given type and entity class
2. create resource with the custom fields

.. http:post:: /settings/customfields/

   Create custom field ``Job``, type ``Text``

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "entityClass": "Job",
        "name": "Require permit",
        "type": "Text",
        "defaultValue": "ACT-12-",
        "readonlyOnDevice": false,
        "barcodeScannable": false,
        "syncable": false
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://apiqa2.fieldaware.net/settings/customfields/50dd8d345e5248b2a3b1b2b162ebb5ce"

      {
        "link": {
          "url": "/settings/customfields/50dd8d345e5248b2a3b1b2b162ebb5ce",
          "rel": "detail"
        },
        "uuid": "50dd8d345e5248b2a3b1b2b162ebb5ce"
      }


.. http:post:: /settings/customfields/

   Create custom field ``Job``, type ``CheckBox``

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "entityClass": "Job",
        "name": "Oncall?",
        "type": "CheckBox",
        "defaultValue": false
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://api.fieldaware.net/settings/customfields/8704814e76d34827a43f24ea7b2be431"

      {
        "link": {
          "url": "/settings/customfields/8704814e76d34827a43f24ea7b2be431",
          "rel": "detail"
        },
        "uuid": "8704814e76d34827a43f24ea7b2be431"
      }


.. http:post:: /job/

   Create a ``Job`` with newly created custom fields.

   **Sample request**:

   .. sourcecode:: http

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

      {
        "scheduledOn": "2014-12-12T00:00:00",
        "description": "Fix the valve no 23-2/s",
        "estDuration": 120,
        "location": {
          "uuid": "757ac7fb6d184c499b760a44ad123f6b"
        },
        "customFields": {
           "50dd8d345e5248b2a3b1b2b162ebb5ce": "Text Example",
           "8704814e76d34827a43f24ea7b2be431": true
        }
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://apiqa2.fieldaware.net/job/b830f7c6b56c4781919aa05e548210a9"

      {
        "link": {
          "url": "https://api.fieldaware.net/job/b830f7c6b56c4781919aa05e548210a9",
          "rel": "detail"
        },
        "uuid": "b830f7c6b56c4781919aa05e548210a9"
      }


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

   Verify the ``Job`` with custom fields is created.

   **Sample request**:

   .. sourcecode:: http

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

   **Sample response**:

   .. sourcecode:: http

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

      {
        "tasks": [],
        "revenue": 0,
        "jobId": "J1858",
        "invoice": null,
        "jobLead": null,
        "scheduledOn": "2014-12-12T00:00:00+00:00",
        "labor": [],
        "uuid": "b830f7c6b56c4781919aa05e548210a9",
        "crew": [],
        "state": [
          "scheduled"
        ],
        "location": {
          "uuid": "757ac7fb6d184c499b760a44ad123f6b",
          "locality": "Commerce",
          "country": null,
          "region": "CA",
          "postcode": "90040",
          "streetName": "9993 QA Ave., Suite 288",
          "name": "Andrew Industrial Ltd."
        },
        "completedOn": null,
        "customFields": {
          "8704814e76d34827a43f24ea7b2be431": true,
          "50dd8d345e5248b2a3b1b2b162ebb5ce": "Text Example"
        },
        "asset": null,
        "startedOn": null,
        "description": "Fix the valve no 23-2/s",
        "estDuration": 120,
        "pre_signature": null,
        "customer": {
          "uuid": "641e352bd0ae4e608040ee49bc7c4ed9",
          "name": "9993 QA Ave., Suite 288",
          "customerId": 127
        },
        "createdOn": "2014-10-21T15:46:58+00:00",
        "contact": null,
        "signature": null
      }


.. http:post:: /settings/customfields/

   Create custom field ``Job``, type ``Text`` with custom key attribute.

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "key": "job-key-text",
        "entityClass": "Job",
        "name": "Require permit",
        "type": "Text",
        "defaultValue": "ACT-12-",
        "readonlyOnDevice": false,
        "barcodeScannable": false,
        "syncable": false
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://apiqa2.fieldaware.net/settings/customfields/50dd8d345e5248b2a3b1b2b162ebb5ce"

      {
        "link": {
          "url": "/settings/customfields/50dd8d345e5248b2a3b1b2b162ebb5ce",
          "rel": "detail"
        },
        "uuid": "50dd8d345e5248b2a3b1b2b162ebb5ce"
      }


.. http:post:: /settings/customfields/

   Create custom field ``Job``, type ``CheckBox``

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json

      {
        "key": "job-key-checkbox",
        "entityClass": "Job",
        "name": "Oncall?",
        "type": "CheckBox",
        "defaultValue": false
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://api.fieldaware.net/settings/customfields/8704814e76d34827a43f24ea7b2be431"

      {
        "link": {
          "url": "/settings/customfields/8704814e76d34827a43f24ea7b2be431",
          "rel": "detail"
        },
        "uuid": "8704814e76d34827a43f24ea7b2be431"
      }


.. http:post:: /job/

   Create a ``Job`` with newly created custom fields. Note that custom fields are now identified by ``key`` attributes.

   **Sample request**:

   .. sourcecode:: http

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

      {
        "scheduledOn": "2014-12-12T00:00:00",
        "description": "Fix the valve no 23-2/s",
        "estDuration": 120,
        "location": {
          "uuid": "757ac7fb6d184c499b760a44ad123f6b"
        },
        "customFields": {
           "job-key-text": "Text Example",
           "job-key-checkbox": true
        }
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://apiqa2.fieldaware.net/job/b830f7c6b56c4781919aa05e548210a9"

      {
        "link": {
          "url": "https://api.fieldaware.net/job/b830f7c6b56c4781919aa05e548210a9",
          "rel": "detail"
        },
        "uuid": "b830f7c6b56c4781919aa05e548210a9"
      }


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

   Verify the ``Job`` with custom fields is created.

   **Sample request**:

   .. sourcecode:: http

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

   **Sample response**:

   .. sourcecode:: http

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

      {
        "tasks": [],
        "revenue": 0,
        "jobId": "J1858",
        "invoice": null,
        "jobLead": null,
        "scheduledOn": "2014-12-12T00:00:00+00:00",
        "labor": [],
        "uuid": "b830f7c6b56c4781919aa05e548210a9",
        "crew": [],
        "state": [
          "scheduled"
        ],
        "location": {
          "uuid": "757ac7fb6d184c499b760a44ad123f6b",
          "locality": "Commerce",
          "country": null,
          "region": "CA",
          "postcode": "90040",
          "streetName": "9993 QA Ave., Suite 288",
          "name": "Andrew Industrial Ltd."
        },
        "completedOn": null,
        "customFields": {
          "job-key-checkbox": true,
          "job-key-text": "Text Example"
        },
        "asset": null,
        "startedOn": null,
        "description": "Fix the valve no 23-2/s",
        "estDuration": 120,
        "pre_signature": null,
        "customer": {
          "uuid": "641e352bd0ae4e608040ee49bc7c4ed9",
          "name": "9993 QA Ave., Suite 288",
          "customerId": 127
        },
        "createdOn": "2014-10-21T15:46:58+00:00",
        "contact": null,
        "signature": null
      }


Common API errors when creating custom fields
---------------------------------------------

Malformed JSON request body (payload)
.....................................

.. http:post:: /settings/customfields/

   In this example user forgot to use quotation mark after ``defaultValue``.

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json
      Cache-Control: no-cache

      {
        "entityClass": "Supplier",
        "name": "MarkSupp Ltd.",
        "defaultValue: "Makita",
        "type": "Dropdown",
        "options": [
          "Bosh",
          "Makita",
          "JCB",
          "BlackDecker",
          "Polkita"
        ]
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 400 BAD REQUEST
      Content-Type: application/json

      {
        "error": {
          "message": "Request body contains malformed JSON data: Expecting ':' delimiter: line 4 column 25 (char 94)",
          "name": "APIMalformedPayload"
        }
      }


Attempt to change drop down options
...................................

.. http:put:: /settings/customfields/

   In this example user tries to add a new option and remove old from the drop down.

   **Sample request**:

   .. sourcecode:: http

      POST /settings/customfields/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token d943a51d68c44ca38cab9abda20a4d18
      Accept: application/json
      Cache-Control: no-cache

      {
        "entityClass": "Supplier",
        "name": "MarkSupp",
        "defaultValue: "Makita",
        "type": "Dropdown",
        "options": [
          "Bosh",
          "Makita",
          "JCB",
          "BlackDecker",
          "Wrangler"
        ]
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 405 METHOD NOT ALLOWED
      Content-Type: application/json

      {
        "message": "The method is not allowed for the requested URL."
      }


Attempt to create duplicated custom field
.........................................

When user sends the same POST requests to create a duplicated custom filed, FAAPI returns
APIValidationError and an error message indicating the root cause of the error.

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 422 UNPROCESSABLE ENTITY
      Content-Type: application/json

      {
        "error": {
          "message": "Invalid Customfield declaration: Duplicate name 'MarkSupp Ltd.' (DUPLICATE NAME)",
          "name": "APIValidationError"
        }
      }