|
|
The features on this page require a GENESIS64 Advanced license and are not available with GENESIS64 Basic SCADA . |
|
|
The features on this page require a GENESIS64 Advanced license and are not available with GENESIS64 Basic SCADA . |
The following sections describe how the services and methods configured in Workbench are exposed by the Web Services runtime, and how can data be used by clients.
In runtime, it is possible to explore the configured Web Methods using the Unified Data Browser. Each configured Web Service Folder is represented by a folder in the address space, containing the Services which, in turn, contain Web Methods.
Browsing the Address Space
Under each method there are some special folders and properties that are always present, like @@Raw, @@Diagnostic and @@StatusCode. The rest of the properties depend on the schema of the web method’s result.
In the example above, the Forecast method is configured to return an array, and that’s why we see the property [0] displayed. If we expand that property, we can observe the schema of the array items:
Browsing into a property
A Web Method is ideal when clients need to consume data from a web service or an API, and the method invoked on the service just returns data without changing the state of the service.
Data from Web Methods can be easily consumed by GENESIS64 clients such as GraphWorX64. The Web Services runtime exposes data both as datasets, which are suitable for visualization in controls like the Table control or GridWorX Viewer, or as individual values, suitable for visualization in process points.
A Web Method node in the Unified Data Browser is exposed as a dataset, which can be consumed, for example, by the table control.
Visualizing the Forecast Result in a Table Control
The Web Services runtime automatically converts the result into tabular format, with some limitations. If the result is an array (like in the picture above), then each item of the array will be bound to a row in the output dataset. If the result contains an object, each property of the object will be bound to a column with the same name in the output dataset.
If a property value that is bound to a column contains a complex type (an object or an array), then the associated cell in the dataset will contain the property’s JSON as a string without being further expanded.
Properties in the result can be subscribed individually as process points.
Subscribing to a Property as a Process Point
The path into the result can be seen in the screenshot above. It shows that we are subscribed to the first item in the array, indexed by [0], and the temperature property. The Unified Data Browser only exposes the first element of an array for performance reasons, but it is possible to subscribe to other elements of the array by manually changing the index in the square brackets.
Subscribing to a Different Element in the Array
The special @@Raw point is exposed by any property that is not a scalar value and returns the property value as a JSON string.
@@Raw Points Exposed at Various Level of the Address Space
The JSON exposed by the @@Raw property can be used in other applications like BridgeWorX64 or AnalytiX-BI for further JSON parsing.
Subscribing to a @@Raw point
Array properties also expose a special @@Count point, which returns the number of items (the length) of the array.
Subscribing to the @@Count point to retrieve the length of an Array
The @@Count point is especially useful when used in conjunction with GraphWorX64’s clone dynamic.
The other points exposed by a web method are @@Refresh and @@StatusCode.
@@StatusCodesimply returns the HTTP status code of the last call made to the web method.
The @@Refresh point is a writeable point of type Boolean. When true is written to this point, it signals to the Web Services runtime to drop all the cached items for the current web method. If clients are subscribed to the web method properties, this will trigger a new call to the underlying service and all web method properties on all clients will receive an update with the new data retrieved.
For more information on how the Web Services Runtime caches data, refer to the How the Web Services runtime caches and refreshes data section.
The @@Refresh point acts like a toggle, and it will automatically revert to the false value after a value is written to it.
The @@Diagnostic folder contains several points that return metadata and information about the method.
Contents of the @@Diagnostic Folder
@@CachedItemsCount. Returns how many items for this method are stored in the Web Services Runtime cache. For more details on how caching works, see How the Web Services runtime caches and refreshes data.
@@LastCallStatus, @@LastCallStatusCode. These points return the outcome of the last call made to the web method respectively as an integer and a human-readable string. The possible values are:
o -1 – Unavailable. The status of the last call is not available.
o 0 – Succeeded. The last call to the web method completed successfully.
o 1 – Running. The call to the web method is currently executing.
o 2 – Failed. The last call to the web method failed.
o 3 – Timed out. The last call to the web method timed out.
@@LastRefreshed. Returns the timestamp, in local time, of when the web method was called for the last time and all the cached items associated to the method were flushed from the cache.
@@LastRefreshedUTC.Returns the timestamp, in UTC, of when the web method was called for the last time and all the cached items associated to the method were flushed from the cache.
@@ResolvedPointName.Returns the actual point name used by the server. This is useful in scenarios where the point name is dynamically built with aliasing, because it allows to verify exactly what the Web Services runtime received when subscribing to the point.
In addition, there is a special diagnostic point at the root of the address space:
@@TotalCachedItemsCount. Returns how many items, in total, are stored in the Web Services runtime cache.
A Web Manipulator is ideal when having to call a service or an API and we need to modify the state of the service (i.e., creating a work order, deleting a post, etc.).
The structure of the address space of a Web Manipulator is a bit different from a Web Method as it does not contain diagnostic points or expose the properties of the method’s result.
Expanding a Web Manipulator in the Unified Data Browser
Under the Web Manipulator we can find a Parameters folder that contains the individual parameters exposed by the Web Manipulator. These tags are writeable and can be used to set the manipulator parameter values before executing the Web Manipulator. The Web Services runtime isolates these special tags by process and user so, if two users are working on the same screen with the same manipulator parameters, each user will receive and will operate on their own individual copy of the parameter tags.
Although the Web Services runtime provides isolation of parameter values, the preferred method of executing a Web Manipulator is to specify the parameters explicitly with the @@Execute tag, or to execute the manipulator as a FrameWorX Method. Both approaches guarantee an atomic execution.
The @@Execute tag is a writeable Boolean tag that is used to execute the Web Manipulator. Writing true to this tag will trigger the execution of the Web Manipulator. If an error occurs during the execution of the Web Manipulator, the Web Services runtime will report a bad status code back from the write: more details about the error can be found in the server’s trace logs (if enabled).
The @@Execute point acts like a toggle, and it will automatically revert to the false value after a value is written to it.
Parameter values for a Web Manipulator can also be specified in the same point name of the @@Execute tag.
Passing Parameters with the @@Execute Tag
If true is written to the @@Execute tag as shown above, the parameter values specified in the point name will be passed to the Web Manipulator. If individual tags for the parameters are present on the same screen, values from those tags will override the parameter values specified with the @@Execute tag.
Finally, Web Manipulators expose two special tags that can be used to retrieve information about the call. The @@StatusCode call returns the HTTP status code from received from the underlying method after the call. The @@Data tag exposes the result from the call to the underlying method (if any). These tags initially do not display any value and will only be refreshed once the manipulator is executed.
Initial State of a Screen with Various Manipulator Points
After writing true to the @@Execute tag, we can see the HTTP status code of the call and the result returned from the underlying method. Note how the value assigned to the @title parameter tag has overridden the value specified for @title in the @@Execute tag.
Result of a Web Manipulator Call
These tags will maintain their value until the Web Manipulator is executed again. In this case, they will display the new result, or they are unsubscribed from. In this case, they will revert to their default values.
The @@Data tag cannot be browsed into from the Unified Data Browser, meaning that if the underlying method’s result is a complex object, its properties will not be exposed under the @@Data tag. However, it is possible to subscribe to individual properties of the result by manually adding the property path after @@Data in the tag name.
Retrieving the Id Property from the Web Manipulator Result
The example above retrieves the value of the id property from the manipulator result. Please note that property names are case-sensitive.
As mentioned previously, the Web Services runtime caches results received from underlying methods and utilizes cached data to improve runtime performance when multiple clients request the same information, and to reduce traffic to the underlying services.
Items are stored in the cache based on the path (folder + service + method) of the method invoked, plus the values passed to the method’s parameters. The entire result of the method is stored in the cache, even if the client only requests a property from the result itself.
For example, the following tag retrieves the current meteorological conditions for the KBOS station:
ws:Sample Web Services.National Weather Service.Current
Conditions<@stationid=KBOS>
If a client requests an individual property from this method call, for example the Temperature:
ws:Sample Web Services.National Weather Service.Current
Conditions<@stationid=KBOS>.Temperature
Since the path and the parameter value(s) are the same, the result will be retrieved from the cache. If another client changes the value of the parameter to retrieve, for example, the current condition for the KPVD station:
ws:Sample Web Services.National Weather Service.Current
Conditions<@stationid=KPVD>
This will cause a call to be made to the underlying service, and the new result will then be added to the cache.
The Web Services runtime default cache size is 400 items. After 400 different results have been cached, if a new item has to be inserted in the cache, the least recently accessed cached item will be evicted from the cache to make space for the new item.
The cache size can be configured by changing the CacheMaxSizeItems parameter as explained in the Web Services Point Manager Parameters section.
Items are kept in the cache using a sliding expiration timer: if an item is not accessed within the configured time, it will be removed from the cache. Accessing the item resets the sliding timeout.
Please note that if the method is configured for Periodic or By Triggers refresh, its cached value can still be removed from the cache if the sliding inactivity timeout happens before the refresh signal.
The default sliding timeout can be configured by changing the ItemCacheSlidingExpirationMins parameter as explained in the Web Services Point Manager Parameters Section.