The latest Hypersync SDK supports data transformation using JSONata. Lets make sure we have the latest SDK and tools.
Latest SDK template from the Hypersync SDK Samples repository https://github.com/Hyperproof/hypersync-sdk-samples
Latest Hyperproof command line interface tool, CLI. https://github.com/Hyperproof/hypersync-sdk/blob/main/doc/hyperproof-cli.md
Often objects returned from a REST API contain property values that need to be formatted before they are presented to the user.
The transform property is where we define the fields that we wish to return in the dataset. The property name is the field name that will be available in the dataset. The value of the property refers to the property in the Json returned from the API call that we will display.
The simplest transformation is the ability to rename the property we wish to display as described above. In the example included in the JSONata discussion below, we can see that the dataset field realname is renamed from the JSON API result property full_name. realname is the name of the field to be referenced in your proof.json
Sometimes the data returned for your API needs to be transformed in some way before it can be used in your dataset. The Hypersync SDK makes use of the query and transformation language JSONata. This allows the use of an extensive library of expressions to transform your data.
Here are a few examples.
In our final dataset, we need to have a property named owner that contains the value of the API result property full_name. If the value of full_name is empty, we use JSONata to replace it with the value from username For our role property, we use JSONata to force this value to contain a concatenated string of values from the roles array which is returned from the API result. The API result value for last_login_time is a unix timestamp in seconds. We use JSONata to convert this value into milliseconds and then into a readable timestamp. The full JSONata documentation of operators and functions can be found here.
https://docs.jsonata.org/overview
Ex.
{
"$schema": "https://cdn.jsdelivr.net/gh/Hyperproof/hypersync-sdk/schema/restDataSource.schema.json",
"baseUrl": "https://THE_SERVICE.com/api/v2",
"dataSets": {
"users": {
"description": "Returns a list of all the users",
"documentation": "",
"url": "/v1/objects/user",
"transform": {
"username": "username",
"realname": "full_name",
"owner": "[(full_name) = ''] ? username : full_name",
"email": "email",
"role": "$join([roles], ', ')",
"enabled": "enabled",
"last_login_time": "$fromMillis(last_login_time * 1000)"
},
"result": "array"
}
}
}