OCP command line tool

Installation steps

Developer Build Installation

This will generate a build without any minimization so useful for development and debugging.

cd ot2-cli
npm install
npm run build:dev

Native Build Installation

This will generate a build, best matching the source code.

cd ot2-cli
npm install
npm run build:dev-native

Production Build Installation

This will generate a build using esbuild with minimization so matching the production artifacts.

cd ot2-cli
npm install
npm run build

Install as command

Run the following command to install the tool as command line tool named ocp that is globally available:

npm run install-ocp

To check whether it is registered:

npm ls -g --depth=0

To unregister:

npm run uninstall-ocp

How to use

The following options are available.

• ocp --help : Shows the help text.
• ocp local profile authenticate Authenticate or Reauthenticate a profile with the OCP environment. By default the "default" profile is authenticated but this behavior may be changed via the command line. See ocp local profile authenticate --help for more details.
• ocp local profile delete Delete an existing profile from the profiles configuration file. See ocp local profile delete --help for more details.
• ocp local package deploy Upload and Deploy one or more models to OCP. The deployment will be monitored until either it completes or the configured timeout is reached. Use ocp local package deploy --help for more details.
• ocp local package create Generates a standalone package file suitable for subsequent upload. Use ocp local package create --help for more details.
• ocp local package upload Uploads a package to ALM consisting of zero or more models. The package may be subsequently deployed as desired. Use ocp local package upload --help for more details.
• ocp local profile list List the configured profiles. Use ocp local profile list --help for more details.
• ocp alm deployment monitor Monitor an ongoing deployment or display the final status of a prior deployment. Use ocp alm deployment monitor --help for more details.
• ocp local profile property global-update Add, update or delete the set of properties associated globally will all profiles. See ocp local profile property global-update --help for more details.
• ocp local profile add Add a profile to the profiles configuration file. Profiles can be either global or associated with a specific project. One of the global profiles must be a default profile that would be used for authentication where a specific profile has not been requested. See ocp local profile add --help for more details.
• ocp local profile update Update a profile from the profiles configuration file. Profiles can be either global or associated with a specific project. One of the global profiles must be a default profile that would be used for authentication where a specific profile has not been requested. See ocp local profile update --help for more details.
• ocp local profile tenant add Add a new tenant to a specified profile. You must provide a tenant name and a Tenant ID. The Tenant ID must be a valid UUID and should match a tenant provisioned against the organization ID specified in your profile. The first tenant added is assumed the default however you may change this.
• ocp local profile tenant default Sets an existing tenant to be the default for deployments. Any previous default tenant is unset from this role.
• ocp local profile tenant update Updates an existing tenant. You may change the name and the default setting for the tenant. The name must be unique within the list of tenants associated with the organization profile. By setting the tenant to be the default any other tenants are unset from this role.
• ocp local profile tenant delete Delete an existing tenant. Note that if the deleted tenant is the default you will need to subsequently select or add another tenant as a replacement otherwise you may experience issues deploying as no default target will be configured.
• ocp local profile tenant list List the tenants currently associated with the specified profile. If no profile is specified the default profile will be used.
• ocp local profile upgrade Upgrades the local profile to the latest schema 3.0.0.
• ocp alm app credentials Regenerate the credentials for the service clients associated with the specified profile. If no profile is specified the default profile will be used. As the credentials are associated with a deployed application the command must either be executed within the root directory of the deployable project associated with the application or you must provide the path to the directory containing the deployable project. Use ocp alm app credentials --help for more details.

Usage Examples

Authentication

Note: Authentication is provided as a convenience mechanism to check the connectivity and correctness of the supplied profile credentials. All operations that interact with ALM will automatically authenticate or re-authenticate as required regardless of whether a previous authentication operation has been invoked.

ocp local profile authenticate

Authenticates or re-authenticates with OT Cloud using the credentials contained within your profile. If the authentication is successful an access token will be obtained and cached for subsequent use. By default authentication is performed against the default profile, however this may be overridden by providing suitable command line switches.

The following command line switches are accepted:

• --name <profile name>. This deploys using an alternative profile selected from your profile configuration file. Example ocp local profile authenticate --name QA.
• --config-file <file path>. Allows you to use an alternative configuration file than the default .ot2/profiles.json
• --project <name>. This field is optional. It allows a profile to be associated specifically with a project as created by the VSCode tool set.

Examples

• ocp local profile authenticate. Authenticate or re-authenticate using the configured default profile.
• ocp local profile authenticate --name QA. Authenticate or re-authenticate using a profile named "QA".

Deployments

ocp local package deploy

ocp local package deploy. This deploys to the default profile from the CWD which must contain deployable artifacts and a .otproject file as generated by the VSCode extensions. In addition you may specify command line switches to modify the behavior.

• --name <profile name>. This deploys using an alternative profile selected from your profile configuration file. Example ocp deploy --profile QA.

• --source <file name>. This takes a previously generated archive (as generated by ocp local package create) and deploys it using the default profile. Use in conjunction with --profile if you want to deploy using a different profile.

