6.5.7 Definition file for emulated configuration information

Organization of this subsection

(1) Format
(2) Function
(3) Specifiable elements
(4) Priority of definitions used for emulation
(5) Example of coding

(1) Format

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE HCSCAutoEmulate SYSTEM "debug_auto_emulate_list_file_1_0.dtd">
<HCSCAutoEmulate>
<viewState>
<emulate condition="(conditional-expression)" operation="(operation-name)" service="(service-name)" type="(response-type)" valid="(whether-to-perform-emulation)" xmlfile="(path-of-response-message-file)"/>
<emulate condition="(conditional-expression)" operation="(operation-name)" service="(service-name)" type="(response-type)" valid="(whether-to-perform-emulation)" xmlfile="(path-of-response-message-file)"/>
 ...
</viewState>
</HCSCAutoEmulate>

To Page Top

(2) Function

Specifies the configuration information for the emulation function in XML format. For details about the service emulation function, see the manual Service Platform Overview.

The definition file for emulated configuration information is read and parsed for each request at the following timing:

At the execution of the invoke service activity that is first defined in the business process
At the execution of the invoke service activity that is first defined after a reply activity
At the execution of the invoke service activity that is first defined after a standby activity

When a process instance is re-executed, this file is read and parsed at the execution of the invoke service activity that is first defined in the re-execution range.

A response message file specified in the xmlfile attribute is also read for each request. Therefore, any changes in the definition file for emulated configuration information or the response message file will be applied at the next request. Note that operations are not guaranteed if the contents of these files are changed during processing of a request.

Important note

If you emulate a response message by using the business process debug function in the development environment, the settings of the definition file for emulated configuration information are not enabled for the relevant invoke service activity.
During emulation, a service adapter is not invoked. Therefore, the functions specific to service adapters and used by service adapters, and some functions of the invoke service activity of a business process cannot be used.

Use the following procedure to create a definition file for emulated configuration information and apply it to the execution environment.

Copy the following template file to any directory.
```
service-platform-installation-directory\CSC\config\msg\templates\service_emulate_info.aels
```
You must define the file based on the template file. Operations are not guaranteed if the file is created in any other way.
Edit the element descriptions, and then save the file with any file name with the extension .aels.

If the extension is not .aels, an error occurs when you execute the cscsvconfig command (HCSC server runtime definitions).

To Page Top

(3) Specifiable elements

<?xml version="1.0" encoding="UTF-8"?>

An XML declaration indicating that this file is an XML file

<!DOCTYPE HCSCAutoEmulate SYSTEM "debug_auto_emulate_list_file_1_0.dtd">

An element-type declaration indicating a DTD subset

<HCSCAutoEmulate>

A root element for emulated configuration information

<viewState>

A root element for emulated configuration information

<emulate condition="(conditional-expression)" operation="(operation-name)" service="(service-name)" type="(response-type)" valid="(whether-to-perform-emulation)" xmlfile="(path-of-response-message-file)"/>

An element that defines emulated configuration information. You can define multiple emulate elements.

If multiple emulate elements that meet the following conditions are defined, the emulate elements are enabled in the order they appear.

The evaluation result of the conditional expression specified in the condition attribute is true.
The service attribute and the operation attribute have the same value.
The valid attribute is set to true.

For details about the priority of emulate elements, see (4) Priority of definitions used for emulation.

The following describes the contents to be specified in the emulate element.

condition="(conditional-expression)"

Enter the conditional expression for emulating the service, by using a string-type XPath.

You can specify the conditional expression only when the variable type of the request message is XML or non-XML. Operations are not guaranteed if the variable type is any.

The conditional expression is evaluated when valid=true (emulation function enabled) is set.

Note the following when you specify the conditional expression:

