Tutorial: Schema configuration with scalars

In this tutorial, you will add new scalar 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 fields that already exist on the User data model entity that are not exposed to Cloud API in the base configuration. The data model entity fields used in this tutorial are:

CreateTime (this datetime field will be readable but not writeable)
Department (this string 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 three new properties.

"definitions": {
  "User": {
    "properties": {
      "createDate_Ext" : {
        "title": "CreateDate",
        "description": "The date on which this user was created",
        "type": "string",
        "format": "date-time",
        "readOnly": true
      },
      "departmentName_Ext": {
        "title": "DepartmentName",
        "description": "The name of the department this user works in",
        "type": "string"
      }
    }
  }
}

There is an additional readOnly property specified for createDate. For more information, see Making properties required by the database.

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

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 createTime and departmentName properties.

"mappers": {
  "User": {
    "properties": {
      "createDate_Ext" : {
        "path" : "User.CreateTime"
      },
      "departmentName_Ext": {
        "path": "User.Department"
      }
    }
  }
}

You now have new properties with information on how data flows into each property. If these properties were needed only for GETs (and not POSTs or PATCHes), you could restart PolicyCenter now and test your work. However, the departmentName_Ext 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 departmentName property.

"updaters": {
  "User": {
    "properties": {
      "departmentName_Ext": {
        "path": "User.Department"
      }
    }
  }
}

The departmentName_Ext property can now be used for GETs, POSTs, and PATCHes. The createDate_Ext property has been omitted from the updater file. Therefore, it is read-only and only appears in responses.

7. Start (or restart) PolicyCenter.

Testing your work

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.
Enter the following call, but do not click Send yet:
1. POST http://localhost:8180/pc/rest/admin/v1/users
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": "scalarTestUser",
      "departmentName_Ext": "schema config tester"
    }
  }
}
```
5. Click Send.

Results

The response should be "201 Created". The response body should contain information about the new user, including the create date and department. Note that:

The structure of these fields (their names and types) comes from the schema file.
The data in the POST response comes from the mapping file.
The setting of the user's department was accomplished by the updater file.