• --tenant-id <comma separated UUID>. Specifies the tenant to deploy against as opposed to the default tenant.

• --tenant-name <name>. Allows the deployment tenant to be selected using it's configured name. This is likely to be easier to use than the tenant ID. The selected tenant must exist within your profile.

• --all-subscribed-tenants <true | false>. The deployment will target all tenants currently subscribed to by the application. The true | false switch value is considered optional and if not present it is assumed set to true. Note: Setting the switch value to false effectively negates the switch so removes it from the command line. When deploying to all subscribed tenants the tenants currently defined within the profile are ignored. However it is possible to add additional tenants to the set of subscribed tenants by using this option in conjunction with the --tenant-id or --tenant-name switches.

• --all-artifacts <true | false>. The deployment package will include all artifacts regardless of whether they have previously been uploaded. The true | false switch value is considered optional and if not present it is assumed set to true. Note: Setting the switch value to false effectively negates the switch so removes it from the command line. The default behaviour is to only upload artifacts that are considered changed therefore setting this flag may increase the size of the upload.

• --credentials-file <file path>. If set then the credential properties generated when an application is initially created will be saved in the properties file indicated by the file path. These properties will be merged into any exiting properties present in the target file. The following properties will be written if available:

  • APPLICATION_ID=<Unique application ID>
  • PUBLIC_CLIENT_ID=<Your public client secret>
  • CLIENT_ID=<Your confidential client ID>
  • CLIENT_SECRET=<Your confidential client secret>

Note: The target credentials file is validated as being a suitable properties file before the deployment and should an issue be identified then the deployment will abort. Also be aware that the actual properties are only writen on initial application creation. For subsequent runs there will be no output.

• --config-file <file path>. Allows you to use an alternative configuration file than the default .ot2/profiles.json
• --pub-client-id <client ID>. For use where no profile exists (for example CI/CD). You may manually specify your client ID. This will be a public client ID.
• --conf-client-id <client ID>. For use where no profile exists (for example CI/CD). You may manually specify your client ID. This will be a confidential client ID.
• --secret <client secret> For use where no profile exists. You may manually specify a client secret. If this is done then the associated conf-client-id.
• --org <UUID>. For use where no profile exists. You may manually specify an ORG ID.
• --region. For use where no profile exists. Allows you to point the deployment at the required OCP environment.
• --apigee-url. For use where no profile exists. Allows you to point the deployment at the required deployment environment. This is intended for pointing at internal development environments that exist outside of a region.

Note: The region and apigee_url options are mutually exclusive. Attempting to specify both will result in an error.

• --workspace <path>. Optional parameter allowing you to point the tool at the directory containing your project. By default, we use the current working directory.

Examples

• ocp local package deploy. Initiate a deployment to the default profile targeting the default tenant.
• ocp local package deploy --name QA. Initiate a deployment using a profile named "QA" targeting the default tenant.
• ocp local package deploy --tenant-name "Tenant 2". Initiate a deployment using the default profile but targeting a tenant name "Tenant 2".
• ocp local package deploy --org 5dd45f25-e88b-453b-9eab-21eb127da9a1 --conf-client-id Z7JFAKE363a67qtmW5gfakeg8IhaDrX1 --secret fk495kf94lkdd9 --region na-1-dev --tenant-id a52460e6-ce3a-47c1-9bbb-6bb595a7adaa, ee9a1029-26cd-496d-b4b7-2faaf93f350f. This is a typical use-case for CI/CD type environment where no profile is configured. By specifying the client secret authentication will be via OAUTH2 grant type with the client id and client secret being confidential credentials.No user interaction via a browser will be required. ocp local package deploy --org 5dd45f25-e88b-453b-9eab-21eb127da9a1 --conf-client-id Z7JFAKE363a67qtmW5gfakeg8IhaDrX1 --secret fk495kf94lkdd9 --apigee-url https://na-1-dev.api.opentext.com --tenant-id a52460e6-ce3a-47c1-9bbb-6bb595a7adaa, ee9a1029-26cd-496d-b4b7-2faaf93f350f. This is identical to the previous example however here we are targeting the environment via it's URL.

ocp local package create

ocp local package create : creates a package from the current folder project, with the default package name as <Project name>_<Application version>.otpp In addition you may specify the following command line switches to modify the behavior.

• --package_name <name> : The package is created with this as filename, but always with extension .otpp.
• --workspace <path> : Allowing to point the cli at the directory containing your application project. By default the current working directory is used to look for the application artifacts.

ocp local package upload

ocp local package upload. This uploads using the default profile from the CWD which must contain uploadable artifacts and a .otproject file as generated by the VSCode extensions. In addition you may specify command line switches to modify the behavior.

