Start XML Session

Creates a new XML session based on an XML file or specified text. This session can be used in subsequent XML steps to modify an in-memory (saved to memory) copy of the XML data. Multiple XML documents can be saved to memory simultaneously allowing several sessions to exist within a single task. Since the XML data is saved to memory, no modifications are made to the original document. 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.

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

AWE's XML actions require a basic understanding of XML and related terms, such as XPath, DTD and XSLT.

When creating an XML task, it is required that an XML session name is initially generated using the Start XML Session action. This session can be identified by subsequent XML steps which include the same session name. This allows several XML documents to be active simultaneously within the same task. When an XML session is created, the XML file bound by that session becomes locked. An End XML Session action can be used to end the current session. This frees the session name to be used in a different session and unlocks the XML file bound to that session.

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 upon the creation of a session. Any modifications performed by subsequent XML steps are performed on the copy of the XML data saved to memory. The Output XML File action can be used to output the in-memory representation of the XML session to a file or variable before ending the XML session. Using this action does not change the XML or end the session, thus allowing subsequent XML steps to continue using the session.

Declaration

<AMXMLSTARTSESSION XMLDOCUMENTFROM="NewFile" FILE="text" ROOTNODENAME="text" NEWVALUE="text" OVERWRITEFILE="YES/NO" DEFAULTNAMESPACE="text" DEFAULTNSPREFIX="text"><Attribute Name="text" Value="text" /><Attribute Name="text" Value="text" /></AMXMLSTARTSESSION>

Example 1 - Start an XML session that originates from an existing XML file.

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

Example 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="AWE" OVERWRITEFILE="YES" DEFAULTNAMESPACE="http://netauto.com/schema" DEFAULTNSPREFIX="edi"><Attribute Name="Version" Value="7" /><Attribute Name="License" Value="Standard" /></AMXMLSTARTSESSION>

Example 3 - 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;" />

See Also: Create XML Node, Delete XML Node, End XML Session, Evaluate Xpath Expression, Extract XML Fragment, Merge XML Files, Output XML, Read XML Node, Sign XML Document, Transform XML, Validate XML File, Verify XML Document, XML Node to Dataset

General Tab

Property

Type

Required

Default

Markup

Description

Start XML session from

Text (options)

Yes

Existing File

XMLDOCUMENTFROM="NewFile"

Specifies where the XML data should derive from in order 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.

Save XML document to

Text

Yes if XML session derives from a new or existing file

(Empty)

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

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

Overwrite if file exists

Yes/No

No

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 Start 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 Start 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 Start XML session from parameter is set to New File.

Default namespace (optional)

Text

No

(Empty)

DEFAULTNAMESPACE=

"http://net.com/schema"

The default namespace 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 Start XML session from parameter is set to New File.

Prefix for default namespace (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 Start 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 Name

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.

Attributes Tab

Use these properties to insert attributes into the new node.

NOTE: These properties become active only if the Start XML session from parameter is set to New File.

Property

Type

Required

Default

Markup

Description

Attribute Name

Text

No

(Empty)

Name="AttributeName"

The name of the attribute to insert.

Attribute value

Text

No

(Empty)

Value="AttributeValue"

The value of the attribute.

Available buttons

        

Use the following buttons in visual mode if needed:

  • Move Up - Move the attribute name/value up one line.

  • Move Down - Move the attribute name/value down one line.

  • Add - Add a new attribute name/value to the list.

  • Remove - Remove an existing attribute name/value.

Namespace Tab

Use these properties to insert a namespace prefix and URI into the new node.

Property

Type

Required

Default

Markup

Description

Prefix

Text

No

(Empty)

PREFIX="PrefixName"

The prefix associated to the namespace.

Use the following buttons in visual mode if needed:

  • Move Up - Move the namespace up one line.

  • Move Down - Move the namespace down one line.

  • Add - Add a namespace to the list.

  • Remove - Remove an existing namespace from the list.

Namespace URI

Text

No

(Empty)

URI="URIName"

The URI associated to the namespace.

Use the following buttons in visual mode if needed:

  • Move Up - Move the namespace up one line.

  • Move Down - Move the namespace down one line.

  • Add - Add a namespace to the list.

  • Remove - Remove an existing namespace from the list.