uCosminexus Service Platform, Basic Development Guide

[Contents][Glossary][Index][Back][Next]

5.5.1 Defining Variables

When defining a business process, you can include characters, numeric values to be included in messages, numeric values that become terms in conditional expressions, or messages as variables. Because variable values can be recorded in a database, they can be managed as execution history.

Organization of this subsection
(1) Variable types
(2) Variable formats
(3) Activities to which variables can be assigned
(4) Showing variables and acquiring paths
(5) Notes on using variables
(6) Variable definition methods
(7) Output of message format definition file

(1) Variable types

There are two types of variables: global variables and local variables.

(2) Variable formats

In variables, you can define the values of following types. You can save the variable only for the value of defined type.

(3) Activities to which variables can be assigned

You can assign variables to the activities and items shown in the following table.

Table 5-4 Activities and items to which variables can be assigned

Activity Item Allocated contents Remarks
Receive activity Request message Variable of message type for referencing the request message received from the service requester It is used in also in specification of correlation set.
Reply activity Response message Variable of message type for referencing response message or fault message to the service requester
Invoke service activity (synchronous) Request message Variable of message type for referencing the request message when invoking the synchronous service
Response message Variable of message type for referencing the response message received from the invoked synchronous service
Fault message Variable of message type for referencing response message to be received when fault occurs in the invoked synchronous service --
Invoke service activity (asynchronous) Request message Variable for message type for referencing the request message when invoking the asynchronous service It is used also in the specification of correlation set
Invoke java activity Argument Variable for referencing the value, which serves as argument when invoking the user-created Java class --
Return value Variable for referencing the return value from the invoked Java class --
Data transformation activity Transformation source data This is variable of message type for referencing the transformation source data when transforming the data in data transformation activity and you can specify multiple variables --
Transformation destination data Variable of the message type for referencing the transformation destination data when transforming the data in the data transformation activity --
Assign activity Copy source Variable for referencing the data that serves as copy source when copying the data in assign activity --
Copy destination Variable for referencing the data that serves as copy destination when copying the data in assign activity --
Throw activity Fault message Variable of message type for referencing the fault message, when throwing fault in the throw activity --
Standby activity Standby time Variable for referencing the value of standby time --
Validate activity Variables to be validated Variable to be validated --
While activity Repetition condition Variable for referencing the value of while loop variable or end condition expression --
Repetition list Variable for referencing in the expression for acquiring the repetition list --
Repetition element variable Variable for storing the repetition element --
Switch activity Distribution condition Variable for referencing the value that serves as item of distribution condition expression --

(Legend)
--: Not applicable

(4) Showing variables and acquiring paths

Clicking the Show Tree button in the Variable-Correlation Set dialog box opens XML schema viewer Parameters. You can show XML schemas that match variables in a tree view. When you choose a variable displayed in the tree view, the path to the chooseed variable is displayed in Chooseed path as an absolute path from the root element.

When you choose and right-click a variable and choose Get Path, you can obtain the absolute path from the root element. You can paste the acquired path in the desired location.

Note
Take note of the following points when operating the Show Variables dialog box:
  • You cannot edit the XML schema displayed in the Show Variables dialog box.
  • You can choose only one variable in the Tree view.
  • If elements re-enter the XML schema of the variables that you want to display in the Show Variables dialog box, elements from the second hierarchy onwards will not be displayed.
  • The substitutionGroup attribute of the XML schema will be ignored.

(5) Notes on using variables

(a) Use of variables when scope activities are used

You can add or edit variables that are used by activities inside business processes or scopes. In this case, variables declared outside a scope can be referenced from inside the scope, but variables declared inside a scope cannot be referenced from outside the scope. Note that the same variable names can be declared within different scopes. In the following figure, while Scope A and Scope B can reference variables outside their scope in other parts of the process, the variables of Scope A and Scope B cannot be referenced from the process (from outside their scope).

Figure 5-5 Relationship between a scope and variables

[Figure]

(b) Use of variables when defining fault handling

When defining fault handling for a scope activity, choose the variable to be used as an assign variable in the Fault Handler dialog box. The chooseable variables are those that are defined in the fault-target scope (including a scope activity) or a scope on the outside. However, if a variable having the same name as the variable chooseed in the Fault Handler dialog box is also defined in the fault-target scope, the variable defined in the fault-target scope, and not the variable chooseed in the Fault Handler dialog box, is used during execution, and may result in unintended operations. Therefore, when defining fault handling for a scope activity, ensure that no variable having the same name as the variable chooseed in the Fault Handler dialog box is defined in the fault-target scope.

(c) Message formats used when defining variables

File name of a message format
When defining variables, you can specify definition files in the message format having the same file name but different XML schemas for multiple variables. However, because only one of these XML schemas is used during execution, an unintended operation may occur. Therefore, ensure that the file names in the message format specified when defining variables correspond to XML schemas on a one-to-one basis.

Setting a message format that contains external XML schema references
For specifying a message format that references an external XML schema, you must specify a file for the root schema. The external XML schema file referenced from the root schema is automatically imported.

Format of a message format
The message format used in the variable must satisfy the conditions described in 2.6.5 Scoping of XML schema. For details about the conditions, see 2.6.5 Scoping of XML schema.
(d) Modifying the definition information of variables

You can change or delete the definition information (variable name, type, message format and part) of variable and correlation set as and when required.

