Defining JSON locators

When you use a Web Service interface in a Data Connector applet to retrieve or send data, the interface generally returns a response in either XML or JSON format. If the interface returns a JSON object, you must understand the basic structure of JSON and how to navigate the object to extract the specific values you require.

To navigate the elements, you must define a Locator element, using a combination of the following items:

Property names. Use a property name to navigate to that specific property.
Dots (.). Use dots to navigate to the properties of an object.
Brackets ([]). Use brackets with a number (n) in between to navigate to the n^th+1 member of an array ([0] points to the first member).

You can navigate to a specific data value through multiple hierarchical levels by combining dots and square brackets in a Locator element.

Example 1

The following JSON object contains data about contacts and their news feed subscriptions:

JSON

{
	"isSuccessful": true,
	"statusMessage": "Successful retrieval",
	"data": {
		"lastUpdated": "2015-07-11 22:34:16",
		"contacts": [
			{
				"name": "Joe Dow",
				"phone": "+4412341234",
				"subscriptions": ["Science", "Engineering", "IT", "Finance"],
				"age": 37			
			},
			{
				"name": "Jane Dow",
				"phone": "+4412351235",
				"subscriptions": ["Media", "Movies", "Finance", "Politics"]				
			}
		]
	}
}

The following Locators retrieve data from the JSON object above:

Locator	Data Value	Explanation

Locator	Data Value	Explanation
isSuccessful	true	The value of the isSuccessful property of the root object.
data.lastUpdated	"2015-07-11 22:34:16"	The value of the lastUpdated property of the data object.
data.contacts[0].name	"Joe Dow"	The value of the name property of the first member of the contacts array, which is a property of the data object.
data.contacts[1].subscriptions[2]	"Finance"	The value of the third member of the subscriptions array, property of the second member of the contacts array, property of the data object.
data.contacts[0].age	37	The value of the property age of the first member of the contacts array, which is a property of the data object.
data.contacts[1].age	null	The value of a non-existing property age of the second member of the contacts array, which is a property of the data object.
data.contacts[0].subscriptions	"["Science", "Engineering", "IT", "Finance"]"	The value of the subscriptions property of the first member of the contacts array, property of the data object.

Example 2

The following JSON array contains just a list of contacts:

JSON

[
	{
		"name": "Joe Dow",
		"phone": "+4412341234",
		"subscriptions": ["Science", "Engineering", "IT", "Finance"],
		"age": 37			
	},
	{
		"name": "Jane Dow",
		"phone": "+4412351235",
		"subscriptions": ["Media", "Movies", "Finance", "Politics"]				
	}
]

The following Locators retrieve data from the JSON array above:

Locator	Data Value	Explanation

Locator	Data Value	Explanation
[0].name	"Joe Dow"	The value of the name property of the first element in the root array.
[1].subscriptions[0]	"Media"	The value of the second member of the subscriptions array, property of the second member of the root array.

Locators pointing to non-existing object properties or array members will retrieve a null value during an interaction without any indication of a failure, thus allowing any expected value to be optional.

Locators pointing to a JSON object or a JSON array rather than a simple data type value will retrieve the whole object or array and allow saving it as plain text.