Deploying workflows

Edit online

To make workflows accessible from external environments, you can deploy them to API endpoints.

To deploy a workflow, you must associate it with at least one API, stage, and endpoint.
  • APIs are collections of endpoints, which are organized into one or more stages.
  • Stages are parallel versions of an API that you can use for different purposes.
    • For example, if you want to make the same API available in development, QA, and production environments, you might create three stages that are called dev, qa, and prod.
  • Endpoints are subpaths that are appended to API URL paths as unique identifiers.
    • For example, you might create two APIs in the prod stage. The paths for these APIs might be /api-1/prod/foo and /api-1/prod/bar. Within the prod stage, the endpoints, that is, /foo and /bar, uniquely identify the APIs.
To deploy a workflow, complete these steps:
  1. Choose and configure an API.
  2. Create stages.
  3. Create endpoints.
  4. Link the API, a stage, and an endpoint to a workflow and deploy the workflow.

1. Choose and configure an API

Complete these steps:
  1. Open the APIs page.
    1. If you are connected to another application, click Workflows.
    2. In the IBM® Concert Workflows® sidebar, click APIs.
  2. Select or create an API. For more information about creating APIs, see Using APIs. After you create or select the API, the Workflow Deployments section is shown.
  3. Click the Settings section.
  4. Optional: Update the API’s name, description, or worker group.
  5. Optional: Click Authentications and update the APIs authentication policy and settings. If you select API keys authentication, select the API key delivery mechanism (query parameter, authorization header, custom header, or cookie) and specify the required delivery mechanism value.
  6. Optional: Click Network Access Control List (NACL) tab and define rules to control which IP addresses and networks can access the API.
  7. Optional: Click Advanced settings and update the API’s advanced settings, such as the response and message timeouts, and the error status code.
  8. Click Save.

2. Create stages

For each stage that you want to create, complete these steps:
  1. Click the Stages section.
  2. Click Create Stage.
  3. Provide a name for the stage. You can also provide a description.
  4. Optional: Map a stage to a subdomain.
    • If the rna.instance.application_subdomains system parameter is enabled in your instance, the Subdomain field is shown.
    • You can use this field to enter a subdomain that you want to map this API and stage to in the deployed endpoints.
    • If you enter a subdomain, you must use the https://[subdomain].[hostname]/[endpoint subpath] format when you call the endpoints that you deploy for this API and stage. For more information, see Configuring API access via subdomains.
  5. Optional: Define which worker group is used on this stage to run the API.
    1. Click Worker group.
    2. Select Override worker group.
    3. Select the worker group that you want to use on this stage.
  6. Optional: Define an authentication policy for this stage.
    1. Click Authentication.
    2. Select Override authentication.
    3. Define the stage’s authentication policy.
      Table 1. Authentication policy
      Authentication policy Meaning
      IBM Concert Workflows® Only logged-in users can access the API on this stage. You can then choose one of these options:
      • Allow access only to your user, when you are logged in.
      • Allow access to every logged-in user.
      • Allow access only to certain users and roles.
      Anonymous Anyone that has the URL can access the API on this stage.
      API keys

      Anyone that has the URL and a specific API key can access the API. To create a unique API key, click + Add API key.

      To use API key authentication, complete these steps:

      • In the Send API key via field, select one of these authentication mechanisms:
        1. Query parameter (default)
        2. Authorization header
        3. Custom header
        4. Cookie
      • Specify the delivery mechanism value in the adjacent field. The default values are:
        • Query parameter: api_key.
        • Authorization header: ApiKey.
        • Custom header: X-API-Key.
        • Cookie: X-API-KEY.

        You can replace the default identifier (such as query parameter name, authorization header value, custom header name or cookie name) with a custom value. The custom value must match the required format, for example:

        
QUERY_PARAM_NAME: /^[a-z0-9._-]+$/,
API_KEY_HEADER_NAME: /^[A-Za-z0-9-]+$/

        If the identifier value does not match the validation pattern, an error message is displayed.

        A notification displays the selected authentication mechanism and its value.

      • Optional: Click the Learn how to use it link to view examples of how customers must specify the authentication delivery mechanism in their API requests.
      Workflow A separate deployed workflow determines the set of users who can access the API on this stage.
  7. Optional: Define which IP addresses and networks can access the API on this stage.
    1. Click Network Access Control List (NACL).
    2. Select Override network access control list (NACL).
    3. Add or update network access rules for this API and stage.
  8. Optional: Override the default API request logging policy for this stage.
    1. Click Advanced settings.
    2. Select Override enable API request logging.
    3. Update the API request logging policy.
      Note: When you no longer need to log API requests on this stage, clear these fields to ensure that logs are not created unnecessarily.
  9. Click Save.
The stage is shown in the Stages list. You can now perform these tasks:
Delete the stage
In the Actions menu, click Delete. In the dialog, confirm whether you want to delete the stage.
Edit the stage
In the Actions menu, click Edit. You can update the settings that you defined for the stage.
View information about the API in Swagger
In the Actions menu, click Swagger UI. The API definition is not shown because you did not deploy the API yet.

3. Create endpoints

For each endpoint that you want to create, complete these steps:

  1. Click the Endpoints section.
  2. Click Create endpoint.
  3. In the Path field, enter a string that starts with a slash (/). This value is appended to the API’s URL to uniquely identify this API endpoint.
  4. In the Method field, select the HTTP method that you want the endpoint to use, that is, GET, POST, PUT, DELETE, or PATCH.
  5. Optionally, enter a description of the endpoint.
  6. Click Save.

