Discover a REST service from a local OpenAPI
2.0 specification (formerly known as Swagger) and generate an external
service based on the discovered REST service. You can then use the
external service in a service flow to invoke the REST service.
For
examples of external services that you can integrate, see
Overview: Integrating external services.
Before you begin
You must have a file with a valid OpenAPI 2.0 specification
that is locally available on your computer. The OpenAPI format can
be either JSON or YAML. To verify that your OpenAPI specification
is valid, open the file in an OpenAPI editor or a Swagger editor.
About this task
To use a REST service in Process Designer, you
discover the service and select the operations that you want to use.
Then, set the server that contains the configuration properties that
are required to invoke the service. An external service is generated
containing the operations that you selected in the discovered service
and a reference to the server that you selected. Business objects
are also generated based on the OpenAPI specification.
Service
providers update their services periodically, and you might want to
rediscover the updated service so that you can use it. When you discover
a service, if an external service discovered from the same file already
exists in Process Designer,
you can either overwrite the existing service or create a new one.
To get the updated version of the REST service, replace the external
service. If you have a service task for the external service, their
operations and data mappings are preserved, unless the operation or
data is not included in the new version. If the server connection
information is unchanged, you can keep the reference to the server
information.
Procedure
To discover an existing REST service with an OpenAPI
specification and generate an external service that you can use in
a service flow, complete the following steps.
- Create an external service in one of the following ways:
- Beside Services in the library navigation,
click the plus sign (+). Select External Service.
In the New External Service page, choose Java,
REST or Web service.
- In the Service Flow editor, select
a Service task. In the Implementation tab
for the service, click New.
- Select Browse local files (Swagger) and
browse to the file. Click Next.
You
might see one or both of the following:
- A list of operations that are not supported by the tool. These
operations will not be included in the generated external service
and are therefore not available to be invoked in a service task. You
can click View Error to see the reason why
the operation is not supported. To invoke these operations, you must
use JavaScript API. To make these operations available for invocation
by using JavaScript, you must complete the service discovery and generate
an external service. You can view the operations in the source view
of the External Service editor. See Invoking a REST service by using JavaScript.
- A list of operations that have warnings in the OpenAPI specification.
You can view the warnings for each operation. The generated external
service will include a corresponding operation, but you might get
unexpected results when you run the service. After viewing the warning,
if you do not want to include the operation, you can remove it in
the next step.
- Click Next.
- The discovered operations are listed. Select the operations
that you want to include in the external service, and click Next.
- If the OpenAPI specification was already discovered, you
can create a new service or replace the existing one. Click Next.
- Set the server that contains the properties used to invoke
the REST service. Either select an existing server, or create a new
one based on information in the OpenAPI specification. Click Finish.
Results
An external service is created. The operations and their
inputs and outputs are based on the operations that you selected in
the discovered REST service.
- In the Details section, the service name
and its documentation is shown.
- Selecting Binding shows the binding type
of REST and the server. If your server binding
properties change, you can select a different server.
- Selecting Source shows the OpenAPI specification
source in read-only mode. This is useful for viewing the operations
that you want to invoke using JavaScript API.
- In the Data library section, you might
see business objects as a result of generating the REST service. These
business objects are only for the external service and are read-only.
Deleting the external service also deletes these business objects.
After your service is created, you can select it as an
implementation of a service task in a service flow.
Select the operation that you want to use from the operation list
and map the inputs and outputs in the Data Mapping tab.
If you are using JavaScript to invoke your operation, enter your JavaScript
in a script task in a service flow. See Creating a service flow and Invoking a REST service by using JavaScript.
To
catch any errors that might occur in the service, attach a catch all
boundary error event to it, as described in Catching errors by using error boundary events.