Skip to main content
Skip table of contents

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

CODE
{
    "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

CODE
"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

CODE
${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

CODE
{
    "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 NameAmountStage
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

XML
<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

CODE
{
    "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

XML
${data.id} - <b>${data.label}</b> (${data.status})



JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.