Creating a REST service

Draft comment:
This topic is shared by BAW, CP4BA, CP4BASaaS. Last updated on 2025-03-13 12:15
You can create a REST service that you expose to external systems so that they can access capabilities from a workflow automation.

Procedure

To create the REST service:

  1. Open the designer.
  2. In the library, select Exposed Automation Services > + > REST service.
  3. Name the REST service.
    The REST service editor opens.
  4. Add an operation for each business function that you want to expose. To add an operation, click Add.
    In the operation details, name the operation and specify the service flow or process that provides the implementation for the operation. For the implementation, you can:
    • Create a new service flow or process by clicking New.
    • Select an existing service flow or process by clicking Select.
    For more information about service flows and how to create them, see Creating a service flow. For more information about processes and how to create them, see Creating a process.

    Inputs and outputs can use the simple types that are included with the product, such as String, Integer, Boolean, Decimal, Date, Time or JSONObject, from the System Data toolkit or custom business objects. Types from other system toolkits are not supported.
    Tip: Make sure that there aren't multiple business objects with the same name in the dependency chain of your exposed REST automation service and its interface.
    Note: Only ASCII characters are allowed in the following:
    • The name of an operation
    • The names of the business objects that are referenced by the inputs or outputs of the automation service implementation (for example, service flow and process)
    Rationale: From the exposed REST automation service definition, a valid OpenAPI definition is generated that adheres to the respective specifications.
    After you edit the REST service, click Save or Finish Editing.
  5. Optional: For consumers other than automation service consumers:

    To develop an external client, see the OpenAPI definition for the REST service as it exists and is available in the development environment, by clicking the OpenAPI definition URL in the Behavior section of the REST service editor.

Results

To invoke a REST service, the appropriate snapshot must be activated.

In the development environment, the REST service on the tip or the default track can be invoked directly. Make sure to make the track the default to open the OpenAPI definition URL in REST service directly.

In a test, staging, or production runtime environment, the consumer can either invoke the REST automation service from the default snapshot or consume the REST automation service from a dedicated snapshot.

You can get the OpenAPI definition for your REST service in a runtime environment from the following URL: 
http://host_name[:port]/[custom_prefix/]automationservices/rest/process_app_acronym/[snapshot_acronym/]rest_service_name/docs
where:
  • host_name is the host name.
  • port is the optional port number.
  • custom_prefix is an optional custom prefix
  • process_app_acronym is the acronym of the process app
  • snapshot_acronym is the optional snapshot acronym that, if not specified, resolves to either the tip of the default branch in the development environment, or to the default snapshot in a runtime environment.
  • rest_service_name is the name of the REST service.

Basic authentication works for service accounts and LDAP users managed by IBM Cloud Pak® for Business Automation or Identity Manager/Zen; it does not work for users managed by Okta. Zen API key authentication works for all user types. See Authorizing HTTP requests by using the Zen API key for more information.

For basic authentication, the user or service accounts should be registered in Cloud Pak for Business Automation.

Note: The capability that you exposed here as a REST automation service can be published, and then consumed by applications and automations in Business Automation Studio.
Note: Advanced Properties and Advanced Parameter Properties defined for Business Objects used in REST Services are neither included in the OpenAPI specification nor validated at runtime.
Tip:
If you use Workflow Process Service, you can find the endpoint of the Workflow Process Service in the status field of the custom resource file. To determine the URL of the REST service:
  1. Execute the command:
    oc get wfps wfps-instance1 -o yaml
  2. In the endpoints section, locate the URI of the external Workflow Process Service, for example:
        - name: External Base URL
      scope: External
      type: https
      uri: https://cpd-wfps3.apps.fjk-ocp474.cp.example.com/wfps-instance1-wfps
  3. The URL of your REST service has the following structure:
    http://host_name:port/[custom_prefix/]automationservices/rest/process_app_acronym/[snapshot_acronym/]rest_service_name/docs{}
    Where, https://host_name:port/[custom_prefix/] is your uri value from the previous step, process_app_name is the name of the process application, snapshot_name is the optional name of the snapshot, and rest_service_name is the name of the REST service.
Workflow automation services can expose both synchronous and asynchronous operations:
  • Synchronous operations are of short-running nature, and are implemented by service flows. In the OpenAPI definition, you can see the inputs and outputs in their REST operation.
  • Asynchronous operations are typically of a long-running nature, and are implemented by processes. In the OpenAPI definition, you can see the inputs in their REST operation, and the outputs are provided through callbacks. For more information, see Response handling for asynchronous operations.