Creating a REST service

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, or Time, 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.

These REST services can be called by all authenticated users by using basic authentication or Zen API key authentication. See Authorizing HTTP requests by using the Zen API key for more information.

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.
Tip:
If you use IBM 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.