Create Web App Custom Field

Create a new Web App custom field.

Request

  • Method: POST
  • Server: https://[app key here]-[site_ID here]-apps.worldsecuresystems.com. Take a look at the Authorize your API calls document for more info on how this URL is formed.
    • Note: When building apps always use relative request URLs. Do not use the "full" URL above because you might have problems running your app on a different site as the site_ID parameter will be different.
  • Path: /api/v2/admin/sites/current/webapps/[webappName]/fields
  • Authorization header: This should contain the authorization token. Here is how to obtain the token.
  • Required Permissions: Edit Web Apps

Parameters

Object:

  • id - unique, required - field id - (int)
  • name - unique, required - the name of the field (it must be unique amongst the custom & system fields) (string)
  • type - required, one of the below: (string)
    • String
    • Number
    • Boolean
    • DateTime
    • DropDown_List
    • CheckBox_List
    • Radio_List
    • Image
    • String_MultiLine
    • ListBox_List
    • String_Hyperlink
    • DataSource
  • required - true if the field is required (not required) (boolean)
  • order - unique - the position of the field when listed starting with 1.

    If a field with the same order value already exists, its order value (and order value for any other fields "bellow") will be incremented by 1.

    If not specified, the field is added as the last one. (integer)

  • dataSource: for DataSource fields should be a valid webapp name (string)

  • listItems - used only by DropDown_List, CheckBox_List, Radio_List, ListBox_List fields (array)
  • addEmptyOption - choose to show a default "Please Select" option for DropDown_List and DataSource fields when editing Web App Items in Admin Console - applicable only for DropDown_List and DataSource fields - default is false (boolean)
  • useRichEditor - define if the Rich Editor is to be used for String_MultiLine fields when editing Web App items in Admin Console - default is false (boolean)

Response

The URI of the newly created custom field in the Location HTTP header.

Examples

Accepts and returns JSON as Content-Type.


Request:

POST /api/v2/admin/sites/current/webapps/WEBAPP_NAME_HERE/fields HTTPS/1.1
Authorization: 7e04176165cd4df7b628cc8ad022a8becf3bb84de44d480aadfae75e4fa07b56
Content-Length: 157
Connection: keep-alive
Content-Type: application/json

{
    "id": 44,
    "name": "Part code",
    "type": "DropDown_List",
    "listItems": [
        "First option",
        "Second one"
    ],
    "required": false,
    "order": 3
}

Response:

HTTP/1.1 201 OK
Content-Type: application/json; charset=utf-8
Location: /api/v2/admin/sites/current/webapps/Cars/fields/123

Sample code

var request = $.ajax({
    url: "/api/v2/admin/sites/current/webapps/test app2/fields",
    type: "POST",
    connection: "keep-alive",
    contentType: "application/json",headers: {
        "Authorization": $.cookie('access_token')
    },
    processData: false,
    data: JSON.stringify({
        "name": "Customfield1",
        "type": "CheckBox_List",
        "required": true,
        "order": 1,
        "listItems": ["First option", "Second one"],
        "addEmptyOption": true
    })
});
request.done(function(msg) {
    console.log(msg);
});
request.fail(function(jqXHR) {
    console.log("Request failed.");
    console.log("Error code: " + jqXHR.status);
    console.log("Error text: " + jqXHR.statusText);
    console.log("Response text: " + jqXHR.responseText);
});

Error codes

This method will return the following error codes:

  • 201 - created
  • 400 - bad request; sub-error codes:
    • 210000 - An unspecified error has occurred
    • 210002 - Invalid field id specified
    • 210003 - Invalid name (name is not syntactically correct or there is already a system or custom field with the same name)
    • 210004 - Invalid listItems
    • 210005 - Invalid dataSourceName
    • 210006 - Invalid order value (must be between 1 and max existing order value + 1)
    • 210007 - Invalid type
  • 401 - unauthorized - when the authentication token is incorrect
    • 101000 - sub-error code
  • 403 - forbidden - when the user does not have Edit WebApp Permission
  • 404 - not found
    • 190001 - The web app could not be found (the webAppName param from the URL does not match)
    • 210001 - The custom field was not found (the fieldId from the URL do not match)