Customization of Envelopes

Envelope definition elements

An Envelope definition is divided into following parts:

• Envelope definition common properties.
  Some common data.
• Namespace definitions.
  Defines the namespaces that should be detected when in and response messages.
• Inbound definitions.
  Defines how to identify the envelope, format of response and error.
• Outbound definitions.
  Defines format of the outbound envelope and identification of response.

Envelope definition common properties

Name	Description	Mandatory	Value	Default
description	A description of the envelope	no
soap	Defines if the envelope has SOAP format	yes	true/false	true

Namespace definitions

This part is not mandatory. NamespaceDefinition tag can contain unlimited Ns rows but can also be empty.
This definition's name will be used as substitute variables in inbound and outbound definitions.

Name	Description	Mandatory	Value
Ns/name	prefix of the namespace	yes
Ns/uri	The namespace uri	yes

Inbound definitions

This part defines the identification of the envelope and the format of the response and error. The entire section can be omitted if the envelope is not supposed to be used for inbound messages.

Identification and Inbound properties

Name	Description	Mandatory	Value	Default
Identification/priority	Defines the priority of the identification. If more then one envelope match, the one with the highest priority will be used.	yes	1 - 10 (1 = Highest)	10
Id/op	Identification operand	yes	exist/not_exist
Id/value	Identification value	yes
BodyTag	Defines the start element of the message body	yes	Namespace definitions can be used as substitute variables
MessageType	Defines the MessageType. MessageType is either fetched from the specified inbound element's value or set fixed.	yes
MessageType/def	Defines how to set the MessageType. MessageType is a part of the internal Application Message. MessageType is either fetched from the specified inbound element's value or set fixed.	yes	element/fixed	fixed
MessageFunction	Defines the MessageFunction. MessageFunction is a part of the internal Application Message. MessageFunction is fetched from the specified inbound element's value.	yes
Sender	Defines the Sender. Sender is a part of the internal Application Message. Sender is fetched from the specified inbound element's value.	no
Receiver	Defines the Receiver. Receiver is a part of the internal Application Message. Receiver is fetched from the specified inbound element's value.	no

Response data format

The response of the message can be formatted with a combination of fixed strings and substitute variables.
The format is defined in a CDATA section in the Response element.

<Response>  
  <![CDATA[  
     <?xml version="1.0" encoding="UTF-8"?>  
     <{SOAP-ENV}:Envelope xmlns:{SOAP-ENV}="http://schemas.xmlsoap.org/soap/envelope/">  
        <{SOAP-ENV}:Header>  
           <fndcn:Response {SOAP-ENV}:mustUnderstand="1" xmlns:fndcn="urn:ifsworld-com:schemas:fndcn">  
              <fndcn:Type>{fndcn:Type}</fndcn:Type>  
              <fndcn:Function>{fndcn:Function}</fndcn:Function>  
           </fndcn:Response>  
        </{SOAP-ENV}:Header>  
        <{SOAP-ENV}:Body>{DATA}</{SOAP-ENV}:Body>  
     </{SOAP-ENV}:Envelope>  
  ]]>  
</Response>

Substitute variable	Description
{Ns/name}	Namespace prefix (name attribute of the Ns tag) from the NamespaceDefinition section can be used as substitute variables
{any element in the request}	Maps elements from the request to the response
{DATA}	Defines where the message data response should be inserted.

The response definition is used for encapsulation of response from a sender, if ENVELOPE_RESPONSE is marked (see Connect Sender configuration). But asynchronous routing of inbound messages will also create a response with information about the queue the message has been put into. This response will also be encapsulated within this definition and, if CREATE_RESPONSE on the actual Reader is marked, the encapsulated response will became the Message Body of the new Application Message.

Error data format

The error of the message can be formatted with a combination of fixed strings and substitute variables.
The format is defined in a CDATA section in the Error element.

<Error>  
  <![CDATA[  
     <?xml version="1.0" encoding="UTF-8"?>  
     <{SOAP-ENV}:Envelope xmlns:{SOAP-ENV}="http://schemas.xmlsoap.org/soap/envelope/">  
        <{SOAP-ENV}:Body>  
           <{SOAP-ENV}:Fault>  
              <faultcode>{SOAP-ENV}:Server</faultcode>  
              <faultstring>{ERROR}</faultstring>  
              <detail>  
                 <ifserr:error xmlns:ifserr="urn:ifsworld-com:schemas:error">  
                    <ifserr:errordetail>{DETAIL_ERROR}</ifserr:errordetail>  
                 </ifserr:error>  
              </detail>  
           </{SOAP-ENV}:Fault>  
        </{SOAP-ENV}:Body>  
     </{SOAP-ENV}:Envelope>  
  ]]>  
</Error>

Substitute variable	Description
{Ns/name}	Namespace prefix (name attribute of the Ns tag) from the NamespaceDefinition section can be used as substitute variables
{ERROR}	The error reason. Normally the exception type
{DETAIL_ERROR}	The detailed error text. Normally the exception text.

