Typescript Based Project

Overview¶

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

Typescript 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 Typescript format. The project consist of content content container. During build operation the contents of the container are transpiled into Orchestrator Javascript and packaged into Orchestrator native package (the same package that can be exported/imported from Orchestrator UI -> Assets -> Packages).

The typescript project type also allows the user to write unit tests and has embedded code coverage.

Note

Supported Typescript version is 5.4.5.

Supported Content¶

Workflows
Workflow Custom Forms
User Interaction Custom Forms
Actions
Configuration Elements
Resource Elements
Policies

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:

Linux / MacOS (Unix)Windows (PowerShell)Windows (CMD)

mvn archetype:generate \
  -DinteractiveMode=false \
  -DarchetypeGroupId=vmware.pscoe.o11n.archetypes \
  -DarchetypeArtifactId=package-typescript-archetype \
  -DarchetypeVersion=4.25.0 \
  -DgroupId=com.company.department \
  -DartifactId=vro-ts

mvn archetype:generate `
  -DinteractiveMode=false `
  -DarchetypeGroupId=vmware.pscoe.o11n.archetypes `
  -DarchetypeArtifactId=package-typescript-archetype `
  -DarchetypeVersion=4.25.0 `
  -DgroupId=com.company.department `
  -DartifactId=vro-ts

mvn archetype:generate ^
  -DinteractiveMode=false ^
  -DarchetypeGroupId=vmware.pscoe.o11n.archetypes ^
  -DarchetypeArtifactId=package-typescript-archetype ^
  -DarchetypeVersion=4.25.0 ^
  -DgroupId=com.company.department ^
  -DartifactId=vro-ts

Expand for Description of Defined Properties for the Command

Following is a list of the properties that you define in the command for generating a project from the archetype with details about their expected and default values.

The interactiveMode flag specifies whether you want to run the command in interactive mode.
The archetypeGroupId property defines the group ID of the archetype (project template) that you want to use for the project. For VCF Operations Orchestrator TypeScript projects, make sure to set the value to vmware.pscoe.o11n.archetypes.
The archetypeArtifactId property defines the artifact ID of the archetype (project template) that you want to use for the project. For VCF Operations Orchestrator TypeScript projects, make sure to set the value to package-typescript-archetype.
The archetypeVersion property is optional and defines the version of the archetype (project template) that you want to use for the project. This version matches the version of Build Tools for VMware Aria.

Note

Note that if you do not specify a value for the archetypeVersion property, the command uses the default value of 2.38.1. However, since the archetype content changes, you are advised to use an up-to-date version.
The groupId property defines the distinct identifier of the group to which your project belongs. You should use this property to define the base name of the company or the group that creates the project. It acts as a namespace that ensures that project names don't clash with each other. It is recommended to choose a groupId that reflects your organization or main project.
The artifactId property defines the unique identifier for your project or module (within the company or project group). It represents the name of the artifact that is generated by the project. It is recommended to use an artifactId value that reflects the specific project (and project type in multi-module projects).

Content Structure¶

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

service-automation
├── README.md
├── pom.xml
├── release.sh
├── tsconfig.json
└── src
    └── integration-service-1
        └── actions
            └── integrationAction.js
        └── classes
            └── IntegrationService1.ts
            └── IntegrationService1.test.ts
        └── policies
            └── EventListener.pl.ts
        └── resources
            └── sample.txt
            └── sample_2.json
            └── sample_2.json.element_info.json
            └── sample_3.xml
            └── sample_3.xml.element_info.yaml
            └── sample_4.json
        └── types
            └── IntegrationService1.d.ts
        └── workflows
            └── CreateIntegration.wf.ts
            └── CreateIntegration.wf.form.json
        └── IntegrationService1.conf.ts
        └── IntegrationService1Alternative.conf.yaml

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 the settings.xml file 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 the Project¶

This section describes the operation for building the project.

Overview¶

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

Usage¶

To build the project, use the following command.

mvn clean package

The output of the command will result in com.company.department.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 the Project¶

This section describes the operation for bundling the project into an installation bundle (ZIP file).

Overview¶

A Maven profile for producing an installation bundle that contains the solution package, all its dependencies, and scripts for deploying them to a target environment.

Usage¶

To bundle the project, use the following command.

mvn clean package -Pbundle-with-installer

The command produces a ZIP file (installation bundle) with a name that follows the pattern <project.groupId>.<project.artifactId>-<project.version>-bundle.zip, where the values for the placeholders are retrieved from the respective properties of the project pom.xml file.

