Local environment tree
The local environment tree is a part of the logical tree (message assembly) in which you can store information while the message flow processes the message.
The root of the local environment tree is called LocalEnvironment. This tree is always present in the input message, and is created when a message is received by the input node. Some input nodes create local environment fields, other nodes leave the tree empty.
- Anything in the format of LocalEnvironment.Destination.output_or_request_node_name, for example; LocalEnvironment.Destination.Email, decides what happens when information is going into an output or request node.
- Anything in the format of LocalEnvironment.WrittenDestination.output_or_request_node_name, for example; LocalEnvironment.WrittenDestination.FTE, gives you information about the processed output of an output or a request node.
- Anything in the format of LocalEnvironment.input_node_name.input, for example; LocalEnvironment.Adapter.Input, contains information that has been stored by an input node.
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 and external to the message flow) to which a message is sent. IBM® App Connect Enterprise also stores information in the local environment in some circumstances, and references it to access values that you might have set for destinations.
The following figure shows an example of the local environment tree structure. The children of Destination are protocol-dependent.
In the tree structure shown, LocalEnvironment has several children:
- This subtree is optional. If you create local environment variables,
store them in a subtree called Variables. It provides a work area
that you can use to pass information between nodes. This subtree is
never inspected or modified by any supplied node.
Variables in the local environment can be changed by any subsequent message processing node, and the variables persist until the node that created them goes out of scope.
The variables in this subtree are persistent only within a single instance of a message flow. If you have multiple instances of a message passing through the message flow, and need to pass information between them, you must use an external database.
- This subtree consists of a number of children that indicate the transport types to which the message is directed (the Transport identifiers), or the target Label nodes that are used by a RouteToLabel node.
- Transport information
Transport information is used by some input and output nodes, including FTE, HTTP, File, Email, SOAP, MQ, JMS, TCPIP, CORBA, CICS®, and MQTT.
LocalEnvironment.Destination.FTE
If the message flow includes an FTEOutput node, you can override its properties with elements in this subtree. See Using local environment variables with file nodes.
LocalEnvironment.Destination.HTTP
If the message flow starts with an HTTPInput node, a single name element HTTP is added to Destination. The element HTTP.RequestIdentifier is created and initialized so that it can be used by an HTTPReply node. You can also create other fields in the HTTP structure for use by the HTTPRequest node; for example, the URL of the service to which the request is sent. For more information, see Local environment overrides in the topic HTTPRequest node, and examples in Populating Destination in the local environment tree.
LocalEnvironment.Destination.File
If the message flow includes a FileOutput node, you can override its directory and name properties with elements in this subtree. See Using local environment variables with file nodes.
LocalEnvironment.Destination.Email
If the message flow includes an EmailOutput node, then information defined in this subtree will specify or override the SMTP server connection information and attachments associated with each email sent by the node. Multiple attachments can be specified for inclusion in the email sent, including the specification of the attachment name, content, and type. See EmailOutput node.
LocalEnvironment.Destination.SOAP
You can place outbound WS-Addressing header information in the local environment to override the defaults that are generated by the SOAPReply, SOAPRequest, or SOAPAsyncRequest nodes. See WS-Addressing information in the local environment.
If the message flow includes SOAPRequest or SOAPAsyncRequest nodes, you can override their HTTP Transport and JMS transport properties in this subtree. See SOAPRequest node, SOAPAsyncRequest node, or Local environment overrides for the SOAPRequest node.
If the message flow includes a SOAPAsyncRequest node, you can use this subtree to pass state and correlation information to a SOAPAsyncResponse node in another message flow. See WS-Addressing with the SOAPAsyncRequest and SOAPAsyncResponse nodes.
If the message flow includes SOAPReply, SOAPRequest, or SOAPAsyncRequest nodes, you can override their use of outbound MTOM messages in this subtree. See SOAP MTOM and the SOAPReply, SOAPRequest, and SOAPAsyncRequest nodes.
LocalEnvironment.Destination.MQ
If the message flow includes an MQOutput node, each element is a name element, MQ (A deprecated alternative exists, called MQDestinationList. Use MQ for all new message flows). If more than one element exists, each is processed sequentially by the node. See the example in Populating Destination in the local environment tree.
You can configure MQOutput nodes to examine the list of destinations and send the message to those destinations, by setting the property Destination Mode to Destination List. If you do so, you must create this subtree and its contents to define those destinations, giving it the name Destination. If you do not do so, the MQOutput node cannot deliver the messages.
If you prefer, you can configure the MQOutput node to send messages to a single fixed destination, by setting the property Destination Mode to Queue Name or Reply To Queue. If you select either of these fixed options, the destination list has no effect onintegration server operations and you do not have to create this subtree.
You can construct the MQ element to contain a single optional Defaults element. The Defaults element, if created, must be the first child and must contain a set of name-value elements that give default values for the message destination and its PUT options for that parent.
You can also create a number of elements called DestinationData within MQ. Each of these can be set up with a set of name-value elements that defines a message destination and its PUT options.
The set of elements that define a destination is described in Data types for elements in the MQ DestinationData subtree.
The content of each instance of DestinationData is the same as the content of Defaults for each protocol, and can be used to override the default values in Defaults. You can set up Defaults to contain values that are common to all destinations, and set only the unique values in each DestinationData subtree. If you do not set a value either in DestinationData or Defaults, the value that you have set for the corresponding node property is used. Similarly, if you specify a field name or value with the wrong spelling or case, it is ignored, and the value that you have set for the corresponding node property is used.
The information that you insert into DestinationData depends on the characteristic of the corresponding node property: This information is described in Accessing the local environment tree.
LocalEnvironment.Destination.JMSDestinationList
A JMSOutput node can be configured to send to multiple JMS Queues or to publish to multiple JMS Topics using a destination list created in the local environment by a transformation node.
The JMSOutput node searches the local environment for data elements called DestinationData under the folder Destination.JMSDestinationList. The node sends the JMS message to each DestinationData entry found in that folder. See the example in Populating Destination in the local environment tree.
LocalEnvironment.Destination.TCPIP
If the message flow includes a TCPIPClientOutput node or a TCPIPServerOutput node, you can override its TCPIP connection with elements in this subtree. See TCPIPClientOutput node and TCPIPServerOutput node.
LocalEnvironment.Destination.CORBA
If the message flow includes a CORBARequest node, you can override its Operation name property by specifying a value in the following location:
For more information about the operation name, see CORBARequest node.$LocalEnvironment/Destination/CORBA/Request/OperationNameLocalEnvironment.Destination.CICS
If the message flow includes a CICSRequest node, you can override the following properties with elements in this subtree:- Program name
- Commarea length
- Mirror transaction ID
- Set EIBTRNID only
- Message domain
- Message set
- Message type
- Message format
- Message coded character set ID
- Message encoding
You can also set LocalEnvironment values for CICS channels and containers. For more information, see COMMAREA or channel data structures.
LocalEnvironment.Destination.MQTT.Output
If the message flow includes an MQTTPublish node, you can override the following properties with elements in this subtree:- Retained
- Topic name
- Quality of service
LocalEnvironment.Destination.Loopback
If the message flow includes a LoopBackRequest node, you can override the properties of those nodes with elements in this subtree. For more information, see Using local environment variables with LoopBackRequest nodes.
LocalEnvironment.Destination.Salesforce
If the message flow includes a SalesforceRequest (no discovery) node, you can override the properties of those nodes with elements in this subtree. For more information, see Using local environment variables with Salesforce nodes (no discovery).
LocalEnvironment.Destination.REST
If the message flow includes a RESTRequest or RESTAsyncRequest node, you can override the properties of those nodes with elements in this subtree. For more information, see Using local environment variables with REST nodes.
LocalEnvironment.Destination.Kafka
If the message flow includes a KafkaProducer node, you can override the properties of the node with elements in this subtree. For more information, see Using local environment variables with Kafka nodes.
- Routing information
The child of Destination is RouterList. It has a single child element called DestinationData, which has a single entry called labelName. If you are using a dynamic routing scenario involving the RouteToLabel and Label nodes, you must set up the Destination subtree with a RouterList that contains the reference labels.
- Transport information
- This subtree contains the addresses to which the message has been written. Its name is fixed and it is created by the message flow when a message is propagated through the Out terminal of a request, output, or reply node. The subtree includes transport-specific information (for example, if the output message has been put to an IBM MQ queue, it includes the queue manager and queue names).
You can use one of the following methods to obtain information about the details of a message after it has been sent by the nodes:- Connect a transformation node to the Out terminal.
The topic for each node that supports WrittenDestination information contains details about the data that it contains.
- This subtree contains information that is stored by the FileInput node.
This information describes the file, and also contains data about the current record.
More details about the information that is stored in this subtree are in Using local environment variables with file nodes.
- This subtree contains information that is stored by SOAPInput, SOAPAsyncResponse, or SOAPRequest nodes.
More details about the information that is stored in this subtree are in WS-Addressing information in the local environment.
- This subtree contains information about the wildcard characters
that are stored by the FileInput node.
On the FileInput node you can specify a file name pattern that contains wildcard characters.
More details about the information that is stored in this subtree are in Using local environment variables with file nodes.
- This subtree contains information that is stored by the WebSphere® Adapters nodes.For a WebSphere Adapters input node:
- MethodName is the name of the business method that corresponds
to the Enterprise Information System (EIS) event that triggered this
message delivery.
The bindings for EIS events or business methods are created by the Adapter Connection wizard.
- Type describes the type of adapter that is being used:
- SAP
- Siebel
- PeopleSoft
- JD Edwards
For a WebSphere Adapters request node:
MethodName is the name of the business method that the request node must use.
- MethodName is the name of the business method that corresponds
to the Enterprise Information System (EIS) event that triggered this
message delivery.
-
If the message flow includes a TCPIPClientReceive node or a TCPIPServerReceive node, you can override its TCPIP connection with elements in this subtree. See TCPIPClientReceive node and TCPIPServerReceive node.
This subtree contains information that is stored by the TCPIPClientInput, TCPIPClientReceive, TCPIPServerInput, and TCPIPServerReceive nodes.
This information describes the connection that the node is using.
More details about the information that is stored in this subtree are in TCPIPClientInput node, TCPIPClientReceive node, TCPIPServerInput node, and TCPIPServerReceive node.
- These subtrees contain information that is stored by the FTEInput node. The LocalEnvironment.FTE
subtree contains information about the current record. The LocalEnvironment.FTE.Transfer
subtree contains information received from IBM MQ File Transfer Edition regarding the file.
More details about the information that is stored in these subtrees are in Using local environment variables with file nodes.
- These subtrees contain information that is stored by the CDInput node. The LocalEnvironment.CD
subtree contains information about the current record. The LocalEnvironment.CD.Transfer
subtree contains information received from IBM Sterling Connect:Direct® regarding the file.
More details about the information that is stored in these subtrees are in Using local environment variables with file nodes.
- This subtree contains information that is propagated from the DatabaseInput node.
The LocalEnvironment.Database.Input.Event.Usr subtree contains user-defined data associated with an event. It is initialized in the ReadEvents procedure of the ESQL module associated with the DatabaseInput node.
LocalEnvironment.Database.Input.Event.Key holds a unique key for an event. It is set in the ReadEvents procedure of the ESQL module associated with the DatabaseInput node.
LocalEnvironment.Database.Input.Event.FailureCount contains a value for the number of times an attempt to process an event has failed. This count includes all unhandled exceptions occurring either in the ESQL module or the message flow.
- This subtree contains information that is stored by the JMSReceive node.
If the message flow includes a JMSReceive node, you can override its JMS connection properties with elements in this subtree.
More details about this information that is stored in this subtree are in Local environment overrides for the JMSReceive node.
- This subtree contains information that is stored by Mapping node.
If your message flow includes a Mapping node, you can override the mapping routine that is used to transform a message instance by specifying a new mapping routine in the MappingRoutine field. You must specify the new mapping routine in the LocalEnvironment.Mapping subtree that is upstream of the Mapping node that you need to modify.
-
This subtree contains information that is stored by a REST API when it receives a request and routes that request to a subflow that implements an operation in the REST API. For more information, see Implementing REST API operation processing in the subflow by using message flow nodes.
This subtree also contains information that is stored by a RESTAsyncResponse node when it receives a response for a request initiated by a RESTAsyncRequest node. For more information, see Using local environment variables with REST nodes.
This subtree contains information that is stored by the KafkaConsumer node, including information about the topic where the message was published. For more details about the information contained in this subtree, see Using local environment variables with Kafka nodes.
When the message flow processing is complete, the local environment tree is discarded.