Tags

Tags define a URL that is used to communicate with the REST service. The URL is a combination of the Base URL configured for the REST client and an optional relative URL configured for each tag.

Add Tags

To add tags, select a topic in the navigation panel and press the “Add” toolbar button.

../_images/rest-add-tags.png

In the dialog that opens, enter an optional tag name prefix and one or more relative URLs in separate lines. For example, if your Base URL is “https://localhost/tags” and each tag is accessible by its ID in the form “https://localhost/tags/1”, “https://localhost/tags/2”, “https://localhost/tags/3” and so forth, then you may want to use a tag name prefix called “Tag” with the relative URLs simply consisting of the ID of each tag:

../_images/rest-add-tags-dlg.png

Click the “Add” button in the dialog to add the tags to the topic. In the example above, tags will be added as “Tag1”, “Tag2” and “Tag3”.

Alternatively, you can use the tag browser to connect to the REST service and query available data.

Tag Browser

The tag browser will send a “GET” request to the given URL (the combination of the Base URL and the relative URL) to retrieve the JSON response. Expand the magnifying glass node in the tag browser to fetch available data. Without JSON decoding, the listed tag will contain the entire JSON response.

../_images/rest-tag-browser.png

Optionally, you can parse the JSON response to extract a subset of information. Check the “Decode JSON” box to decode the JSON response.

../_images/rest-tag-browser-2.png

In this case the JSON response contains an array of tag objects and each object and its properties are listed separately in the tag browser. You can now drag separate elements onto the topic panel.

Note

When tags are added using JSON decoding then the entire JSON response is requested from the REST service and parsed to extract the information of interest for each tag. JSON decoding is best used when most of the JSON response contains useful information.

JSON decoder settings are:

  • JSON path
    A path that selects the relavant parts of the JSON response for processing (see https://datatracker.ietf.org/doc/id/draft-goessner-dispatch-jsonpath-00.html). If the path is empty then the entire JSON response is selected for processing and the response itself should contain a single tag object or an array of tag objects.
  • JSON Tag Object Property containing the tag name
    If the tag object contains a property that identifies the tag object by name, then enter the name of the property here. For example, the property name could be “name” or “tagName” or similar. If such a name property exists then the tag browser will use the value of the name property to construct a more descriptive tag name, for example “Tag1.floatValue” instead of “#[0].floatValue”.
  • JSON Tag Object Property Selector
    If only one property of the tag object is of interest then enter the name of the property here. If specified then the tag browser will locate the property and omit the property name from the tag name. For example, if the property of interest is “floatValue” then the tag browser may present tags simply as “Tag1” instead of “Tag1.floatValue” with “Tag1” representing the specified value of the tag.

Select one or more tags and drag the tags onto the topic panel to add tags.

../_images/rest-drag-tags.png

Tag Settings

Select a tag in the content panel to modify its settings.

../_images/rest-tag-settings.png
  • Name
    Choose a name for the tag.
  • Relative URL
    The REST client’s base URL combined with the tag’s relative URL form the request URL used to request information about this tag from the REST service. The service response is expected to contain the tag’s value, either in its entirety (for example, as a JSON string) or partially when used with JSON decoding.
  • Value
    This field is read-only and shows the current tag value. If the value is a JSON string then you can copy the value and use it in tasks as a representative JSON object within the JSON encoder or decoder .
  • Decode JSON
    Check the box to decode the service response. If tags were dragged from the tag browser then this and the following fields may be pre-populated with settings determined by the tag browser.
  • JSON path
    A path that selects the relavant parts of the JSON response for processing (see also https://datatracker.ietf.org/doc/id/draft-goessner-dispatch-jsonpath-00.html). If the path is empty then the entire JSON response is selected for processing and the response itself should contain the tag object.
  • JSON Tag Object Property containing the tag name
    If the tag object contains a property that identifies the tag object by name, then enter the name of the property here.
  • JSON Tag Object Name that identifies this tag
    The value of the tag’s name property that identifies this tag.
  • JSON Tag Object Property Selector
    If only one property of the tag object is of interest then enter the name of the property here.

Remove Tags

To remove tags from a topic, select tags within the topic’s content panel, then press the toolbar’s “Remove” button to remove selected tags.

../_images/rest-remove-tags.png

Warning

Note that the tags are also removed from any task using the tags.