User's Guide
Version 2.13.0 May 2021
Contents
Contents
2
Introduction
6
Concepts 6
Flogo Enterprise Version 7
Creating Your First REST API 8
App Development
43
Creating and Managing a Flogo App in the Web UI 43
Creating an App 43
Editing an App 45
Renaming an App 45
Editing the Version of an App 46
Using App Tags 46
Switching Between Display Views on the App Page 49
Deleting an App 51
Exporting and Importing an App 51
App File Persistence 61
Creating Flows and Triggers 64
Flows 64
Triggers 104
Synchronizing Schema Between Trigger and Flow 105
Data Mappings 105
Data Mappings Interface 105
Scopes in Data Mappings 108
Reserved Keywords to be Avoided in Schemas 109
Mapping Different Types of Data 111
Using Functions 146
Supported Operators 149
Developing APIs 150
Using an OpenAPI Specification 150
Using GraphQL Schema 156
Using gRPC 159
Using App Properties and Schemas 163
App Properties 164
App Schemas 178
Using Connectors 182
Creating Connections 183
Editing Connections 183
Deleting Connections 183
Using Extensions 184
Important Considerations 185
Uploading Extensions 186
Pulling Extensions from an Open Source Public Git Repository 189 Adding Custom Golang Code or Dependencies to the App 190
Deleting Extensions or Extension Categories 193
Flow Tester 193
Testing Flows from the UI 194
Testing Flows from the CLI 208
Using the test command to test your flow from the CLI 209
Deployment and Configuration
213
Building an App Binary 213
Building the App 213
Building a Generic Flogo Enterprise Engine Binary 219
Environment Variables 220
App Configuration Management 223
Consul 223
AWS Systems Manager Parameter Store 229
Environment Variables 235
Encrypting Password Values 238
Container Deployments 239
Kubernetes 239
Amazon Elastic Container Service (ECS) and Fargate 247
Pivotal Cloud Foundry 248
Microsoft Azure Container Instances 253
Google Cloud Run 257
Red Hat OpenShift 260
Developing for Lambda 264
Creating a Connection with the AWS Connector 265
Creating a Flow with Receive Lambda Invocation Trigger 266 Creating a Flow with AWS API Gateway Lambda Trigger 270 Creating a Flow with S3 Bucket Event Lambda Trigger 272
S3 Bucket Event Lambda Trigger 274
Pushing Apps to TIBCO Cloud 276
Monitoring
278
About the TIBCO Flogo® Enterprise Monitoring App 278
Using the Flogo Enterprise Monitoring App 279
Running Flogo Enterprise Monitoring as a Standalone App 279 Running the Flogo Enterprise Monitoring App on Docker 280 Running the Flogo Enterprise Monitoring Application on Kubernetes 282
Configuring the Flogo Enterprise Monitoring App 286
Registering a Flogo App with the Flogo Enterprise Monitoring App 288
Viewing Statistics of Apps 290
App Metrics 295
Enabling App Metrics 297
Enabling statistics collection using environment variables 297
Logging App Metrics 298
Fields returned in the response 299
Prometheus 300
Distributed Tracing 307
Tracing Apps Using Jaeger 308
Tracing Apps by Using AWS X-Ray 311
Using APIs 313
Healthcheck API 313
Go Language Runtime Statistics and Profiling 314
CPU and Memory Profiling 315
Best Practices in Flogo Enterprise
318
Performance Tuning
323
Tuning Environment Variables 323
FLOGO_RUNNER_TYPE 323
FLOGO_LOG_LEVEL 329
GOGC 331
CPU and Memory Monitoring 333
Top Command 333
Docker Stats Command 334
Runtime Statistics and Profiling 334
Samples
335
TIBCO Documentation and Support Services
336
Legal and Third-Party Notices
338
Introduction
TIBCO Flogo® Enterprise is an open-core product based on Project Flogo™, an open source ecosystem for event-driven apps. Its ultra-light app engine offers you the flexibility to deploy your Flogo apps in containers, as Serverless functions, or as static binaries on IoT edge devices. The developer-centric web-based UI of Flogo® Enterprise enables you to quickly implement use cases such as microservices, Serverless functions, event-driven apps, integrations, and APIs.
Concepts
This section describes the main concepts used in the Flogo Enterprise environment.
Apps
Flogo apps are developed as event-driven apps using triggers and actions and contain the logic to process incoming events. A Flogo app consists of one or more triggers and one or more flows.
Trigger
Triggers receive events from external sources such as Kafka, Salesforce, GraphQL and so on. Handlers residing in the triggers, dispatch events to flows. Flogo Enterprise provides a set of out-of-the-box triggers as well as a range of connectors for receiving events from a variety of external systems.
Flow
The flow allows you to implement the business logic as a process. You can visually design and test the flows using the Web UI. A flow can consist of one or more activities that perform a specific task. Activities are linked in order to facilitate flow of data between them and can contain conditional logic for branching. Each flow is also connected to a default error handler. A Flogo app can have one or more flows. A flow can be activated by one or more Triggers within the app.
Activity
Activities perform specific tasks within the flow. A flow typically contains multiple activities.
How Flogo Enterprise Works
The trigger consists of one or more handlers that serve as the means of communication between the trigger and the flow. When the trigger receives an event, the trigger uses the respective flow handlers to pass the data from the event on to the flow in the form of flow input. The business logic in the flow then can use the event data coming in through the flow input. When the trigger expects a reply from the flow, the data from the flow is passed on to the trigger in the form of flow output. A flow can contain one or more conditional branches.
In a nutshell, to use Flogo Enterprise:
1. Create an app.
2. Create a flow in your app.
3. Add one or more activities to the flow and configure them.
4. Optionally, add a trigger to your flow. You can add one or more triggers to a flow as and when you need them.
5. Build your app.
Flogo Enterprise Version
The Flogo Enterprise version number of your current installation can be obtained from two locations:
l In the Flogo Enterprise product footprint from where you start the Web UI - the folder name in which the /bin folder resides.
l The Flogo Enterprise banner which appears in the command prompt window or the terminal window once the Web UI starts.
Creating Your First REST API
Tip: If you prefer a video of the Creating your First REST API tutorial, visit https://youtu.be/tAvUz-zwVJM.
This tutorial walks you through the steps to build a simple app with a REST service in Flogo Enterprise. It shows how to create a basic app that returns the booking details of a specific customer based on a query sent to the app. In this tutorial, the query sent to the app checks whether the passenger's last name is "Jones" and the app then returns the booking details.
For the sake of this tutorial, the sample data used is: a passenger whose last name is
“Jones” flies by the Business class. All other customers fly by the Economy class.
Overall Structure of the App This app contains:
l ReceiveHTTPMessage trigger: This trigger listens for a HTTP GET request containing the last name of the passenger requesting for flight booking details. Once it receives a request, it triggers the flow attached to the trigger.
l FlightBookings flow: This flow is attached to the ReceiveHTTPMessage trigger. This flow handles the business logic of the app. In this flow, you must configure a
LogMessage activity to log a custom message when a request is received successfully. The LogMessage activity has two success branches:
o The first branch (the one with the Return activity in the following screenshot) accepts requests with any last name and uses a condition to check if the last name in the request is "Jones". It executes a Return activity to return the information of a flight booked in Business class for Jones.
o The second branch (the one with the Return1 activity in the following screenshot) is executed when the first branch executes as false (that is, the last name is not
"Jones"). It executes a Return1 activity to return the information of a flight
booked in Economy class if the last name is not “Jones”.
Note: Each branch must have its own Return activity as the last activity in the branch.
High-Level Steps in the Tutorial
The high-level steps for creating and configuring the app in this tutorial are as follows:
1. Create a new app
2. Create a JSON schema to reuse it across your app. The JSON schema describes the format of the JSON data used in the tutorial. In this tutorial, we use a simple JSON schema for the request that the REST service receives and the response that the service sends back. You can specify the JSON schema directly or specify JSON data which is converted to JSON schema automatically.
3. Create a flow and add a REST trigger (Receive HTTP Message)
4. Map trigger output to flow input. This is the bridge between the trigger and the flow where the trigger passes on the request data to the flow input.
5. Map flow output to trigger reply. This is the bridge between the flow output and the response that the trigger sends back to the HTTP request it received. After the flow has finished executing, the output of the flow execution is passed back to the trigger by the Return activity. Hence, we map the flow output to the trigger reply. This mapping is done in the trigger configuration.
6. Add a LogMessage activity to the flow and configure a message that the activity must log in the logs for the app as soon as it receives a request.
7. Add the first branch to check whether the passenger’s last name is Jones to return the information of a flight booked in Business class for Jones.
8. Add a second branch to process any other passengers and return the information of a flight booked in Economy class if the last name is not “Jones”.
9. Validate the app to ensure that there are no errors or warnings in any flows or activities.
10. Build the app 11. Test the app
Step 1: Create a new app
Tip: To watch this step in the video tutorial, click
To create a new Flogo app in Flogo Enterprise:
1. Click Apps.
If this is your first app, a blank screen appears suggesting that you need to create or import a new app. If you have already created apps earlier, the apps are displayed on this screen.
2. Click Create/Import app.
Flogo Enterprise creates an app with a default name in the New_Flogo_App_
<sequential_app_number> format.
3. Click the default app name to make it editable. Change the app name to FlightApp
and click anywhere outside the name to save the changes made to the name.
Step 2: Create a JSON schema to reuse it across your app Tip: To watch this step in the video tutorial, click
1. Copy the following JSON sample to use it in your app:
{
"Class" : "string",
"Cost" : 0,
"DepartureDate" : "2017-05-27",
"DeparturePoint" : "string",
"Destination" : "string",
"FirstName" : "string",
"Id" : 0,
"LastName" : "string"
}
Note: Ensure you use straight quotes when entering the schema elements and values.
2. On the Apps page, in the Flows section, click Schemas.
3. In the Schemas dialog box that opens, click Schema to add a new JSON schema.
4. Name your schema as FlightResponse and paste the copied schema into the text editor. Alternatively, if you enter JSON data in the editor, the JSON data is
automatically converted to JSON schema.
5. Click Save.
Step 3: Create a flow and add a REST trigger (Receive HTTP Message) Tip: To watch this step in the video tutorial, click
Every app must have at least one flow and, in most cases, a trigger that initiates the flow.
Create a new flow with the REST trigger. The ReceiveHTTPMessage REST trigger listens for an incoming REST request that contains the details of a passenger who wants to book a flight. Specify the fields for the request in the REST trigger in JSON schema format.
To create a flow:
1. On the Flows page, click Create .
The Add triggers and flows dialog box is displayed. The Flow option is selected by default.
2. In the Flow details section, provide the following details and click Create:
Name: FlightBookings
Description : Optional description of the flow
3. In the dialog box that appears, click Start with a trigger.
4. In the Triggers catalog, click Receive HTTP Message.
5. In the Configure trigger: ReceiveHTTPMessage dialog box:
a. Select GET as the Method.
b. Enter /flightbookings in the Resource path box.
c. Enable the Use App Level Schema toggle next to Response Schema to open the Schemas dialog box and select the FlightResponse schema you defined earlier.
The schema you select automatically appears in the Response Schema box.
d. Click Continue.
6. Select Copy Schema when prompted as shown in the following image.
The schema that you entered when creating the trigger is automatically copied to the Flow Inputs & Outputs tab to match the input and output of the trigger.
A new flow is created and attached to a REST trigger.
Your flow should look similar to the following:
7. Collapse the Flow Inputs & Outputs tab.
Step 4: Map trigger output to flow input
Tip: To watch this step in the video tutorial, click
When Flogo Enterprise receives a request from a passenger (a REST request), the data from the request is output by the ReceiveHTTPMessage REST trigger. For the request to be processed, this output must be used by the flow in the form of flow input. Hence, you must map the trigger output to the flow input.
To do this:
1. Click the REST trigger icon to open its configuration dialog box.
In the configuration dialog box, multiple tabs are displayed in a column on the left.
Trigger Settings is selected by default.
2. Click Output Settings to add the query parameter.
3. Click Add row to add a new query parameter.
4. In the new row that appears in the Query Parameters table, enter the value of
ParameterName as lastname and click Save in the same row (in the Action column).
5. To start the mapping, click the Map to Flow Inputs tab and configure the mapping of the trigger output. On the Map to Flow Inputs tab, the Flow Input section is displayed. This is the list of flow inputs that can be mapped to the trigger outputs.
Only headers are displayed in the flow inputs. The new query parameter is not visible yet.
6. Click Sync to display the new values. Now, queryParams should appear in the Flow Input column.
7. In the Flow Input section, click headers.
The headers box on the right of Flow Input appears empty to begin with.
8. Map the trigger output headers to the flow input header:
a. Expand $trigger to see all the trigger outputs available.
This displays the headers and body.
b. To map the Trigger Output headers to the Flow Input headers, in the Trigger Output section, click $trigger and then click headers.
The box should now display $trigger.headers. This indicates that you have successfully mapped the trigger output headers to the flow input header.
9. To map the flow input, in the Flow Input section, click queryParams .
The data mapper view is the same as the one while mapping headers. The queryParams text editor appears empty to begin with.
10. To map the flow input queryParams with the trigger output queryParams, in the Trigger Output section, click $trigger and then click queryParams.
The box should now display $trigger.queryParams. This indicates that you have successfully mapped the trigger output queryParams to the flow input
queryParams.
11. Click Save to save your progress.
This completes the mapping of flow inputs.
Step 5: Map flow output to trigger reply
Tip: To watch this step in the video tutorial, click
When the execution of the flow is completed, the output must be sent back to the trigger for the trigger to send a reply to the REST request initiator. Hence, the flow output data must be mapped to the trigger reply, which then returns the result of the flow execution to the REST request initiator.
To map the flow output to the trigger reply:
1. In the left pane, click the Map from Flow Outputs tab to configure the mapping of the trigger reply. A Trigger Reply column is displayed in the right pane. You can map the following trigger replies to the flow outputs - code and data.
2. In the Trigger Reply section:
a. To map code, click code. The code text editor appears empty on the right of your Trigger Reply section.
The Flow Output section displays the data available for the mapping. $flow should appear in this section. To see all the flow outputs available for the mapping, expand $flow. This displays code and data.
The Functions section displays functions available for mapping.
b. In the Flow Output section, under $flow, click code.
$flow.code should now appear in the code text editor. You have successfully mapped the Trigger Replycode to the Flow Outputcode.
3. Repeat the same steps to map Trigger Reply data to Flow Output data.
4.
Note: You can expand data in both the Trigger Reply section and the Flow Output section to see the tree structure of the data you have
defined in schemas.
5. Click Save and close the trigger dialog box.
The blank flow with mappings is created and should look like this:
Step 6: Add a Log Message activity to the flow
Tip: To watch this step in the video tutorial, click
The flow uses the LogMessage activity to log an entry in the app logs when the trigger receives a request from the passenger that reaches the trigger in the form of a REST request.
To add a LogMessage activity:
1. On the right of the Flow Inputs & Outputs tab, click .
2. In the Add Activity page, go to the General tab and click Log Message.
The LogMessage activity’s configuration window opens automatically after its creation. By default, the Settings tab is selected.
3. To configure the LogMessage activity with a message to log when it receives an incoming request from the ReceiveHTTPMessage trigger:
a. Click the Input tab. An Activity Input column is displayed on the right side of the LogMessage activity’s tabs. This column lists the activity inputs. In the Activity Input column, message appears highlighted in red as the
configuration of this activity input is mandatory.
b. Click message to open the mapper to the right. In the mapper, you must configure a message to be logged by the LogMessage activity when the flow receives the input from the request that the trigger received and passed on to the flow.
c. To configure the message, in the Functions section, expand string. Click concat (str, str2) to add the function to the message box. As the box is populated, the error message is cleared.
d. Select str in the box and replace it by entering "Request received for: "
(include the quotes too):
string.concat(Request received for: ", str2)
4. Replace str2 with the last name of the passenger who booked the flight.
(The last name of the passenger is passed on from the trigger to the flow. We had mapped this trigger output to flow input previously. Hence it is now available for mapping under $flow in Upstream Output.)
a. Select str2.
b. In the Upstream Output section, expand $flow.
c. Click lastname.
d. Click Save.
5. Close the LogMessage dialog box. The LogMessage activity is added to the right of the Flow Inputs & Outputs tab.
Your flow should now look like this:
Step 7: Add the first branch to check if the passenger’s last name is Jones Tip: To watch this step in the video tutorial, click
To add a branch and configure its condition to look for the last name “Jones”:
1. Hover over the LogMessage activity and click .
The branch is added and the Add Activity dialog box opens.
2. Close the Add Activity dialog box and configure the condition of the branch first.
You must configure the branch with a condition to read the last name of the passenger.
3. Hover over to the end of the branch until you see a button with three dots placed horizontally.
4. Click the button to expose the following options and click .
5. In the Branch Mapping Settings dialog box opens, select the Success with condition branch condition.
a. In the left pane, click condition to open the mapper in the right pane.
b. In the right pane, configure the branch condition with a regular expression as follows:
i. In the Functions section, expand the string category under Functions and click contains(str1, str2). The selected function is added to the condition box at the top of the right pane.
ii. Configure str1 in the expression to take the value of the last name that the user enters: In the Upstream Output, expand $flow > queryParams, and select lastname. This last name is the name entered by the user in the search query.
iii. Define str2 to be Jones: Replace str2 in the condition by manually typing
Jones.
iv. Click Save. Now, this branch is configured to be executed when the name entered as a query parameter is Jones.
6. Add a Return activity to the branch in order to return the flight booking matching
the last name Jones. To do so:
a. Hover over the end of the branch and click .
b. Scroll to the Default category and select it.
c. Click Return to add the activity. The Return activity configuration window opens by default.
7. Configure the Return activity for the branch to output the flow results if this branch executes (when the passenger's last name is anything but Jones):
a. Click code under Flow Outputs to open the mapper and type 200 in the code box, which is the HTTP success code.
b. Expand the next flow output data. All the different elements under data that are returned by this activity are displayed. You must attribute a value to each field under data.
c. Start by clicking Class under data and type "Business" as Jones is booked in Business Class.
d. Click Cost to type a number of your choice. You can also use a function to randomize the value. To do so, in the Functions section, expand the number category and click random(). Enter 5000 as an input parameter to the random () function.
e. Click DepartureDate to enter the departure date in any format of your choice.
You must use quotation marks as the date needs to be specified as a string.
For example, “01/01/21” or “January 1st, 2021” are valid values.
f. Click DeparturePoint to enter the departure airport name of your choice. You must use quotation marks as the departure point needs to be specified as a string. For example, “LAX” or “LHR” are valid values.
g. Click Destination to enter a string for this field. For example, “Paris” or “JFK”
are valid values.
h. Click FirstName to enter the first name associated with the last name Jones.
For example, “Brian” or “Paul” are valid values.
i. Click Id to enter a number of your choice. You can also use a function to randomize the value. To do so, in the Functions section, expand the number category and click random(). Enter 999999 as an input parameter to the random() function.
j. Click LastName to map this field to the query parameter lastname. Before doing so, we can use a string function to capitalize the last name that is returned by our app. To do so, under Functions, expand string and click toTitleCase(str). Once string.toTitleCase(str) is added to your box, select str to replace it with the query parameter. Expand $flow and then queryParams under Upstream Output and click lastname. The box should look like this:
k. Click Save and then close the dialog box.
Your flow should look like this:
Step 8: Add a second branch to process any other passengers Tip: To watch this step in the video tutorial, click
The second branch you add from the LogMessage activity executes when the success condition of the first branch is not matched. If the passenger's last name is not "Jones", the passenger's seat is in Economy Class.
To add a second branch from the LogMessage activity:
1. Hover your mouse cursor over the LogMessage activity and click .
The branch gets added and the Add Activity dialog box opens.
2. Close the Add Activity dialog box.
3. Hover your mouse cursor to the end of the branch until you see a button with three dots placed horizontally. Click the button to expose the following options:
4. Click . The Branch Mapping Settings dialog box opens.
5. Select the Success with no matching condition branch condition. If the conditions of all the other Success with condition branches are not true, this branch is
executed. This means, if the last name entered as a query parameter is not Jones, this second branch is executed.
6. Instead of manually adding another Return activity and enter the value of each field under data again, duplicate the Return activity from the first branch by hovering over the activity that you want to copy and click . The copied activity should appear next to your original Return activity:
7. Drag the duplicate activity to your second branch.
8. Click CopyOfReturn activity to configure the response this branch returns.
9. In the Flow Inputs section, expand data , select Class and type “Economy” as this branch should return Economy Class bookings.
10. Click Save and close the dialog box.
Your flow should look like this:
Step 9: Validate the app
Tip: To watch steps 9 and 10 in the video tutorial, click
Your app is now ready. Before you push the app to the Cloud, validate all the flows to confirm that there are no errors or warnings. To do so, click Validate. Flogo Enterprise validates each flow and activity within the flow. If there are any errors or warnings, you see the respective icons next to the flow name or activity tab which contains the error or warning.
On a successful validation, you get the following message:
Step 10: Build the App
Your app is now ready to be built. There are two ways to build a Flogo app.
l As an executable file
l Build it as a Docker image in a Docker container
1. Click the left arrow next to the flow name to open the FlightApp page.
2. Click Build.
3. Select your target platform from the Build drop-down list. Select Windows/amd64 on Windows, Darwin/amd64 on Macintosh or Linux/amd64 or Linux/86 on Linux from the list.
You see a Build log with the progress of the build command. When the build
completes, you see an executable file called FlightApp-darwin_<processor> in your
/Downloads directory.
Docker Image
1. Click Docker Image from the drop-down list. You should see a progress bar.
2. While the Docker image is being created, you see a Build log with the progress of the build command.
3. Once the image is created successfully, it is available in your local Docker repository.
To view it in your Docker repository, open a terminal and run the following command:
docker images
You should see the docker image for your app:
Note: Even though the app name contains camelCase, the name is converted to all lowercase letters when the Docker image is named. For example, "FlightApp" translates to "flightapp".
Step 11: Test the app
Now that the app has been built successfully, you run the app. Once it runs successfully, you can test your API in a REST client.
On Macintosh and Linux Platforms To test the app:
1. Open a terminal and change directory to the location of FlightApp-darwin_amd64,
FlightApp-linux_amd64 or FlightApp-linux_86 file depending on your platform.
2. Run the following commands:
chmod +x <FlightApp-darwin_amd64>
./FlightApp-darwin_amd64
Note: In the commands, use the file name specific to your platform -
FlightApp-linux_amd64 or FlightApp-linux_86 in the case of Linux.
3. Click Allow in the following dialog box:
The following messages are displayed in the console:
4. Make a note of the port number 9999 and path /flightbookings in the logs.
5. You can test your API in a REST client such as Postman by entering the port number
9999, path /flightbookings and query parameter lastname. For example,
http://localhost:9999/flightbookings?lastname=jones.
In the above example, note that since the query parameter sent has the last name as
"Jones", the Class in the response has been automatically set to Business Class.
6. Go back to your terminal. You should see the logs you configured with the Log activity.
Docker Image
1. Open a terminal.
2. Run the following command:
docker run -p 9999:9999 flogo/flightapp
You should see the following:
3. Test your API in a REST client such as Postman.
4. Press Ctrl + C to stop the docker container. Run docker ps -a to ensure that your container has stopped.
App Development
Flogo Enterprise offers a wizard driven approach to app development. You can create apps in Flogo Enterprise using only a browser. It is powered by Project Flogo™, a lightweight integration engine.
For more information about Project Flogo™, go to http://www.flogo.io/.
Creating and Managing a Flogo App in the Web UI
This section describes how to create and manage Flogo apps.
Creating an App
You can create a Flogo® app from the Apps page.
Procedure
1. Open the Apps page.
2. Click Create/Import app.
The app details page opens. By default, the app is named in a sequential order in the format New_Flogo_App_<sequential_number>. For example, if you created three apps without renaming them, then the first one has a default name of New_
Flogo_App_1, the second one is called New_Flogo_App_2 and the third one is called
New_Flogo_App_3. The version of a newly-created app is 1.0.0 and is displayed as v:
1.0.0 beside the name of the app. You can edit the version of the app. For more information, refer to Editing the Version of an App .
3. Edit the app name to a meaningful string. To do so, click anywhere within the app name and edit it, then click anywhere outside the text box to persist your change.
Note: The app name must not contain any spaces. It must start with a letter or underscore and can contain letters, digits, periods, dashes, and
underscores.
4. Click Create.
Result
The app is created. When the app is created, the following files are generated in the
<FLOGO_HOME>/apps/<app>/ directory:
l flogo.json: contains the app itself
l manifest.json: contains the manifest details such as the endpoints, memory resource details, and so on. The manifest.json file is automatically updated whenever you make changes to the app.
You can now create one or more flows for the app. See the Creating a Flow topic and its sub-topics for details on creating a flow.
Creating an App from a Saved Specification
If you have an existing specification saved in either the TIBCO Cloud™ Integration - API Modeler or on your local machine, you can use the specification to create a Flogo app.
Currently, Flogo Enterprise supports app creation using a Swagger Specification 2.0, OpenAPI Specification 3.0, GraphQL Schema, or gRPC Protobuf.
The specification must exist prior to creating the Flogo app.
Refer to the appropriate topics under the Building APIs section for information on how to create a Flogo app using the specification:
Using an OpenAPI Specification Using GraphQL Schema
Using gRPC
Validating your App
After you have created the flows in your app, you must validate the app before you push it to the cloud.
To validate your app, click the Validate button on the app details page. This validates each flow and activity. If a flow or activity has an error, it displays an error or warning icon on the top right corner of the flow or activity.
Note: Flogo Enterprise does not retain the results of the previous validation if you navigate into a flow after you have validated the app. For example, if two of your flows have errors, and you navigate into one of those flows to fix the error, when you get back to the app detail page, the results of the second flow
validation are lost. If you navigate into a flow after you have validated the app, you must validate the app again irrespective of whether you have made changes to the flow or not.
Refer to Viewing Errors and Warnings section for more details.
Editing an App
You can edit your Flogo app from the Apps page. Click any app to edit flows, triggers, and so on.
Warning: Editing the same app in two browser tabs is not supported.
When you make changes to the app, the flogo.json and manifest.json files in <FLOGO_
HOME>/apps/<app>/ are updated automatically. For example, if you add a flow and add a trigger to it, the flogo.json and manifest.json files are updated automatically to include the details of the flow and the trigger.
Renaming an App
To rename an existing app, do the following:
Procedure
1. Open the app details page by clicking the app name.
2. Click anywhere in the app name and edit the name.
3. Click away from the app name to persist your changes.
Editing the Version of an App
When you create an app, the default version of the app is 1.0.0. You can edit the version of an app.
The format of a valid app version is:
xxx.xxx.xxx
Note: Alphabets or special characters are not allowed in an app version.
Some examples of valid app versions are:
1.1.1 11.22.13 111.222.333
Procedure
1. Open the app details page.
Beside the name of the app, the version of the app is displayed as follows:
New_Flogo_App_<sequential_number> v: 1.0.0
For a newly-created app, the version is 1.0.0.
2. To edit the version of the app, click on the version number and specify the new version.
The new version of the app is reflected everywhere. For example, in runtime logs.
Using App Tags
You can use app tags to provide additional information and organize your apps. For example, you can specify whether it is a REST app, whether it is running in Kubernetes, and so on. One or more tags can be added to an app. You can view and filter the tags from the list of apps on the Apps page. The tags are preserved after exporting a Flogo app.
Adding Tags
1. Click the Apps tab.
2. Click the app you want to modify. The App Details page opens.
3. Click Tags or +Tags (if the app has no tags). Tags that have already been applied to this app are shown.
For example, the following screenshot shows that the app FE has no tags. Click +Tags to view the tags in the organization.
l To add a new tag, enter a name in the search control, then click Create New.
Tags are case-sensitive.
l If you enter text in the search box, all matching tags in your organization are shown. This search is case-insensitive. Click a tag to add it.
l Click close (×) next to a tag to remove it from the app.
4. Click outside the dialog box to save the changes.
The same set of tags is used across your organization. A tag is deleted from your organization when it is removed from the last app using it.
Filtering Tags
To filter the apps list on the Apps page:
1. In the filters shown on the left side of the apps list, the Tags filter shows the total number of tags and a search control. Enter text in the search filter to show buttons for each tag containing the text. This search is case-insensitive.
For example, the following screenshot shows the tags starting with the letters "Che".
2. Click a tag button to limit the list of displayed apps to only apps with that tag. Click a selected tag button to clear it. You can select multiple tags.
A tag icon is next to each name in the Name column on the Apps page. Hover over the tag icon to see a list of all tags in that app. The following screenshot displays the tags for the app FE.
Notes
l When you export a Flogo app, its app tags are not retained in the Flogo JSON app archive file.
l When you create tags, they are case-sensitive, but the tag filter search is case- insensitive. For example, you can create unique app tags for abc and ABC, but when
you search for a in the search control, both are shown.
Role Requirements
l Admins can edit tags for any app in their organization.
l Users can only edit tags on apps they own.
l Read-only users cannot change tags on any app.
Switching Between Display Views on the App Page
When you click an app name on the Apps page, the app details page opens. The flows in the app are listed on the app details page. You have the option to view this page in the Trigger View or Flow View. By default, it opens in the Trigger View. Click Trigger View and select Flow View from the drop-down menu to switch to the flow view. When you are in the flow view, click Flow View and select Trigger View from the drop-down menu to go back to the trigger view.
Trigger View
In this view, the flows are displayed attached to the trigger(s) that they use. If a flow is attached to multiple triggers, it is attached to each trigger separately. So, you can see it multiple times on the page but attached to different triggers. Flows that are not attached to any trigger display No trigger in place of the trigger name.
The following image shows the Trigger View:
In the image above, MyRESTFlow2 is attached to both TimerTrigger and
ReceiveHTTPMessage trigger as shown, hence it appears twice. The MyTimerTrigger flow
was created with a new Timer trigger, hence it is not attached to the top Timer trigger which has two flows attached to it and TimerTrigger appears twice on the page.
Hovering on a trigger displays the New flow option. Click the New flow option to create a new flow to attach the newly created flow to that trigger.
Hovering over No trigger displays the Add trigger option which takes you to the triggers catalog.
Flow View
In this view, each flow is shown separately and the trigger that it is attached to is shown on the extreme left of the flow. Shown below is a Flow View representation of the Trigger View image above:
The following image shows the Flow View:
Notice that MyRESTFlow2 shows two triggers. That is because this flow is attached to two triggers as you can see in the Trigger View. A blank flow shows 0 triggers against it as it is not attached to any triggers.
Deleting an App
You can delete an app using the Delete app icon which appears when you hover your mouse cursor to the end of the app row.
To delete an app:
Procedure
1. On the Apps page, hover your mouse cursor to the end of the app row until the Delete app icon ( ) appears.
2. Click the Delete app icon.
3. On the confirmation dialog box, click Delete app.
Result
The selected app is deleted. The <FLOGO_HOME>/apps/<app>/manifest.json file is also deleted.
Exporting and Importing an App
You can export and import apps and use them as templates to quick start development, or simply put them in a version control system such as GitHub.
Tip: When an app is created, the flogo.json file and manifest.json file are automatically created in the <FLOGO_HOME>/apps/<app>/ directory. Instead of using the Export option, you can use the files from the <FLOGO_
HOME>/apps/<app>/ directory to push the app directly using TIBCO Cloud CLI.
For more information see, Creating an App and Editing an App.
Exporting an App
Here are a few things to keep in mind before you export an app:
l When you export an app, all flows in your app get exported. You cannot pick and choose flows to export.
l Passwords configured in any activity within any flow or connection in the app to be exported are removed in the exported app. You must manually configure the credentials in the flows after importing such apps.
l Some apps created in Project Flogo™ use the any data type. The any data type is not supported in Flogo Enterprise. Such apps get imported successfully, but the element of type any gets converted into an empty object. You must explicitly use the mapper to populate the empty object with member elements.
Warning:
When exporting an app, if the app contains Launch Configurations to hold its test data, the Launch Configurations are not be exported with the app. Launch Configurations in an app must be exported independently of the app export.
To export an app:
Procedure
1. On the Apps page, click the app to open the app details page.
2. Click the shortcut menu ( ).
3. Click Export.
The Export option in the Flogo Web UI has a drop-down menu which gives you the option to download any of the following:
l App - exports a single <appname>.json file. You can use this option to
download an app which you plan to import into TIBCO Cloud Integration using the drag-and-drop method.
l TIBCO Cloud Integration artifacts - downloads two files, manifest.json and
flogo.json. The manifest.json contains the manifest details such as the endpoints, memory resource details, and so on. The flogo.json contains the app itself. These artifacts are needed to push the app directly using TIBCO Cloud CLI. You must have the TIBCO Cloud CLI installed on your local machine to do so. Use this option to push a Flogo app to TIBCO Cloud Integration without having to import it into TIBCO Cloud Integration. See the section Pushing Apps to TIBCO Cloud for details on how to do this.
Exporting an App's JSON File
When an App's binary is built, the .json file is embedded within the binary file. To export the .json file from the binary file to the disk, use the following command.
./<app-binary-name> --export app
The .json is exported as <app-binary-name>.json.
Tip: To provide a different file name to the exported .json, use the following command:
./<app-binary-name> --export -o <new-app-binary-name>.json app
Importing an App
You can import the triggers and flows from an exported app into an existing app or into a new app. The target app into which you want to import must exist. You can import an app by dragging and dropping its .json file into the Web UI.
Note: Flogo apps that are exported from Flogo Enterprise 2.5.0 and later cannot be imported into previous versions of Flogo Enterprise.
Here are a few things to keep in mind before you import an app:
l If any flow in the app uses extensions developed by the community, those
extensions must be available to the target app into which you are importing, at the time of the import. Flows that make use of extensions that are not available to the target app are not imported.
l Passwords configured in any activity within any flow or connection in the app to be exported are removed in the exported app. You must manually configure the credentials in the flows after importing such apps.
l Some apps created in Project Flogo use the any data type. The any data type is not supported in Flogo Enterprise. Such apps get imported successfully, but the element of type any gets converted into an empty object. You must explicitly use the mapper to populate the empty object with member elements.
l When importing an app, be aware that the long and double data types get converted to the number data type.
The suffixes used in the Mapper have undergone some changes, because of which you may receive a mapper-related warning in the Import app dialog when importing an
existing app. Click Continue and the app imports successfully. After the import completes, be sure to re-map the properties in the activities that show errors. This ensures that they switch to the new suffix format.
The following table shows you the changes in the suffixes:
Original suffix appearing in imported apps
New suffix used by the Mapper (after you re- map)
For example... Used when mapping...
activity_id. activity_
parameter
$activity [activity_id].
activity_
parameter
Old suffix:
$InvokeRESTService.
responseBody.userId New suffix after re- mapping property:
$activity
[InvokeRESTService].
responseBody.userId
When mapping to a parameter in the activity's output. Used to resolve activity params.
$TriggerData $trigger Old suffix: When mapping from the output of
Original suffix appearing in imported apps
New suffix used by the Mapper (after you re- map)
For example... Used when mapping...
$TriggerData.
queryParams.title
New suffix after re- mapping property:
$trigger.
queryParams.
title
the trigger to flow input
N/A There was no
equivalent for this in the old mapper
$flow.headers.
parameter
$flow.body.
parameter
$flow is a newly introduced suffix which did not have an
equivalent suffix in the old mapper.
When mapping to any parameter in the flow's header or input schema (schema entered in the Input tab of Flow Inputs &
Outputs dialog) which is the same as the output of the trigger, since the output of the trigger is mapped to the input of the flow.
Used to resolve parameters from within the current flow. If a flow has a single trigger and no input parameters defined, then the output of the trigger is made available via $flow.
Note:
l In imported apps, the passwords and secrets for any connections configured in the app do not get imported. You must reconfigure any password or secret for the connection after the app has been imported.
l When you import an app which does not have a Return activity in any flow (main or branched flow), the Return activity is not added
automatically by default. However, if an existing app already has Return activities in main or branched flows, the app is imported as expected.
Importing into a new or empty app
1. Create a new app if you do not already have one. See Creating a Flogo app for details on creating an empty app.
2. On the app details page, select Import app.
3. Navigate to or drag and drop the .json file for the app that you want to import.
4. Click Upload. The Import app dialog displays some generic errors and warnings as well as any specific errors or warnings pertaining to the app you are importing. It validates whether all the activities and triggers used in the app are available in the Extensions tab.
5. You have the option to import all flows from the source app or selectively import flows.
l Import all - To import all the triggers and flows in the app, select Import All.
If any activities or triggers are missing in the Extensions tab, the import process ignores the flows that contain those activities resulting in those flows not being imported. If the existing app already has activities or triggers with the same name as the ones you are importing, you see a warning that they are overwritten. If you do not want to overwrite the flows, you can click Back and clear the selection then click Next. If you do so, the duplicate flows that you de-selected do not get imported. You have the option to rename the flows in the Web UI and export the app and re-import it.
l Selective import - Select Selective Import, to import only specific triggers and flows from the app. The Import app dialog displays a list of triggers with a check box next to each one. If any activities or triggers are missing in the Extensions tab, the activities or triggers missing in the Extensions tab are not listed in the Import app dialog, hence you cannot select them to import. By default, all check boxes are selected. Clear the check box next to the triggers that you do not want to import. All flows associated with the selected trigger(s) get imported by default. If you do not select a trigger, the flows and their subflows associated with the unselected trigger(s) are listed in the next screen.
6. Click Next.
If you had not selected a trigger in the previous dialog, the flows associated with that trigger are displayed. You have the option to select one or more of these flows such that the flows get imported as blank flows that are not attached to any trigger.
By default, all flows are selected. Clear the check box for the flows that you do not
want to import. If your flows have subflows, and you select only the main flow but do not select the subflow, the main flow gets imported without the subflow. Click Next.
Importing into an app that has existing flows
When importing the app into another app that has existing flows, keep the following in mind:
l If the existing app already has flows, activities or triggers with the same name as the ones you are importing, a warning is displayed. You can opt not to import those flows, activities, or triggers. You can go back and rename them in the Web UI and export the app again and re-import it.
l If any of the flows that were imported with the app had credentials such as a password or a connection, be sure to re-configure them.
1. Open the app details page by clicking the app name.
2. Click the shortcut menu ( ) and select Import.
3. Navigate to or drag and drop the .json file for the app that you want to import.
4. Click Upload. The Import app dialog displays some generic errors and warnings as well as any specific errors or warnings pertaining to the app you are importing. It validates whether all the activities and triggers used in the app are available in the Extensions tab.
5. You have the option to import all flows from the source app or selectively import flows.
l Import all - To import all the triggers and flows in the app, select Import All.
If any activities or triggers are missing in the Extensions tab, the import process ignores the flows that contain those activities resulting in those flows not being imported. If the existing app already has activities or triggers with the same name as the ones you are importing, you see a warning that they are overwritten. If you do not want to overwrite the flows, you can click Back and clear the selection then click Next. If you do so, the duplicate flows that you de-selected do not get imported. You have the option to rename the flows in the Web UI and export the app and re-import it.
l Selective import - Select Selective Import, to import only specific triggers and flows from the app. The Import app dialog displays a list of triggers with a
check box next to each one. If any activities or triggers are missing in the Extensions tab, the activities or triggers missing in the Extensions tab are not listed in the Import app dialog, hence you cannot select them to import. By default, all check boxes are selected. Clear the check box next to the triggers that you do not want to import. All flows associated with the selected trigger(s) get imported by default. If you do not select a trigger, the flows and their subflows associated with the unselected trigger(s) are listed in the next screen.
6. Click Next.
If you had not selected a trigger in the previous dialog, the flows associated with that trigger are displayed. You have the option to select one or more of these flows such that the flows get imported as blank flows that are not attached to any trigger.
By default, all flows are selected. Clear the check box for the flows that you do not want to import. If your flows have subflows, and you select only the main flow but do not select the subflow, the main flow gets imported without the subflow.
7. Click Next.
Importing flows without importing the triggers that they are attached to 1. Select Selective Import when importing the app.
2. Clear the check box for the triggers that you do not want to import.
3. Click Next. A list of flows is displayed.
4. Select the flows that you would like to import and click Next. The flows are imported as blank flows without being attached to a trigger.
Handling connections when importing an app
Each connection in Flogo Enterprise contains a unique internal ID. The IDs are not exposed in the Web UI and are unique based on the user who created them.
When Flogo Enterprise compares connections, it does so by comparing their internal IDs.
It considers two connections identical if they have the same connection type and same connection ID. It considers two connections as similar if they have the same connection type, but different connection ID.
Hence, if the app you are importing was not created by you, then any connections used in that app cannot have the same ID as any existing connection of the same type that you might already have in your installation of Flogo Enterprise. For example, if you import an app created by some other user that has some Salesforce connections, even though your installation of Flogo Enterprise might already have some existing Salesforce connections,
the connections are considered similar, because they are of the same type (Salesforce) but not identical because they do not have the same ID because they were not created by the same user.
When importing an app containing a connection, if your target app has an existing connection with an identical internal ID as the connection in the app being imported, a new connection does not get created. The imported app uses the existing connection in such a case. The connection credentials do not get exported with the app. If a new connection gets created, you must re-configure the connection credentials after the app has been imported.
Keep the following in mind when you import an app with connections:
Import all
If you had selected Import all when importing the app, you have the following options:
l If you are the owner who created the app to be imported, if identical connections exist in your environment, the existing connections are automatically re-used.
l If identical connections do not exist, then new connections get created without passwords. You must set the password for such connections after the app has been imported.
l If there are similar connections (same type but different IDs) in the host app, Flogo Enterprise does not re-use those connections. It creates new connections without passwords. You must set the password for such connections after the app has been imported.
Selective import
If you chose to do a selective import when importing an app, the Import app dialog lists the connections that are used in the flows and triggers that you selected for import in the app to be imported. It displays a drop-down menu next to each connection. You have the following options:
l If you have any existing identical connections (same connection type and same connection ID) in the host app, that connection is automatically selected in the drop- down menu next to the connection. You have the option to re-use the existing identical connection by leaving it pre-selected.
l If there are any similar connections in the host app (same connection type but different connection ID), you can select the similar connection from the drop-down menu next to it.
l You always have the option to select Create new connection from the drop-down menus for any of the connections. Flogo Enterprise creates new connections with no passwords. You must manually create a password for the new connection after importing the app.
Resolving Missing Activities and Triggers
When you import an app that contains one or more activities or triggers that are not installed in your environment, you see a warning in the Import App dialog.
Note: When importing an app that has a connection configured in it, but the connector is not installed in your environment, after you install the connector, the connection configuration field values of type SECRETS are retained post installation as long as they were not configured using application properties. If you had configured your SECRETS as application properties, you need to reconfigure them after installing the missing connector. This is because all application properties in the app are wiped out when the app is imported.
To resolve missing activities or triggers for which TIBCO provides connectors When an activity or trigger used in an app being imported is missing from your Flogo Enterprise environment, the flows in the app get imported, but you see a warning in the Import App dialog.
When you validate your app by clicking on the Validate button in the app details dialog, you see an error marker ( ) next to the flow name. This indicates that one or more activities or triggers are missing. The number next to it indicates how many activities or triggers that are missing appear in the flow. When you click on the missing activities or triggers, you are prompted to refer to connector installation guide.
Note: Do not upload a TIBCO connector using Upload Extension. For more information on how to install a TIBCO connector, refer to connector installation guide.
This is also true when you copy an app into the designated folder (the folder you specified when you started your Web UI) for your apps on your local machine.
To resolve your custom activities or triggers that are missing
When one or more of your custom activities or triggers used in the app being imported are missing from your Flogo Enterprise installation, you see a warning in your Import App dialog similar to the following:
Once the app is imported, you see an error marker ( ) next to the flow name. After you install the missing activity of trigger, this marker goes away. The number next to the error indicates how many activities or triggers are missing in the flow.
To install the missing custom activities or triggers, do the following:
1. Click the flow name to open the flow details page. The Upload an extension dialog opens. You upload custom activity or trigger from the Git repository, hence only the From Git repository option is enabled.
2. Click From Git repository. The Git repository URL text box is pre-populated.
3. Click Import. Flogo Enterprise downloads the activity or trigger from the Git
repository and uploads it into your Extensions tab. Refer to the section, Uploading Extensions for details on this option.
App File Persistence
Your Flogo app files get persisted to the directory that you specify on your local machine.
You can use an external source control system such as Git or SVN to store your apps. You can then check in and check out your apps locally from the remote repository. This makes it possible for you to implement the Continuous Integration/Continuous Deployment
