Custom Fields¶

List Custom Field Declarations¶

GET /settings/customfields/¶

List the custom field declarations for all the entity types.

Sample request:

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

Query Parameters:

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

Sample response:

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
}

Response JSON Object:

count (int) – Number of custom fields
pageSize (int) – Number of items per page
items (array) – JSON objects representing custom fields
sortedBy (array) – An array of strings (sorting criteria)
page (int) – Page number
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.

POST /settings/customfields/¶

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

Sample request:

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

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

Request JSON Object:

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

Sample response:

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
}

Response JSON Object:

link (obj) – JSON object representing a path to the created custom field
uud (string) – UUID of the created custom field

POST /settings/customfields/¶

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

Sample request:

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"
}

Request JSON Object:

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

Sample response:

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"
}

Response JSON Object:

link (obj) – JSON object representing a path to the created custom field
uud (string) – UUID of the created custom field

POST /settings/customfields/¶

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

Sample request:

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
}

Request JSON Object:

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

Sample response:

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"
}

Response JSON Object:

link (obj) – JSON object representing a path to the created custom field
uud (string) – UUID of the created custom field

POST /settings/customfields/¶

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

Sample request:

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"
}

Request JSON Object:

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

Sample response:

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"
}

Response JSON Object:

link (obj) – JSON object representing a path to the created custom field
uud (string) – UUID of the created custom field

POST /settings/customfields/¶

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

Sample request:

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"
  ]
}

Request JSON Object:

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

Sample response:

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"
}

Response JSON Object:

link (obj) – JSON object representing a path to the created custom field
uud (string) – UUID of the created custom field

POST /settings/customfields/¶

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

Sample request:

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:

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"
}

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.

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¶

GET /settings/customfields/(declaration_ref)¶

Retrieve a given custom field declaration.

Sample request:

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

Sample response:

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
}

Response JSON Object:

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

Request JSON Object:

displayOnPdf – If the custom field is to be displayed on PDF

GET /settings/customfields/(declaration_ref)¶

Retrieve a given custom field declaration.

Sample request:

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

Sample response:

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"
}

Response JSON Object:

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

Update Custom Field Declaration¶

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.

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"
  ]
}

Request JSON Object:

options (array) – A list of strings representing drop down options

Sample response:

A successful custom field update.

HTTP/1.1 204 NO CONTENT

Sample response:

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

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

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

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

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

Response JSON Object:

error (obj) – JSON object representing error message and name
error.message (string) – Error message
error.name (string) – Name to the returned error

Delete Custom Field Declaration¶

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:

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

Sample response:

HTTP/1.1 204 No Content