Configuring the local environment tree Variables folder by using the Cast function

You can use the Cast function to define variables in a message map that are defined in the local environment tree Variables folder.

Before you begin

Customize the message map to include the local environment tree. For more information, see Customizing a message map to include the local environment tree.

About this task

The local environment tree is a part of the logical message tree in which you can store information while the message flow processes the message. You use the local environment tree to store variables that can be referred to and updated by message processing nodes that occur later in the message flow. You can also use the local environment tree to define destinations (that are internal or external to the message flow) to which a message is sent.

When you add the local environment tree to a message map, you must provide transforms for all of its elements so that the input values of each element are not lost. You can copy the input field unchanged or modified by a transform. Many IBM® App Connect Enterprise nodes depend on information in the local environment tree being copied along the message flow.

The variables folder in the local environment tree is defined as xsd:any. When you add the local environment tree, you can see the structure of the destination folders with all its elements, and a Variables folder with a single element defined with a generic type.

This figure shows graphically how the variables folder is defined with type any.

You manually define the elements that are included in the Variables folder. There is no predefined structure for the Variables folder. Each message flow has its own local environment tree Variables folder. For this reason, if you want to access any of these elements within your message map, you must define each element that you want to use in the message map by using the Cast function.

Note:

You can use the Cast function to explicitly define other elements in the message map message assembly.
In IBM App Connect Enterprise, the local environment tree predefines other folders to reflect the data created and used by IBM App Connect Enterprise nodes.

In this scenario, you create an element called Country under the local environment Variables folder to be used by other nodes later in the message flow for routing.

Procedure

To add the Country element to the local environment tree Variables folder complete the following steps:

Define a Move transform between the input local environment tree and the output local environment tree. Create a connection between the input local environment tree and the output local environment tree. You can do this in any of the following ways:
- In the message map, right-click the input local environment tree, and select Add Connection. Move the mouse to the output local environment tree, and click local environment to define the Move transform.
- In the message map, right-click the input local environment tree, and select Quick Link. A new window appears where you can select the output element local environment. Use this option when you have a long list of output elements. You can filter the list in Quick link too.
If you need to modify only some fields in the local environment tree, you can use a Move transform to copy the local environment tree unchanged, and then use the Override function to modify the elements you must update.

The following figure shows graphically how the Move transform is defined between the input local environment tree and the output local environment tree.

All the input values are copied onto the output values.
Create a schema file in your application, service, or library to define the elements of the local environment tree Variables folder and their type:
- In the Application Development view, select New... > Message Model... > Other XML. Click Next.
- Select Create an empty XML schema file, I will model my data using the XML schema editor, and then click Next.
- Create the XSD file LEVariablesFolderStructure.xsd within the project AddressBookProvider. Then, click Finish.
- The file LEVariablesFolderStructure.xsd opens in a new tab where you use the XML Schema editor to define your variables and their types.
  In our example, we define the following schema:
```
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
       <xsd:element name="Country"  type="xsd:string"/>
       <xsd:element name="CountryCode"  type="xsd:integer"/>
</xsd:schema>
```
  Note: In our example, the nodes reading these elements require them to not be namespaced. For this reason, the schema is also defined without a namespace declaration.
Use the Cast function to define the local environment variables in the message map so they are visible under the Variables folder in the map. Complete the following steps to cast the any element to a variable and its type in the output local environment tree:
- Right-click the any element, and then select Cast.
- In the Type Selection window, select Country and then click OK.

Results

You now have defined one local environment variable that can be used by other nodes in your message flow for routing or filtering.

You can see the element Country under the local environment Variables folder in the message map.

This figure shows graphically the element Country under the any element of the local environment Variables folder.

What to do next

Configure the message map to include the SOAP message. For more information, see Configuring the message map to include the SOAP message.