• --name <name>. This uploads using an alternative profile selected from your profile configuration file. Example ocp local package upload --name QA.
• --source <file name>. This takes a previously generated archive (as generated by ocp package) and deploys it using the default profile. Use in conjunction with --name <profile name> if you want to deploy using a different profile.
• --all-artifacts <true | false>. The upload package will include all artifacts regardless of whether they have previously been uploaded. The true | false switch value is considered optional and if not present it is assumed set to true. Note: Setting the switch value to false effectively negates the switch so removes it from the command line. The default behaviour is to only upload artifacts that are considered changed therefore setting this flag may increase the size of the upload.
• --credentials-file <file path>. If set then the credential properties generated when an application is initially created will be saved in the properties file indicated by the file path. These properties will be merged into any exiting properties present in the target file. The following properties will be written if available:
  • APPLICATION_ID=<Unique application ID>
  • PUBLIC_CLIENT_ID=<Your public client secret>
  • CLIENT_ID=<Your confidential client ID>
  • CLIENT_SECRET=<Your confidential client secret>

Note: The target credentials file is validated as being a suitable properties file before the upload and should an issue be identified then the upload will abort. Also be aware that the actual properties are only writen on initial application creation. For subsequent runs there will be no output.

• --config-file <file path>. Allows you to use an alternative configuration file than the default .ot2/profiles.json
• --pub-client-id <client ID>. For use where no profile exists (for example CI/CD). You may manually specify your client ID. This will be a public client ID.
• --conf-client-id <client ID>. For use where no profile exists (for example CI/CD). You may manually specify your client ID. This will be a confidential client ID.
• --secret <client secret> For use where no profile exists. You may manually specify a client secret. This option is used in conjunction with the --conf-client-id option.
• --org <UUID>. For use where no profile exists. You may manually specify an ORG ID.
• --region. For use where no profile exists. Allows you to point the upload at the required OCP environment.
• --apigee-url. For use where no profile exists. Allows you to point the upload at the required environment. This is intended for pointing at internal development environments that exist outside of a region.
• --all-artifacts.

Note: The region and apigee-url options are mutually exclusive. Attempting to specify both will result in an error.

• --workspace <path>. Optional parameter allowing you to point the tool at the directory containing your project. By default we use the current working directory.

Examples

• ocp local package upload. Initiate an upload using the default profile.
• ocp local package upload --name QA. Initiate an upload using a profile named "QA".
• ocp local package upload --org 5dd45f25-e88b-453b-9eab-21eb127da9a1 --conf-client-id Z7JFAKE363a67qtmW5gfakeg8IhaDrX1 --secret fk495kf94lkdd9 --region na-1-dev. This is a typical use-case for CI/CD type environment where no profile is configured. By specifying the client secret authentication will be via OAUTH2 grant type with the client id and client secret being confidential credentials.No user interaction via a browser will be required. ocp local package upload --org 5dd45f25-e88b-453b-9eab-21eb127da9a1 --conf-client-id Z7JFAKE363a67qtmW5gfakeg8IhaDrX1 --secret fk495kf94lkdd9 --apigee-uurl https://na-1-dev.api.opentext.com. This is identical to the previous example however here we are targeting the environment via it's URL.

Profile Management

Other profiles may be added configured to point at other environments whether this is simply an alternative organization through to pointing at a different OT cloud installation.

ocp local profile upgrade

Upgrades the profile to the latest schema 3.0.0. ocp local profile upgrade. Upgrades the profile to the latest schema 3.0.0.

The following command line switches are accepted:

• --config-file <file path>. Selects an alternative configuration file to load the profiles from.

ocp local profile list

Outputs the profiles currently configured as a list. ocp local profile list. Lists all profiles defined within the default configuration file.

The following command line switches are accepted:

• --config-file <file path>. Selects an alternative configuration file to load the profiles from.
• --extended. If specified outputs additional information about the profiles.

Output Fields

• name. The profile name.
• project. The project the profile is associated with. Typically, this field will be blank.
• Org Name. The user readable organization name associated with the organization.
• Org ID. The UUID code for the organization.
• Default. Set to "YES" if this is a default profile otherwise it will be blank.
• Auth Creds . (Extended). Type of configured authentication credentials. Either "Public", "Confidential" or "Undefined". The actual configured values are not shown.
• Authenticated. (Extended). Has the profile previously been authenticated. (Extended). "YES" if the profile has previously been authenticated successfully. "SUSPECT" if previously authenticated but subsequently something has gone wrong. Blank if not authenticated.
• Properties. (Extended).List of properties associated with the profile. There will be 2 lists present in this field. properties - those properties associated with this profile. global properties - those properties configured at a global level and inherited by the profile.

ocp local profile add

ocp local profile add. This allows a profile to be added. As an example to add a simply profile: ocp local profile add --profile TEST --org_id 6bab3d9a-16b1-453b-b6dd-8866a1aa5806 --org-name Opentext --pub-client-id 4509843uriejfif9843 --region na-1.

The following command line switches are accepted:

• --name <profile name>. This field is mandatory and identifies the name of the profile to add. Note: This field cannot be subsequently modified.

• --project <project name>. This field is optional. It allows a profile to be associated specifically with a project as created by the VSCode tool set. Note: This field cannot be subsequently modified.

  Note: This field cannot be subsequently modified. This flag is for advanced usage so the --project switch should be avoided unless you have a specific requirement.

