Overview

The module allows you to execute gRPC calls within microflows.

Documentation

Typical usage scenario

The module allows you to execute gRPC calls within microflows.

Features and limitations

The module provides a Java action to execute gRPC calls and includes all required Java dependencies. The Java action relies on an appropriate gRPC Java client being present in the Mendix project. This gRPC client needs to be generated outside of Studio Pro (e.g., via the protoc command line tool, for details refer to the step-by-step guide below). No additional Java implementations are required.

Step-by-step guide for generating a gRPC Java client

Prerequisites

A .proto file for the gRPC service you want to connect to is available. In this guide we will use a "Hello World" service with the following definition (content of file helloworld.proto):

syntax = "proto3";

option java_multiple_files = true;

option java_package = "helloworldgrpc.implementation.grpc";

option java_outer_classname = "HelloWorldProto";

option objc_class_prefix = "HLW";

package helloworld;

// The greeting service definition.

service Greeter {

// Sends a greeting

    rpc SayHello (HelloRequest) returns (HelloReply) {}

}

// The request message containing the user's name.

message HelloRequest {  

    string name = 1;

}

// The response message containing the greetings

message HelloReply {  

    string message = 1;

}

Steps

1. Download the required tools    
   • protoc (Protobuf compiler, https://mvnrepository.com/artifact/com.google.protobuf/protoc/3.25.1)    
   • Java Plugin for protoc (e.g., protoc-gen-grpc-java-1.59.1-windows-x86_64.exe, https://mvnrepository.com/artifact/io.grpc/protoc-gen-grpc-java/1.59.1 )
2. Execute protoc to generate a Java client from the proto file (paths to protoc, protoc-gen-grpc-java-1.59.1-windows-x86_64.exe and helloworld.proto should be adapted as needed)
   • .\bin\protoc --plugin=protoc-gen-grpc-java-1.59.1-windows-x86_64.exe -I="." --grpc-java_out=.\java\ --java_out=.\java\ "helloworld.proto"
   • It's recomended to set the package name (option java_package = ...) to a sub-package of the Mendix module in which you implement the gRPC calls, e.g. {your Mendix module}.implementation.grpc
3. Copy the generated Java code to the javasource folder in your Mendix project (the copied folder structure needs to match the package hierarchy, as always in Java)
4. In your Mendix project create entities whose attributes match the specified request and reply messages. For our hello world example 2 entities are needed:     
   • An entity "HelloRequest" (can also be named differently) with an attribute "Name" (needs to match the attribute name - ignoring case - and type in the corresponding protobuf message) of type String    
   • An entity "HelloReply" (can also be named differently) with an attribute "Message" (needs to match the attribute name - ignoring case - and type in the corresponding protobuf message) of type String
5. To invoke the remote procedure "SayHello" execute the Java action RPC1ArgTls. The following arguments are required     
   • the entities for the request and reply object    
   • a request object    
   • The fully qualified name of the Java class representing the gRPC service providing the remote procedure to be called. In general, this will be {java_package}.{service name}Grpc (In our example: helloworldgrpc.implementation.grpc.GreeterGrpc)    
   • the remote procedure name (in our example sayHello, as in the proto file, first letter in lowercase)
   • the target location ({host}:{port}) of the gRPC service    
   • If the communication shall be TLS encrypted: set flag TLS to true and, in case the TLS root certificate of the targeted service is not in the standard Java trust store, provide the root certificate (PEM-encoded as a System.FileDocument).