Configuring a TurboIntegrator process to execute on a workflow action

You can configure the execution of a TurboIntegrator process from a Cognos® TM1® Application Server workflow action.

Procedure

Create the custom TurboIntegrator process that you want to execute.

The Cognos TM1 Application Server needs the context of the workflow action, the approval hierarchy node used, and the Application from which the workflow action was performed. The TurboIntegrator process must have the following parameters in this order on the Advanced tab:

pExecutionId
pAppId
pNodeId
pWorkflowAction

pAppId

Represents the GUID unique identifer for the application. The GUID identifies the application that triggered the action. You can deploy more than one application from the same cube so you need to identify exactly which application triggered the action.

pNodeId

Represents the node from which the workflow action was performed. pNodeId is always a single value; in the case of a multi-node edit, pNodeId represents the consolidated node from which the action was performed. To return a list of leaf nodes below this consolidated node, you can write your own process logic, or use the tp_custom_process_util_get_editable_leaf_children_subset utility process provided with the Cognos TM1 Application Server.

pWorkflowAction

Returns one of the following values:

Table 1. pWorkflowAction values
Value of pWorkflow Action	Description
ENTER	Open an approval hierarchy node with either the Cognos Insight or Cognos TM1 Application Web clients.
OWN	Take Ownership of a node.
SAVE	Commit data for a node.
SUBMIT	Submit a node.
REJECT	Reject a node.
LEAVE	Close the Cognos Insight or Cognos TM1 Application Web client after using a particular node.
SUBMITCHILDREN	Submit the leaf children of a consolidated node from the Cognos Insight or Cognos TM1 Application Web client.
ANNOTATE
RELEASE	Release ownership of a node
OFFLINE	Take the approval hierarchy node Offline when using the Cognos Insight client in Distributed mode.
ONLINE	Return the approval hierarchy node to Online when using the Cognos Insight client in Distributed mode.

All workflow actions are not available in all application types. For example, the Submit and Reject actions cannot occur in a Responsibility application.

You cannot set a Pre-Workflow TurboIntegrator process for the Commit action.

To return specific messages in the correct locale to the user of the Application, the Process must call a specific system-generated TurboIntegrator process that generates a ProcessError; call:

vReturnValue = ExecuteProcess('}tp_error_update_error_cube', 
		'pGuid', pExecutionId, 
		'pProcess', 'tp_pre_action_validation', 
		'pErrorCode', 'OtherRevWarning',
		'pErrorDetails', vErrorDetails,
		'pControl', 'Y');

ProcessError;

Update only the pErrorCode and pErrorDetails fields in this ExecuteProcess() statement. Do not edit the other fields.

pProcess

The name of the current process.

pErrorCode

A code that represents the error condition that is used to warn the user about (OtherRevWarning in this example). A more descriptive string that can be localized corresponding to this Error Code can be configured in the Cognos TM1 Applications Portal as described in this topic.

pErrorDetails

Can be any string that returns supplementary information that you want returned to the user when the user takes the workflow action. In this case, a variable vErrorDetails was used, but a specific text string can also be used. This value cannot be localized. The custom Process must display a ProcessError; statement in order for the Cognos TM1 Application Server to present an error or warning to the user. The actions that cause the custom Process to return a warning or error are also logged in the }tp_process_errors cube. This cube is maintained by the Cognos TM1 Application Server and is not edited.

Determine the messages to return to the user.
You can define a number of Error Codes in the Cognos TM1 Application Portal and associate them with text strings for specific user locales. You can also define an Error condition which stops workflow execution immediately.

For example, the for an Error Code called CheckPrices, CheckPrices is the code used for the parameter pErrorCode in the custom Process. The strings that you see for English and French can be identified by their system locale. To display the correct strings, the Cognos TM1 server must be correctly configured with Caption support, so that the relevant Cultures (en, en-GB, en-US, fr, fr-FR, and so on) are linked to the relevant Captions in the Cognos TM1 server.
To set the codes, click the Maintenance option found on the IBM® Cognos TM1 Application Configuration menu.
To set the custom action, open the application in the Application Design tab of Cognos TM1 Performance Modeler.
Select the application and display the Properties tab in the pane.
Click the ellipses at the Custom Processes label to display the dialog box where you can set the Pre and Post Process names and whether it is enabled.
Click OK.
```
						Enabled				PreProcess										Enabled		PostProcess
Submit			Yes					Other Revenue Validation		No
Reject			No 					Other Revenue Validation		No
Annotate		No 					Other Revenue Validation		No
```
In this example, the Process Other Revenue Validation is configured to run as a Pre-workflow action process in the event of Submit, Reject or Annotate. However, it is enabled only for the Submit workflow action.

You can configure the same action for Pre- and Post-workflow actions. However, you can configure only one Process to run in each case. For example, you cannot name three Processes to run as Post Process actions for the Submit operation. Only one process is allowed.

The Application must be deployed for these settings to take effect.

Test the custom Process execution in a Development environment before deploying to a Production system. If any problems occur with the custom Process execution, use the Enabled flag to selectively isolate the custom Processes to determine whether the workflow actions proceed normally when the custom Process is not running.