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.

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 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. Click Accept Certificate in case the URL that you entered needs a certificate.
    6. 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 [email protected] you must enter svc_vro in the Username text area.

      • If you select Token for the authentication type, generate the Private Token.
        The VMware Cloud Services API token authenticates you for external API connections with Code Stream. To obtain the API token:
        1. Click Generate Token.
        2. Enter the email address associated with your user name and password and click Generate.
          The token that you generate is valid for six months. It is also known as a refresh token.
          • To keep the token as a variable for future use, click Create Variable, enter a name for the variable and click Save.
          • To keep the token as a text value for future use, click Copy and paste the token into a text file to save locally.
          You can choose to both create a variable and store the token in a text file for future use.
        3. Click Close.
  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.