FieldValues

Overview

Each resource that supports custom fields (incident, scriptrun, requirement, script) has an optional expand called "FieldValues". FieldValues is an object with properties for each custom field and values representing the values for that type of custom field.

Here is an example of a FieldValues expand:

{
    //...
    "FieldValues": {
         "SourceCustom": "src/customer/something.js",
         "ScriptRunBuildNumber": "24876",
     }
}

Single Valued Fields

For single valued custom field types (e.g. text,date, checkbox, hyperlink) the property name is the name of the custom field and the value is the JSON encoded value of that custom field value. e.g.

{
    //...
    "FieldValues": {
         "customdate": "2013-06-17T12:00:00Z",
         "customhyperlink": "http://google.com",
         "customnumber": 12,
     }
}

Picklist Fields

For custom field types which represent picklist value/s (Combo Box, Checkbox Group, Radio Group and Multi Select) things are slightly different. When you GET the resource the Id and Text of the picklist value is returned. (To get a list of valid picklist values for the custom field you can use the customfield/{name}?$expand=Options resource.)

For a Combo Box field you might get:

{
    //...
    "FieldValues": {
         "Automation_System": {
             "Id": "f13e6fbb-c1b9-49ad-b4cb-d895a9affab1",
             "Text": "Selenium Runer"
         }
     }
}

For picklists field types which support multiple values - the property is a list of Id/Text values.

A Checkbox Group field might look like:

{
    //...
    "FieldValues": {
         "ProjectCategories": [
             {
                 "Id": "8e3df968-42ad-474a-94ab-b1374174345e",
                 "Text": "Reporting"
             },
             {
                 "Id": "cb1a014d-016e-4e18-824e-ab71c33938b2",
                 "Text": "User Acceptance"
             }
         ]
     }
}

Updating Picklist FieldValues (PUT)

When you PUT picklist values - only the Id is required. This is the Id of the pick list value. The list of Ids for picklist values can be retrieved via the customfield/{name}?$expand=Options resource.

Here's an example:

Get the list of Picklist Value Ids

GET /api/customfield/Automation_System?$expand=Options

In the response we can see the "Options" expand has the list of picklist values for this custom field.

{
    "Id": "c9c0f30b-c460-47eb-a3aa-a1db00f948c1",
    "Name": "Automation_System",
    "CustomFieldTypeName": "ComboBox",
    "Label": "Automation System",
    "Description": "",
    "Required": false,
    "Entities": [
        "ScriptRun"
    ],
    "Scopes": [
        {
            "Type": "Organisation",
            "Id": "de266140-1f28-4816-bb73-a1c40106ac8d",
            "Name": "Awesome Testing services"
        }
    ],
    "Expands": [
        "Configuration",
        "Type"
    ],
    "Options": [
        {
            "Identifier": "e79ef86f-cb69-4647-9c14-52ccacdd1bec",
            "Text": "Selenium"
        },
        {
            "Identifier": "f13e6fbb-c1b9-49ad-b4cb-d895a9affab1",
            "Text": "Webdriver"
        },
        {
            "Identifier": "d1682d5c-20da-4c29-a748-133375df04e9",
            "Text": "Hand on mouse"
        }
    ],
    "Self": "http://localhost:8092/EnterpriseTester/api/customfield/Automation_SystemAutomation_System?$expand=Options",
    "Links": [
        {
            "Href": "http://localhost:8092/EnterpriseTester/api/customfieldtype/combobox",
            "Rel": "CustomFieldType"
        }
    ]
}

Update picklist values on a resource

PUT /api/scriptrun/e5e1e31f-40ba-4e87-8776-a1d300d6efd4?$expand=FieldValues

The body should look like:

{
    "Id": "e5e1e31f-40ba-4e87-8776-a1d300d6efd4",
    "ActualDuration": "",
    "ScriptId": "866bd9aa-2cd3-4127-b171-a1d300d6efd4",
    "ScriptVersion": 20,
    "AssignmentId": "866bd9aa-2cd3-4127-b171-a1d300d6efd4",
    "CreatedAt": "2013-03-20T21:45:18Z",
    "LastUpdatedAt": "2013-06-12T03:47:12Z",
    "CreatedById": "cd38e32a-adb4-42f6-a075-a1c40106d2d0",
    "CreatedBy": "Administrator",
    "RunById": "cd38e32a-adb4-42f6-a075-a1c40106d2d0",
    "RunBy": "Administrator",
    "LastUpdatedById": "cd38e32a-adb4-42f6-a075-a1c40106d2d0",
    "LastUpdatedBy": "Administrator",
    "Status": "In Progress",
    "Expands": [
        "Assignment",
        "FieldControls",
        "StepResults"
    ],
    "FieldValues": {
        "Automation_System": {
            "Id": "f13e6fbb-c1b9-49ad-b4cb-d895a9affab1"
        }
    },
    "Self": "http://localhost:8092/EnterpriseTester/api/scriptrun/e5e1e31f-40ba-4e87-8776-a1d300d6efd4"
}

Simplified syntax for PickList values

We also support shortcuts for picklist values. For single valued picklists - we support PUTs using the picklist Text or Id. For multi-valued picklists - you can supply an array of Id or Text.

e.g.

PUT /api/scriptrun/e5e1e31f-40ba-4e87-8776-a1d300d6efd4?$expand=FieldValues

With a body like

{
    //...
    "FieldValues": {
         "ProjectCategories": ["Reporting", "8e3df968-42ad-474a-94ab-b1374174345e"],
         "Automation_System": "Selenium"
     }
}
  • No labels