Code Stream can integrate with vRealize Orchestrator (vRO) to extend its capability by running vRO workflows. vRealize Orchestrator includes many predefined workflows that can integrate with third-party tools. These workflows help to automate and manage your DevOps processes, automate bulk operations, and more.

For example, you can use a workflow in a vRO task in your pipeline to enable a user, remove a user, move VMs, integrate with test frameworks to test your code as the pipeline runs, and much more. You can browse examples of code for vRealize Orchestrator workflows in code.vmware.com.

With a vRealize Orchestrator workflow, your pipeline can run an action as it builds, tests, and deploys your application. You can include predefined workflows in your pipeline, or you can create and use custom workflows. Each workflow includes inputs, tasks, and outputs.

To run a vRO workflow in your pipeline, the workflow must appear in the list of available workflows in the vRO task that you include in your pipeline.

Before the workflow can appear in the vRO task in your pipeline, an administrator must perform the following steps in vRealize Orchestrator:

  1. Apply the CODESTREAM tag to the vRO workflow.
  2. Mark the vRO workflow as global.

As an on-premises endpoint, vRealize Orchestrator must communicate with Code Stream through a cloud proxy.

Prerequisites

  • Verify that as an administrator you can access an on-premises instance of vRealize Orchestrator. For help, see your own administrator and the vRealize Orchestrator documentation.
  • Verify that you are a member of a project in Code Stream. If you are not, ask a Code Stream administrator to add you as a member of a project. See How do I add a project in Code Stream.
  • In VMware Cloud Assembly, create a cloud proxy that enables the communication between Code Stream and the on-premises instance of vRealize Orchestrator. For an example of how to create a cloud proxy, see Setting up Code Stream to model my release process.
  • Understand the importance of using a cloud proxy for an on-premises endpoint. See What are Endpoints in Code Stream.
  • In Code Stream, create a pipeline and add a stage.

