The presentation of a workflow can define constraints for the values that you can pass to the input parameters of the workflow, such as a predefined list of values or a certain range of values. To ensure that the workflow runs successfully, you must validate the values that you pass to the input parameters of the workflow against the definition of the workflow presentation.

About this task

When you integrate workflows in custom applications, you might need to create a wizard where you enter values for the input parameters of the workflow when you run it. By using the Workflow Presentation service, you can instantiate the presentation of a workflow and pass values for its input parameters in parts that correspond to the different screens of the wizard. You can validate the values that you pass to the input parameters against the constraints that are defined in the workflow presentation.

Prerequisites

Verify that you have imported the sample workflows package in Orchestrator. The package is included in the Orchestrator sample applications ZIP file that you can download from the Orchestrator documentation page.

Procedure

  1. Retrieve the definition of the workflow that you want to run by making a GET request at the URL that contains the workflow definition:
    GET https://{vcoHost}:{port}/vco/api/workflows/{workflowID}/

    You receive the definition of the workflow in the response body of the request. In the workflow definition, you can view the input parameters of the workflow, the workflow description and other information.

  2. Retrieve the definition of the workflow presentation by making a GET request at its URL:
    GET https://{vco host}:{port}/vco/api/workflows/{workflowID}/presentation/
  3. In the response body of the request, examine the definition of the workflow presentation for any constraints of the values that you can pass to the input parameters.

    For example, an input parameter can have a predefined list of values to choose from.

  4. Instantiate the workflow presentation by making a POST request at the URL of the presentation instances:
    POST https://{vcoHost}:{port}/vco/api/workflows/{workflowID}/presentation/instances/
  5. Provide an execution-context element in the request body to instantiate the presentation.

    You can pass an empty execution-context or pass an execution-context with values only for some of the input parameters.

  6. To pass values to the input parameters in parts, make as many POST or PUT requests as needed at the URL that holds the presentation instance:
    PUT https://{vcoHost}:{port}/vco/api/workflows/{workflowID}/presentation/instances/{executionID}/
  7. Review the response body of the POST or PUT request that you made.

    If the values that you passed to the input parameters are valid, you find a valid="true" attribute in the execution tag. If the presentation is valid, you can take the values that are listed in the out-parameters element of the response, and pass them as values to the input parameters when you run the workflow.

  8. If the values for the input parameters are valid, run the workflow by making a POST request at the URL that holds the workflow executions:
    POST https://{vcoHost}:{port}/vco/api/workflows/{workflowID}/executions/
  9. Provide the valid values to the input parameters of the workflow in an execution-context element.

Run the Send Hello Workflow by Validating Its Input Parameters

You can run the Send Hello workflow by validating its input parameters against the definitions of its presentation.

  1. Make a GET request at the URL that holds the definition of the Send Hello workflow:

    GET https://localhost:8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/

    You receive the workflow definition in the response body of the request:

    <xml version="1.0" encoding="UTF-8" standalone="yes">
    <workflow xmlns="http://www.vmware.com/vco" customized-icon="false"
       href="https://localhost:8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/">
       <relations>
          <link rel="up"
              href="https://localhost:8281/vco/api/inventory/System/Workflows/Samples/HelloWorld/" />
          <link rel="add"
              href="https://localhost:8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/executions/" />
          <link rel="down"
              href="https://localhost:8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/executions/" />
          <link rel="down"
              href="https://localhost:8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/presentation/" />
          <link rel="down"
      	       href="https://localhost:8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/tasks/" />
          <link rel="down"
              href="https://localhost:8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/icon/" />
       </relations>
       <input-parameters>
          <parameter name="name" type="string" />
       </input-parameters>
       <output-parameters>
          <parameter name="message" type="string" />
       </output-parameters>
       <name>Send Hello</name>
    	  <description></description>
    </workflow>
  2. Make a GET request at the URL that holds the definition of the workflow presentation:

    GET https://localhost:8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/presentation/
  3. Make a POST request at the URL that holds the execution instances of the workflow presentation:

    POST https://localhost:8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/presentation/instances/ 

    Provide an empty execution-context so that just to instantiate the presentation without providing any values for the input parameters:

    <execution-context xmlns="http://www.vmware.com/vco"/>

    The response body contains error messages attached to every field, indicating that the values for the input parameters are invalid.

    .......
    <fields>
      <field type="string" hidden="false" id="name">
        <display-name>name</display-name>
        <description>name</description>
        <messages>
           <message severity="ERROR" code="VCO-CNS0002">
              <Summary>
                    The minimum number of characters allowed for this field is 3.0
              </Summary>
           </message>
        </messages>
        <constraints>
           <number-range max="15.0" min="3.0" />
        </constraints>
    .......
  4. Make a POST request at the URL that holds the particular presentation instance:

    POST https://localhost:8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/presentation/instances/888080808080808080808080808080803F8080800132145338690643f66a027ec/

    In the request body, provide values for the input parameters:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
     <execution-context xmlns="http://www.vmware.com/vco">
      <parameters>
        <parameter name="name" type="string">
          <string>John Smith</string>
        </parameter>
      </parameters>
    </execution-context>

    In the response body of the request, you can check whether the values of the input parameters are valid:

    <execution started-by="vcoadmin" .... valid="true".....>
  5. If the presentation is valid, run the workflow by making a POST request at the URL that holds the workflow executions:

    POST https://localhost:8281/vco/api/workflows/CF808080808080808080808080808080DA808080013086668236014a0614d16e1/executions/

    In the request body, pass values to the input parameters of the workflow. Use the same values that are returned as output parameters of the workflow presentation, or directly use the request body of the last POST request that you made to the workflow presentation.