XML Based Project¶

Overview¶

Field	Value
Name	xml
Archetype Group ID	com.vmware.pscoe.o11n.archetypes
Archetype Artifact ID	package-xml-archetype
Package extension	package
Product compatibility	VCF Operations Orchestrator (9.x) Aria Automation Orchestrator (8.x) vRealize Orchestrator (7.x)

XML project type is one of the available Orchestrator project types in Build Tools for VMware Aria. The project type is a representation of Orchestrator content into XML format. The project consist of local content container and remote content descriptor on the target server. During build operation the contents of the container are packaged into Orchestrator native package (the same package that can be exported/imported from Orchestrator UI -> Assets -> Packages).

Content Descriptor defines what Orchestrator content will be part of this project when exporting content. The Orchestrator package from UI -> Assets -> Packages plays this role and defines what content is exported. For more information refer to the pull operation section below.
Content Container holds the actual content representation - ./src folder.

Supported Content¶

Workflows
Workflow Custom Forms
User Interaction Custom Forms
Actions
Configuration Elements
Resource Elements
Policy Templates

Create New Orchestrator Project¶

Build Tools for VMware Aria provides ready to use Orchestrator project templates (maven archetypes).

To create a new Orchestrator project from archetype use the following command:

mvn archetype:generate \
    -DinteractiveMode=false \
    -DarchetypeGroupId=com.vmware.pscoe.o11n.archetypes \
    -DarchetypeArtifactId=package-xml-archetype \
    -DarchetypeVersion= # (1)! \
    -DgroupId=com.company.bu # (2)! \
    -DartifactId=project.type # (3)! \
    -DworkflowsPath=integration-service-1/workflows # (4)!

This parameter is optional. Default value is 2.38.1. Note that archetype contents change so usually an up-to-date version is preferred.
The groupId in Maven is a distinctive identifier specifically used for a project. It acts as a namespace, ensuring that project names don't clash with each other. It is recommended to choose a groupId that reflects your organization or project.
The artifactId is a unique identifier for a specific project or module within a project. It represents the name of the artifact that is generated by the project. It is recommended to choose a artifactId that reflects the project type.
Defines the base path (Workflow Category path or labels depending on Orchestrator version) and local folder structure for all the Workflows inside your project. This describes the initial state and can be manually updated later.

Content Structure¶

The result of this command will produce the following project file structure:

service-automation
├── pom.xml
├── release.sh
└── src
    └── main
        └── resources
            └── META-INF
                └── dunes-meta-inf.xml
            └── Workflow
                └── Workflow
                    └── integration-service-1
                        └── workflows
                            └── Install.element_info.xml
                            └── Install.xml
            └── dunes-meta-inf.xml

Environment Connection Parameters¶

The following need to be added to the profile that you intend to use:

<!-- (1)! -->
<profile>
    <!--    ..... OTHER DIRECTIVES .....  -->
    <vro.host>flt-auto01.corp.internal</vro.host>
    <vro.auth>vra|basic</vro.auth>
    <vro.authHost>flt-auto01.corp.internal</vro.authHost>
    <vro.authPort>443</vro.authPort>
    <vro.port>443</vro.port>
    <vro.username>configurationadmin</vro.username>
    <vro.password>someSecurePassword</vro.password>
</profile>

The location of settings.xml for MacOS is ~/.m2 and C:\Users\username\.m2 for Windows

Configuration:

vro.username - For VCF Operations Orchestrator (9.x) you need to provide username in the following format: user@domain.
- admin@System - Provider admin.
- configurationadmin@Classic - Classic organization admin.
vro.auth - Defines the authentication type used for REST API communication.
- Supported values: vra, basic (depending on Orchestrator version might need to be explicitly enabled in the product).
- If set to vra, vro.authHost and vro.authPort need to be provided with the hostname and port of the target VCFA server.

Use the profile by passing it with -P, e.g.:

mvn vrealize:push -Ptarget-env

Operations¶

Build Project¶

Overview¶

Maven goal for compiling the code into a deployment ready package.

Usage¶

mvn clean package

The output of the command will result in com.company.bu.project.type-1.0.0-SNAPSHOT.package file generated in the target folder of the project. This is an Orchestrator native package that can be imported from Orchestrator UI -> Assets -> Packages.

Bundle Project¶

Overview¶

Maven goal for producing an installation bundle containing the solution package, all its dependencies and scripts for deploying to target environment.

Usage¶

mvn clean package -Pbundle-with-installer

For more information refer to Installer documentation.

Pull Content¶

Overview¶