The error definition is used for encapsulation of response from asynchronous routing of inbound messages on failure. If CREATE_RESPONSE on the actual Reader is marked, the encapsulated response will became the Message Body of the new Application Message.

Outbound definitions

This part define the format of the outbound message. The entire section can be omitted if the envelope is not supposed to be used for outbound messages.

Out data format

The output format of the message can be formatted with a combination of fixed strings and substitute variables.
The format is defined in a CDATA section in the Out element.

<OutboundDefinition>  
  <Out>  
    <![CDATA[  
       <?xml version="1.0" encoding="UTF-8"?>  
       <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">  
          <SOAP-ENV:Header>  
             <fndcn:Message SOAP-ENV:mustUnderstand="1" xmlns:fndcn="urn:ifsworld-com:schemas:fndcn">  
                <fndcn:Type>{head-MESSAGE_TYPE}</fndcn:Type>  
                <fndcn:Function>{head-MESSAGE_FUNCTION}</fndcn:Function>  
                <fndcn:Sender>{head-SENDER}</fndcn:Sender>  
                <fndcn:Receiver>{head-RECEIVER}</fndcn:Receiver>  
                <fndcn:SentAt>{addr-SENT}</fndcn:SentAt>  
                <fndcn:ExpiresAt>{addr-EXPIRES}</fndcn:ExpiresAt>  
             </fndcn:Message>  
          </SOAP-ENV:Header>  
          <SOAP-ENV:Body>{DATA}</SOAP-ENV:Body>  
       </SOAP-ENV:Envelope>  
    ]]>  
  </Out>  
+ <Response>  
</OutboundDefinition>

Substitute variable	Description
{Ns/name}	Namespace prefix (name attribute of the Ns tag) from the NamespaceDefinition section can be used as substitute variables
{head-SENDER}	Maps the ApplicationMessage Sender attribute to the output
{head-RECEIVER}	Maps the ApplicationMessage Receiver attribute to the output
{head-MESSAGE_TYPE}	Maps the ApplicationMessage MessageType attribute to the output
{head-MESSAGE_FUNCTION}	Maps the ApplicationMessage MessageFunction attribute to the output
{head-SUBJECT}	Maps the ApplicationMessage Subject attribute to the output
{head-OPTIONS}	Maps the ApplicationMessage Options attribute to the output
{head-EXTERNAL_MESSAGE_ID}	Maps the ApplicationMessage ExternalMessageId attribute to the output
{addr-SENDER}	Maps the AddressLabel Sender attribute to the output
{addr-SENDER_ORGANIZATION}	Maps the AddressLabel SenderOrganization attribute to the output
{addr-RECEIVER}	Maps the AddressLabel Receiver attribute to the output
{addr-RECEIVER_ORGANIZATION}	Maps the AddressLabel ReceiverOrganization attribute to the output
{addr-OPTIONS}	Maps the AddressLabel Options attribute to the output
{addr-SENT}	Maps the AddressLabel Sent attribute to the output
{addr-EXPIRES}	Maps the AddressLabel Expires attribute to the output
{DATA}	Defines where the message data should be inserted.

The out definition will be used for encapsulation of output data just before sending it to the destination, if Envelope is defined on the actual Routing Address.

Response Identification and Response properties

Response element defines tags used for identification of the response message received by a Connect Sender and extracting of the message body. The entire section can be omitted if the body is not supposed to be extracted.

Name	Description
OKIdentification	Identification string. If the response message contains this string, the framework will make an attempt to extract the message body.
ErrorIdentification	If the response is an error, the identification of the error.
ErrorText	The description of the error
ErrorDetailText	The details of the error.
EnvelopeTag	The tag of the envelope.
BodyTag	Specification of the XML tag denoting body of the response message

Note: Internally all type of text data (plain text or XML) is always encoded in UTF-8 character encoding. Re-coding from/to another character set is done, if necessary, in Readers, when reading messages and Senders, when sending messages. Thus it is not necessary to specify encoding in Response, Error or Out definitions above.

How to create an envelope

Follow these steps to create a new envelope:

1. Navigate to Solution Manager > Integration > IFS Connect > Setup IFS Connect and select Envelopes.

2. Create a new envelope instance by duplication and renaming an existing one or by choosing New from the RMB menu as described in section How to create a new configuration parameter instance.

3. Set the predefined route parameters to some useful elements that exists in the new Envelope's header as comma separated values. These are content based conditions that will later be used in the routing rules. For example if  SOAP-IFS envelope type is used these will be fndcn:Type, fndcn:Function etc.
   

4. If you have created the envelope by duplicating an existing one, you can save the definition to a file to use it as a template for the new instance. You can use any of the existing envelopes for this purpose. Open the file and edit the EnvelopeDefinitions elements.

1. When you are ready with the definitions, load the edited envelope from file.

1. The envelope is now ready for test in your IFS Connect runtime installation.
   Use the Message Routing administration tool for connecting the envelope to a destination address. All envelopes deployed and stored in the database will be available in the field for Envelope.

1. When the envelope is tested and ready to use you can export it. In the Save Configuration As dialog you can choose between exporting to an XML or an INS file. See section about exporting and importing configuration.