Basics - An Introduction to Ytria Automation

XML Basics

Ytria applications allow you to automate various Actions using XML scripts (eXtensible Markup Language).
XML files are plain text files that can be created with any text editor (e.g. Notepad).
Either UTF-8 or UTF-16 encoding will be accepted.

Script Structure

A compatible automation script is made up of a series of Actions.
These Actions represent functions within Ytria tools (Ex: Load Server, Switch ID, Export, Discover Replicas, etc.).

NOTE	Only the Actions performed by Ytria tools can be automated, and these Actions are directly related to those normally done through the UI. An automation script does not give a user access to the backend of Ytria tools.

XML Script Example

The following script example would load a database called mailbase.nsf located on the server named ACME01/ACME in viewEZ provided that the environment contains a valid matching filepath.

Additionally, one design, NoteID h398e, would be selected in the tree.

XML

<ytriaAutomation>
<Load Database="PROD\mailbase.nsf" Server="ACME01/ACME"/>
<UnSelect>
	<SetParam Name="All"/>
</UnSelect>
<Expand Category="Designs" Target="Tree"/>
<Select>
	<SetParam NoteID="h398e"/>
</Select>
</ytriaAutomation>

NOTE

A quick note about Ytria's XML compliance:

All automation scripts follow normal XML guidelines. If you are not fully familiar with XML, we suggest that you look at this page for further reference.
The practice of "escaping" is one that may be needed when using certain operations (e.g. special characters within formulas or value names).
As a reminder, here is a list of characters that must be "escaped," along with the proper characters to do so:

" should be written as "

' should be written as '

< should be written as <

> should be written as >

& should be written as &

Parts of the Script

The example script above will be used as a reference for the following breakdown of the different parts of a basic script.

Script Header and Footer
Actions
Action Attributes
Action Parameters

Script Header and Footer

Script Header

The first line in the script header is called the XML declaration. This line is a standard requirement for all XML scripts, as it defines the XML version (1.0) and the type of encoding.

<?xml version="1.0" encoding="UTF-8"?>

The first true line of the automation script is identified as such by using the ytriaAutomation tag.

The following attributes are used in the example above:

Application - This is the application name that the automation script is intended to run on. It is case insensitive.

NOTE	There are some automation scripts that are general and can be used on more than one product.

ApplicationVersion - This is the product version that the automation is intended for: version 16.5.

TIP	Although the general header is mandatory, attributes in the ytriaAutomation header tag are not. Please be advised that some Actions will not be compatible across products and versions. It is considered a best practice to include these attributes for reference purposes.

Example of a minimum mandatory header in a Ytria Automation script:

<?xml version="1.0" encoding="UTF-8"?>
<ytriaAutomation>

TIP

Some Optional Additional Header Parameters

Hiding automation console:

Adding the parameter Console="False" to the ytriaAutomation header tag will hide the automation console while the automation script is running.
This dialog will therefore only be displayed at initialization time (during XML script loading and analysis).
Example

XML

<ytriaAutomation Console="False" Application="viewEZ" ApplicationVersion="16.5">

Adding a user attribute:

Adding the user attribute to the YtriaAutomation header tag restricts the script to use by a specific organization or user.
For example, adding user="John Doe/ACME" to the line will restrict the use of this script to this user only.

XML

<ytriaAutomation Application="viewEZ" ApplicationVersion="16.5" user="John Doe/ACME">

Wildcards are also possible. Adding user="*/ACME" to the line will allow all users from ACME domain to execute the script.

XML

 <ytriaAutomation Application="viewEZ" ApplicationVersion="16.5" user="*/ACME">

Script Footer

All Ytria automation scripts must end with the script footer
</ytriaAutomation>

Actions

Actions are placed within tags and run in chronological order upon completion of the preceding Action in the script.

Actions can be nested: In the structure of a script, the outer Action is a 'Parent' Action and the inner Actions are 'Child' Actions.

For instance, using the same basic example script:

In the structure of a script, the outer Action is a 'Parent' Action and the inner Actions are 'Child' Actions

The results of all Actions will be shown, as they are completed, in the automation console.
If a 'Parent' Action is cancelled, all 'Child' Actions within it will also be cancelled.

The example above shows the automation console in replicationEZ.

You can find the complete list of available Actions on this page.

Action Attributes

The Attributes are added to Actions as arguments.
Returning to the example script, the Actions are emphasized with a

, and their Attributes are signified by

.

Returning to the example script, the Actions are emphasized in red, and their Attributes are signified by green

For more information about these specific Actions and their Attributes, please look here.

Action Parameters

If performing a specific Action manually through the UI would require the user to select parameters in a dialog box or make a specific manual selection, these selections can be made in an automation script by using SetParam in 'Child' actions.