• --config-file <file path>. Selects an alternative configuration file to load and store the profile from.

• --org <UUID>. When initially creating the profile you must specify a valid ORG ID. Subsequently you only need to specify if there is a need to modify the ORG ID.

• --org-name <name>. When initially creating the profile you must specify a name for your organization. Subsequently you only need to specify if there is a need to modify the ORG name.

• --pub-client-id <ID>. When initially creating the profile you must specify a client ID for authentication purposes. Subsequently you only need to specify if there is a need to modify the client ID.

• --conf-client-id <ID>. When initially creating the profile you must specify a client ID for authentication purposes. Subsequently you only need to specify if there is a need to modify the client ID.

• --secret <secret>. Used in conjunction with the --conf-client-id to specify the client secret.

• --default. Marks the profile as being the default. Any existing default profile is unset as part of the operation.

• --region <region>. This is a convenience operation allowing the region property to be easily set. We provide this as the profile must point at a target environment whether this is specified via the region or the apigee_url property. Typically, it is assumed that region will be used to specify the environment. If no region or apigee_url is specified then the profile will inherit from the global properties if possible and will error if this is not possible.

Note: Specifying the region via the --region option actually adds a property so "--region na-1-dev" is analogous to "--properties region=na-1-dev".

• ocp local profile add --name DEFAULT --properties <List of properties>. Allows properties to be added to the profile. The possible profile properties are listed further below.

Examples

• Setting properties with values: ocp local profile add --name --properties apigee_url=https://devx1.dev.apigee.otxlab.net,authentication_handler=otDeveloperIdp
• Setting properties with empty values: ocp local profile add --name DEFAULT --org 6bab3d9a-16b1-453b-b6dd-8866a1aa5806 --org-name Opentext --pub-client-id 4509843uriejfif9843 --region eu-1 --properties authentication_handler=
• Setting the region via --region: ocp local profile add --name DEFAULT --org 6bab3d9a-16b1-453b-b6dd-8866a1aa5806 --org-name Opentext --pub-client-id 4509843uriejfif9843 --region na-1-dev
• Setting the region via --properties: ocp local profile add --name DEFAULT --org 6bab3d9a-16b1-453b-b6dd-8866a1aa5806 --org-name Opentext --pub-client-id 4509843uriejfif9843 --properties region=na-1-dev
• Setting the apigee_url via --profile: ocp local profile add --name DEFAULT --org 6bab3d9a-16b1-453b-b6dd-8866a1aa5806 --org-name Opentext --pub-client-id 4509843uriejfif9843 --properties apigee_url=https://devx1.dev.apigee.otxlab.net
• Switch from region to apigee_url: ocp local profile add --name DEFAULT --org 6bab3d9a-16b1-453b-b6dd-8866a1aa5806 --org-name Opentext --pub-client-id 4509843uriejfif9843 --properties region,apigee_url=https://devx1.dev.apigee.otxlab.net

All of the above may be mixed on the command line if desired.

ocp local profile update

ocp local profile update. This allows an existing profile to be updated. As an example to add a simply profile: ocp local profile update --name TEST --org 6bab3d9a-16b1-453b-b6dd-8866a1aa5806 --org-name Opentext --pub-client-id 4509843uriejfif9843.

The following command line switches are accepted:

• --name <profile name>. This field is mandatory and identifies the name of the profile to add or update. Note: This field cannot be subsequently modified.

• --project <name>. This field is optional. It allows a profile to be associated specifically with a project as created by the VSCode tool set. Note: This field cannot be subsequently modified.

  Note: This field cannot be subsequently modified. This is for advanced usage so the --project switch should be avoided unless you have a specific requirement.

• --config-file <file path>. Selects an alternative configuration file to load and store the profile from.

• --org <UUID>. When initially creating the profile you must specify a valid ORG ID. Subsequently you only need to specify if there is a need to modify the ORG ID.

