Typelist metadata

There may be situations where a caller application needs to retrieve information about PolicyCenter typelists. For example, a caller application may need to know:
  • The code for a specific typecode
  • A list of all typecodes for a typelist
  • A list of all typecodes for a typelist associated with a given typekey filter

The Common API contains two /typelist endpoints to help retrieve this information.

The /typelists endpoints

The Common API contains two /typelist endpoints:

  • common/v1/typelists - By default, this returns the names and descriptions of all typelists in PolicyCenter.
  • common/v1/typelists/{typelistName} - By default, this returns the non-retired typecodes in the named typelist.

In the base configuration, these endpoints are available only to callers who have been authenticated.

Including retired typecodes

By default, the common/v1/typelists/{typelistName} endpoint returns only non-retired typecodes. You can include retired typecodes by adding the following query parameter to the call:

?includeRetired=true

Querying with typekey filters

Some typelists have a parent/child relationship. These typelists make use of typekey filters. A typekey filter is a mapping that identifies, for a typecode in one typelist, the valid values in a related typelist. For more information on typekey filters, refer to the Configuration Guide.

For example, the following typelists make use of typekey filters:

  • ActivityType - The activity's broad type, such as General, Approval, or Assignment Review.
  • ActivityCategory - An activity's specific category, such as Interview, Reminder, or Approval Denied.

If an activity's ActivityType is set to General, then some ActivityCategory values (such as Interview and Reminder) are valid, whereas others (such as Approval Denied) are not.

The typekeyFilter query parameter

When using the /typelists/{typelistName} endpoint, if the typelist is associated with a typekey filter, you can limit the results to only those typecodes that have a given relationship with the typekey filter. You can specify three types of criteria:

  • /typelists/{typelistName}?typekeyFilter=category:in:typecodeList
    • Returns all typekeys whose categories array contains at least one of the listed typecodes
  • /typelists/{typelistName}?typekeyFilter=category:cn:typecodeList
    • Returns all typekeys whose categories array contains all of the listed typecodes
  • /typelists/{typelistName}?typekeyFilter=category:ni:typecodeList
    • Returns all typekeys whose categories array does not contain any of the listed typecodes

The typecode list must be specified as:

relatedTypelist1.Typecode1,relatedTypelist2.Typecode2,...

where:

  • relatedTypelistX is the name of the Nth related typelist.
  • TypecodeX is the Nth typecode to use as a filter

Examples

No filter parameter

This call does not use the typekeyFilter query parameter. Therefore, it retrieves all typecodes in the ActivityCategory typelist:

GET /common/v1/typelists/ActivityCategory

Associated with one category

This call retrieves only the typecodes in the ActivityCategory typelist that are associated with the ActivityType of General:

GET /common/v1/typelists/ActivityCategory?typekeyFilter=category:in:ActivityType.general

Associated with any of the listed categories

This call retrieves only the typecodes in the ActivityCategory typelist that are associated with the ActivityType of either General or Approval:

GET /common/v1/typelists/ActivityCategory?typekeyFilter=category:in:ActivityType.general,ActivityType.approval

Associated with all of the listed categories

This call retrieves only the typecodes in the ActivityCategory typelist that are associated with the ActivityType of both General and Approval: (Note that, in the base configuration, there are no typecodes that meet this criteria.)

GET /common/v1/typelists/ActivityCategory?typekeyFilter=category:in:ActivityType.general,ActivityType.approval

Associated with none of the listed categories

This call retrieves only the typecodes in the ActivityCategory typelist that are not associated with either the ActivityType of General or the ActivityType of Approval:

GET /common/v1/typelists/ActivityCategory?typekeyFilter=category:ni:ActivityType.general,ActivityType.approval

Tutorial: Query for typelist metadata

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more information, see Tutorial: Set up your Postman environment.

In this tutorial, you will query for all typecodes in the VehicleType typelist. You will then use a typekey filter to query for all vehicle types that are related to the personal auto policy line.

Tutorial steps

  1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
  2. Specify Basic Auth authorization using user su and password gw.
  3. Enter the following call and click Send:
    • GET http://localhost:8180/pc/rest/common/v1/typelists/VehicleType
  4. The response payload contains all non-retired vehicle types. Verify that the first three codes in the payload are: Commercial, PP, PublicTransport.)
  5. Modify the call by adding the following query parameter to the end, and then click Send:
    • ?typekeyFilter=category:cn:PolicyLine.PersonalAutoLine
  6. The response payload now contains only vehicle types relevant to personal auto policies. Verify that there are only two codes in the payload now: auto, other. (Commercial, PP, and PublicTransport no longer appear because they are not valid vehicle types for a personal auto policy.)