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:
Define the actions to be performed in a configuration file
Start the Automation Tool
Enter a Server url and user credentials and click Connect
Select the projects on which the actions shall be applied
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:
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="Users@MedixProject.urs"/>
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@MedixProject@QualityAssurer.ugr"/>
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:
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.
Last updated
