Chapter 3. Creating a Fuse Online integration that is triggered by an API call

Procedure

1. In Fuse Online, in the left navigation panel, click Integrations.
2. Click Create Integration.
3. On the Choose a connection page, click API Provider.

4. On the Start integration with an API call page:

   • If you have an OpenAPI document that defines the REST API operations, upload the OpenAPI document.
   • If you need to define the OpenAPI document, select Create a new OpenAPI 3.x document or Create a new OpenAPI 2.x document.

5. Click Next.

   • If you uploaded a document, review or edit it:

     1. Click Review/Edit to open the API Designer editor.

     2. Review and edit as needed.

        Optionally, if your document uses the OpenAPI 2 specification, you can click Convert to OpenAPI 3 if you want the API Designer to convert your document to conform with the OpenAPI 3 specification.

     3. In the upper right, click Save or Cancel to close the editor.
     4. Click Next.

   • If you are creating a document, then in the API Designer editor that Fuse Online opens:

     1. Define the OpenAPI document as described in Creating a REST API definition in API Designer.
     2. In the upper right, click Save, which closes the editor.
     3. Click Next.

Procedure

1. In the Operations list page, for the operation whose flow you want to define, click Create flow.

2. For each connection that you want to add to this flow:

   1. In the flow visualization, click the plus sign to add a connection at that location.
   2. Click the connection that you want to add.
   3. Select the action that you want this connection to perform.
   4. Configure the action by entering data in the labeled fields.
   5. Click Next.

   Add all desired connections to the flow before you continue.

3. In this operation flow, to process data between connections:

   1. In the flow visualization, click the plus sign where you want to add a step.
   2. Click the step that you want to add.
   3. Configure the step by entering data in the labeled fields.

   4. Click Next.

      For help, see Adding steps between connections.

   If you want to add another step that processes data between connections, repeat this subset of instructions.

4. Map data to fields in the next connection:

   1. In the flow visualization, check for data type mismatch icons, which indicate that the connection cannot process the incoming data. You need to add a data mapper step here.

   2. For each data mismatch icon in the flow visualization:

      1. Click the plus sign that is just before that step.
      2. Click Data Mapper.
      3. Define the needed mappings. For help, see Mapping integration data to fields in the next connection.
      4. Click Done to add the data mapper step to the flow.

5. In the flow visualization, on the Provided API Return Path step, click Configure.

   Every API provider integration finishes each operation flow by sending a response to the REST API caller that triggered execution of the operation flow. The response contains one of the return codes that you configure for the Provided API Return Path step that finishes the operation’s flow. Configure the return path step as follows:

   1. Under Default Response, in the Return Code field, accept the default response that Fuse Online displays, or click the down caret and scroll to select the default response that you want. The flow sends this response when execution of the operation flow does not return any of the configured error responses. Typically, the default response return code indicates a successful operation.

   2. Under Error Handling, indicate whether you want to include the error message in the body of the returned message.

      During development, you typically want to return the error message. In production, however, you might want to hide the error message if it contains sensitive or proprietary information. The error message is a JSON formatted string that contains responseCode, category, message, and error elements, for example:

         {
            responseCode: 404,
            category:  "ENTITY_NOT_FOUND_ERROR",
            message: "SQL SELECT did not SELECT any records"
            error: SYNDESIS_CONNECTION_ERROR
          }

      Note that during development, the most reliable way to know that an error happened is to check the HTTP_RESPONSE STATUS header in the response to the caller. You can also check the integration pod’s log for INFO messages. The integration’s Activity log shows a successful exchange and errors are not always visible in the Activity log.

   3. Under Error Response Codes, Fuse Online displays an entry for each error that a connection in the flow might return. For each error, accept the 200 All is good default return code or click to select another HTTP status return code.

      The return codes that you can select from, are the return codes that the OpenAPI document defines for the operation that this flow executes. If Fuse Online does not display a return code that you need, you can edit the OpenAPI document to add it.

      To do this, in the upper right, click View/Edit API Definition. Edit the OpenAPI document as needed. When you are done, save the OpenAPI document. Fuse Online returns to editing the Provided API Return Path and reflects any changes that you saved.

   4. Click Next to complete configuration of the return path.

6. When this flow has all needed connections and steps and there are no data mismatch icons, or when you no longer want to edit the flow for now, do one of the following:

   • Publish — To start running the integration, in the upper right, click Publish. This builds the integration, deploys the REST API service to OpenShift, and makes the integration available to be executed. You can publish the integration each time that you complete the creation of an operation’s flow or each time that you edit an operation’s flow.
   • Save — To display the list of operations, in the upper right, click Save.