The out-of-the-box gRPC trigger in Flogo Enterprise 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.
● Flogo Enterprise 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, Flogo Enterprise 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.
● 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 the trigger during new flow creation
When you create a new flow, you have the option to select gRPC Protobuf which will generate the gRPC trigger. To generate the gRPC Trigger during flow creation:
1. Create a file with your schema and name it with a .proto extension. While creating the file with the schema, consider the limitations in section "Limitations when creating the .proto file".
2. In Flogo Enterprise, open the app details page and click Create.
3. Click gRPC Protobuf and upload your <name>.proto file by either dragging and dropping it or navigating to it using the browse to upload link. Flogo Enterprise validates the file extension. You see a green check mark and the Upload button appears.
4. Click Upload. Flogo Enterprise validates the contents of your schema and if it passes the validation, it creates the flows based on the definitions in your schema file. One flow is created for each method in your schema.
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. On the app details page, hover your mouse cursor over No trigger next to the flow then click Add trigger. Alternatively, 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 Flogo® Enterprise 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 Flogo® Enterprise 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. Flogo Enterprise 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.
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, Flogo Enterprise 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 Flogo Enterprise.
This data type supported in protocol
buffer… …is converted to this JSON data type in Flogo Enterprise
int32 number
int64 number
double number
float number
This data type supported in protocol
buffer… …is converted to this JSON data type in Flogo Enterprise
uint32 number
uint64 number
sint32 number
sint64 number
fixed32 number
fixed64 number
bool boolean
byte string
string string