Let’s have a look at the structure of the Petstore connector first.
The Java connectors for the flowground platform are built by Gradle and so have a typical structure of a Gradle project. Each connector has a build.gradle (1) file used to configure Gradle project, dependencies, plugins, etc. Your build file can be a regular Gradle build file. We only require you to define the following dependency:
Sailor is the Java SDK for the flowground platform. It makes your connector a citizen of the flowground platform by providing you a simple programming model for connectors and ensuring a smooth communication with the platform.
Java connectors are always built with Gradle Wrapper in order to make sure that we build your connector with the same version of Gradle as you did. That’s why you are required to add Gradle wrapper (3), (4) and (5) to your project and commit it to Git.
If you have a logo for the connector, you can place the file called
logo.png (5) in the root directory of the connector. Typically the logo of the API vendor gets used as connector logo. If you did not provide any logo, the connector will show a generic logo for your connector.
src/main/java (8) is predefined directory Gradle expects your Java sources to be located in and the schemas (7) directory is the location of JSON schemas defining the connector’s metatada which we will cover later in this article.
Last but not least the
component.json file (2) is the connector descriptor interpreted by the platform to gather all the required information to be presented to the user in the platform UI. For example, you can define simple things like connector’s title in the connector descriptor but also the connector’s authentication mechanism. The descriptor is the only place to list the functionality provided by the connector, the so called
As mentioned above the
component.json file is the connector descriptor interpreted by the platform to gather all the required information about the connector. Let’s explore the descriptor of the Petstore connector:
The connector descriptor above defines the connector title (1) and description (2). It also defines the fields used to ask the user to provide input for authentication (3). In this case a single field is define in which the user will input the API key for the Petstore API so that the connector can communicate with the API on user’s behalf. The property
verifier (4) is used to define an implementation of the
io.elastic.api.CredentialsVerifier interface which will be invoked by the platform when a user credential, such as an API key, needs to be verified before storing it in the platform.
triggers (5) and
actions (6) properties are used to define the connector’s triggers and actions.
Now let’s have a closer look on how to define
triggers. The example below demonstrates the triggers section from the
component.json connector descriptor file.
The example above demonstrates that the trigger with id
getPetsByStatus (1) is implemented by the
GetPetsByStatus class (2). The trigger is of
polling type (3) meaning it will wake up periodically to poll for changes in the Petstore API. The triggers can be configured with some fields (4) and defines out-metadata in the file
As mentioned above you can configure a credentials verifying in the connector’s descriptor. In the Petstore connector the verifier is implemented in the
io.elastic.petstore.ApiKeyVerifier class, shown below:
ApiKeyVerifier class above is an implementation of the i
o.elastic.api.CredentialsVerifier interface (1) which defines the method
verify (2). This method takes a J
sonObject which represents the connector’s configuration and may throw an
InvalidCredentialsException exception. The connector’s configuration holds the values user input into the credentials fields defined in
component.json (see above). The verification above is implemented by sending a simple request to the Petstore API (3). If the request succeeds, the
verify method’s execution completes successfully and the credentials as assumed to be valid. Otherwise an
InvalidCredentialsException is thrown to signal the platform that the provided credentials (API key) is invalid. An error will be displayed to the user.
Implementing a trigger
Any integration flow starts with a trigger which is responsible to start the flow’s execution by providing new data to be processed. A trigger might query an API for updates and in case of new changes start the integration flow.
Now let’s have a look at how to implement a trigger defined in the
component.json descriptor above. The following listing demonstrates the
GetPetsByStatus class which is responsible to retrieve pets from the Petstore API by a status. If new pets can be found, the trigger will start the flow to process the new pets.
GetPetsByStatus class is an implementation of the
Module interface (1). This interface specifies the
execute method (2) to implement the trigger’s logic. This method takes an instance of
ExecutionParameters which provides a connector with data required for execution. For example, the connector may retrieve its configuration (3) from these parameters.
The trigger’s author defined a field named
component.json to let the integrator enter a status of pets he is interested in. The value of this field is available to the connector from the configuration (4). Because
status is required, the trigger throws an exception if the value does not exist (5). The value of the
status field is encoded into the request url as a query parameter and the request is sent to the Petstore API (6). The retrieved response is an array of pets, returned as
JsonArray instance. Because flowground platform does not support naked arrays yet, the response is wrapped into an instance of
Message is created (8) and emitted to the platform (9). Please note that you can’t emit pure JSON objects to the platform but always must create a platform message from you payload and emit this message. The emitted message will be passed by the platform to the next step of the integration flow.