Following is a sample listing of the structure of the installation bundle ZIP file for the VCF Operations Orchestrator TypeScript project in which the project version is 0.1.0-SNAPSHOT.

Sample structure of an installation bundle

com.company.department.vro-ts-0.1.0-SNAPSHOT-bundle.zip
└── bin
    └── installer
    └── installer.bat
└── etc
    └── logback.xml
└── repo/
└── vro 
    └── com.company.department.dependency-package-1-1.1.0.package  
    └── com.company.department.dependency-package-2-1.2.0.package  
    └── com.company.department.vro-ts-0.1.0-SNAPSHOT.package

Following is a list of the directories in the installation bundle with a short description of their contents.

The bin directory contains the installer script (CLI tool) for importing the solution components from the bundle in two formats, Bash (for Linux/Mac OS) and .bat (for Windows). For more information about using the CLI tool, see the documentation of the Installer.
The etc directory contains configuration files of the Java binaries for the installer script, such as the logging configurations in the logback.xml file. For more information about the logging configuration file, see Logging Configuration.
The repo directory contains the Java binaries for the installer script.
The vro directory contains the project file(s) with the components that you can import to the remote server.

Note

Based on your configurations and dependencies, you can have multiple Maven modules in a single installation bundle. So in addition to the vro directory for the VCF Operations Orchestrator TypeScript project, you can have additional modules for projects of other types.

Bundle Additional Files¶

By default, the -Pbundle-with-installer Maven profile packages only the files and directories that are strictly necessary for importing the project components to the target system (as shown in the Sample structure of an installation bundle listing). However, it also allows you to package additional files or directories from your repository as part of the bundle ZIP and copy them to the root of the installation bundle.

You can use such additional files and directories to bundle supplementary version-controlled content (such as integration tests, files with sample inputs for Orchestrator workflows, properties files for the installer script, Ansible playbooks, etc.) in a single deliverable file.

You specify the additional content that you want to add to the bundle in the <properties> element of the pom.xml file of the project. You can use up to nine <installer.included.item*> elements (in which * stands for a number between 1 and 9) to specify the paths to the files and directories that you want to include.

For example, the following sample configuration of a pom.xml file includes a file with the name environment.properties as item1 and the contents of the integration-tests/ directory as item2.

Sample pom.xml file