The endpoint is shown in the Endpoints list. You can now perform these tasks:

Delete the endpoint
In the Actions menu, click Delete. In the dialog, confirm whether you want to delete the endpoint.
Edit the endpoint
In the Actions menu, click Edit. You can update the settings that you defined for the endpoint.
Note: When you create an endpoint, it is made available in all stages. For example, if you create an endpoint called test, you can use this endpoint to deploy different workflows on all of your stages. You can deploy one workflow on the /api-1/prod/test path, another on the /api-1/qa/test path, and another on the /api-1/dev/test path.

4. Link the API, a stage, and an endpoint to a workflow and deploy the workflow

Complete these steps:
  1. Click the Workflow Deployments section.
  2. In the Stage field, select the stage that you created.
  3. In the row that contains the endpoint that you created, click the Actions menu.
  4. Click Create. The Deploy workflow page is shown.
  5. In the Workflow field, click the folder and select the workflow that you want to deploy.
  6. In the Workflow version drop-down, select the version of the workflow that you want to use.

    • Select Always use latest version to use the latest saved version of the workflow when you run the workflow from the deployed endpoint.

    • Select Use current version to use the workflow version that is the latest when the deployment is created. This version of the workflow is always used, even if later versions of the workflow are created.

    • Select Use specific version to choose the version that you want to use from the list of saved versions.

  7. Optional: Override the default worker group that is used on this endpoint to run the API.
    1. Select Override worker group.
    2. Select the worker group that you want to use on this endpoint.
  8. Optional: Override the default advanced settings for this endpoint.
    1. Click Advanced settings.
    2. For each setting, select Override and enter a setting that is specific to this endpoint.
  9. Optional: Define the mapping of input variables for the workflow.
    1. Click Input variables mapping.
    2. Select Enable for each variable that you want to override the mapping for.
    3. In the Request part field, select the part of the request that you want to map the variable to when API requests are made to this endpoint. For example, to map the variable as a query parameter in API requests, select Query parameter.
    4. Optional: In the Field name field, enter a custom name that represents the variable in API requests to this endpoint.
  10. Optional: Customize the response policy for this endpoint.
    1. Click Custom Response Configuration.
    2. In the Status Code field, configure the status code of the response to the API request.

      You can enter a number in the range 100-599, select a workflow variable that contains a status code, or enter free text.

    3. In the Body field, configure the body of the response.

      You can select a workflow variable, leave the field empty to return all workflow output, or enter free text.

    4. In the Format field, select the output format of the response.
  11. Click Deploy.
The deployment, that is, the deployed endpoint and its associated workflow, is shown in the Workflow Deployments list. You can now perform these tasks:
Copy the deployment to another stage
In the Actions menu, click Duplicate to stage. In the dialog, select the stage where you want the copied deployment to run and click Duplicate.
Delete the deployment
In the Actions menu, click Delete. In the dialog, confirm whether you want to delete the deployment.
Edit the deployment
In the Actions menu, click Edit. You can update the settings that you defined for the deployment.
Test the deployment
In the row that contains the endpoint, click the folder icon to copy the full deployment URL for the API endpoint. You can test the deployment by pasting this URL into a separate browser tab.
View the API definition for the deployment
To view the deployment’s API definition in Swagger, click Swagger UI.

Direct deployment

You can also deploy workflows by using these alternative methods:
  • Direct deployment in a selected API
  • Direct deployment in the Workflows page
  • Direct deployment in the workflow editor

Direct deployment in a selected API

Complete these steps:
  1. In the IBM Concert Workflows® sidebar, click APIs.
  2. Select an API. The Workflow Deployment section is shown.
  3. Click Create.
  4. In the Deploy Workflow page, select the workflow that you want to deploy.
  5. Select the version of the workflow that you want to deploy.
  6. Select or create the stage and endpoint that you want to associate with the API and workflow.
  7. Optional: Override the default worker group and advanced settings, define the input variable mapping, and customize the endpoint response policy.
  8. Click Deploy. The deployment is shown in the Workflow Deployments list.

Direct deployment in the Workflows page

Complete these steps:
  1. In the IBM Concert Workflows® sidebar, click Workflows.
  2. Select a workflow from the list.
  3. In the Actions menu, click Automate > Deploy. The Deploy Workflow page is shown.
  4. Select the version of the workflow that you want to deploy.
  5. Select or create the API, stage, and endpoint that you want to associate with the workflow.
  6. Optional: Override the default worker group and advanced settings, define the input variable mapping, and customize the endpoint response policy.
  7. Click Deploy. The Workflows page is shown and a tag indicates that the workflow is now deployed.

Direct deployment in the workflow editor

Complete these steps:
  1. In the IBM Concert Workflows® sidebar, click Workflows.
  2. Click the workflow that you want to edit.
  3. In the workflow editor, click Deploy Workflow.
  4. Select the version of the workflow that you want to deploy.
  5. Select the API, stage, and endpoint that you want to associate with the workflow.
  6. Optional: Override the default worker group and advanced settings, define the input variable mapping, and customize the endpoint response policy.
  7. Click Deploy. The workflow is re-opened in the editor.