When working on an Orchestrator XML project, you mainly make changes on a live server using the Orchestrator UI and then you can capture those changes in the maven project on your filesystem to be able to store the content, track changes, collaborate, etc.

Usage¶

To support this use case, a custom maven goal vro:pull is used. During this operation the package in Orchestrator UI -> Assets -> Packages has the role of Content Descriptor and defines what content is exported. Everything added to that package is exported during pull operation.

The following command will pull the content outlined into the Orchestrator package to the current project from a specified server and expand its content in the local filesystem overriding any local content:

mvn vro:pull -Ptarget-env

Warning

The command will fail with 404 error if the package does not exist on the target Orchestrator server.

Note

If the package does not exist in the target server it can be manually created via the UI by following the naming convention and the current values of parameters from your project's pom.xml: {groupId}.{artifactId}-{version}.package. However, before your first pull you need to have certain maven dependencies downloaded locally which happens during your first build operation. Thus it is recommended to first push your current content (which also triggers a build operation) to the target Orchestrator server at least once before manually adding new content to the package from UI and pulling it locally.

Additional Parameters¶

Additional parameters that can be passed as flags to the maven command, e.g. mvn vro:pull -Dvro.packageExportConfigurationAttributeValues=true.

vro.packageExportConfigurationAttributeValues - if set to true exports all configuration values besides SecureStrings.
vro.packageExportConfigSecureStringAttributeValues - if set to true exports all Secure String configuration values.

Push Content¶

Overview¶

Maven goal for packaging and deploying all local content from ./src folder to the remote server.

Usage¶

mvn clean package vrealize:push -Ptarget-env

Include Dependencies¶

By default, the vrealize:push goal will deploy all dependencies of the current project to the target environment. You can control that by the -DincludeDependencies flag. The value is true by default, so you skip the dependencies by executing the following:

mvn package vrealize:push -Ptarget-env -DincludeDependencies=false

Note