• `--org-name . When initially creating the profile you must specify a name for your organization. Subsequently you only need to specify if there is a need to modify the ORG name.

• --pub-client-id <ID>. When initially creating the profile you must specify a client ID for authentication purposes. Subsequently you only need to specify if there is a need to modify the client ID. This is for a public client ID.

• --conf-client-id <ID>. When initially creating the profile you must specify a client ID for authentication purposes. Subsequently you only need to specify if there is a need to modify the client ID. This if for a confidential client ID.

• --secret <secret>. Used in conjunction with the --conf-client-id to set the client secret for a confidential client.

Note: If you wish to use confidential credentials then this must be done when the profile is initially created otherwise the profile is assumed to use public credentials.

• --default. Marks the profile as being the default. Any existing default profile is unset as part of the operation.

• --region <region>. This is a convenience operation allowing the region property to be easily set. We provide this as the profile must point at a target environment whether this is specified via the region or the apigee_url property. Typically, it is assumed that region will be used to specify the environment. If no region or apigee_url is specified then the profile will inherit from the global properties if possible and will error if this is not possible.

  Note: Specifying the region via the --region option actually adds a property so "--region na-1-dev" is analogous to "--properties region=na-1-dev".

• ocp update-profile --profile DEFAULT --properties <List of properties>. Allows properties to be added, replaced or removed from a profile. The possible profile properties are listed further below.

Note: Specifying the region via the --region option actually adds a property so "--region na-1-dev" is analogous to "--properties region=na-1-dev".

• ocp local profile update --name DEFAULT --properties <List of properties>. Allows properties to be added, replaced or removed from a profile. The possible profile properties are listed further below.

Examples

• Setting properties with values: ocp local profile update --name --properties apigee_url=https://devx1.dev.apigee.otxlab.net,authentication_handler=otDeveloperIdp
• Setting properties with empty values: ocp local profile update --name DEFAULT --properties authentication_handler=
• Deleting properties: ocp local profile update --name DEFAULT --properties apigee_url,authentication_handler
• Setting the region via --region: ocp local profile update --name DEFAULT --region na-1-dev
• Setting the region via --profile: ocp local profile update --name DEFAULT --properties region=na-1-dev
• Setting the apigee_url via --profile: ocp local profile update --name DEFAULT --properties apigee_url=https://devx1.dev.apigee.otxlab.net
• Switch from region to apigee_url: ocp local profile update --name DEFAULT --properties region,apigee_url=https://devx1.dev.apigee.otxlab.net
• Unsetting the region via --region:ocp local profile update --name DEFAULT --region

All of the above may be mixed on the command line if desired.

ocp local profile delete

Deletes a profile from your profile configuration file.

Note: You may not delete the default profile unless it is the only configured profile. If you need to delete the default you must first specify a replacement using ocp local profile update --name <name> --default.

The following command line switches are supported:

• --name <profile name>. This field is mandatory and identifies the name of the profile to be removed.
• --project <name>. Required where the profile has been previously created against a named project.
• --config-file <file path>. Indicates that you wish to remove a profile from an alternative configuration file.

ocp local profile property global-update

This command adds, updates and removes global profile properties. These are properties that apply globally to all profiles present within your configuration file.

This command adds, updates and removes global profile properties. These are properties that apply globally to all profiles present within your configuration file.

Note: Were a profile also defines a setting for the same property then the value in the profile will take precedence.

The following command line options are supported:

• --config-file <file path>. Selects an alternative configuration file to load and store the profile from.
• --properties <List of properties>. Allows properties to be added, replaced or removed from a profile. The possible profile properties are listed further below.

Examples

• Setting properties with values: ocp local profile property global-update --properties apigee_url=https://devx1.dev.apigee.otxlab.net,authentication_handler=otDeveloperIdp.
• Setting properties with empty values: ocp local profile property global-update --properties authentication_handler=.
• Deleting properties: ocp local profile property global-update --properties apigee_url,authentication_handler.

Monitoring Deployments

The actual deployment will continue even though monitoring has stopped so a mechanism is provided to restart the monitoring. Additionally this allows for the final state of a completed deployment to be returned.

ocp alm deployment monitor

Restart monitoring a deployment or report the final state of a completed deployment.

The following command line options are supported:

• --deployment-id <ID>. The ID of the deployment to monitor. The ID will have been returned by the previous ocp deploy command and is a mandatory field.
• --profile <name>. Identifies the name of the profile associated with the deployment. The default profile will be selected if not specified.
• --project <name>. This field is optional. It selects a profile that is associated with a project.
• --config-file <file path>. Selects an alternative configuration file to load the profile from.
• --timeout <value in ms>. Provides an override value for the timeout configured within the profile. By default the deployment will be monitored for 120000ms.

Note: a value of 0 will cause the deployment to be monitored until it eventually completes.

• --refresh <value in ms>. Provides an override value for the monitor refresh period configured within the profile. By default, the deployment state is refreshed every 2000ms.

Tenant Configuration

The configured tenants can be associated with a profile for deployment purposes. One tenant will be the default with the others being selectable on demand. The current behavior from the CLI command line will be to deploy to a single tenant or all tenants however internally we do support deployment from a list and this may be exposed from the VSCode extensions from the graphical interface if desired.

ocp local profile tenant add

Add a new tenant to the provisioned list of tenants. Note: If this is the 1st tenant then it will automatically be set as the default tenant for deployments.

The following command line options are supported:

• --name <profile name>. Identifies the name of the profile to add the tenant against.
• --project <name>. This field is optional. It selects a profile that is associated with a project.
• --config-file <file path>. Selects an alternative configuration file to load the profile from.
• --tenant-id <UUID>. Specifies the tenant ID for the new tenant. Must be specified as a UUID. This should align with what is provisioned at the DEVX console.
• --tenant-name <name>. Specifies the tenant name associated with the new tenant. This is optional. If the option is not specified then the value will be derived from the DEVX console.
• --default. Sets this tenant as the default tenant. Any existing default tenant is unset from this role as a consequence.
• --all-tenants. I specified the current tenants as assigned at the DEVX console will be loaded and added to the profile.

Note: The 1st tenant added always defaults to be the default regardless of this switch being specified. Examples:

• ocp local profile tenant add --name DEV --tenant-id 7d90cf7d-d771-4bf0-af52-1502560e3f89. Adds a tenant with Id = "7d90cf7d-d771-4bf0-af52-1502560e3f89". The tenant name will be derived from the DEVX console so we will exactly match the DEVX console. If this is your 1st tenant it will be marked as the default otherwise it will not.
• ocp local profile tenant add --name DEV -- tenant-name "Tenant 4". Loads the tenants from the DEVX console and locates a tenant with the name set to "Tenant 4" to determine the tenant ID. The tenant is then added to the profile with the specified name and the derived ID. If this is your 1st tenant it will be marked as the default otherwise it will not.
• ocp local profile tenant add --name DEV --tenant-id a397b5b9-b6c7-430c-9123-522ae95abb80 -- tenant-name "Tenant 1. Adds a tenant with Id = "a397b5b9-b6c7-430c-9123-522ae95abb80" and name = "Tenant 1". If this is your 1st tenant it will be marked as the default otherwise it will not.
• ocp local profile tenant add --name DEV --tenant-id 1963d0d2-fa43-4a85-8703-8737fd532af5 -- tenant-name "Tenant 2 --default. Adds a tenant with Id = "1963d0d2-fa43-4a85-8703-8737fd532af5" and name = "Tenant 2". This tenant will be marked as your default with any other tenant previously being set as the default being unset as part of the operation.
• ocp local profile tenant add --name DEV --all-tenants. Loads the list of tenants from the DEVX console. Any tenants not yet present in the profile are added. If the end result is just a single tenant in our profile then this tenant is automatically set to be the default otherwise it will not do this and the default will need to be manually set if necessary.

ocp local profile tenant default

Sets an existing tenant as being the default. Any tenant previously marked as the default is unset from this role as part of the process.

The following command line options are supported:

• --name <profile name>. Identifies the name of the profile managing the configured tenants.
• --project <name>. This field is optional. It selects a profile that is associated with a project.
• --config-file <file path>. Selects an alternative configuration file to load the profile from.
• --tenant-id <UUID>. Specifies the tenant ID for the tenant. The field is an optional UUID however you must specify either the tenant-id or the tenant-name.
• --tenant-name <name>. Specifies the tenant name associated with the tenant. The field is optional however you must specify either the tenant-id or the tenant-name.
• --default <true|false>. Optional switch to set default as true or false. If the switch is not specified or is provided without a value then the default behavior is to set default as true.

Examples

• ocp local profile tenant default --name DEV --tenant-id a397b5b9-b6c7-430c-9123-522ae95abb80. Locates the tenant with Id = "a397b5b9-b6c7-430c-9123-522ae95abb80" and marks this as the default tenant.

ocp local profile tenant delete

Deletes either an existing tenant or all tenants from a specified profile.

The following command line options are supported:

• --name <profile name>. Identifies the name of the profile managing the configured tenants.
• --project <name>. This field is optional. It selects a profile that is associated with a project.
• --config-file <file path>. Selects an alternative configuration file to load the profile from.
• --tenant-id <UUID>. Specifies the tenant ID for the tenant to delete. The field is an optional UUID however you must specify either the tenant-id or the tenant-name.
• --tenant-name <name>. Specifies the tenant name associated with the tenant to delete. The field is optional however you must specify either the tenant-id or the tenant-name.

Examples

• ocp local profile tenant delete --name DEV --tenant-name "Tenant 1". Locates the tenant with name = "Tenant 1" in your DEV profile and deletes it. Note: If this tenant is your default tenant then at this point you have no default tenant until a replacement is selected.

ocp local profile tenant update

Updates an existing tenant.

The following command line options are supported:

• --name <profile name>. Identifies the name of the profile managing the configured tenants.
• --project <name>. This field is optional. It selects a profile that is associated with a project.
• --config-file <file path>. Selects an alternative configuration file to load the profile from.
• --tenant-id <UUID>. Specifies the tenant ID for the tenant to update. The field is a UUID and is mandatory.
• --tenant-name <name>. Specifies a replacement value for the tenant name. The field is optional.
• --default <true|false>. Optional switch to set default as true or false. If the switch is not specified or is provided without a value then the default behavior is to set default as true.

Note: Where a tenant Id and a tenant name are specified, the operation will update the tenant name field. It is not possible to modify the tenant Id and the tenant should be deleted and added again if this is desired. *--default. Sets the tenant as being the default tenant. Any existing default tenant is unset from this role.

Examples

• ocp local profile tenant update --name DEV --tenant-id a397b5b9-b6c7-430c-9123-522ae95abb80 --tenant-name "New Tenant Name" --default. Locates the tenant with ID "a397b5b9-b6c7-430c-9123-522ae95abb80", changes the name to be "New Tenant Name" and marks it as being the default tenant.

ocp local profile tenant list

List the tenants associated with a profile. If it is possible to authenticate with the DEVX console then any unassociated tenants will also be output and any mismatches between the profile and the DEVX console will be shown.

The following options are supported:

• --name <profile name>. Identifies the name of the profile managing the configured tenants.
• --project <name>. This field is optional. It selects a profile that is associated with a project.
• --config-file <file path>. Selects an alternative configuration file to load the profile from.

Output Fields

The following fields are output by ocp list-tenants.

• Tenant ID. The Tenant Id.
• Tenant Name. The tenant name.
• Default. Set to "YES" if the tenant is a default otherwise left as blank.

Regeneration of Service Client Credentials

When an application is first deployed a pair of service clients are automatically generated for the application. Each application has a public service client and a confidential service client. Associated with each service client is a client ID. The confidential client also has an asspciated client secret used for authentication. The public client authenticates using OTConnect and requires the use of a password.

Should the cconfidential client credentials be lost or compromised it is possible to regenerate these by the OCP CLI.

Note: As part of the operation to regenerate the service client credentials the existing public client ID will be returned. This is never changed hence we are only regenerating the confidential service client credentials which will return a new client ID and client secret pair.

ocp alm app credentials

Regenerate the service client credentials.

The following options are supported:

• --profile <name>. This field is optional. Identifies the name of the profile used to originally deploy the application. If not specified the default profile will be used.
• --project. This field is optional. It selects a profile that is associated with the project by name.
• --workspace <path to project workspace>. This field is optional. If specified it will contain the path to the project workspace folder used for the original deployment. This may be an absolute or relative path. If not specified it is assumed that the current directory path contains the project workspace.
• --config-file <path to config file>. This field is optional. If specifoed an alternative config file will be used to load the profile.
• --force. By default the ocp cli will ask the user to confirm they wish to regenerate the service client credentials and will abort if not confirmed. By specifying the --force switch the confirmation check will be skipped.
• --app-credentials-output <file path> If set then the regenerated service client credential properties generated will be saved in the properties file indicated by the file path. These properties will be merged into any exiting properties present in the target file. The following properties will be written if available:
  • APPLICATION_ID=<Unique application ID>
  • PUBLIC_CLIENT_ID=<Your public client secret>
  • CLIENT_ID=<Your confidential client ID>
  • CLIENT_SECRET=<Your confidential client secret>

Environment variables

The following environment variables are used. They can be set in the context or in the .env.

• OCP_APIGEE_URL - the url that points to the runtime environment (an apigee host). Mutually exclusive with OCP_REGION
• OCP_REGION - the region that points to the runtime environment. Mutually exclusive with OCP_APIGEE_URL
• EXCLUDES - an array of folder names that need to ignored when deploying. Default value is [".git"].
• OCP_ALM_DEV_INTEGRATION_URL - an alternative URL to use for the ALM. This is for developer use and typically involves an ALM running on the local machine (http://localhost:8080) with the dev profile. Note: The OCP_APIGEE_URL API is still used for initial authentication and to access other DevX services
• OCP_ORGANIZATION_ID - Organization Id to authenticate against
• OCP_ORGANIZATION_CLIENT_ID - Organization Client Id for authentication
• OCP_ORGANIZATION_CLIENT_SECRET - Organization client secret for immediate authentication in conjunction with the client Id
• OCP_AUTHENTICATION_CALLBACK_URL - Authentication flow callback endpoint - defaults to http://localhost:22682/login/oauth2/code if unset
• OCP_LOGIN_TIMEOUT - timeout period in milliseconds to wait for the authentication flow to return from the login page. Defaults to 180000 (3 minutes) if unset.
• OCP_DISABLE_PKCE - Do not use PKCE extensions in the authentication login flow. This is for debug purposes and must be disabled prior to the public release. Default is FALSE
• OCP_AUTH_HANDLER - The authorization flow login auth handler. The default if unset is otconnect for the production system however for internal use against devx1 or devx2 please set this to be "otDeveloperIdp"
• OCP_HTTPS_DEVELOPER_MODE - set to true for internal OpenText DevX systems when using the associated VSCode extension. This provides a workaround for internally generated certificates being rejected by the VSCode HTTPS implementation.
• OCP_DEPLOYMENT_MONITOR_TIMEOUT - timeout period in milliseconds to wait for a deployment to complete. Defaults to 120000 (2 minutes if unset). A value of 0 indicates wait indefinitely otherwise the minimum allowed value is 100.
• OCP_DEPLOYMENT_MONITOR_REFRESH - refresh period in milliseconds for monitoring of an ongoing deployment. Defaults to 2000 (2 seconds) if unset. The minimum allowed value is 100.
• OCP_SHOW_STACKTRACE - if set to 'true' a stacktrace will be output when ocp cli generates errors. Default value is `false'.
• OCP_TENANT_ID - Tenant Id to target for deployment.
• OCP_ALM_API_VERSION - The ALM API version to use for deployments. Current supported values are v1, v2 and auto with auto being the default if not set.

