XML - Create Session

Declaration

<AMXML ACTIVITY="create_node" XPATH="text" NEWNODE="text" 
NEWVALUE="text" DEFAULTNSPREFIX="text" DEFAULTNAMESPACE="text" 
INSERTAT="text (options)" SPECIFIEDNODE="text" 
SPECIFIEDNODENOTEXIST="text (options)" SESSION="text"><ATTRIBUTE 
NAME="text" VALUE="text" /><NAMESPACE 
PREFIX="text" URI="text" /></AMXML>

Description: Creates a new session based on the XML file or text specified. During an XML session, modifications are not performed on the original XML file bound by that session. Rather, as a safety measure, a copy of the file is saved to memory. Any modifications by subsequent XML steps are performed on the copy of the XML data saved to memory. Multiple XML documents can be saved to memory simultaneously allowing several sessions to exist within a single task. Use the Output XML action to output the final XML data to the original XML file or optionally, a new file. Use the End XML Session action to end an active session.

IMPORTANT: Use of XML activities require a basic interpretation of XML schema and general knowledge of XML related terms, such as Nodes, XPath, DTD and XSLT.

Practical Usage

Used to create an in-memory XML document to be used in subsequent XML actions.

Session Parameters

Property

Type

Required

Default

Markup

Description

Create XML session from

Text (options)

Yes

Existing File

  1. XMLDOCUMENTFROM="existingfile"

  2. XMLDOCUMENTFROM="newfile"

  3. XMLDOCUMENTFROM="text"

Specifies where the XML data should derive from to start the new session. The XML data will be saved into memory. Different parameters become active depending on which option is selected. The available options are:

  • Existing file (Default) - The XML data originates from an existing file. This option allows you to browse for an existing XML file to use.

  • New file - Creates a new XML file to use.

  • Text -  The XML data originates from specific text.

File

Text

Yes if XML session derives from a new or existing file

(Empty)

FILE="c:\foldername\file.XML"

The path and filename of the new or existing XML file. This parameter is active only if the Create XML session from parameter is set to Existing file or New file.

Overwrite if file exists

Yes/No

Yes if XML session derives from a new file

No

OVERWRITEFILE="YES"

If set to YES, specifies that if an XML file with the same name already exists at the specified location, it will be overwritten with the new file. If set to NO (default), the step fails if the file already exists. This parameter is active only if the Create XML session from parameter is set to New file.

Root node name

Text

Yes if XML session derives from a new file

(Empty)

ROOTNODENAME="Automate"

The root node name for new XML file. This parameter is active only if the Create XML session from parameter is set to New file.

Root node value (optional)

Text

No

(Empty)

NEWVALUE="Value"

The root node value for the new XML file. This parameter is active only if the Create XML session from parameter is set to New file.

Default namespace prefix (optional)

Text

No

(Empty)

DEFAULTNSPREFIX="edi"

The prefix of the default namespace for the new XML file. A namespace prefix is a text string assigned as an element name prefix to a namespace. When an element name is preceded by the prefix and a colon, then that element is in that assigned namespace. This parameter is active only if the Create XML session from parameter is set to New file.

Default namespace URI (optional)

Text

No

(Empty)

DEFAULTNAMESPACE=

"http://net.com/schema"

The default namespace URI for the new XML file. An XML namespace is a collection of element type and attribute names that are uniquely identified by the name of the unique XML namespace of which they are a part. This parameter is active only if the Create XML session from parameter is set to New file.

Text

Text

Yes if XML session derives from text

(Empty)

XMLTEXT="theText"

The text that the XML data should originate from. This parameter is active only if the Start XML session from parameter is set to Text.

Session

Text

No

(Empty)

SESSIONNAME="FirstXMLSession"

The session name to identify the in-memory XML document to use in subsequent XML steps. This allows several in memory XML documents to be active simultaneously.  Use the Output XML action to output the final XML data to the original XML file or optionally, a new file. Use the End XML Session action to end an active session.

Namespace Parameters

Property

Type

Required

Default

Markup

Description

Namespace Prefix

Text

No

(Empty)

PREFIX="PrefixName"

The prefix associated to the added namespace. Use this parameter to insert namespace prefix and URI values into the new node. To enter a new row of values select Click here to add new row... To delete an existing row, click the red "X". This parameter supports insertion of multiple namespace prefixes and URIs.

Namespace URI

Text

No

(Empty)

URI="URIName"

The URI associated to the added namespace. Use this parameter to insert namespace prefix and URI values into the new node. To enter a new row of values select Click here to add new row... To delete an existing row, click the red "X". This parameter supports insertion of multiple namespace prefixes and URIs.

Description tab - A custom description can be provided on the Description tab to convey additional information or share special notes about a task step.

Error Causes tab - Specify how this step should behave upon the occurrence of an error. (Refer to Task Builder > Error Causes Tab for details.)

On Error tab - Specify what AWE should do if this step encounters an error as defined on the Error Causes tab. (Refer to Task Builder > On Error Tab for details.)

Example

The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.

Sample 1: Start an XML session that originates from an existing XML file.

<AMXMLSTARTSESSION XMLDOCUMENTFROM="ExistingFile" 
FILE="C:\Tutorials\XML Data\book.xml" />

Sample 2: Start an XML session that originates from a newly created XML file.

<AMXMLSTARTSESSION XMLDOCUMENTFROM="NewFile" 
FILE="C:\Tutorials\XML Data\NewFile.xml" 
ROOTNODENAME="Automate" 
NEWVALUE="BPA Server" OVERWRITEFILE="YES" 
DEFAULTNAMESPACE="http://netauto.com/schema" DEFAULTNSPREFIX="edi">
<Attribute Name="Version" Value="7" />
<Attribute Name="Licence" Value="Standard" />
</AMXMLSTARTSESSION>

Start an XML session that originates from the specified text.

<AMXMLSTARTSESSION XMLDOCUMENTFROM="Text" 
XMLTEXT="&lt;?xml version=&quot;1.0&quot; 
encoding=&quot;UTF-8&quot;?&gt;&#xD;&#xA;&lt;Automate&gt;No 
Code No Limit!&lt;/Automate&gt;" />