Procedure

  1. As an administrator, prepare a vRealize Orchestrator workflow for your pipeline to run.
    1. In vRealize Orchestrator, find the workflow that you need to use in your pipeline, such as a workflow to enable a user.
      If you need a workflow that does not exist, you can create it.
    2. In the search bar, enter Tag workflow to find the workflow named Tag workflow.
    3. On the card named Tag workflow, click Run, which displays the configuration area.
    4. In the Tagged workflow text area, enter the name of the workflow to use in your Code Stream pipeline, then select it from the list.
    5. In the Tag and Value text areas, enter CODESTREAM in capital letters.
    6. Click the check box named Global tag.
    7. Click Run, which attaches the tag named CODESTREAM to the workflow that you need to select in your Code Stream pipeline.
    8. In the navigation pane, click Workflows and confirm that the tag named CODESTREAM appears on the workflow card that your pipeline will run.
      After you log in to Code Stream, and add a vRO task to your pipeline, the tagged workflow appears in the workflow list.
  2. In Code Stream, create an endpoint for your vRealize Orchestrator instance.
    1. Click Endpoints > New Endpoint.
    2. Select a project.
    3. Enter a relevant name.
    4. Enter the URL of the vRealize Orchestrator endpoint.
      Use this format: https://vro-appliance.yourdomain.local:8281
      Do not use this format: https://vro-appliance.yourdomain.local:8281/vco/api
      The URL for a vRealize Orchestrator instance that is embedded in the vRealize Automation appliance, is the FQDN for the appliance without a port. For example: https://vra-appliance.yourdomain.local/vco
      For external vRealize Orchestrator appliances starting with vRealize Automation 8.x, the FQDN for the appliance is https://vro-appliance.yourdomain.local
      For external vRealize Orchestrator appliances included with vRealize Automation 7.x, the FQDN for the appliance is https://vro-appliance.yourdomain.local:8281/vco
      If a problem occurs when you add the endpoint, you might need to import a YAML configuration with a SHA-256 certificate fingerprint with the colons removed. For example, B0:01:A2:72... becomes B001A272.... The sample YAML code resembles: 
      ```
---
project: Demo
kind: ENDPOINT
name: external-vro
description: ''
type: vro
properties:
  url: https://yourVROhost.yourdomain.local
  username: yourusername
  password: yourpassword
  fingerprint: <your_fingerprint>
```
    5. Select a cloud proxy.
    6. Click Accept Certificate in case the URL that you entered needs a certificate.
    7. If the vRealize Orchestrator endpoint is version 8.0 to 8.7, you can select Basic Auth or Token for the Authentication type. If the vRealize Orchestrator endpoint is version is 8.8 or later, you must select Token for the Authentication type.
      Note: If the vRealize Orchestrator endpoint is version 8.8 or later, do not select Basic Auth. Basic Auth is not supported and endpoint creation will fail.
      • If you select Basic Auth, enter the user name and password for the vRealize Orchestrator server.

        If you're using a non-local user for authentication, you must omit the domain part of the user name. For example, to authenticate with svc_vro@yourdomain.local you must enter svc_vro in the Username text area.

      • If you select Token for the authentication type, generate and paste the Private Token.
        The CSP API token authenticates you for external API connections with Code Stream. To obtain the API token:
        1. Sign in to vRealize Automation Cloud.
        2. Click the drop-down arrow by your name.
        3. Click My Account.
        4. Click API Tokens.
        5. Click Generate Token.
          1. Enter a Token Name.
          2. Under Organization Roles, select Organization Owner.
          3. Under Service Roles, click to expand VMware Code Stream and select Code Stream Administrator.
          4. Click Generate.

            The Token Generated window displays a token with the name that you specified and the name of your organization.

        6. Click the COPY icon.

          Clicking COPY ensures that you capture the exact string and is more reliable than using your pointer to copy the string.

  3. Prepare your pipeline to run the vRO task.
    1. Add a vRO task to your pipeline stage.
    2. Enter a relevant name.
    3. In the Workflow Properties area, select the vRealize Orchestrator endpoint.
    4. Select the workflow that you tagged as CODESTREAM in vRealize Orchestrator.
      If you select a custom workflow that you created, you might need to enter the input parameter values.
    5. For Execute task, click On condition.
      If you must apply conditions for the vRealize Orchestrator task, enter them in the Condition area.
    6. Enter the conditions that apply when the pipeline runs.
      When to run pipeline... Select conditions...
      On Condition

      Runs the pipeline task only if the defined condition is evaluated as true. If the condition is false, the task is skipped.

      The vRO task allows you to include a boolean expression, which uses the following operands and operators.

      • Pipeline variables such as ${pipeline.variableName}. Only use curly brackets when entering variables.
      • Task output variables such as ${Stage1.task1.machines[0].value.hostIp[0]}.
      • Default pipeline binding variables such as ${releasePipelineName}.
      • Case insensitive Boolean values such as, true, false, 'true', 'false'.
      • Integer or decimal values without quotation marks.
      • String values used with single or double quotation marks such as "test", 'test'.
      • String and Numeric types of values such as == Equals and != Not Equals.
      • Relational operators such as >, >=, <, and <=.
      • Boolean logic such as && and ||.
      • Arithmetic operators such as +, -, *, and /.
      • Nested expressions using round brackets.
      • Strings that include the literal value ABCD are evaluated as false, and the task is skipped.
      • Unary operators are not supported.

      An example condition might be ${Stage1.task1.output} == “Passed” || ${pipeline.variableName} == 39

      Always If you select Always, the pipeline runs the task without conditions.
    7. Enter a message for the greeting.
    8. Click Validate Task, and correct any errors that occur.
  4. Save, enable, and run your pipeline.
  5. After the pipeline runs, examine the results.
    1. Click Executions.
    2. Click the pipeline.
    3. Click the task.
    4. Examine the results, input value, and properties.
      You can identify the workflow execution ID, who responded to the task and when, and any comments they included.

Results

Congratulations! You tagged a vRealize Orchestrator workflow for use in Code Stream, and added a vRO task in your Code Stream pipeline so that it runs a workflow that automates an action in your DevOps environment.

Example: vRO task output format

The output format for a vRO task resembles this example. 

[{
                "name": "result",
                "type": "STRING",
                "description": "Result of workflow run.",
                "value": ""
},
{
                "name": "message",
                "type": "STRING",
                "description": "Message",
                "value": ""
}]

What to do next

Continue to include vRO workflow tasks in your pipelines so that you can automate tasks in your development, test, and production environments.