Profile Properties

Properties may be configured within the profiles.json file either globally or against a specific profile. Where a property exists both globally and against a profile the version defined against the profile will take precedence.

Note: Profile properties take precedence over any equivalent environment variable. The following profile properties are currently supported:

• apigee_url Set the Apigee URL. Mutually exclusive with region and either apigee_url or region must be set.
• region. Set to the environment region to target the required APIGEE host. Mutually exclusive with apigee_url and either region or apigee_url must be set. This property currently supports the following values: au, ca, eu-1, na-1, na-1-dev, us.
• alm_integration_url Internal Developer alternative ALM Integration URL.
• alm_api_version Set to the required ALM API version. Current supported values are v1, v2 and auto. The default if not specified is auto which will select the latest API version mutually supported by both the tooling and the ALM.
• authentication_callback_url Alternative authentication flow callback URL. Defaults to http://localhost:22682/login/oauth2/code. If this is set you are responsible for setting the callback URL within the DevX console.
• authentication_disable_pkce Disable the PKCE extension in the authorization flow authentication process. This is for internal developer use.
• authentication_handler Set the authentication handler used by the authentication flow web. This defaults to otconnect which aligns with the external PROD system. However, for internal use against the devx1 ... devx2 development platforms an alternative authentication handler must be specified. Please use otDeveloperIdp for the internal development platforms.
• authentication_timeout Timeout in milliseconds for the authentication flow web authentication process. The default is 180000 (3 minutes). This is intended for internal developer use.
• authentication_tls_dev_mode Allow VSCode to inter-work with the internal OpenText DevX platforms to prevent issues with internally generated SSL certificates being rejected by VSCode. Set to true for these internal platforms. Not required for the standalone ot2-cli or the external PROD platforms.
• chunk_size Set the number of bytes that an upload will be broken into. The default setting is 2097152 (2MB chunks) and the actual setting must be within the range 524288 to 10000000 (0.5MB bytes to 9.53 MB). Unless configuration dictates otherwise where a package size is <= the chunk size then we will upload as a single contiguous upload as opposed to a chunked upload.
• deployment_monitor_refresh Set the refresh interval in ms for monitoring a deployment. The default is 2000 (2s)
• deployment_monitor_timeout Set the maximum period in ms that we will wait for a deployment to complete whilst monitoring. Exceeding this limit will result in timeout being reported for any non deployed artifacts although the actual deployment continues running. A value of 0 indicates run until completed. Default is 120000 (2 minutes)
• http_upload_max_time The maximum time in ms for the model data upload to complete. The default setting is 0 indicating there is no maximum time set to allow for slow running uploads.
• http_timeout The maximum time in ms that a request to the ALM is allowed to take excluding the upload of model data. The default setting is set to 30000 indicating we will wait 30s for a response from ALM.
• http_timeout_max_retries. The number of times we will attempt to retry upon a timeout to ALM having been encountered. The default setting is 3.
• http_upload_timeout The maximum time in ms that the tool will wait for a model data block to be uploaded. Exceeding the timeout is interpreted as a network issue and will result in the upload being aborted. Setting the value to 0 is interpreted as no timeout. The default setting is 10000 for a 10s maximum delay between data being uploaded.
• upload_max_flow_rate Set the maximum flow rate for model uploads into ALM. The set value is in multiples of Kb hence a value of 29 would indicate 29Kb/s maximum. Setting the property to 0 indicates an unlimited flow rate. The default value is 29 for GCP environments and 0 for all other environments.
• upload_mode Sets the mode of upload. This property supports the following values: auto, chunked and contiguous. The default setting is auto which indicates that the tool should choose the most appropriate package upload mechanism.

