Note: To add or use external actions, you need TIBCO Cloud™ Integration license (TCI). For more information, see Enabling External Actions with TIBCO Cloud™ Integration.
Actions that include sending data to external systems make use of integration and connection services in TCI. Services can be created for specific action needs. From Spotfire, the services are then accessed using TIBCO Cloud Mesh, a global repository of these kinds of services.
A service contains various parameters to configure. When adding an action that calls a service, these defined parameters will be provided automatically in a configuration flyout in Spotfire, where you map them to your data. For example, you can define what kind of data in the visualization to send to the external system.
A configured action is then activated using some type of trigger in the visualization, like a floating button, as shown below, or a right-click menu item.
When adding a new action, you add it to a visualization of your choice, and you can specify one or more triggers in that visualization. When you have added an action, it becomes available for selection in all visualizations in the analysis. That is, an action can be added to more than one visualization in an analysis, using the same type of trigger or a different one. You can also add more than one action to a single visualization.
To add a new external action:
Right-click the visualization, and select Properties from the pop-up menu.
Go to the Actions page.
Click Add in the upper right corner.
Response: A default trigger type, Floating button, is added to the Triggers in visualization list.
If you want another trigger type, change to Right-click menu option or Title bar button in the Trigger type drop-down list.
To select a service to use for the action, click New.
Response: The TIBCO Cloud Login dialog is opened.
Log in to TIBCO Cloud, and follow the steps.
Response: Once logged in, the Select a service from TIBCO Cloud Mesh dialog is opened.
Locate and select the service to use for the action.
Response: The Configure action flyout is opened, listing the parameters that are defined for the service.
Optionally, click the pen to rename the action, and type a description.
Comment: A description of the action is recommended to inform people who run it about the purpose of the action.
Click 
to select an icon that will represent the action.
Expand the parameters, and configure the action, that is, map inputs to the contents of your analysis. For more details on the available options for the parameters, see Options for action parameters below.
Comment: It is the configurator of the action who determines what data the action will send. The configurator might select a data table, or one or more columns, to send data from, add a document property (perhaps a property that people can change using controls in a text area), or even type a value directly. By specifying the type Prompt for input when running action, the person who runs the action will be asked to provide the input. Optionally, a description can be added to a parameter using prompt as input type. A question mark icon will then be shown next to that parameter in the prompt, and the description will be available in the tooltip.
Click Next.
Response: The Review action configuration flyout is opened. The flyout shows the configuration and affected data that potentially will be sent externally.
Make sure the configuration is correct, and click Done.
Response: You are now the signer of the action. The action is added to the Available actions in analysis list on the Actions page of the Visualization Properties, and it is possible to add and use the action in any visualization in the analysis by associating it with a trigger.
Select the added action in the Action drop-down list to associate it with your trigger.
Response: A trigger of the chosen type is now available in the visualization for running the associated action.
Which options you have when configuring an action parameter, depends on how the parameter has been defined in the service. All input types and options described below will therefore not be available for each parameter. Open the Type drop-down list to see which input types are available for a parameter.
Value – type or select an input value. How to provide input depends on the data type of the parameter.
Custom expression – specify your own expression in the Edit expression dialog. The Limit by option is available for custom expressions, and can be used if you want to limit the data using filterings and/or markings.
Document property – select a document property to use as input. Use the search field to help locate your property.
Prompt for input when running action – select this option if you want the person running the action to provide the input. You can change the label and add a description to each parameter. For example, it can sometimes be useful to add a description to explain what input is expected for a specific parameter. How the parameter is defined, for example what data type is expected, will decide what kind of control will be shown in the prompt when the action is triggered:
Boolean (true/false) –
check box.
Note: It is important that you phrase
the check box label to clearly state that a selected check box
means true, while a cleared check box means false.
Predefined values (enum) – drop-down list.
Integer – spin box where only integers are allowed.
Real – text field where numeric values (integer or real) can be entered.
String – text field.
Data
view – if a parameter has been defined with Data
view as input type, a number of records in a tabular format
will be sent when the action is run. Select which data table the parameter
should retrieve data from, and in Row for each,
select a column to split the data into categories. Then define what
data to send for each of the categories by mapping each item in the
parameter to a column. The Limit by option
is also available for data view parameters, and can be used if you
want to limit the data using filterings and/or markings. The image
below shows an example of a parameter with data view input.
None – this option is available if a parameter has been defined as optional. Select None if you do not want to provide any input for the parameter.
Row limits for data view parameters
The person creating the service can specify row limits for data view parameters. This means that to run the action, the number of rows sent from that parameter must be within the limits. When row limits exist for a data view parameter, information about the limits will be shown in the Configure action flyout. The image below shows a data view parameter where only a maximum row limit has been specified, but you might also encounter services where the parameter expects a minimum number of rows, has both a minimum and a maximum number of rows defined, or expects an exact number of rows.
If you configure a data view parameter that requires a minimum or exact number of rows so that it also is limited by one or more markings, then any triggers that exist for the action will become grayed out until some items in the visualizations are marked.
A tooltip will let the person who wants to run the action know which markings must be used before it is possible to run the action, as you can see in the image below.