<!-- Parameters for including additional files in installation bundles in the pom.xml file --> 
<project>
    ...
    <properties>
        <installer.included.item1>environment.properties</installer.included.item1>
        <installer.included.item2>integration-tests/**</installer.included.item2>
    </properties>
    ...
</project>

Pull Content¶

Warning

Not supported! Typescript development is unidirectional - local code is transpiled into Orchestrator Javascript. Extracting Orchestrator content into local Typescript files is not supported.

Push Content¶

This section describes the operation for pushing project content to the target environment.

Overview¶

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

Usage¶

To push the project content to the target environment (defined in the Maven build profile that you specify in the -P${PROFILE} argument), use the following command.

mvn clean package vrealize:push -Ptarget-env

Include Dependencies¶

By default, the vrealize:push goal deploys all dependencies of the current project to the target environment. You can control this behavior by adding the -DincludeDependencies flag with the value false (to overwrite the default value true).

To skip deploying the project dependencies, run the following command.

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

Note

Note that dependent packages are not deployed to the target environment if the Orchestrator server already has a newer version of the same package deployed.

For example, if your project depends on com.vmware.pscoe.example-2.4.0 but the target server already has com.vmware.pscoe.example-2.4.2 deployed on it, the package on the server will not be downgraded and the dependency package will not be deployed. You can force the deployment of the older version of the dependency package on the remote server by adding the -Dvro.importOldVersions flag.

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

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

Ignore Certificates¶

This section describes the flags that allow you to bypass the security feature for verifying the certificate and certificate hostname of the remote server in a development/testing environment.

Warning

Do not use the flags described in this section when targeting production servers.

Instead, make sure that the certificates have the correct CN, use FQDN to access the servers, and add the certificates to the Java key store (i.e. cacerts).

Use the Maven ProfileDirectly Pass The Parameters

You can ignore certificate errors for all operations by adding the following parameters to the target profile in your Maven settings.xml file.

For the the certificate is not trusted error, use the vrealize.ssl.ignore.certificate parameter.
For the the CN does not match the actual hostname error, use the vrealize.ssl.ignore.hostname parameter.

<!-- Parameters for ignoring certificates in 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 the settings.xml file for MacOS is ~/.m2 and C:\Users\username\\.m2 for Windows.

You can ignore certificate errors for specific operations by adding the following flags to your command.

To ignore the the certificate is not trusted error, add the -Dvrealize.ssl.ignore.certificate flag to your command.
```
mvn package vrealize:push -Ptarget-env -Dvrealize.ssl.ignore.certificate
```
To ignore the the CN does not match the actual hostname error, add the flag -Dvrealize.ssl.ignore.certificate:
```
mvn package vrealize: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¶

This section describes the operation for cleaning up project content from a target environment.

Note

Note that the supported functionality for the cleaning up of project content from a target environment depends on the project type. For details, see the Project Type Support for Content Clean Up.

Overview¶

A dedicated goal for cleaning up project packages from a given environment (server).

Usage¶

To clean up content from the target environment (defined in the Maven build profile that you specify in the -P${PROFILE} argument), use the following command.

mvn vrealize:clean -DincludeDependencies=true -DcleanUpOldVersions=true -DcleanUpLastVersion=false -Ddryrun=true -Ptarget-env

Following is a list of the properties that you define via the -D command line arguments in the command with short description of their values.

The includeDependencies flag specifies whether the package dependencies should be deleted together with the project package.
The cleanUpOldVersions flag specifies whether old versions of the package should be deleted. When combined with the includeDependencies flag, the operation is extended to the dependencies of the project package as well.
The cleanUpLastVersion flag specifies whether the latest version of the project package should be deleted before importing.
The dryrun flag specifies whether the operation should be run in dry run mode.

Examples¶

Following is a list of usage examples for cleaning up content from an environment.

To clean up only the current project package version from the server and keep the older package versions and dependencies, use the command with the following argument values.
```
mvn vrealize:clean -DcleanUpLastVersion=true -DcleanUpOldVersions=false -DincludeDependencies=false -Ptarget-env
```
To clean up the current project package version and its dependencies from the server but keep the older package versions, use the command with the following argument values. Note that this is a force removal operation.
```
mvn vrealize:clean -DcleanUpLastVersion=true -DcleanUpOldVersions=false -DincludeDependencies=true -Ptarget-env
```
To clean up the old project package versions and the old versions of package dependencies but keep the current (latest) package version, use the command with the following argument values.
```
mvn vrealize:clean -DcleanUpLastVersion=false -DcleanUpOldVersions=true -DincludeDependencies=true -Ptarget-env
```

Project Type Support for Content Clean Up¶

The following table provides details about the support of the cleaning up of project content via the vrealize:clean command per project type (archetype).

Archetype	Supported	Comment
vro	Yes	-
vcd	Partial	Does not support dry run mode.
abx	No	Not implemented.
vrops	No	Not implemented.
vra-ng	Partial	Does not support dry run mode.
vrli	No	Product does not provide native package support.
cs	No	Product (Code Stream Services) does not provide native package support.
vcfa-all-apps	Partial	Does not support dry run mode.

Operation Troubleshooting¶

Following is a list of tips on how to resolve issues that you might face when performing any of the supported operations.

If a Maven error does not contain enough information, re-run the command with the -X debug flag.
```
mvn -X <rest of the command>
```
Sometimes Maven might cache old artifacts. To force the fetching of new artifacts, run the command with the -U flag. Alternatively, remove < home >/.m2/repository directory.
```
mvn -U <rest of the command>
```

Known issues¶

Array functions are not transpiled to Orchestrator code¶

If an Array variable is not explicitly defined or recognized as such, the transpiler does not convert the TS-specific Array prototype functions (find(), some(), etc.) into Orchestrator compatible code which results in a runtime error.

Consider the following example:

const testArray = [1, 2, 3, 4, 5];

let objectsForIteration = null;
if (true) {
    objectsForIteration = testArray;
}

// Fails to transpile correctly because type is resolved to "any"
const res = objectsForIteration.find(o => o === 2)
System.log(res + "")

The code above is be converted to the following Orchestrator code, which during execution throws the error TypeError: Cannot find function find in object 1,2,3,4,5.

var testArray = [1, 2, 3, 4, 5];

var objectsForIteration = null;
if (true) {
    objectsForIteration = testArray;
}

// Fails to transpile correctly because type is resolved to "any"
var res = objectsForIteration.find(function (o) { return o === 2; });
System.log(res + "");

Proper variable typization solves this problem. Let's revisit the example but this time we will explicitly define the type of values that we expect the objectsForIteration variable to receive.

const testArray = [1, 2, 3, 4, 5];

let objectsForIteration: Array<number> = null;
if (true) {
    objectsForIteration = testArray;
}

// Transpiles correctly because of explicit typization
const res = objectsForIteration.find(o => o === 2)
System.log(res + "")

The code is transpiled correctly to Orchestrator code and executes successfully.

var __global = System.getContext() || (function () {
    return this;
}).call(null);
var VROES = __global.__VROES || (__global.__VROES = System.getModule("com.vmware.pscoe.library.ecmascript").VROES());
var testArray = [1, 2, 3, 4, 5];

var objectsForIteration = null;
if (true) {
    objectsForIteration = testArray;
}
// Transpiles correctly because of explicit typization
var res = VROES.Shims.arrayFind(objectsForIteration, function (o) { return o === 2; });
System.log(res + "");

How to prevent this issue¶

The recommended configuration to prevent such issues is to set the strictNullChecks property to true in your project's local tsconfig.json file. This allows for a type hint warning to be displayed in case the type is not explicitly defined.

Note

The warning messages received are optional and are NOT blocking package build and push operations.

Let's revisit the example once again with strictNullChecks enabled:

const testArray = [1, 2, 3, 4, 5];

let objectsForIteration = null;
if (true) {
    // The following warning message is displayed: Type 'number[]' is not assignable to type 'null'.ts(2322)
    objectsForIteration = testArray;
}

// The following warning message is displayed: 'objectsForIteration' is possibly 'null'.ts(18047)
const res = objectsForIteration.find(o => o === 2)
System.log(res + "")

Sample tsconfig.json:

{
  "compilerOptions": {
    "target": "ES5",
    "module": "CommonJS",
    "moduleResolution": "Node",
    "lib": [
      "ES5",
      "ES2015.Core",
      "ES2015.Collection",
      "ES2015.Iterable",
      "ES2015.Promise",
      "ES2017.String"
    ],
    "experimentalDecorators": true,
    "strictNullChecks": true
  }
}

VROTSC config¶

The presence of a tsconfig.json file in a directory indicates that the directory is the root of a TypeScript project and is being read by the code editor for autocompletion. Modifying tsconfig.json in the context of vrotsc can affect only the code editor autocompletion.

Because of the nature of extending the typescript compiler and the specific runtime of Orchestrator, vrotsc package has a default tsconfig that is applied for all typescript-project-all projects.

/typescript/vrotsc/src/compiler/config.ts

Example

  return {
   module: ts.ModuleKind.ESNext,
   moduleResolution: ts.ModuleResolutionKind.NodeJs,
   target: ts.ScriptTarget.ES5,
   lib: [
    "lib.es5.d.ts",
    "lib.es2015.core.d.ts",
    "lib.es2015.collection.d.ts",
    "lib.es2015.iterable.d.ts",
    "lib.es2015.promise.d.ts",
    "lib.es2017.string.d.ts",
    "lib.es2016.array.include.d.ts"
   ],
   strict: false,
   allowUnreachableCode: true,
   stripInternal: false,
   removeComments: false,
   experimentalDecorators: true,
   emitDecoratorMetadata: true,
   importHelpers: true,
   suppressOutputPathCheck: true,
   rootDir: rootDir,
   baseUrl: rootDir,
   allowJs: true,
   declaration: true,
   sourceMap: true,
   declarationMap: false,
  // verbatimModuleSyntax: true,
  ignoreDeprecations: "5.0"
};

Typescript Based Project

Overview¶

Supported Content¶

Create New Orchestrator Project¶

Content Structure¶

Environment Connection Parameters¶

Operations¶

Build the Project¶

Overview¶

Usage¶

Bundle the Project¶

Overview¶

Usage¶

Bundle Additional Files¶

Pull Content¶

Push Content¶

Overview¶

Usage¶

Include Dependencies¶

Ignore Certificates¶

Additional Parameters¶

Configuring .vroIgnore File¶

Clean Up Content¶

Overview¶

Usage¶

Examples¶

Project Type Support for Content Clean Up¶

Operation Troubleshooting¶

Known issues¶

Array functions are not transpiled to Orchestrator code¶

How to prevent this issue¶

VROTSC config¶

Configuring `.vroIgnore` File¶