Help Contents

 

Custom Fields (Resources)

Resource: Custom Fields ( /api/customfields )

Custom fields (collection) resource

Root Relation: CustomFields

This resource supports the following methods: GET POST

 

Methods

GET


Retrieves all custom fields.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Status Codes

These are the expected status codes returned by the service - in addition, some other status codes may be returned if either an internal error occurs or there is an authentication issue (such as an expired OAuth token).

StatusDescription
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if the custom field type does not exist.

 

Example - Get all custom fields

 

An Example of fetching all custom fields.

Request Headers

KeyValueDescription
Acceptapplication/json 

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8 

Response Body

{
  "Items": [
    {
      "Id": "4b4329a0-44a3-4e3c-a527-6973bb2b063b",
      "Name": "IsRegression",
      "CustomFieldTypeName": "Checkbox",
      "Label": "Is Regression?",
      "Description": null,
      "Required": false,
      "Entities": [
        "TestScript",
        "Requirement",
        "Incident"
      ],
      "Scopes": [
        {
          "Type": "Project",
          "Id": "d17289f6-8f43-4074-88d0-3841f9830b19",
          "Name": "Test Project"
        }
      ],
      "Expands": [
        "Configuration",
        "Options",
        "Type"
      ],
      "Self": "http://localhost/api/customfield/IsRegression",
      "Links": [
        {
          "Href": "http://localhost/api/customfieldtype/checkbox",
          "Rel": "CustomFieldType"
        }
      ]
    },
    {
      "Id": "8b385cac-fcbf-4d27-83d0-132e121e8ea1",
      "Name": "Severity",
      "CustomFieldTypeName": "ComboBox",
      "Label": "Severity",
      "Description": null,
      "Required": true,
      "Entities": [
        "Incident"
      ],
      "Scopes": [
        {
          "Type": "Organisation",
          "Id": "3d0d2ebf-d9c4-40bb-ab8e-85d63dab1f8a",
          "Name": "Testing Intl"
        }
      ],
      "Expands": [
        "Configuration",
        "Options",
        "Type"
      ],
      "Self": "http://localhost/api/customfield/Severity",
      "Links": [
        {
          "Href": "http://localhost/api/customfieldtype/combobox",
          "Rel": "CustomFieldType"
        }
      ]
    }
  ]
}

Status Code

200 - OK

 

Example - Get custom fields using OData filter

 

An Example of fetching subset of custom fields using OData filter and expansion for options.

Request Headers

KeyValueDescription
Acceptapplication/json 

Request Parameters

KeyValueDescription
$filterCustomFieldTypeName eq 'ComboBox'Fetch all custom fields of type combo box.
$expandOptionsExpands the options for any matching field.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8 

Response Body

{
  "Items": [
    {
      "Id": "8b385cac-fcbf-4d27-83d0-132e121e8ea1",
      "Name": "Severity",
      "CustomFieldTypeName": "ComboBox",
      "Label": "Severity",
      "Description": null,
      "Required": true,
      "Entities": [
        "Incident"
      ],
      "Scopes": [
        {
          "Type": "Organisation",
          "Id": "3d0d2ebf-d9c4-40bb-ab8e-85d63dab1f8a",
          "Name": "Testing Intl"
        }
      ],
      "Expands": [
        "Configuration",
        "Type"
      ],
      "Options": [
        {
          "Identifier": "05ec42ae-2713-4d51-9306-3226a2446712",
          "Text": "Low"
        },
        {
          "Identifier": "05ec42ae-2713-4d51-9306-3226a2446712",
          "Text": "Medium"
        },
        {
          "Identifier": "05ec42ae-2713-4d51-9306-3226a2446712",
          "Text": "High"
        }
      ],
      "Self": "http://localhost/api/customfield/Severity",
      "Links": [
        {
          "Href": "http://localhost/api/customfieldtype/combobox",
          "Rel": "CustomFieldType"
        }
      ]
    }
  ]
}

Status Code

200 - OK

POST


Create a new custom field.

Status Codes

These are the expected status codes returned by the service. In addition, some other status codes may be returned if either an internal error occurs or there is an authentication issue (such as an expired OAuth token).

StatusDescription
201 - CreatedReturned if the custom field is created successfully.
409 - ConflictReturned if the custom field already exists.

Example - POST (create a Combo Box field)

Request Headers

KeyValueDescription
Content-Typeapplication/json 

Request Body

{
  "Name": "CSTest",
  "HandlerType": "ComboBox",
  "Label": "CS Test Label",
  "Description": "This is a custom field test.",
  "Required": false,
  "Entities": ["Requirement", "TestScript"],
  "Scopes": [{
    "Type": "Project",
    "Id": "d31d4c3e-dfea-4204-a9dd-a54f00b8af79",
  },
  {
    "Type": "Project",
    "Id": "c5b7e6d0-4f8b-482b-bd71-a47600e37658",
  }]
}

Status Code

201 - Created