XML - Create 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>

See Also

XML - Create Node | XML - Dataset to XML | XML - Delete Node | XML - Edit Node | XML - End Session | XML - Evaluate Xpath | XML - Export | XML - Import | XML - Node to Dataset | XML - Read Node | XML - Save | XML - Sign | XML - Transform | XML - Validate | XML - Verify

Start XML 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>

See Also

Create XML Node | Dataset to XML | Delete XML Node | Edit XML Node | End XML Session | Evaluate Xpath Expression | Extract XML Fragment | Merge XML Files | Output XML | Read XML Node | Sign XML Document | Start XML Session | Transform XML | Validate XML File | Verify XML Document | XML Node to Dataset

Description

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.

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

Practical Usage

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

NOTE: 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.

Parameters

General Properties

Property

Type

Req'd

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 Properties

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

Req'd

Default

Markup

Description

Attribute Name

Text

No

(Empty)

Name="AttributeName"

The name of the attribute to insert. 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.

Attribute value

Text

No

(Empty)

Value="AttributeValue"

The value of the attribute. 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 Properties

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.

Description Properties

The Description tab allows you to customize the text description of any step as it appears in the Task Builder's Steps Pane.

More on setting custom step description

Error Causes Properties

The Error Causes tab properties lets you instruct a task step to react only to specific errors or ignore certain errors that should cause it to fail.

More on Error Causes properties

On Error Properties

The On Error tab properties lets you determine what the task should do if a particular step encounters an error as defined in the Error Causes properties.

More about On Error properties

Additional Notes

Expressions, Variables & Functions

A percent sign is used as a special character in AutoMate to indicate the beginning and end of an expression. This allows variables, functions and other expressions to be entered in any text parameter of a task's properties. For example: %1+1% inside a task will resolve to 2 at runtime. A more elaborate example is %FileDateTime(myFile)% which results to the date/time of myFile. To help construct expressions, you can open Expression Builder by clicking the Insert Expression (%) button or by pressing F2.

More on expressions

More on variables

More on functions

More on extended functions
More on the expression builder

Example

NOTE: The code below can be copied and pasted directly into the Steps pane 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 9" OVERWRITEFILE="YES" DEFAULTNAMESPACE="http://netauto.com/schema" DEFAULTNSPREFIX="edi"><Attribute Name="Version" Value="7" /><Attribute Name="Licence" Value="Standard" /></AMXMLSTARTSESSION>

 

 

Sample 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;" />

 

↑ Top of Page