Dependencies will not be deployed if the server has a newer version of the same package deployed. For example, if the current project depends on com.vmware.pscoe.example-2.4.0 and on the server there is com.vmware.pscoe.example-2.4.2, the package will not be downgraded. You can force that by adding the `-Dvra.importOldVersions flag:

mvn package vrealize:push -Ptarget-env -Dvra.importOldVersions

The command above will forcefully deploy the exact versions of the dependent packages, downgrading anything it finds on the server.

Ignore Certificates¶

This section describes how to bypass a security feature in development/testing environment. Do not use those flags when targeting production servers. Instead, make sure the certificates have the correct CN, use FQDN to access the servers and add the certificates to Java's key store (i.e. cacerts).

Use Maven ProfilesDirectly Pass The Parameters

You can ignore certificate errors the certificate is not trusted and the CN does not match the actual hostname by appending the following parameters to the target profile in your maven settings.xml file:

...<!--# (1)! -->
<profiles>
  ...
  <profile>
      <id>target-env</id>
      <properties>
          ...
          <vrealize.ssl.ignore.hostname>true</vrealize.ssl.ignore.hostname>
          <vrealize.ssl.ignore.certificate>true</vrealize.ssl.ignore.certificate>            
      </properties>
  </profile>
</profiles>

The location of settings.xml for MacOS is ~/.m2 and C:\Users\username\.m2 for Windows

You can ignore certificate error, i.e. the certificate is not trusted, by adding the flag -Dvrealize.ssl.ignore.certificate:

mvn package {projectGoal}:push -Ptarget-env -Dvrealize.ssl.ignore.certificate

You can ignore certificate hostname error, i.e. the CN does not match the actual hostname, by adding the flag -Dvrealize.ssl.ignore.certificate:

mvn package {projectGoal}:push -Ptarget-env -Dvrealize.ssl.ignore.hostname

Additional Parameters¶

Additional parameters that can be passed as flags to the maven command, e.g. mvn clean package -DskipInstallNodeDeps=true.

skipInstallNodeDeps - skip the deletion and re-installation of node-deps.

Note

If node_modules folder doesn't exist, then this flag is ineffective.

vro.forceImportLatestVersions - This strategy will force you to upload the same or newer version of a package, otherwise it will fail the build, allowing us for better CI/CD pipelines, where we can ensure that the latest versions are always used on the server. Default value is false.

Note

Snapshot versions are considered newer if they are the same as the version on the server.

vro.importOldVersions - This strategy will upload a version of the package even if it is older than the version on the server.

Note

Snapshot versions are considered newer if they are the same as the version on the server.

Note

If forceImportLatestVersions is set to true this configuration is ignored.

vro.packageImportConfigurationAttributeValues - if set to true pushes all configuration values besides SecureStrings.
vro.packageImportConfigSecureStringAttributeValues=true - if set to true pushes all Secure String configuration values.

Configuring `.vroIgnore` File¶

Custom file can be added to the project containing glob patterns for file paths to be ignored during compilation, packaging and testing.

The vroIgnoreFile property can be added in the pom.xml file of an Orchestrator project to specify a custom Orchestrator ignore file.

If left unspecified, the default name .vroignore will be used.
If the file with the given name doesn't exist, it will be generated with default content. If it exists but does not match the expected file structure, it will be modified.

Note

In Linux dot files have a special status, use a custom name in case of issues.

Example excerpt from Orchestrator project pom.xml:

  <properties>
    <vroIgnoreFile>customVroignoreFile</vroIgnoreFile>
    <!-- other properties -->
  </properties>

Default .vroignore file structure:

# General
## This file contains glob patterns for file paths to be ignored during compilation, packaging and testing.
## The file will be (re)generated when the project is rebuilt to maintain the default categories and patterns, ignoring blank lines and repeating comments.
## The default categories, defined as rows starting with a single '#', are 'General', 'Packaging', 'Compilation', 'Testing', 'TestHelpers'.
## Patterns not under one of those categories will be considered in the 'General' category and ignored during all operations.
## Patterns must be listed on separate rows (without in-line comments), can be negated with a single '!' at the start and will be trimmed before processing.
## The 'TestHelpers'category will contain these two patterns by default: '**/*_helper.js', '**/*.helper.[tj]s'
## Rows starting with '##' are considered as comments and will be ignored on processing.
# Packaging
## Files with these paths will not be included in the vro package.
## For Workflows, Configurations, Resources and Policies: it is recommended to use the 'General' category (will skip xml element generation).
## Otherwise the patterns below must be based on the _element name_.element_info.xml files in target/vro-sources/xml.
# Compilation
## Files with these paths will be compiled without TS definitions
# Testing
## Files with these paths will be excluded from test coverage
# TestHelpers
## Files with these paths will be included in the tests but will not have TS definitions and will not be included in the test coverage or the vro package
**/*_helper.js
**/*.helper.[tj]s

Clean Up Content¶

Overview¶

A dedicated goal is implemented to clean up project packages on a given environment.

Usage¶

mvn vrealize:clean -DincludeDependencies=true -DcleanUpOldVersions=true -DcleanUpLastVersion=false -Ddryrun=true -P${PROFILE}

includeDependencies - a flag depicting if dependencies should also be deleted
cleanUpOldVersions - a flag depicting if old versions of the package (and dependencies in case of includeDependencies) should be deleted
cleanUpLastVersion - a flag depicting if the latest version should also be deleted before importing
dryrun - Dryrun or not

Examples¶

Clean up only current package version from the server

mvn vrealize:clean -DcleanUpLastVersion=true -DcleanUpOldVersions=false -DincludeDependencies=false

Clean up current package version from the server and its dependencies. This is a force removal operation.
```
mvn vrealize:clean -DcleanUpLastVersion=true -DcleanUpOldVersions=false -DincludeDependencies=true
```

Clean up old package versions and the old version of package dependencies.

mvn vrealize:clean -DcleanUpLastVersion=false -DcleanUpOldVersions=true -DincludeDependencies=true

Project Type Support for vrealize clean¶

Archetype	Supported	Comment
vro	Yes	-
vcd	Partial	It does not support dryRunning
abx	No	Not implemented
vrops	No	Not implemented
vra-ng	Partial	Does not support dryRunning
vrli	No	vRLI does not provide native package support
cs	No	Code Stream Services does not provide native support for packages

Troubleshooting¶

If maven error does not contain enough information re-run it with -X debug flag.
```
mvn -X <rest of the command>
```
Sometimes maven might cache old artifacts. Force fetching new artifacts with -U. Alternatively remove /.m2/repository folder.
```
mvn -U <rest of the command>
```

XML Based Project¶

Overview¶

Supported Content¶

Create New Orchestrator Project¶

Content Structure¶

Environment Connection Parameters¶

Operations¶

Build Project¶

Overview¶

Usage¶

Bundle Project¶

Overview¶

Usage¶

Pull Content¶

Overview¶

Usage¶

Additional Parameters¶

Push Content¶

Overview¶

Usage¶

Include Dependencies¶

Ignore Certificates¶

Additional Parameters¶

Configuring .vroIgnore File¶

Clean Up Content¶

Overview¶

Usage¶

Examples¶

Project Type Support for vrealize clean¶

Troubleshooting¶

Known issues¶

Configuring `.vroIgnore` File¶