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.
● In Flogo Enterprise, the 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.
● 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 do 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.
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 Flogo Enterprise, 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. On 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. Flogo Enterprise validates the file extension. You see a green check mark and the Upload button appears.
5. Click Upload. Flogo Enterprise 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 to the same trigger.
Manually adding an existing flow to the trigger
If you have an existing flow, you can manually add the flow to a gRPC trigger. 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 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 Add new trigger 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
You must adhere to the following limitations when creating your .proto file:
● Currently, importing a .proto file into another .proto file 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 libraries.
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
This data type supported in protocol
buffer… …is converted to this JSON data type in Flogo Enterprise
int64 number
This section discusses how to create app properties, which you can use when populating field values. It also describes how to create a schema that can be reused in your app.
App Properties
App properties provide a way to override property values included in the app binary. You can configure some supported fields with app properties when configuring triggers and activities. Connection-related app properties cannot be used for configuration anywhere within an app. Their only purpose is to allow you to change a connection value if need be during runtime. Configuration fields in your flow that require their values to be changed when the app goes from a testing stage to production are best configured using app properties instead of hard coding their values. App properties for triggers and activities reside within the app. App properties for connections are not modifiable from the App Properties dialog in the app.
The URL field in an activity is a good example of a field for which you would want different values – maybe an internal URL when testing the app and an external URL when the app goes into production. You may want the URL used in the activity to change when the app goes from a test environment to production.
In such a case, it is best to configure the URL field in the activity with an app property instead of
hardcoding the URL. This way, you can change the URL by changing the value of the app property used to configure the URL field.
Before building the app, you can change the default value of an app property from the App Properties dialog. Once you have built the app and have the app binary, use the CLI to change the value of an app property in the app.