Reference data and Pick Lists

The ERM applications in Folio (Agreements and Licenses) rely extensively on what are known as "pick lists" in the UI, and called "reference data" in the backend applications. Reference data consists of "categories" and "values", and in Pick List terms, each pick list is a reference data category and the list of values in a pick list are the reference data category values. 

Pick lists are typically used in the UI when a property can take a limited list of values - and in the UI this is usually surfaced when editing the property, or in other situations, such as search filters, where the user can select from the values in the pick list. The remainder of this documentation will use the terminology used in the API: i.e. reference data, categories and values.

Fetching Reference data

method: GET
OKAPI endpoints: 
* /agreements/refdata/
* /licenses/refdata/
Optional parameters that can be appended to endpoint:

• max=<integer> ← maximum number of refdata categories to include in the response (maximum value 100, default 10)

• offset=<integer> ← in the case of paging through a list of refdata categories (i.e. if max is lower than the total number of categories), where to retrieve the next page of results from

• stats=<boolean> ← to include in the response the total number of results available

While searches and filters can also be applied to limit the set of returned reference data, the number of reference data categories is usually small enough that retrieving 100 is sufficient to get all the reference data in the system.

Data format of returned data

A GET request to the refdata endpoints will result in two potential data structures. In the case of using the parameter

stats=false

(or omitting this parameter) the results will be of the form:

[
    {
        "id": "<refdata category UUID, string>",
        "desc": "<refdata category description, string>",
        "internal": <refdata internal flag, boolean>,
        "values": [
            {
                "id": "<refdata value UUID, string>",
                "value": "<refdata value value, string>",
                "label": "<refdata value label, string>"
            },
            <additional value objects as necessary>
        ]
    },
   <additional refdata categories as necessary>
]

In the case of using the parameter

stats=true

The list of refdata categories will be wrapped in a results  structure:

{
    "results": [
    {
      "id": "<refdata category UUID, string>",
      "desc": "<refdata category description, string>",
      "internal": <refdata internal flag, boolean>,
        "values": [
            {
              "id": "<refdata value UUID, string>",
              "value": "<refdata value value, string>",
              "label": "<refdata value label, string>"
          },
          <additional value objects as necessary>
        ]
     },
     <additional refdata categories as necessary>
    ],
    "pageSize": <results per page, integer>,
    "page": <page number, integer>,
    "totalPages": <total pages, integer>,
    "meta": {},
    "totalRecords": <total records, integer>,
    "total": <total records, integer>,
}

Adding Reference data values

To add values to a reference data category, you need to retrieve the UUID for the relevant refdata category, and then PUT an array of values to the OKAPI refdata endpoint as follows

method: PUT
OKAPI endpoints: 
* /agreements/refdata/<categoryUUID>
* /licenses/refdata/<categoryUUID>
Data format:
{
"values": [
"label": "<refdata value label 1, string>",
"label": "<refdata value label 2, string>",
"label": "<refdata value label 3, string>",
etc.
}