Using gRPC

The out-of-the-box gRPC trigger in TIBCO Cloud Integration - Flogo (PAYG) uses a .proto file to define one or more services and the various Remote Procedure Calls (methods) under the service. For an understanding of gRPC concepts, refer to the gRPC documentation.

Note:
  • TIBCO Cloud Integration - Flogo (PAYG) gRPC Trigger supports only protocol buffers (.proto) as the Interface Definition Language (IDL) for describing both the service interface and the structure of the payload messages.
  • Currently, TIBCO Cloud Integration - Flogo (PAYG) only supports the proto3 version of the protocol buffer. Refer to the Creating a Flow Attached to a gRPC Trigger section for details on flow and gRPC trigger creation.
  • While creating the .proto file, consider the limitations in section "Limitations when creating the .proto file".
  • You must not use the same gRPC .proto file for a gRPC trigger and gRPC activities in the same app. The package names for the gRPC trigger and gRPC activities must be unique.
  • The gRPC trigger and gRPC activity does not support options in the .proto file. If your .proto file contains any options, be sure to remove the options in .proto file before using it.

Creating a new gRPC trigger

To create a new gRPC trigger, follow these steps:
  1. Open the app details page.
  2. Click Create. The Add triggers and flows dialog opens.
  3. Under Create new, select Trigger.
  4. Select the gRPC Trigger card.
  5. Follow the on screen prompts to configure the trigger. See the section, "gRPC Trigger", in the Activities and Triggers Guide for details on configuring the trigger.
  6. Click Create. The new gRPC trigger gets created with a placeholder for a flow attached to it.

To implement a single method in your .proto file

You can implement only a single method from your .proto file. To do so, follow these steps:
  1. In TIBCO Cloud Integration - Flogo (PAYG), open the Apps page and click Create.
  2. In the Add triggers and flows dialog, click Flow under the Create new.
  3. Enter a name for the flow in the Name text box. Optionally, enter a description for the flow in the Description text box.
  4. Click Create.
  5. Select Start with a trigger.
  6. In the Triggers catalog, select the gRPC Trigger card.
  7. Follow the on screen prompts to configure the trigger. See the section, "gRPC Trigger", in the Activities and Triggers Guide for details on configuring the trigger. A flow with the name you specified gets created and attached to the newly created gRPC trigger.

To implement all methods defined in your .proto file

You can generate the gRPC trigger along with implementing one flow per method defined in your .proto file. The flows will all be attached to the same trigger. To do so follow these steps:
  1. In the app details page, click Create. The Add triggers and flows dialog opens.
  2. Select Flow under Create new.
  3. Click gRPC Protobuf under Start with.
  4. Click gRPC Protobuf and upload your <name>.proto file by either dragging and dropping it to the Add triggers and flows dialog or navigating to it using the browse to upload link. TIBCO Cloud Integration - Flogo (PAYG) validates the file extension. You see a green check mark and the Upload button appears.
  5. Click Upload. TIBCO Cloud Integration - Flogo (PAYG) validates the contents of your schema and if it passes the validation, it creates the flows based on the methods defined in your schema file. One flow is created for each method in your schema. All the flows are attached the same trigger.

Manually adding an existing flow to the trigger

If you have an existing flow, you can manually add a gRPC trigger to the flow. To do so:
  1. Open the flow details page by clicking on the flow name.
  2. Click the icon to the left of your flow.

    You have the option to either select an existing gRPC trigger that is used in another flow in the same app or you can create a new gRPC trigger and attach this flow to the new trigger.

    • To select an existing gRPC trigger already used in the app, click gRPC Trigger. The Port field is disabled, as this trigger is already in use by other flows. Refer to the "gRPC Trigger" section in the TIBCO Cloud™ Integration - Flogo® (PAYG) Activities and Triggers Guide for details on the other fields.
    • To create a new gRPC trigger and attach the flow to it, click Select New and click on the gRPC Trigger from the Triggers catalog. Refer to the "gRPC Trigger" section in the TIBCO Cloud™ Integration - Flogo® (PAYG) Activities and Triggers Guide for details on the other fields.
  3. Click Finish.

Limitations when creating the .proto file

The following are limitations you must adhere to when creating your .proto file:
  • Currently, importing a .proto file into another .proto is not supported. Hence, you cannot use import statements in a .proto file.
  • Streaming is not supported in either the request or the response.
  • Since import statements are not supported in .proto files, you cannot use data types that need to be imported from other .proto files, such as google.protobuf.Timestamp and google.protobuf.Any.
  • Cyclic dependency in request or response messages is not supported.
  • Setting a default value to a blank field within a message is not supported.
  • Maps for data definition are not supported.
  • Oneof - gRPC mandates that you enter a value for only one field. TIBCO Cloud Integration - Flogo (PAYG) considers all fields optional in order to allow you to select any field and enter a value for it. If you enter a value for multiple fields, only the value you entered for the last field displayed will be accepted and the remaining field values above it will be ignored.

Building the App Binary for an App Containing gRPC Trigger from the CLI

To build an app that contains a gRPC trigger from the CLI:
  1. Install protoc and protoc-gen-go library.
    Note: The minimum supported versions are:

    protoc 3.8.0

    protoc-gen-go 1.3.2

    Refer to the gRPC.io documentation for details on installing the libraries.

  2. Make sure the two libraries are included in your system PATH.
  3. Build the app binary. For more information, refer to Building the App.

Conversion of Data Types in Protocol Buffer to JSON Data Types

JSON does not support all data types supported in protobuf. Hence, TIBCO Cloud Integration - Flogo (PAYG) converts some of the data types to an equivalent data type in JSON. Here is a list of data types supported by protobuf and their representation in TIBCO Cloud Integration - Flogo (PAYG).

This data type supported in protocol buffer… …is converted to this JSON data type in TIBCO Cloud Integration - Flogo (PAYG)
int32 number
int64 number
double number
float number
uint32 number
uint64 number
sint32 number
sint64 number
fixed32 number
fixed64 number
bool boolean
byte string
string string
Related tasks