Specify an empty string if you do not use a conditional expression. If no conditional expression is used, true is assumed as the evaluation result of the conditional expression.
When you specify an XPath in a conditional expression, do not acquire information by using an extension function (for example, bpws:getVariableProperty) or by directly specifying a variable name. If you use such methods to specify an XPath, operations are not guaranteed.
To include an escape character (<, >, &, ", ') in the conditional expression, specify an entity reference.

operation="(operation-name)"

Specify the operation name of the service adapter in the string type.

service="(service-name)"

Specify the service name of the service adapter in the string type.

type="(response-type)"

Specify one of the following response types.

RESPONSE_NORMAL

This option specifies the normal response.

The contents of the response message file will be returned as a response message.
RESPONSE_FAULT

This option specifies the fault response.

The contents of the response message file will be returned as a fault message.

valid="(whether-to-perform-emulation)" ~ <<false>>

Select one of the following to specify whether to perform emulation.

true

Emulation is performed.
false

The service adapter is invoked without performing emulation.

xmlfile="(path-of-response-message-file)"

Specify the path of the response message file that contains the messages to be emulated, by using a string-type absolute path.

For a path separator, specify a forward slash (/) for the HCSC server in Windows and specify a backslash (\) for the HCSC server in UNIX.

To include an escape character (<, >, &, ", ') in the file path, specify an entity reference.

To specify XML format data for the response message, make sure that the XML character code is UTF-8.

Note that if you specify an XSLT style sheet (file extension: .xsl) for a response message, a message transformed from a request message by using the XSLT style sheet can be emulated as the response message. Note the following when you perform this emulation:

You can perform the emulation when the variable type is XML for both the request message and the response message. If the variable type of both messages is not XML, operations are not guaranteed.
You can specify only one transformation source (request message).
For the XSLT style sheet, you must specify a data transformation definition file generated by the mapping definition editor. In addition, the file extension must be .xsl. If any other file is specified, operations are not guaranteed.

To Page Top

(4) Priority of definitions used for emulation

The priority of definitions used for emulation is given in the order in which the emulate elements appear in the definition file for emulated configuration information.

The priority is applied to the emulate elements that meet the following conditions in the definition file for emulated configuration information:

The same value is set for the service attribute and operation attribute.
The valid attribute is set to true.

In the following example, false is set for the valid attribute of the first emulate element. Therefore, the emulation will be performed for the configuration information for the second emulate element.

                   :
<viewState>
<emulate condition="/root/elm1 = &quot;exec1&quot;" operation="exec" service="TP1Adapter" type="RESPONSE_NORMAL" valid="false" xmlfile="/data/telegram/exec1"/>
<emulate condition="/root/elm1 = &quot;exec2&quot;" operation="exec" service="TP1Adapter" type="RESPONSE_NORMAL" valid="true" xmlfile="/data/telegram/exec3"/>
<emulate condition="" operation="exec" service="TP1Adapter" type="RESPONSE_NORMAL" valid="true" xmlfile="/data/telegram/exec3"/>
</viewState>
                   :

Note that this priority does not apply to the emulate elements for which the evaluation result of the conditional expression specified in the condition attribute is false. Therefore, the response message to be emulated can be changed according to the evaluation result of the conditional expression.

The following example shows that conditional expressions are specified in the condition attributes of some emulate elements. The conditional expressions define that the response message to be emulated changes according to the value set for the elm1 element of the request message.

Figure 6‒1: Definition example when conditional expressions are specified in the definition file for emulated configuration information

To define a conditional expression (XPath), you must specify the path of an element of the request message to be evaluated. You can obtain the path by selecting the relevant variable from the variable list in the Business Process Definition window and then clicking the Display button.

In the figure, the three emulate elements have the same values of the service and operation attribute, and the valid attribute is set to true. Therefore, the emulate element that becomes valid changes as follows according to the evaluation result of the conditional expression specified in the condition attribute.

When the value of the request message is exec1

The first emulate element is valid.
When the value of the request message is exec2

Because the evaluation result of the conditional expression of the first emulate element is false, the conditional expression of the second emulate element is evaluated.

Because the evaluation result of the conditional expression of the second emulate element is true, the second emulate element becomes valid.
When the value of the request message is exec3

Because the evaluation result of the conditional expressions of the first and second emulate elements are false, the third emulate element becomes valid.

To Page Top

(5) Example of coding

The following is an example of coding of the definition file for emulated configuration information. This example indicates that the exec operation of the TP1 adapter is emulated.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE HCSCAutoEmulate SYSTEM "debug_auto_emulate_list_file_1_0.dtd">
<HCSCAutoEmulate>
<viewState>
<emulate condition="" operation="exec" service="TP1Adapter" type="RESPONSE_NORMAL" valid="true" xmlfile="/data/telegram/exec1"/>
</viewState>
</HCSCAutoEmulate>

The following values are set in this example:

Attribute name	Set value
`condition`	An empty string (`""`) is set to indicate that no conditions are to be defined.
`operation`	`exec` selected for the operation name of the invoke service activity is set.
`service`	`TP1Adapter` selected for the service name of invoke service activity is set.
`type`	`RESPONSE_NORMAL` is set.
`valid`	`true` is set to perform the emulation.
`xmlfile`	The response message file `/data/telegram/exec1` is set. The contents of this file will be set in the `out` body allocated variable for the response message of the invoke service activity.

To Page Top