# The Automation Tool

## Introduction

The **Aligned Elements Automation Tool** is an application that can be used to perform batch actions on an Aligned Elements project. 

The Tool is installed as a **Windows Application** and a **Command Line tool** and is designed for administrators being faced with repetitive tasks when; e.g., setting up new projects, manager users, or integrate Aligned Elements action in continuous integration.

{% hint style="info" %}
Note! The Automation Tool uses the Aligned Elements Web Rest API to perform tasks and having access to an Aligned Elements Web Server Application is, therefore, a prerequisite to use the tool.
{% endhint %}

{% hint style="info" %}
Note! It is **strongly** advised to test the Automation actions on a test project before using them in production to make sure the result from the performed actions corresponds to your intentions and expectations.
{% endhint %}

## How to use the Automation Tool

The steps to use the Automation Tool are fairly straight forward:

1. Define the actions to be performed in a configuration file 
2. Start the Automation Tool
3. Enter a Server url and user credentials and click **Connect**
4. **Select the projects** on which the actions shall be applied
5. Click **Start** to run the actions on the selected projects

![](https://2062592451-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LNF6QkY13KiUT4AxV9A%2F-L_mm2Tk32lZSzZkaODV%2F-L_mo-WSs6S321aGVcsY%2Fimage.png?alt=media\&token=e51043fe-7c47-4ffc-beca-9f5bf4fa664a)

## Supported Action Types

The Automation Tool supports the following actions:

* Importing Chapter Structures
* Importing Users
* Importing User Groups
* Importing Queries
* Importing Charts
* Importing Trace Tables
* Importing Dashboards
* Importing Project Settings
* Importing Document Objects
* Import and Synchronize Document Objects
* Exporting Document Objects
* Synchronize Documents in File Objects
* Update Users (such as Disable)
* Update individual Document Objects
* Upgrade Project

## How to define a configuration file

The actions performed by Automation Tool is defined in a configuration xml file. An xsd schema is available on request.

A configuration file is an xml file containing all the actions to be performed by the automation tool. The actions are run in sequence. The main body of the configuration file is defined as:

```
<?xml version="1.0" encoding="utf-8" ?>
<RestApiActions xmlns="urn:RestApiActions.xsd">
  <Actions>
... the list of actions
  </Actions>
</RestApiActions>
```

All actions have a required **Name** attribute. The name is displayed in the GUI and the log files and denotes the action to be performed.&#x20;

### The usage of files and file paths

Many of the actions make use of import files from Aligned Elements, such as User (.usr) files, User Group files (.usg), Chapter structure files, and regular Document Object import files (.xml). A prerequisite for usage is that these files are made available (i.e. have been exported) to the Automation Tool before the actions can be performed.

{% hint style="info" %}
Note! If required, open and modify the files to import to suit your needs. Always test the import actions on a test project before applying them in production in order to verify that the actions behave as you intended.
{% endhint %}

If the file path attribute value is defined as a file name, the file is expected to be found in the same directory as the configuration file. If the file is located in a different place, the file attribute value shall be defined with the full path.

### The usage of Targets

The Target attribute is available in several actions and denotes a selection of a set of Document Objects. Targets can be defined in one of three ways:

1\) Referring to a Query Name (case-sensitive) of an existing Query in the project

2\) Referring to a single Document Object ID (without project name or revision)

3\) Referring to a search statement such as "TypeName=File,Title=PRD"

## Configuration File Actions

### Import Chapter Structure

Example:

`<ImportChapterStructure Name="Import chapters to Spec" ImportFilePath="Traces.chs" TargetBookName="Specification"/>`

The **Traces.chs** file is an existing chapter structure file. Such files can be created/exported as described here.

The required **TargetBookName** attribute defines in the Document Object Type root in which the chapter structure shall be imported.

{% hint style="info" %}
The Document Object type defined in TargetBookName must exist in the target project.
{% endhint %}

### Import Users

Example:

`<ImportUsers Name="Add the user Frank" OverwriteExisting="true" ImportFilePath="Users@MedixProject.urs"/>`

