Description
Allows you to get context data using RESTful API’s.
Configuration
To add the REST API Context Provider to a stream, follow the steps below:
- Ensure you have a use case open in the stream designer, this can be a new use case or an existing use case
- From the toolbox on the left expand the Context Provider option and scroll down until you can see “REST API Context Provider”
- You can also use the search in the header to find the agent quickly
- Click and drag the REST API Context Provider from the toolbox onto the canvas
- Rename the Context Provider by clicking into the text button on the action bar
- Save the Stream by clicking the save button in the action bar
- Hover over the icon for the agent until it turns orange and then double click to open the configuration page
- You can optionally use the configure option on the action bar once you have selected the specific agent and then clicking this option
- Configuration options
- The drop-down allows you to associate this agent with a specific collection. The default option is derived from the default specified against the specific use case and is generated left as the same option. If you do need to change it to another collection make the change by selecting the new collection in the drop-down.
- Enter a value for the Polling Interval (the interval at which new records are accessed/checked for, in seconds)
- Enter Service details
- Enter the Base Url
- Attach Metadata File by selecting files or drop files
- Tick Use Authentication to enter Username and Password
- Enter Operation details
- Select Operation from drop-down list
- Select Result Entity from drop-down list
- Click Apply on the action bar, and then save the stream using the save button.
Metadata File Specifications
The operations object describes the operations that are displayed in the list of allowed operations in the Integration Wizard when using this agent. This object contains one or more operations specified as key-value pairs (separated by comma), where key is the name of the REST operation, which should be unique, and value is an object that contains several properties that describe the REST operation as explained below:
| Property Name | Required | Type | Property Value |
| endPoint | Required | string | Relative path to an individual endpoint of the REST API. This path is appended to the Base URL to construct the full URL of the REST API. |
| method | Required | string | Value to specify the operation type. Possible values are GET, POST, PUT, DELETE. |
| description | Required | string | Text which describes the operation. |
| contentType | Optional | string | Type of the content. Possible values are “application/json” (default) and “multipart/formdata”. |
| parameters | Optional | array | JSON array of input parameters. Only required when the operation requires any input. Refer to Parameters Object for more details. |
| responseSchema | Optional | string | Name of the response schema. This should match the name of one of the items specified under the “definitions” object. Required when the operation has a response. |
“operations”: {“Get Asset By ID”: {
“endPoint”: “/Asset?id={AssetID}”,
“method”: “GET”,
“description”: “Gets a list of Assets”,
“parameters”: [
{
“name”: “X-APIKEY”,
“in”: “header”,
“type”: “string”,
“required”: true
},
{
“name”: “AssetID”,
“in”: “path”,
“type”: “string”,
“required”: true
}],
“responseSchema”: “PlantSet”
},
“Get Customers”: {
…………
}
}
The parameters object describes the input parameters that are required by the RES operation. This object is of type JSON array, in which each item describes one Parameter. Each Parameter object has several properties as explained below.
| Property Name | Required | Type | Property Value |
| name | Required | string | Name of the parameter. This value is case-sensitive and should be unique. |
| in | Required | string | Specifies the location of the parameter. Possible values are “header”, “path”, “body”, “formdata”. |
| type | Required | string | JSON data type that denotes the type of the property’s value. Value can be specified as “file” when the REST operation requires a file as input, in which case the value of the “in” property should be “formdata”. |
| required | Optional | boolean | Specifies whether this parameter is required or not. The default value is false. If this value is true, the mapped XMPro form control will also be set to Required = true. |
| schema | Optional | string | Required when the parameter type is an object and the value of the “in” property is “body”. |
Example:
“parameters”: [
{
“name”: “X-APIKEY”,
“in”: “header”,
“type”: “string”,
“required”: true
},
{
“name”: “ID”,
“in”: “path”,
“type”: “string”,
“required”: true
},
{
“name”: “Announcement”,
“in”: “body”,
“type”: “object”,
“schema”: “NewAnnouncement”
}]
The definitions object describes the definition of schemas referred to in the Operations object. This object contains one or more definitions specified as key-value pairs separated by comma, where the key is the name of the schema which should be unique and the value is an object that contains several properties that describes the schema, as explained below. The value should conform to the Newtonsoft JSON Schema specifications.
| Property Name | Required | Type | Property Value |
| title | Required | string | Short text that describes the schema. |
| description | Optional | string | Text that describes the schema. |
| type | Required | string | JSON data type that denotes the type of the property’s value. Possible options are “object”, “array”. |
| properties | Optional | object | Required when the definition type is “object”. Comma separated key-value pairs that define the properties of the schema, where the key is the name of the property and the value is an object which defines the schema of the property. Use “format”=“date” or “date-time” and “pattern”=“<date/time format>” to format properties that contain date or datetime values. (refer to examples for syntax) |
| items | Optional | object | Required when the definition type is “array”. Defines the schema of a single item of the array. This schema definition can be specified inline as another definition object or as a reference to one of the definition objects already specified using “$ref” property (refer to example below for syntax). |
Example:
“definitions”: {
“Announcement”: {
“title”: “Announcement”,
“description”: “Announcement”,
“type”: “object”,
“properties”: {
“id”: {
“type”: “string”
},
“type”: {
“type”: “string”
},
“priority”: {
“type”: “string”
},
“status”: {
“type”: “string”
}
}
},
“AnnouncementList”: {
“title”: “Announcement List”,
“description”: “Announcement List”,
“type”: “array”,
“items”: {
“$ref”: “#/definitions/Announcement”
}
},
“announcementModels”: {
“title”: “AnnouncementModels”,
“type”: “array”,
“items”: {
“title”: “AnnouncementModels”,
“type”: “object”,
“properties”: {
“modelID”: {
“type”: “string”
},
“modelName”: {
“type”: “string”
},
“modelClass”: {
“type”: “string”
}
}
}
}
}
Limitations
- Only JSON based REST APIs are supported.
Release Notes
| Version: | 3.02 |
| Released: | 13-Aug-2018 |
| Release Notes: | Added OnError endpoint. |
| Version | Released | Release Notes |
| 3.01 | 07-Aug-2018 | Removed SSL3 protocol support |
| 3.0 | 03-Aug-2018 | Initial Release |