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.

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.

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.

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

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.

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.

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.

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.

The Document Object type defined in TargetBookName must exist in the target project.

Import Users

Example:

<ImportUsers Name="Add the user Frank" OverwriteExisting="true" ImportFilePath="[e-mail]"/>

The .urs file is an exported User file as described here.

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.

Import User Groups

Example:

<ImportUserGroup Name="Add Group Quality Assurer" OverwriteExisting="true" ImportFilePath="UserGroup@[e-mail]"/>

The .ugr file is an exported User Group file as described here.

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.

Import Queries

Example:

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

The ImportFilePath refers to an exported query definition that results in an xml file as described here.

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.

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.

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.

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.

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.

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

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

Update Document Object

Example:

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

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.

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.

Required parameters

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.