Profile Configuration

By default, your configuration is held in a subdirectory .ot2 found within your home directory. If it does not currently exist a file named profiles.json will be created to hold your profile configuration. This will be updated each time a change is made.

You should avoid manually modifying this file as it may lead to corruption, however within the .ot2 directory you will find backups of the configuration file to assist with any need to recover following an accidental change.

The current backup is called profiles.json.backup and in addition up to 10 additional historic backups are also held profiles.json.backup.1 through to profiles.json.backup.10 where profiles.backup.10 is the oldest backup.

Please be aware that the profile configuration is versioned. An older version of the ocp cli or the associated VSCode extensions may refuse to run if they encounter a profile configuration that is of a newer vintage. If you encounter this scenario then your tooling must be upgraded to the latest versions.

How to install in a different project

npm install --save-dev @opentext/ocp@next or npm install --save-dev @opentext/ocp With @next it will install the last continuous integration version. @latest is the last available stable version.

Use the command line tool:

npx ocp

This will show the usage message.

Docker

There are two Dockerfiles in the repo. 1: ./docker/Dockerfile - used by the build server to create an image 2: ./Dockerfile - to build a image locally

Build and Run docker images locally:

docker-compose

Use the following docker-compose command to build and run a docker image:

Pull the latest image or build from a Dockerfile

docker-compose build --pull;

Start the ot2-cli container/service

docker-compose run ot2-cli

This gives a shell where the command ocp is available.

To start all the services

docker-compose up -d

Stop the containers specified in the docker compose file

docker-compose down