The .urs file is an exported User file as described [here](https://docs.aligned.ch/aligned-elements-web-client-user-manual/2.5.148.19484/settings/manage-users#export-users).

The **OverwriteExisting** attribute is applied if the imported user already exists in the project. If **OverwriteExisting** is true, then the existing user data will be overwritten by the data in the import file.

The behavior of the import action is described [here](https://docs.aligned.ch/aligned-elements-web-client-user-manual/2.5.148.19484/settings/manage-users#import-users).

### Import User Groups

Example:

`<ImportUserGroup Name="Add Group Quality Assurer" OverwriteExisting="true" ImportFilePath="UserGroup@MedixProject@QualityAssurer.ugr"/>`

The .ugr file is an exported User Group file as described [here](https://docs.aligned.ch/aligned-elements-web-client-user-manual/2.5.148.19484/settings/manage-user-groups#export-user-group).

The **OverwriteExisting** attribute is applied if the imported user group already exists in the project. If **OverwriteExisting** is true, then the existing user rights in the user group will be overwritten by the data in the import file.

The behavior of importing a user group is described [here](https://docs.aligned.ch/aligned-elements-web-client-user-manual/2.5.148.19484/settings/manage-user-groups#import-user-group).

### Import Queries

Example:&#x20;

`<ImportQuery Name="Import query" ImportFilePath="AllRequirementsTracedToSpecs.xml"/>`

The **ImportFilePath** refers to an exported query definition that results in an xml file as described [here](https://docs.aligned.ch/aligned-elements-web-client-user-manual/2.5.148.19484/queries/run-a-query#export-a-query).

### Import Charts

Example:

`<ImportChart Name="Import Chart" ImportFilePath="RequirementChart.xml" />`

The **ImportFilePath** refers to an exported chart definition that results in an xml file as described [here](https://docs.aligned.ch/aligned-elements-web-client-user-manual/2.5.148.19484/charts/display-a-chart#export-a-chart).

### Import Trace Tables

Example:

`<ImportTraceTable Name="Import trace table" ImportFilePath="ReqToSpecsTraceTable.xml"/>`

The **ImportFilePath** refers to an exported Trace Table definition which results in an xml file as described [here](https://docs.aligned.ch/aligned-elements-web-client-user-manual/2.5.148.19484/trace-tables/design-a-trace-table#export-a-trace-table-definition).

### Import Dashboards

Example:

`<ImportDashboard Name="Add Management Dashboard" ReplaceProjectName="Convulix HPA" ImportFilePath="ManagementDashboard.xml"/>`

The **ImportFilePath** refers to an exported Dashboard definition that results in an xml file. The export is described [here](https://docs.aligned.ch/aligned-elements-web-client-user-manual/2.5.148.19484/dashboards/create-a-dashboard#export-and-import-a-dashboard).

The **ReplaceProjectName** attribute is used to replace and hyperlink references in RichText Widgets in the imported Dashboard.

### Import Project Settings

Example:

`<ImportProjectSettings Name="Import our standard Project Settings" ImportFilePath="CompanyWideProjectSettings.xml"/>`

The **ImportFilePath** refers to an exported Project Settings definition which results in an xml file. The export is described [here](https://docs.aligned.ch/aligned-elements-web-client-user-manual/2.5.148.19484/settings/project-settings#export-project-settings).

### Import Document Objects

Example:

`<ImportObjects Name="Import some Requirements" ImportChangeComment="Import From rest api client" KeepIncommingTraces="false" KeepInternalTraces="true" KeepOutgoingTraces="false" TargetBookName="Requirement" RebuildChapterStructure="true" ImportFilePath="ExportedRequirements.zip" WriteExternalID="false" SynchronizeUsingExternalID="false"/>`

The Import settings correspond to the options in the Import Document Object import dialog as described [here](https://docs.aligned.ch/aligned-elements-web-client-user-manual/2.5.148.19484/document-object-actions/import-document-objects#options-in-the-import-document-objects-dialog).

The **ImportFilePath** shall refer to a zip file or xml file.

#### Synchronized import of items from external systems

The **ImportObjects** action has the additional attribute **InitialTransformationFilePath** which defines an xsl transformation path that is applied to the file defined in the **ImportFilePath** before the import takes place.

### Synchronize File

Example:

`<SynchronizeFile Name="Sync PRD Document" Target="FI 15" ExpectMultiplePages="false"/>`

This action automatically synchronizes Word Documents with File Objects.

The usage of the **Target** attribute is explained [here](#the-usage-of-targets).

The optional parameter **ExpectMultiplePages** can be used as an extra check regarding if the Target definition is expected to result in more than one Document Object.&#x20;

### Export Document Objects

Example:

`<ExportObjects Name="Export reqs" ExportFilePath="ExportedReqs.zip" Target="typeName=Requirement" ConvertToPlainText="false" IncludeHazardLike="false" IncludeMitigationLike="false" />`

The **ExportFilePath** attribute denotes the name of the exported result file (must have a .zip extension).

The **Target** attribute defined which Document Objects to export. The possible target parameter values are explained [here](#the-usage-of-targets).

The is an optional **ExportTransformationName** parameter to specify an XSL transformation run on the result file to transform the exported output to the desired format. The Export Transformation File must be available in the **TransformationMapping** directory in the template directory.

The **ConvertToPlainText**, **IncludeHazardLike,** and **IncludeMitigationLike** attributes are explained [here](https://docs.aligned.ch/aligned-elements-web-client-user-manual/2.5.148.19484/document-object-actions/export-document-objects#export-document-objects-dialog-options).

### Update Document Object

Example:

```markup
<UpdatePage Name="Update a Req" Target="RQ 1" ExpectMultiplePages="false" ChangeComment="Changed from the Automator">
      <ValueForPropertyOnPage PropertyName="Title" Value="Size should not be too large" ValueType="String"/>
      <StrValForAttribute AttributeName="Priority" Value="1"/>
      <StrValForAttribute AttributeName="Applicable To" Value="Operator"/>
    </UpdatePage>
```

The usage of the **Target** attribute is explained [here](#the-usage-of-targets).

The optional parameter **ExpectMultiplePages** can be used as an extra check regarding if the Target definition is expected to result in more than one Document Object.&#x20;

The **ChangeComment** attribute defines the change comment used when committing the updated Document Object to the project.

Use the **ValueForPropertyOnPage** element to define an update on Title or Disabled.

For Title, use **PropertyName**="Title" and **ValueType**="string".

For Disabled, use **PropertyName**="Disabled" and **ValueType**="Bool".

For other Attributes, use the **StrValForAttribute** element. Set the **AttributeName** attribute value to the name of the attribute and a compatible value with the **Value** attribute.

For Richtext Attributes, use the **ValueAsHtmlForAttribute** element. Set the **AttributeName** attribute value to the name of the attribute and a **FilePath** to an exported docx rich text attribute file.

### Update User

Example:

`<UpdateUser Name="Disable Frank" UserName="Frank"><ValueForProperty PropertyName="Disabled" Value="true" ValueType="Bool" /></UpdateUser>`

Use the Update Value action to disable users by setting the **PropertyName** to Disabled, the **Value** to true, and the **ValueType** to Bool.

### Upgrade Project

Example:

`<UpgradeProject Name="Upgrade"/>`

Use the Upgrade Project action to re-load templates and check for modified templates for one or more project(s). This is equivalent to the option 'Force reload of the project and any linked projects (use after template change)' in the Open Project Dialog.

## Error Handling

If an action fails, the execution will stop with an error message.  Subsequent actions are not performed.&#x20;

However, all actions steps have the optional attribute **ContinueOnError**. If set to true, and the action fails, the subsequent actions will still be performed and the error will be ignored.

## How to use the Command Line Tool

Use the console exe called Elements.AutomationToolConsole.exe to run the Automation Tool from the command line.

![](https://2062592451-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LNF6QkY13KiUT4AxV9A%2F-Lao-XFmM8sDUGkL7boF%2F-Lao-lfMjBk8sxkiM4S_%2Fimage.png?alt=media\&token=1606ca36-68bc-4919-8b03-c29681ad5241)

### Required parameters

![](https://2062592451-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LNF6QkY13KiUT4AxV9A%2F-La0LL0kCfSihGqvzA9P%2F-La0YyiNLl1o1Y4782Mz%2Fimage.png?alt=media\&token=1ae52fc2-5c11-4199-bd19-7e245db31b56)

The required parameters are:

* Server url (e.g., /server:<https://elements.aligned.ch>)
* Web User Name (e.g., /user:Frank)
* Web User Password (e.g., /password:654321+)
* Path to Configuration file (e.g., /config:MyNewConfiguration.xml)
* Name of projects separated by a pipe string (e.g., /projects:"Medix Ambulator|Medix Propulator")

Names or paths containing spaces must be placed within quotation marks.

### Exit codes

The Command Line Tool returns a 0 if the execution of the configuration was successful. If the configuration is not well formed or if an action failed, -1 is returned unless **ContinueOnError** is defined for the failed action step.