Get Control Sets For Entity

Used to return a detailed definition of all control sets that are linked to an entity

Endpoint

POST - /ControlSets/GetControlSetsForEntity

Overview

Use this endpoint to lookup a HelpMaster entity (Clients, Sites, Assets etc.), and return a detailed definition (including set values) of any Control Sets that are linked to that entity. If any Control Sets are linked to the entity, a JSON definition of each Control Set will be returned. This information can then be used to update the Control Set using the ControlSetValue API, or when logging a new job via the LogJobFromJobTemplate API endpoint.

Input Parameters

The PKID of an existing entity. The PKID is found on the “Properties” tab of each entity within the Desktop Edition of HelpMaster. See picture below for an example of the PKID for a Job Template.

Job Template PKIKD

entityType

The entity type that you wish to look up. Supported values include:

  • Client
  • Site
  • Asset
  • Job
  • JobTemplate
  • ChangeRequest

Examples

Query all of the Control Sets linked to Job Template #17

{
  "entityLink": 17,
  "entityType": "JobTemplate"
}

Query all of the Control Sets linked to Client #88

{
  "entityLink": 88,
  "entityType": "Client"
}

Results

The results include a definition of any linked Control Sets, including the current values of the each field.

[
  {
    "controlSetPKID": 33,
    "controlSetName": "Employee Details",
    "controls": [
      {
        "guid": "0462fdb3-a6bf-4033-8c61-c22d5617b1ad",
        "name": "Date1",
        "caption": "Start date",
        "isRequired": true,
        "regularExpressionValidator": "",
        "controlType": "DateCtrl",
        "stringValue": null,
        "intValue": null,
        "decimalValue": null,
        "dateValue": "2000-01-01T12:59:48.293"
      },
      {
        "guid": "263da27e-c545-4e84-a3a1-25ec52ac3388",
        "name": "Text2",
        "caption": "First name",
        "isRequired": false,
        "regularExpressionValidator": "",
        "controlType": "TextCtrl",
        "stringValue": null,
        "intValue": null,
        "decimalValue": null,
        "dateValue": null
      },
      {
        "guid": "2de62207-1df8-4d9c-82e6-74c54ae7d649",
        "name": "Text1",
        "caption": "Employee #",
        "isRequired": false,
        "regularExpressionValidator": "",
        "controlType": "TextCtrl",
        "stringValue": "4",
        "intValue": null,
        "decimalValue": null,
        "dateValue": null
      },
      {
        "guid": "46161283-b39f-4ab1-a3fd-36708ae20d63",
        "name": "TextMultiLine1",
        "caption": "Additional information",
        "isRequired": false,
        "regularExpressionValidator": "",
        "controlType": "TextCtrlMultiLine",
        "stringValue": "Good guy",
        "intValue": null,
        "decimalValue": null,
        "dateValue": null
      },
      {
        "guid": "48603d60-e014-4f97-9ed5-350faad00880",
        "name": "DropDown1",
        "caption": "Employment type",
        "isRequired": false,
        "regularExpressionValidator": "",
        "controlType": "DropDownCtrl",
        "stringValue": "Full time",
        "intValue": null,
        "decimalValue": null,
        "dateValue": null
      },
      {
        "guid": "7ea80f89-cb8e-4e75-8e71-39026a896d45",
        "name": "Date2",
        "caption": "End date",
        "isRequired": false,
        "regularExpressionValidator": "",
        "controlType": "DateCtrl",
        "stringValue": null,
        "intValue": null,
        "decimalValue": null,
        "dateValue": null
      },
      {
        "guid": "970f76d6-21a7-4216-a0f2-9b7a1ba1b573",
        "name": "Text4",
        "caption": "Job Title",
        "isRequired": false,
        "regularExpressionValidator": "",
        "controlType": "TextCtrl",
        "stringValue": null,
        "intValue": null,
        "decimalValue": null,
        "dateValue": null
      },
      {
        "guid": "b65cafb3-619c-4f47-8507-9cabb6edf8e0",
        "name": "Text3",
        "caption": "Last name",
        "isRequired": false,
        "regularExpressionValidator": "",
        "controlType": "TextCtrl",
        "stringValue": null,
        "intValue": null,
        "decimalValue": null,
        "dateValue": null
      },
      {
        "guid": "e8538aad-39f4-4389-8f61-5d4574f0a386",
        "name": "TriChoice1",
        "caption": "Requires Carpark Access?",
        "isRequired": false,
        "regularExpressionValidator": "",
        "controlType": "TriChoice",
        "stringValue": "",
        "intValue": 2,
        "decimalValue": null,
        "dateValue": null
      }
    ]
  }
]

Using the results in other API calls

The results can be used in other Control Set APIs to update values. Copy the results and use the JSON structure as the input in other APIs. Update the values as required.

When updating Control Set data, only the GUID, and value is required.

eg. The definition of a single field in a Control Set contains the definition, the value and other meta data. This additional meta data is useful for understanding context and field validation, however this meta data is not required when updating the field. By removing all of the non-necessary Control Set meta data, the JSON payload is reduced in size, and the actual API call is simplified down to its most basic state.

A complete Control Set definition includes the definition as well as the value as shown below.

      {
        "guid": "0462fdb3-a6bf-4033-8c61-c22d5617b1ad",
        "name": "Date1",
        "caption": "Start date",
        "isRequired": true,
        "regularExpressionValidator": "",
        "controlType": "DateCtrl",
        "stringValue": null,
        "intValue": null,
        "decimalValue": null,
        "dateValue": "2000-01-01T12:59:48.293"
      }

In order to update this date field, only the GUID and dateValue information is required. The other meta data is not required.

      {
        "guid": "0462fdb3-a6bf-4033-8c61-c22d5617b1ad",
        "dateValue": "2000-01-01T12:59:48.293"
      }

See also

Control Sets