Note
Take note of the following points, when changing the definition information of variables,
  • When you change the message format of variables used in data transformation activity, re-define the data transformation. For details on definition when changing the message format, see "6.3.2 Procedure for defining changed message formats".
  • When you change the name of a variable used in data transformation activity for which data transformation definition file has been defined, warning message is displayed. In that case, mapping related to the changed variable is discarded.
  • When you change the variable definition information, you must re-assign to the location where that variable is assigned.
    For example, when you assign variable X to some activity and then change the name of that variable X to variable Y, perform either of the following:
    Re-assign a variable again to the activity
    Re-define variable X.
  • You must take care when changing variable name after upgrading the version of a business process. For details, see "5.9.4(3) Points to be noted when upgrading the version of business process".
(e) Initializing definition information of variables

When executing a business process, you must set a numeric value or message, which can serve as item of numeric value or condition expression, included in the character or message, in the variable.

When receiving a request from the service requester or receiving a response from the service by Invoke service activity, a value has been entered in the variable. However, in other cases, you must set a value to variable ,(initialize) by using data transformation activity or Switch activity.

Following section describes the cases when variable initialization is not required:

For the variables specified in the following locations, value has been set before referencing the variable (message) and hence you need not initialize these variables:

Following figure shows the example when initializing a variable is not required:

Figure 5-6 Examples when initialing a variable is not required

[Figure]

Variable A:
Request message from the service requester is set as the value of variable. Also, as variable A for which service invoking value has already been set, initializing is not required.

Variable B:
As variable has been set in the reply message from a service, initializing is not required.

Description about the cases when initializing a variable is required, is as follows:

As value is not set for the variable not specified in the location shown when initializing the variable is not required, if you reference such variables in a business process, an error occurs. You must set the value beforehand and initialize the variable.

Following are the locations where variables for which value has not been set, can be specified:

Following figure shows the examples of cases when initializing a variable is required:

Figure 5-7 Example when initializing a variable is required

[Figure]

Variable A:
As a request message from the service requester has been set in the variable, initializing is not required.

Variable B:
Initializing a variable is required. In data transformation A, you can set a value in variable B, based on the information of variable A.

Variable C:
Initializing is not required as the reply message from the service is set in the variable.

Variable D:
Initializing a variable is required. In data transformation B, you can set value to variableD, based on the information of variableC.

(6) Variable definition methods

(a) Defining new variables

The procedure for defining new variables is described below. Note that variables cannot be defined on a canvas inside a while activity.

  1. Use one of the following methods to open the Variable-Correlation Set dialog box:
    • Double-click the Variable-Correlation Set icon on the canvas in the Business Process Definition screen.
    • Click Edit in the dialog boxes for the following activities:
      [Figure] Receive activity
      [Figure] Reply activity
      [Figure] Service invocation activity
      [Figure] Java invocation activity
      [Figure] Data transformation activity
      [Figure] Assign activity
      [Figure] Throw activity
  2. In the list that is displayed, choose Variable List.
  3. Enter a variable name.
  4. Choose a variable type from the drop-down list.
  5. Perform one of the following operations as needed:
    If the variable type is message type and you want to set the message format specified in the request message, response message, or fault message of a service component to be invoked or user-defined reception to variable:
    Click Get Format to view the Get Message Format dialog box. Specify the message format you want to use in the Get Message Format dialog box.
    For details about the input and display items of the Get Message Format dialog box, see the manual Cosminexus Service Platform Reference.
    Proceed to step 6. after the operations in the Get Message Format dialog box are complete.
    If the variable type is message type, and for the cases other than mentioned above
    Click ... and set the definition file of the message format that uses the variable.
    For converting an exception for error occurred when invoking service component (Web Services) from service adapter to a fault message in service adapter, click the ... button and choose Cosminexus installation directory\CSC\system\msg\cscfault.xsd.
  6. When the variable type is Message, choose the Part Specifications check box.
  7. Click Add Line and specify a part name, an expression, and a type.
  8. Click Add.
    The added variable is displayed in the variable list.
  9. Click OK.
(b) When a message format definition file is modified

If the message format definition file specified during the definition of the variable is modified, the contents of the modified definition file can be committed using the following procedure:

  1. Open the Variable-Correlation Set dialog box.
    For details about how to open the Variable-Correlation Set dialog box, see step 1 in 5.5.1(6)(a) Defining new variables.
  2. Perform one of the following operations:
    If the variable type is message type and you want to set the message format specified in the request message, response message, or fault message of a service component to be invoked or user-defined reception to variable:
    Click Get Format to view the Get Message Format dialog box. Specify the message format you want to use in the Get Message Format dialog box.
    For details about the input and display items of the Get Message Format dialog box, see the manual Cosminexus Service Platform Reference.
    Proceed to step 3. after the operations in the Get Message Format dialog box are complete.
    If the variable type is message type, and for the cases other than mentioned above
    Click ... and set the definition file of the message format that uses the variable.
  3. Click Update button.

(7) Output of message format definition file

Description about a method to output a message format definition file is as follows:

When you want to set the message format of variable set in the activity at copy source, to the variable of activity at copy destination, you can output a message format definition file in the Variable/correlation set list dialog.

Format of the message format definition file that you can output, is either of the following formats:

Procedure to output the message format definition file is as follows:

  1. Click [Output] button of the Variable/correlation set list dialog.
    Dialog for specifying the output destination is displayed.
  2. Specify an output destination and click [OK] button.
    The message format definition file is output to the specified folder. In case of message type (XML) variable formed from definition file having multiple output targets, output file name is automatically assigned.