Tutorial: Schema configuration with compound datatypes

In this tutorial, you will add a new compound datatype properties to the base configuration User schema in the Admin API, and provide mapping and updater information as appropriate. To reduce the number of steps required, this tutorial uses a field that already exist on the User data model entity that is not exposed to Cloud API in the base configuration. The data model entity field used in this tutorial is:

  • ExperienceLevel (this typekey field will be readable and writeable)

Tutorial steps

1. In Studio, open the admin_ext-1.0.schema.json file.

2. The file contains the following line of code.

"definitions": { }

Replace that line with the following, which defines the new property. (If you have already done the tutorial for scalars, then add the experienceLevel property to the existing extensions.)

"definitions": {
  "User": {
    "properties": {
      "experienceLevel_Ext": {
        "title": "ExperienceLevel_Ext",
        "description": "The user's level of experience (high, mid, low)",
        "$ref": "#/definitions/TypeKeyReference",
        "x-gw-extensions": {
          "typelist": "UserExperienceType"
        }
      }
    }
  }
}

At this point, you have defined the structure of the new property. But there is no information on how data flows into and out of this property.

3. In Studio, open the admin_ext-1.0.mapping.json file.

4. The file contains the following line of code.

"mappers": { }

Replace that line with the following, which defines how data is mapped from the database to the experienceLevel property. (If you have already done the tutorial for scalars, then add the experienceLevel property to the existing extensions.)

"mappers": {
  "User": {
    "properties": {
      "experienceLevel_Ext": {
        "path": "User.ExperienceLevel",
        "mapper": "#/mappers/TypeKeyReference"
      }
    }
  }
}

You now have a new property with information on how data flows into it. If this property were needed only for GETs (and not POSTs or PATCHes), you could restart PolicyCenter now and test your work. However, the experienceLevel property needs to be writeable.

5. In Studio, open the admin_ext-1.0.updater.json file.

6. The file contains the following line of code.

"updaters": { }

Replace that line with the following, which defines how data is mapped from the database to the experienceLevel property. (If you have already done the tutorial for scalars, then add the experienceLevel property to the existing extensions.)

"updaters": {
  "User": {
    "properties": {
      "experienceLevel_Ext": {
        "path": "User.ExperienceLevel",
        "valueResolver": {
          "typeName": "TypeKeyValueResolver"
        }
      }
    }
  }
}

This property can now be used for GETs, POSTs, and PATCHes.

7. Start (or restart) PolicyCenter.

Testing your work

  1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
    1. On the Authorization tab, select Basic Auth using user su and password gw.
  2. Enter the following call, but do not click Send yet:
    1. POST http://localhost:8180/pc/rest/admin/v1/users
  3. Specify the request payload.
    1. In the first row of tabs (the one that starts with Params), click Body.
    2. In the row of radio buttons, select raw.
    3. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
    4. Paste the following into the text field underneath the radio buttons. 
      {
  "data": {
    "attributes": {
      "username": "compoundTestUser",
      "experienceLevel_Ext" : {
          "code" : "mid"
      }
    }
  }
}
    5. Click Send.

Results

The response should be "201 Created". The response body should contain information about the new user, including the experience level. Note that:

  • The structure of the field (its name and type) comes from the schema file.
  • The experience level in the POST response comes from the mapping file.
  • The setting of the user's experience level was accomplished by the updater file.