The payload generated in the <driver-operation-data> needs to be transformed into a format supported by your RESTful service. You can modify the JSON payloads that are received in the Subscriber and Publisher channels through conversion policies. The conversion policies modify the request and response documents to a compatible format that is easily comprehended by both Identity Manager and the connected application. The REST Driver requires JSON inputs to be in a certain format, so in order to help the user to perform operations such as extracting a value, and modifying the data using the following predefined functions that are available.
JSON Path expressions resemble XPath expressions for XML and provide a way to navigate the JSON structure.Following are the delimiters used in constructing JSON Path:
|
Path expression |
Description |
|---|---|
|
$ |
To provide the root object or array. |
|
.property |
To access the specified property in a parent object. |
|
[n] |
To access the n-th element from an array. Indexes are 0-based.To access objects in JSON Array Ex: [id eq P000000] Note:Based on its attribute, we can filter JSON objects contained within an array. |
|
[property eq value] |
Iterates JSON object array and returns object whose .property is equal to the specified value. |
You can execute the above JSON path expressions using the available functions with examples given below:
getJSONValue: This function parses the input JSON string and returns the JSON path expressions.
Example:
Syntax: String getJsonValue(String jsonstring, String jsonPath)
Input parameters:
jsonstring =
"emails": [{"value": "adrian.stephens@microfocus.com","primary": true}],"name": {"givenName": "Adrian","familyName": "Stephens"},
jsonPath = $.name
Output:
Token Value: "{"givenName":"Adrian","familyName":"Stephens"}"
modifyJson: This function modifies the input JSON string with respect to the given JSON path expressions according to the requirement.
Example:
Syntax: public static String modifyJson (String oldjson, String newjson)
Input parameters:
oldjson =
"emails": [{"value": "adrian.stephens@microfocus.com","primary": true}],"name": {"givenName": "Adrian","familyName": "Stephens"},
newjson = {"givenName1":"$.name.givenName"}
Output:
Token Value: {"givenName1":"Adrian"}
createJson: This function helps to create a new JSON with respect to the given JSON path expressions.
Example:
Syntax: public static String createJson (String newjson, String oldjson)
Input parameters:
oldjson =
"emails": [{"value": "adrian.stephens@microfocus.com","primary": true}],"name": {"givenName": "Adrian","familyName": "Stephens"},
newjson =
{"$.name.firstname":"abc","$.name.givenName":"$.name.givenName","$.emails[].value":"abc@mf.com"}
Output:
Token Value: "{"emails":[{"value":"abc@mf.com"}],"name":{"firstname":"abc","givenName":"Adrian"}}"
Following are JSON modifiers functions available in policy:
This section explains the procedure to use JSON modifier with an example:
Add the following paths in policy to call json modifier functions:
xmlns:jc=”https://www.netiq.com/documentation/identity-manager-developer/driver-developer-kit/rest-driver-developer-docs/com/novell/nds/dirxml/driver/rest/common/JSONCreator.html”.
xmlns:jp="https://www.netiq.com/documentation/identity-manager-developer/driver-developer-kit/rest-driver-developer-docs/com/novell/nds/dirxml/driver/rest/common/JSONParser.html”.
Verify that the HTTP response string length is greater than zero.
Extract the HTTP response and set it to a local variable.
Extract the Resource array from the response using the getJsonValuefunction.
Add modification rules for User and Group resources with the help of JSON path expressions.
Example : { "class-name" : "User","CN": "$.userName", "Surname": "$.name.familyName", "workforceID": "$.id" }
Modify the resource according to the modification rules using modifyJsonArray function.
Use creation Rules to create new json with modified resource array.
Example: {"$.results" : "$"}. Here we are creating new json which has a result attribute and its value is mapped to a modified json array.
Call createJson function and pass the above creation rules and modified JSON array.
Remove existing http response from driver operation data and add new modified json created from createJson function.
Following policy illustrates the above steps:
<arg-actions>
<do-if>
<arg-conditions>
<and>
<if-xpath op="true">string-length(./response/value/text())>0</if-xpath>
</and>
</arg-conditions>
<arg-actions>
<do-set-local-variable name="httpResponse">
<arg-string>
<token-xpath expression="./response/value"/>
</arg-string>
</do-set-local-variable>
<do-if>
<arg-conditions>
<and>
<if-class-name op="equal">User</if-class-name>
</and>
</arg-conditions>
<arg-actions>
<do-set-local-variable name="modificationRules">
<arg-string>
<token-text>{"class-name" : "User","CN": "$.name", "Surname": "$.lastName", "workforceID": "$.id"}</token-text>
</arg-string>
</do-set-local-variable>
<do-set-local-variable name="responseArray">
<arg-string>
<token-xpath expression='jp:getJsonValue($httpResponse, "$.users")'/>
</arg-string>
</do-set-local-variable>
</arg-actions>
</do-if>
<do-if>
<arg-conditions>
<and>
<if-class-name op="equal">Group</if-class-name>
</and>
</arg-conditions>
<arg-actions>
<do-set-local-variable name="modificationRules">
<arg-string>
<token-text>{ "CN" : "$.name", "Description" : "$.id", "class-name" : "Group" }</token-text>
</arg-string>
</do-set-local-variable>
<do-set-local-variable name="responseArray">
<arg-string>
<token-xpath expression='jp:getJsonValue($httpResponse, "$.groups")'/>
</arg-string>
</do-set-local-variable>
</arg-actions>
<arg-actions/>
</do-if>
<do-set-local-variable name="modifiedArray">
<arg-string>
<token-xpath expression="jp:modifyJsonArray($responseArray, $modificationRules)"/>
</arg-string>
</do-set-local-variable>
<do-set-local-variable name="creationRules">
<arg-string>
<token-text xml:space="preserve">{"$.results" : "$"}</token-text>
</arg-string>
</do-set-local-variable>
<do-set-local-variable name="modifiedHttpResponse">
<arg-string>
<token-xpath expression="jc:createJson($creationRules, $modifiedArray)"/>
</arg-string>
</do-set-local-variable>
<do-strip-xpath expression="./response/value/text()"/>
<do-append-xml-text expression="./response/value">
<arg-string>
<token-local-variable name="modifiedHttpResponse"/>
</arg-string>
</do-append-xml-text>
<do-set-local-variable name="xmlInput" notrace="true" scope="policy">
<arg-string>
<token-base64-encode charset="UTF-8">
<token-replace-all regex="&lt;" replace-with="<">
<token-xml-serialize>
<token-xpath expression="."/>
</token-xml-serialize>
</token-replace-all>
</token-base64-encode>
</arg-string>
</do-set-local-variable>
<do-set-local-variable name="applicationContent" notrace="true" scope="policy">
<arg-string>
<token-xpath expression="rs:jsonToXDS($xmlInput)"/>
</arg-string>
</do-set-local-variable>
<do-if notrace="true">
<arg-conditions>
<and>
<if-local-variable mode="nocase" name="applicationContent" op="not-equal"/>
</and>
</arg-conditions>
<arg-actions>
<do-set-local-variable name="xdscontent" scope="policy">
<arg-node-set>
<token-xml-parse>
<token-local-variable name="applicationContent"/>
</token-xml-parse>
</arg-node-set>
</do-set-local-variable>
<do-clone-xpath dest-expression=".." src-expression="$xdscontent/input/modify"/>
</arg-actions>
<arg-actions/>
</do-if>
<do-strip-xpath expression="."/>
</arg-actions>
<arg-actions/>
</do-if>
</arg-actions>