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.

{
  "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.

{
  ...
  "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¶

GET /settings/customfields/¶

Retrieve general information about user’s custom fields

Sample request:

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

Sample response:

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
}

Response JSON Object:

number (int) – Total number of declared custom fields
pageSize (int) – How many items should be displayed per page
items (array) – JSON objects representing custom fields
sortedBy (array) – An array of strings
page (int) – 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).

GET /settings/customfields/(customfield_ref)¶

Retrieve general information about given custom field.

Sample request:

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

Sample response:

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.

GET /settings/customfields/(customfield_ref)¶

Custom field type dropdown before an update.

Request:

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

Response:

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

PUT /settings/customfields/(customfield_ref)¶

Add new drop down options and change custom field position.

Sample request:

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:

HTTP/1.1 204 NO CONTENT

GET /settings/customfields/(customfield_ref)¶

Custom field type text before an update.

Sample request:

GET /settings/customfields/f54facbfe3da48e6b57a216d9deb1003 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": "Asset",
  "name": "Asset Name",
  "defaultValue": "0",
  "readonlyOnDevice": false,
  "barcodeScannable": false,
  "displayOnPdf": false,
  "syncable": true,
  "key": "f54facbfe3da48e6b57a216d9deb1003",
  "position": 2,
  "type": "Text",
  "uuid": "f54facbfe3da48e6b57a216d9deb1003"
}

PUT /settings/customfields/(customfield_ref)¶

Update custom field type text: defaultValue, position, displayOnInvoice

Sample request:

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:

HTTP/1.1 204 NO CONTENT

How to create custom fields¶

POST /settings/customfields/¶

Create custom field entity class Customer, type Text

Sample request:

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

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

Sample response:

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

POST /settings/customfields/¶

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

Sample request:

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:

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

POST /settings/customfields/¶

Create custom field entity class Activity Job, type CheckBox

Sample request:

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:

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

POST /settings/customfields/¶

Create custom field entity class Activity Item, type Date

Sample request:

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:

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

POST /settings/customfields/¶

Create custom field entity class Asset, type Time

Sample request:

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:

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

POST /settings/customfields/¶

Create custom field entity class Invoice, type Text

Sample request:

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:

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

POST /settings/customfields/¶

Create custom field entity class Supplier, type Dropdown

Sample request:

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:

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

POST /settings/customfields/¶

Create custom field entity class Location, type Number

Sample request:

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:

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

POST /settings/customfields/¶

Create custom field entity class Contact, type CheckBox

Sample request:

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:

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

POST /settings/customfields/¶

Create custom field entity class User, type Time

Sample request:

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:

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:

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

POST /settings/customfields/¶

Create a new custom field

Sample request:

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:

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

PUT /settings/customfields/(customfield_ref)¶

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

Sample request:

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:

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

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:

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:

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

GET /settings/customfields/(customfield_ref)¶

Verify that the custom field is updated.

Sample request:

GET /settings/customfields/4c346afb78bd48588ed8e313c6ab7c5d 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": "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).

DELETE /settings/customfields/(customfield_ref)¶

Delete custom field with given UUID (reference number)

Sample request:

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

Sample response:

HTTP/1.1 204 NO CONTENT

Creating Entities with Custom Fields¶

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

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

POST /settings/customfields/¶

Create custom field Job, type Text

Sample request:

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:

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

POST /settings/customfields/¶

Create custom field Job, type CheckBox

Sample request:

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:

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

POST /job/¶

Create a Job with newly created custom fields.

Sample request:

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:

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

GET /job/(job_ref)¶

Verify the Job with custom fields is created.

Sample request:

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

Sample response:

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
}

POST /settings/customfields/¶

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

Sample request:

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:

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

POST /settings/customfields/¶

Create custom field Job, type CheckBox

Sample request:

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:

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

POST /job/¶

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

Sample request:

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:

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

GET /job/(job_ref)¶

Verify the Job with custom fields is created.

Sample request:

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

Sample response:

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)¶

POST /settings/customfields/¶

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

Sample request:

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:

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¶

PUT /settings/customfields/¶

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

Sample request:

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:

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:

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

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