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

List Custom Field Declarations
------------------------------

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

   List the custom field declarations for all the entity types.

   **Sample request**:

   .. sourcecode:: http

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

   :query sortedBy: Available sorting criteria: ``type``, ``entityClass``, ``key``, ``name``
   :query type: A filtering value for ``type``
   :query entityClass: A filtering value for ``entityClass``
   :query key: A filtering value for ``key``
   :query name: A filtering value for ``name``

   **Sample response**:

   .. sourcecode:: http

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

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

   :>json int count: Number of custom fields
   :>json int pageSize: Number of items per page
   :>json array items: JSON objects representing custom fields
   :>json array sortedBy: An array of strings (sorting criteria)
   :>json int page: Page number
   :>json int pageSize: Indicates how many items per page is returned



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

   Custom fields of type ``Text`` can hold up to 10,000 unicode characters. Custom fields of type ``Number``
   will can contain integer or decimal numbers with at least 20 digits to the left of the decimal point,
   and 10 to the right. For a declaration of type ``Dropdown``, the ``defaultValue`` must be included
   in the list of ``options`` and they are both required. Value of the ``key`` attribute is set to the same
   value as ``uuid``, unless the ``key`` attribute-value pair is included in the payload.


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

   Create a minimal custom field declaration: type ``Text``, entity ``Customer``.

   **Sample request**:

   .. sourcecode:: http

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

      {
        "entityClass": "Customer",
        "name": "LO Card id",
        "type": "Text"
      }

   :<json string entityClass: Entity type for which the custom field applies (mandatory, see :ref:`Create Custom Field Declaration <entities-table>` table for possible values)
   :<json string name: Name to be used by GUI (mandatory)
   :<json string type: type of values to be stored, one of ``Text``, ``Number``, ``CheckBox``, ``Dropdown``, ``Date``, or ``Time`` (mandatory)
   :<json boolean availableOnJob: whether given custom field should be settable on a job (see :ref:`Create Custom Field Declaration <entities-table>` table for supported ``entityClass`` values)

   **Sample response**:

   .. sourcecode:: http

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

      {
        "link": {
          "url": "/settings/customfields/e54a6892cc7a4d92b950258941572714",
          "rel": "detail"
        },
        "uuid": "e54a6892cc7a4d92b950258941572714"
         "entityClass": "Job",
         "uuid": "00769539cf7242f799b730cb29b81387",
         "key": "svc_det",
         "name": "Svc Detail",
         "type": "Dropdown",
         "options": [
           "Maintenance",
           "Installation",
           "Repair"
         ],
         "defaultValue": "Maintenance",
         "displayOnInvoice": false,
         "readonlyOnDevice": false,
         "syncable": true,
         "displayOnPdf": true
      }

   :>json obj link: JSON object representing a path to the created custom field
   :>json string uud: UUID of the created custom field


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

   Create a minimal custom field declaration with type ``Text``, entity ``Customer`` and attribute ``key``.

   **Sample request**:

   .. sourcecode:: http

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

      {
        "key": "my_custom_reference_key",
        "entityClass": "Customer",
        "name": "LO Card id",
        "type": "Text"
      }

   :<json string key: Attribute that (along with uuid) identifies the custom field.
   :<json string entityClass: Entity type for which the custom field applies (mandatory)
   :<json string name: Name to be used by GUI (mandatory)
   :<json string type: type of values to be stored, one of ``Text``, ``Number``, ``CheckBox``, ``Dropdown``,
       ``Date``, or ``Time`` (mandatory)

   **Sample response**:

   .. sourcecode:: http

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

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

   :>json obj link: JSON object representing a path to the created custom field
   :>json string uud: UUID of the created custom field


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

   Create a custom field declaration: type ``CheckBox``, entity ``Contact``.

   **Sample request**:

   .. sourcecode:: http

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

      {
        "key": "cfcontacts001",
        "entityClass": "Contact",
        "name": "VIP",
        "type": "CheckBox",
        "defaultValue": false
      }

   :<json string key: Custom attribute
   :<json string entityClass: Entity type for which the custom field applies (mandatory)
   :<json string name: Name to be used by GUI (mandatory)
   :<json string type: Type of the value to be stored, in this example ``CheckBox`` (mandatory)
   :<json boolean defaultValue: Default value of the custom field

   **Sample response**:

   .. sourcecode:: http

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

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

   :>json obj link: JSON object representing a path to the created custom field
   :>json string uud: UUID of the created custom field


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

    Create a custom field declaration: type ``Date``, entity ``Item``.

    **Sample request**:

    .. sourcecode:: http

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

       {
         "key": "item-date-key"
         "entityClass": "Item",
         "name": "Expire on: ",
         "type": "Date",
         "defaultValue": "2020-02-09"
       }

    :<json string entityClass: Entity type for which the custom field applies (mandatory)
    :<json string name: Name to be used by GUI (mandatory)
    :<json string type: type of values to be stored, one of ``Text``, ``Number``, ``CheckBox``, ``Dropdown``,
        ``Date``, or ``Time`` (mandatory)
    :<json string defaultValue: Date in ISO format string

    **Sample response**:

    .. sourcecode:: http

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

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

    :>json obj link: JSON object representing a path to the created custom field
    :>json string uud: UUID of the created custom field


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

    Create a custom field declaration: type ``Dropdown``, entity ``Supplier``.

    **Sample request**:

    .. sourcecode:: http

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

       {
         "key": "cf-dropdown-001",
         "entityClass": "Supplier",
         "name": "Supp:",
         "defaultValue": "Makita",
         "type": "Dropdown",
         "options": [
           "Bosh",
           "Makita",
           "JCB",
           "BlackDecker",
           "Polkita"
         ]
       }

    :<json string entityClass: Entity type for which the custom field applies (mandatory)
    :<json string name: Name to be used by GUI (mandatory)
    :<json string defaultValue: The default value must be included in the list of ``options`` (mandatory)
    :<json string type: Type of values to be stored, in this example ``Dropdown`` (mandatory)
    :<json array options: A list of strings, dropdown options

    **Sample response**:

    .. sourcecode:: http

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

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

    :>json obj link: JSON object representing a path to the created custom field
    :>json string uud: UUID of the created custom field


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

    Create a custom field declaration: type ``Text``, entity ``Task``.

    **Sample request**:

    .. sourcecode:: http

        POST /settings/customfields/ HTTP/1.1
        Accept: application/json, */*
        Accept-Encoding: gzip, deflate
        Authorization: Token b76c4928f3ee4bd79bcc2baacf59bbca
        Connection: keep-alive
        Content-Length: 94
        Content-Type: application/json
        Host: localhost:8085

        {
            "availableOnJob": true,
            "entityClass": "Task",
            "name": "category",
            "type": "Text"
        }


    **Sample response**:

    .. sourcecode:: http

        HTTP/1.0 201 CREATED
        Content-Length: 299
        Content-Type: application/json
        Date: Mon, 12 Dec 2016 16:48:03 GMT
        Location: https://api.fieldaware.net/settings/customfields/5a20f240a2904282a29fe536ad7b45d4

        {
            "availableOnJob": true,
            "defaultValue": "",
            "entityClass": "Task",
            "key": "5a20f240a2904282a29fe536ad7b45d4",
            "link": {
                "rel": "detail",
                "url": "/settings/customfields/5a20f240a2904282a29fe536ad7b45d4"
            },
            "name": "category",
            "position": 14,
            "type": "Text",
            "uuid": "5a20f240a2904282a29fe536ad7b45d4"
        }



.. _entities-table:

    .. note::

        There are additional boolean attributes (``syncable``,
        ``readonlyOnDevice``, ``displayOnInvoice``, ``displayOnPdf`` and
        ``availableOnJob``) that are potentially available to a custom field
        declaration. Depending on the declaration's value of ``entityClass``,
        any of these attributes may or may not be available in the declaration
        response payloads or request payloads. The following table defines
        their availability for the payload ``GET`` response and
        ``POST``/``PUT`` requests.

    .. table::

      +---------------+----------+------------------+--------------------+-------------------+----------------+
      | entityClass   | syncable | displayOnInvoice |  readonlyOnDevice  | displayOnPdf      | availableOnJob |
      +===============+==========+==================+====================+===================+================+
      |     Job       |    YES   |    YES           |       YES          |      YES          | NO             |
      +---------------+----------+------------------+--------------------+-------------------+----------------+
      |     Asset     |    YES   |      NO          |       YES          |      YES          | NO             |
      +---------------+----------+------------------+--------------------+-------------------+----------------+
      |     Invoice   |      NO  |      NO          |         NO         |        NO         | NO             |
      +---------------+----------+------------------+--------------------+-------------------+----------------+
      |     Supplier  |      NO  |      NO          |         NO         |        NO         | NO             |
      +---------------+----------+------------------+--------------------+-------------------+----------------+
      |     Customer  |      NO  |      NO          |         NO         |        NO         | NO             |
      +---------------+----------+------------------+--------------------+-------------------+----------------+
      |     Task      |      NO  |      NO          |         NO         |        NO         | YES            |
      +---------------+----------+------------------+--------------------+-------------------+----------------+
      |     Item      |      NO  |      NO          |         NO         |        NO         | YES            |
      +---------------+----------+------------------+--------------------+-------------------+----------------+
      |     Location  |      NO  |      NO          |         NO         |        NO         | NO             |
      +---------------+----------+------------------+--------------------+-------------------+----------------+
      |     Contact   |      NO  |      NO          |         NO         |        NO         | NO             |
      +---------------+----------+------------------+--------------------+-------------------+----------------+
      |     User      |      NO  |      NO          |         NO         |        NO         | NO             |
      +---------------+----------+------------------+--------------------+-------------------+----------------+




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

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

    Retrieve a given custom field declaration.

    **Sample request**:

    .. sourcecode:: http

       GET /settings/customfields/e54a6892cc7a4d92b950258941572714 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": "Job",
         "uuid": "00769539cf7242f799b730cb29b81387",
         "key": "svc_det",
         "name": "Svc Detail",
         "type": "Dropdown",
         "options": [
           "Maintenance",
           "Installation",
           "Repair"
         ],
         "defaultValue": "Maintenance",
         "position": 2,
         "displayOnInvoice": false,
         "readonlyOnDevice": false,
         "syncable": true,
         "displayOnPdf": true
       }

    :>json string entityClass: Name of the entity class
    :>json sting uuid: A unique identifier (UUID) of the custom field
    :>json string key: A unique identifier (UUID) of the custom filed
    :>json string name: Name of the custom field (displayed on the website/mobile device)
    :>json string type: A type of the custom field
    :>json array options: A list of strings representing options of the drop down menu
    :>json string defaultValue: Default value of the drop down option
    :>json int position: Custom field position on the page
    :>json boolean displayOnInvoice: If the custom field is displayed on an invoice for a job
    :>json boolean readonlyOnDevice: If the custom filed is read-only on a mobile device
    :>json boolean syncable: If the custom field is syncable
    :<json displayOnPdf: If the custom field is to be displayed on PDF


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

    Retrieve a given custom field declaration.

    **Sample request**:

    .. sourcecode:: http

       GET /settings/customfields/x00a6892cc7a4d92b950258941572714 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": "Item",
         "name": "Expire:",
         "defaultValue": "2015-09-09",
         "key": "x00a6892cc7a4d92b950258941572714",
         "position": 24,
         "type": "Date",
         "uuid": "x00a6892cc7a4d92b950258941572714"
       }

    :>json string entityClass: Name of the entity class
    :>json string name: Name of the custom field (displayed on the website/mobile device)
    :>json string defaultValue: Default value of the drop down option
    :>json string key: A unique identifier (UUID) of the custom filed
    :>json int position: Custom field position on the page
    :>json string type: A type of the custom field
    :>json sting uuid: A unique identifier (UUID) of the custom field


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

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

    Update a given custom field declaration. Not all of a declaration's attributes can be updated.
    For example, it is not possible to change a declaration's entity class or type.
    Note that it is possible to update the key, display name and any other meta-data attributes.
    The ``options`` of a drop-down can be modified under the condition that the ``defaultValue`` is
    one of the ``options`` values and, in case of a smaller list, none of the removed values is in use
    by any entity.

    **Sample request**:

    Updating a custom field of the type drop down by adding additional two options.

    .. sourcecode:: http

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

       {
         "defaultValue": "Select One",
         "options": [
           "Select One",
           "Draw",
           "Opt 2",
           "Opt 3",
           "Choice5",
           "Choice6"
         ]
       }

    :<json array options: A list of strings representing drop down options

    **Sample response**:

    A successful custom field update.

    .. sourcecode:: http

       HTTP/1.1 204 NO CONTENT

    **Sample response**:

    Following error responses can be returned when user tries to change (update) existing drop down options.

    .. sourcecode:: http

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

       {
         "error": {
           "message": "Default value must be one of options.",
           "name": "APIValidationError"
         }
       }

    .. sourcecode:: http

       HTTP/1.1 409 CONFLICT
       Content-Type: application/json

       {
         "error": {
           "message": "Unable to remove options: set([u'Draw']), some are in use",
           "name": "ConflictError"
         }
       }

    :>json obj error: JSON object representing error message and name
    :>json string error.message: Error message
    :>json string error.name: Name to the returned error


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

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

    Delete a given custom field declaration. All the existing instances on entities
    past and present will be deleted as well. **This action can not be undone**.

   **Sample request**:

   .. sourcecode:: http

      DELETE /settings/customfields/b888e03bef8d4a29be0a8dceb4d1e6fe HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 No Content