Connected items using a REST API datasource
Let's take a look at how to configure Connected items depending on their types:
- Select list (single choice or multiple choices)
- Read-only
Select list
For Connected items of type "Select list", the template is called on each option of the JSON document returned by the REST endpoint which are nested under the root element specified in the "Location of the Connected item options in the response" field.
Let's see through an example of how it works.
Step by step example
JSON response
The JSON response of the REST endpoint returns three options ("has-more", "offset" and "companies"), where the last one ("companies") is an object comprised of two instances:
JSON response
{
"has-more": false,
"offset": 5593477585,
"companies": [
{
"portalId": 25843600,
"companyId": 5592718290,
"isDeleted": false,
"properties": {
"website": {
"sourceId": null,
"timestamp": 1457513066540,
}
"name": {
"value": "Elements Apps",
"source": "BIDEN"
}
}
"additionalDomains": [],
"stateChanges": [],
"mergeAudits": [] },
{
"portalId": 25843600,
"companyId": 5592718290,
"isDeleted": false,
"properties": {
"website": {
"sourceId": null,
"timestamp": 1457513066540,
}
"name": {
"value": "Elements Apps",
"source": "BIDEN"
}
}
"additionalDomains": [],
"stateChanges": [],
"mergeAudits": []
},
]
}Requirement
The requirement is to display a list of company names, such as:
- Company name #1
- Company name #2
Template
As mentioned above, the template is called on each item of the root element specified in the "Location of the Connected item options in the response" field from the JSON document returned by the REST endpoint. In this example, the root element is "companies".
"Companies" is an object which has been instantiated three times and is described by several attributes:
"Companies" JSON object
"portalId": 25843600,
"companyId": 5592718290,
"isDeleted": false,
"properties": {
"website": {
"sourceId": null,
"timestamp": 1457513066540,
}
"name": {
"value": "Elements Apps",
"source": "BIDEN"
}
}
"additionalDomains": [],
"stateChanges": [],
"mergeAudits": [] In order to display the name of the company, we need to reference the access path all the way to the attribute "value" that is located under the "name" attribute of "properties":
Template
${row.properties.name.value}Read-only
For Connected items of type "Read-only", the template is called on the JSON document returned by the REST endpoint. Depending on the use case, the JSON response of read-only connected items will return either:
- an array of objects, or
- a single object with attributes in the form of key-value pairs.
Depending on the JSON response, the template configuration will differ, let's see how.
1 - Array of objects
Response
Let's take an example where the JSON response of the REST endpoint is an array of objects. In this case, the REST endpoint queries the list of applications:
https://xxxx/deals/v1/deal/associated/company/{id}/paged?&properties=dealname&properties=amount&properties=dealstage
The JSON response outputs a list of two deals (objects):
JSON response -Array of objects
{
"deals": [
{
"portalId": 25843600,
"dealId": 4627355362,
"isDeleted": false,
"associations": null,
"properties": {
"dealname": {
"value": "Manufacture marketing goodies",
"versions": [
{
"name": "dealname",
"value": "Manufacture marketing goodies",
}
]
},
"amount": {
"value": "57000",
"timestamp": 1652108844466,
"source": "CRM_UI",
"sourceId": "userId:28401755",
"updatedByUserId": 28401755,
"versions": [
{
"name": "amount",
"value": "57000",
}
]
},
"dealstage": {
"value": "contractsent",
"timestamp": 1652108844466,
"source": "CRM_UI",
"sourceId": "userId:28401755",
"updatedByUserId": 28401755,
"versions": [
{
"name": "dealstage",
"value": "contractsent",
}
]
}
},
"stateChanges": []
},
{
"portalId": 25843600,
"dealId": 4627378383,
"isDeleted": false,
"associations": null,
"properties": {
"dealname": {
"value": "Revamp website",
"versions": [
{
"name": "dealname",
"value": "Revamp website",
}
]
},
"amount": {
"value": "10000",
"versions": [
{
"name": "amount",
"value": "10000",
}
]
},
"dealstage": {
"value": "presentationscheduled",
"versions": [
{
"name": "dealstage",
"value": "presentationscheduled",
}
]
}
},
"stateChanges": []
}
],
"hasMore": false,
"offset": 4627378383
}Requirement
The requirement is to display the name, the amount and the stage of each deal in the form of a table
| Deal Name | Amount | Stage |
|---|---|---|
| Manufacture marketing goodies | $57,000 | contractsent |
Revamp website | $10,000 | presentationscheduled |
Template
The JSON response is an array of two objects, where each of these objects is a row.
In the template, we want to display the deal name, its amount and its stage in the form of a table:
Template - Array of objects
<table class="aui">
<thead>
<tr>
<th>Name</th>
<th>Amount</th>
<th>Status</th>
</tr>
</thead>
<tbody>
<#list data.deals as deals>
<tr>
<td>${deals.properties.dealname.value}</td>
<td>$${deals.properties.amount.value?number?string(",##0.00")}</td>
<td>${deals.properties.dealstage.value}</td>
</tr>
</#list>
</tbody>
</table>The <#list> method is used to iterate over each deal object (assigned to the "deals" variable).
After doing that, the access path to the attributes to display is provided, preceded by the data variable.
2 - Single object
Response
Let's take an example where the JSON response of the REST endpoint is a single object. In this case, the REST endpoint queries a specific application identified by its ID:
https://xxxx/api/v1/apps/appId
The JSON response outputs a list of key-value pairs for this specific application:
JSON response - Single object
{
"id": "1234",
"name": "saasure",
"label": "Okta Admin Console",
"status": "ACTIVE",
"lastUpdated": "2022-02-18T10:52:11.000Z",
"created": "2022-02-18T10:52:09.000Z",
"accessibility": {
"selfService": false,
"errorRedirectUrl": null,
"loginRedirectUrl": null
}Requirement
The requirement is to display the ID, the label and the status of this specific application:
- 1234 - Okta Admin Console (ACTIVE)
Where the label displays in bold and the status is in parentheses.
Template
The JSON response is a single object with attributes in the form of key-value pairs. These attributes can be accessed in the template through the data variable.
Single object - Template
${data.id} - <b>${data.label}</b> (${data.status})