Table of Contents
- Pipeline Modes
- Configuring a Server Action
- SQL Action:
- Node Variable Mappings
- Additional Services
- dataProducerService API for edgeSuite 3.7.x and newer
- dataProducerService API for edgeSuite 3.6.x and older
- Example Statements
- Configuring Refresh
- Refresh Indication
- Creating a Server Action
- Invoking Server Actions via Edge CLI
Conceptually, a Server Action is a feed that works in reverse. Instead of pulling data in from a source (left to right), a Server Action updates values on the source (right to left). Server Actions are typically used to update values for a specific record, such as changing ticket status from “open” to “acknowledged”. They require special configuration off of a connection before they become available on a page.
Pipeline Modes #
Server Actions have a special pipeline mode. In the pipeline, there is a button group located at the far right of the footer. By default, it is set to “Data”. This mode shows the normal data flow, from source to visualization, and hides Server Actions.
In order to see Server Actions, the pipeline must be set to “Actions”. This hides the normal flow of data, and shows only the Server Action Feeds that write back to the server.
Configuring a Server Action #
Action Name #
Give this Action a name that will be used on a context menu if more than one Action is configured for the event.
Wait for server response #
Determines whether this Action will block a user from interacting with the user interface while waiting for the Action to be completed by the server.
|Yes||The user is blocked from interacting with the user interface until the action is complete.|
|No||The user can continue interacting with the user interface. They will be notified via a client message when the server action is complete.|
User Notification #
|Always||This will notify an end user whenever a server action completes successfully or when there is an error.|
|Never||This will suppress all messages for server actions.|
|On Error||This will only notify an end user when there is an error.|
The Message Center should also contain information about the results of the server action.
SQL Action: #
Query Timeout #
Number of seconds to wait for the query to return results from the database. If time is exceeded, the feed and downstream pipeline steps will display an error.
Ignore SQL Comment
|Yes||Text inside of the comment block /* … */ or inline comment — in the query statement will be ignored|
|No||The server will attempt to parse comments for edgeSuite tokens nodeVar, safeNodeVar, and src which can result in server error. This option should be on in most of the cases unless you need to have /*, */ or — as part of a literal string.|
A SQL statement that will fire when a Server Action is initialized on the client.
|Secured Variables||Secured Variables resolve to values based on the User that is logged into the system. If you have configured Secured Variables in the system, you can include them here to filter the data that will be returned based on what User is accessing this Action. For more information, see Configuring Secured Variables.To access a variable in the script, use secVars.varName.|
|Java Libraries||If the Action’s script contains any references to Java library code which depends on any libraries installed in the
Node Variable Mappings #
When Node Variables are used in Server Actions, the administrator will be presented with some additional configuration to define how the Node Variables should be evaluated.
|Default||Use the default value for the Node Variable.|
|Page Variable||Set the Node Variable based on the current value of a Page Variable on the page.|
Present a dialog for the user to manually enter a value at the time of the action.
Optionally initialize the value with any of the other four options listed in this table.
|Record Value||Use the value of an attribute on the record associated with the action.|
|Static||Assign a hard-coded value for the action that is always used whenever the action is fired.|
|Status||SUCCEEDED, FAILED, or ERROR|
|Action Result Details||Any message passed to makeActionSuccessResult(detailString) or makeActionFailureResult(detailString)|
|Console Output||Any text written to stdout using the print(string) function|
|Log Statements||Any text written to the edgeSuite log files using logger.debug(), logger.info(), logger.warn(), or logger.error().|
|Reference||Error details and, if available, a stacktrace to help identify where the error occurred|
Some situations require fetching the results of other data producers within the pipeline. This can be achieved via the dataProducerService object.
dataProducerService API for edgeSuite 3.7.x and newer #
fetchRecords(producerName, nodeVars, secVars) #
This function takes the name of the producer, as well as the nodeVars and secVars objects. Generally speaking, the nodeVars and secVars objects can be passed from the parent function (see above documentation for details). However, nodeVars can also be defined as an object with key:value pairs, which are then internally converted as required by the server.
The returned value is an array of objects (records) whose properties correspond to the attribute names of the resulting data set. The value of a record for a given attribute can then be accessed via record.attrName, e.g. record.foo = “bar”.
dataProducerService API for edgeSuite 3.6.x and older #
fetch(producerName, nodeVars, secVars) #
In addition to getData(), the returned DataResultsDO object has a method getResultStatusCode(), which returns an enum, the value of which is one of CURRENT, ERROR_STALE, ERROR_MISSING, REQUIRE_CREDENTIALS, or BAD_CREDENTIALS.
Example Statements #
The example below shows a sample statement that updates the status of a ticket.
This is the first of two steps required to configure a server action. This initial step will make a new action available off of any Visualization that uses this dataset. In the example above, an administrator will need to pass in two values to satisfy the variables used in the statement. These values will be passed in based on the record that is clicked in the associated Visualization. The variables can be wired to any attribute available in the underlying dataset, which means even values that are not displayed in the Visualization can be used.
Configuring Refresh #
Refresh determines whether any Feeds should be updated after the Server Action is performed. When a Feed is added to this list, any dataset downstream of that Feed will automatically refresh.
As of edgeSuite v3.7.2, there is an option to delay the refreshing of Feeds listed as part of the Server Action configuration. In case some time needs to be given for some datasources to update as a result of, or in relation to, the invoked Server Action, a delay in seconds can be specified. The default is to refresh all related pipeline jobs for the listed feeds immediately.
As of edgeSuite v3.8.4, there is an option to filter the refreshing of Feeds such that the pipeline jobs affected are only those whose Secured Variable values match the ones of the edgeSuite user who invoked the Server Action. Enabling this can reduce server resource use when there are potentially many pipeline jobs where refreshing them would be redundant, due to them being unrelated to the data affected by the Server Action.
When finished, the “incident_setstatus” Server Action appears as a visible node off of a connection.
Refresh Indication #
Switching the Pipeline to Data mode will hide the Server Action nodes. However, any Feed that has been targeted to be refreshed by a Server Action will have adecorator.
Creating a Server Action #
Once you have completed the above configuration of a Server Action, you are ready to add the Server Action to any Visualization that is configured off of that same connection. For instructions on creating an Action in a Visualization, see Actions.
When a user invokes a Server Action that is configured to have User Notification, a Message will be generated to make sure the user is aware that an external data update has occurred. A brief message is shown in the banner, and a more detailed message is also logged. The user can view messages by selecting System Menu / Messages.
Invoking Server Actions via Edge CLI
action -n NAME
[-v VARS...] where NAME is the name of the action, and VARS (which is optional) is a list of “key=value” pairs to set any node variables that have been defined for the action. An example of the command is as follows:
To run the command, user credentials need to accompany the arguments, or the edgeSuite server needs to be configured for pre-authenticated CLI access. For more information about action and other commands, see Edge CLI.