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. PUT is used here (not POST) as this is to add values to an existing reference data category.

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

On PUTting one or more values with labels, the relevant values will be added to the category identified by the UUID used.

It is possible to put a value property in refdata value object (in addition to the label property as illustrated above), but generally this is not recommended. If just the label is provided then the value will be automatically generated. If the automatically generated value matches an existing value, this will update the existing value.

These PUTs are additive - i.e. you do not need to provide a full list of all the reference data values for a category with each PUT, only the values you wish to add or update..

N.B. Not all reference data categories can be freely edited using the API as some are deliberately restricted (e.g. agreement status). For these categories, which will have a property

"internal": true

only the reference data value labels can be edited.

Populating Reference data values from a CSV using Postman

The APIs documented here can be used to populate reference data values as desired. For more general information about using Folio APIs see Working with FOLIO APIs

As an example, if it is desirable to populate a list of reference data values from a CSV file, this could be done a using a Postman "Runner":

Setup a CSV file with 2 columns and as many rows as you have reference data values to add:
1. category (containing the appropriate refdata category uuid for each line in the csv)
2. value (containing the appropriate refdata value label i.e. the value you want to appear in the pick list)
Setup a Postman collection (or use an existing one)
Add an http call to the collection using the curl
```
curl --location --globoff --request PUT 'https://<OKAPI URL>/oa/refdata/{{category}}' \
--header 'x-okapi-tenant: diku' \
--header 'Content-Type: application/json' \
--data '{
  "values": [
    {
      "label": "{{value}}"
    }
  ]
}'
```
Depending on the authentication method being used, you may need to look at how to authenticate. Information on using the x-okapi-token header with Postman is at Getting started with Postman#Lookinguptheauthenticationtoken. Other authentication methods may require different approaches
Use the Collection Runner (see Getting started with Postman#UsingPostmanCollectionRunner) to run this single call, selecting the CSV as your "data file"