TIBCO Flogo® Enterprise User's Guide

(1)

User's Guide

Software Release 2.6.0

May 2019

(2)

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE

SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.

ANY SOFTWARE ITEM IDENTIFIED AS THIRD PARTY LIBRARY IS AVAILABLE UNDER SEPARATE SOFTWARE LICENSE TERMS AND IS NOT PART OF A TIBCO PRODUCT. AS SUCH, THESE SOFTWARE ITEMS ARE NOT COVERED BY THE TERMS OF YOUR AGREEMENT WITH TIBCO, INCLUDING ANY TERMS CONCERNING SUPPORT, MAINTENANCE, WARRANTIES, AND INDEMNITIES. DOWNLOAD AND USE OF THESE ITEMS IS SOLELY AT YOUR OWN

DISCRETION AND SUBJECT TO THE LICENSE TERMS APPLICABLE TO THEM. BY PROCEEDING TO DOWNLOAD, INSTALL OR USE ANY OF THESE ITEMS, YOU ACKNOWLEDGE THE

FOREGOING DISTINCTIONS BETWEEN THESE ITEMS AND TIBCO PRODUCTS.

This document is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.

TIBCO, the TIBCO logo, the TIBCO O logo, Two-Second Advantage, TIB, Information Bus, and Flogo are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.

This software may be available on multiple operating systems. However, not all operating system platforms for a specific software version are released at the same time. Please see the readme.txt file for the availability of this software version on a specific operating system platform.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF

MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE,

INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

This and other products of TIBCO Software Inc. may be covered by registered patents. Please refer to TIBCO's Virtual Patent Marking document (https://www.tibco.com/patents) for details.

(3)

TIBCO Documentation and Support Services

How to Access TIBCO Documentation

Documentation for TIBCO products is available on the TIBCO Product Documentation website, mainly in HTML and PDF formats.

The TIBCO Product Documentation website is updated frequently and is more current than any other documentation included with the product. To access the latest documentation, visit https://

docs.tibco.com.

Documentation for TIBCO Flogo^® Enterprise is available on the TIBCO Flogo^® Enterprise Product Documentation page.

Product-Specific Documentation

The following documents for this product can be found on the TIBCO Documentation site:

● TIBCO Flogo^® Enterprise Installation

● TIBCO Flogo^® Enterprise User's Guide

● TIBCO Flogo^® Enterprise Release Notes

● TIBCO Flogo^® Activities and Triggers Guide

How to Contact TIBCO Support

You can contact TIBCO Support in the following ways:

● For an overview of TIBCO Support, visit http://www.tibco.com/services/support.

● For accessing the Support Knowledge Base and getting personalized content about products you are interested in, visit the TIBCO Support portal at https://support.tibco.com.

● For creating a Support case, you must have a valid maintenance or support contract with TIBCO.

You also need a user name and password to log in to https://support.tibco.com. If you do not have a user name, you can request one by clicking Register on the website.

How to Join TIBCO Community

TIBCO Community is the official channel for TIBCO customers, partners, and employee subject matter experts to share and access their collective experience. TIBCO Community offers access to Q&A forums, product wikis, and best practices. It also offers access to extensions, adapters, solution accelerators, and tools that extend and enable customers to gain full value from TIBCO products. In addition, users can submit and vote on feature requests from within the TIBCO Ideas Portal. For a free registration, go to https://community.tibco.com.

(8)

Overview

TIBCO Flogo^® Enterprise is an event-driven app engine for all kinds of application development use cases. It is used to build ultralight microservices or serverless functions with flexibility to deploy on premise, in public, private, or hybrid cloud environment using containers as well as serverless computing. Flogo^® Enterprise is based on Project Flogo^™, an open source ecosystem for event-driven apps.

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.

Concepts

The following describes some concepts that are 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 actions such as flows.

Trigger

Triggers receive events from external sources such as Kafka, Salesforce, GraphQL and so on. Handlers dispatch events to actions such as flow. 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 Flogo ecosystem provides a set of actions for processing events in a manner suitable to your implementation logic. The flow is one of the actions in Flogo that allows you to implement the business logic as a process. Flows are visually designed and tested using the Web UI. A Flow can consist of one or more activities that perform a specfic task. Activities are linked and can contain conditional logic for branching. Each Flow also has a default error handler. A Flogo app can have one or more flows. A flow can be triggered by one or more Triggers within the application.

Activity

Activities perform specific tasks within the flow. A flow typically contains multiple activities.

(9)

Tutorial on Building a Simple REST Service

The following tutorial walks you through building a simple REST service in Flogo Enterprise.

This tutorial walks you through creating a basic airlines flight reservation app which takes input from a user (a potential passenger), checks to see if the passenger's last name is "Jones" and for passengers with last name "Jones" upgrades them to Business Class.

The app contains a REST flow, FlightBookings, which implements the POST HTTP operation to book a seat for the passenger requesting it on the flight. The flow is triggered by the ReceiveHTTPMessage REST trigger which listens for a request to book a seat that comes in from a passenger. The flow contains a LogMessage activity which you configure to log a custom message when a request has been received successfully. The LogMessage activity has two branches. Each branch has its own Return activity.

When a request comes in:

1. The first branch accepts requests with any last name that appears in the REST request.

2. The second branch then checks to see if the last name in the request is "Jones". You configure this check (condition) in the Branch Mapping Settings for this branch. If the last name is "Jones" then the flow outputs the passenger details with the Class element automatically set to Business Class meaning that the passenger's seat has been booked in Business Class. You configure this action of automatically setting the Class element to BusinessClass for passengers with last name "Jones" in the Return1 activity for this branch.

3. If the last name received is not "Jones" the control is transferred to the first branch whose flow outputs the details of the request as received.

Creating the JSON Schema for REST Request and Response

You start by creating a simple JSON schema for the REST request that the service receives and the response that the service sends back. In this tutorial, we use the following sample JSON message which gets converted internally into a JSON schema:

{

"Class" : "string", "Cost" : 0,

"DepartureDate" : "2017-05-27", "DeparturePoint" : "string", "Destination" : "string", "FirstName" : "string", "Id" : 0,

"LastName" : "string"

}

High-level Steps in the Tutorial

The high-level steps for creating and configuring the airlines flight reservation service REST app in this tutorial are as follows:

1. Create a New TIBCO Flogo^® App

(10)

2. Create a Flow in the App with a REST Trigger

3. Map Flow Output to Trigger Reply to configure the Reply activity to output the outcome of the flow

execution.

4. Map Trigger Output to Flow Input

5. Delete the Return Activity

6. Add a Log Message Activity in 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. Create A Branch from the Log Message Activity and Configure it and configure the branch to accept

any last name from the user.

8. Add a Second Branch to Check if Passenger Last Name is "Jones"

9. Build the App

10.Test the App using any REST client app.

Step 1: Create a New TIBCO Flogo^® App

Create a new TIBCO Flogo^® App in Flogo Enterprise.

Follow these steps to create a new app:

1. Open the Apps page in Flogo Enterprise.

2. Click Create.

3. Enter ^FlightApp as your app name in the Give your new app a name text box and click Create.

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.

(11)

Step 2: Create a Flow in the App with the REST Trigger (Receive HTTP Message) Every app must have at least one flow. Create a new flow with the REST trigger. The

ReceiveHTTPMessage REST trigger listens for an incoming REST request that contains the details of the passenger who wants to book a flight. You configure the expected fields for the request in the REST trigger in JSON schema format.

Follow these steps to create a flow:

1. Click +Create.

2. Click New flow in the Create flows and triggers dialog.

3. Enter FlightBookings in the Name text box and optionally a description for the flow in the Description text box and click Create.

(12)

4. Click Start with a trigger.

5. Select Receive HTTP Message card in the Add a trigger dialog.

(13)

6. Select POST under Method.

7. Enter /FlightBookings in the Resource path text box.

8. Enter the following schema that an incoming request must adhere to in the text box for Enter a JSON Schema or an example of your JSON message:

Make sure to use straight quotes when entering the schema elements and values.

{

"Class" : "string", "Cost" : 0,

"DepartureDate" : "2017-05-27", "DeparturePoint" : "string", "Destination" : "string", "FirstName" : "string", "Id" : 0,

"LastName" : "string"

}

(14)

9. Click Continue.

10. Select Copy Schema when prompted as shown below.

The schema that you entered when creating the trigger automatically gets copied to the following locations when the trigger is added:

● It is displayed in a tree format in the Map to Flow Inputs tab of the trigger. This allows you to map the elements from the trigger output to flow input elements, such that the trigger output feeds into the flow input.

● Flow input in the Input Settings tab of the Flow Inputs & Outputs accordian tab.

● The Reply Settings tab of the trigger, if the trigger has a reply. In the next step, you map the flow output schema elements to the trigger reply. By doing so, you send the output from the flow back to the trigger such that it becomes the trigger reply.

A new flow is created with a REST trigger.

11. Collapse the Flow Inputs & Outputs accordian tab by clicking the left-facing arrow above the tab name in the blue vertical bar.

Step 3: Map Flow Output to Trigger Reply

When the flow has finished executing its output data must be mapped to the trigger reply which in turn will output the result of the flow execution.

To map the flow output to the trigger reply, do the following:

1. Click the trigger to open its configuration dialog.

2. Click the Map from Flow Outputs tab.

a. Click the code under Trigger Reply to open the mapper.

b. Click the code under Flow Output.

c. Click data under Trigger Reply.

d. Click data under Flow Output.

(15)

e. Click x to close the dialog.

Step 4: Map Trigger Output to Flow Input

The input to the FlightBookings flow comes from the output of the ReceiveHTTPMessage trigger.

Hence, you must map the trigger output to the flow input.

To do so, follow these steps:

1. Click the trigger on the top left corner of the flow to open its configuration dialog.

2. Click the Map to Flow Inputs tab.

3. Click headers under Flow Input, then click $trigger > headers to map the headers.

4. Click body under Flow Input, then click $trigger > body to map the elements under body.

5. Click x on the top right to exit the dialog.

Your flow should now look similar to the following:

Step 5: Delete the Return Activity

Since our FlightBookings flow has two branches each of which has the capability to output the return data if it executes, the Return activity in the main flow does not ever get executed. So, delete the Return activity in the main flow. To delete the activity, hover your mouse cursor over the Return activity, then click the icon.

Step 6: Add a Log Message Activity to the Flow

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.

Follow these steps to add a LogMessage activity to the right of the Flow Inputs & Outputs tab:

1. Add a new LogMessage activity from the General tab and configure it.

a. Hover your mouse cursor to the right of the Flow Inputs & Outputs tab.

(16)

b. Click .

c. In the Add Activity box, click General, then click Log Message.

d. Configure the LogMessage activity with a message to log when it receives an incoming request from the ReceiveHTTPMessage trigger. To do so:

a. Click the Input tab.

b. Click message to open the mapper to the right and configure a message to be logged by the LogMessage activity.

c. To configure the message, expand the string function under the Search bar on the right and click concat(str1, str2) to add this function to the message text box.

d. Select str1 in the message text box and enter "We have received a message from

" (include the quotes too) to replace it.

e. Replace str2 with the last name of the person who booked the flight. Do this by replacing str2 with the LastName element.

To map the LastName do the following:

1. Select str2.

2. Expand $flow > body under Upstream Output.

3. Click LastName.

e. Click the x on the upper right side of the LogMessage box to close it. The LogMessage activity is added to the right of the Flow Inputs & Outputs tab.

(17)

Your flow should now look similar to the following:

Step 7: Add the First Branch and Configure It

We want the REST response to be based on the last name in the incoming request. If the last name is

"Jones" we want to book the passenger in Business Class. If the passenger's last name is anything other than "Jones", we want the passenger's seat to be booked in Economy class. To do this, use the branching feature in Flogo Enterprise. Add a branch from the LogMessage activity.

Do the following to add a branch and configure its condition to accept any last name:

1. Hover your mouse cursor over the LogMessage activity and click .

The branch gets added with the Add Activity dialog open.

2. Click the x on the upper right corner of the Add Activity dialog to close it.

3. Click and drag the Return activity one space to the left such that it is the first activity in the branch.

4. Hover your mouse cursor to the end of the branch until you see a button with three dots placed horizontally.

(18)

Click the button to expose the following options:

Click ( ). The Branch Mapping Settings dialog opens.

Select the Success with condition branch condition.

1. Click condition to open the mapper on the right.

2. Configure the branch condition with a regular expression that accepts all last names.

1. Expand the string function under the right Search bar and click regex(pattern, str) to add this function to the condition text box.

2. Replace pattern in the expression by manually entering ".*" (include the quotes too).

3. Replace str in the function with the last name that is mapped from the flow output under Upstream Output. To do so, expand $flow > body and click on LastName. Your condition

4. Click Save.

5. Configure the Return activity for the branch to output the flow results if this branch executes (when the passenger's last name anything but Jones.)

1. Click on the Return activity to open its configuration.

(19)

2. Expand data under Flow Outputs.

3. Click code to open the mapper and enter ²⁰⁰ in the text box.

5. One by one, map all elements under data (Class, Cost, DepartureDate, DeparturePoint,

Destination, FirstName, and LastName) except ID, by first clicking on them and then clicking on the corresponding element under body. Do not map ID.

6. Click ID under data to configure it.

7. Expand the number function and click random(limit).

8. Select limit and enter ⁹⁹⁹⁹⁹⁹ to replace it.

9. Click x to close the dialog.

Your flow should continue to look similar to this:

Step 8: Add a Second Branch to Check for Last Name "Jones"

The second branch you add from the LogMessage activity checks the LastName element in the incoming request to see if it is "Jones". If the passenger's last name is "Jones", the passenger's seat is automatically upgraded to the Business Class.

The string for the last name is case sensitive. So, "Jones" is viewed as different from "jones".

To add a second branch from the LogMessage activity, follow these steps:

1. Hover your mouse cursor over the LogMessage activity and click .

The branch gets added with the Add Activity dialog open.

2. Click the x on the upper right corner of the Add Activity dialog to close it.

3. Click and drag the Return1 activity one space to the left such that it is the first activity in the branch.

(20)

4. 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:

Click ( ). The Branch Mapping Settings dialog opens.

Select the Success with condition branch condition.

5. Configure the condition for the branch to check if the last name ends with "Jones".

The string for the last name is case sensitive. So, "Jones" is considered different from

"jones".

1. Click condition to open the mapper.

3. Expand the string function group under the right Search text box and click regex(pattern, str).

4. Replace pattern by manually typing "Jones" (include the quotes).

The string for the last name is case sensitive. So, "Jones" is viewed as different from

"jones".

5. Select str, then click LastName under body. This replaces the str with the last name extracted from the output of the ReceiveHTTPMessage trigger.

(21)

6. Click x on the upper right corner of the Branch Mapping Settings dialog to close it.

6. Configure the Return1 activity to output the flow results if the second branch executes (when the passenger's last name is Jones.).

a. Click Return1 to open its configuration dialog.

b. Expand data under Activity Input.

c. Click code and enter 200 in its text box.

d. Click Class under data and enter "Business Class" (include the surrounding double quotes).

e. Expand $flow > body under Upstream Output.

f. Map all remaining elements under data (Cost, DepartureDate, DeparturePoint, Destination, FirstName, and LastName) except ID, by clicking on them one at a time and then clicking on the corresponding element under body. Do not map ID.

g. Click ID under data to configure it.

h. Expand the number function and click random(limit).

i. Select limit and enter ⁹⁹⁹⁹⁹⁹ to replace it.

j. Click x to close the dialog.

Your flow should look similar to the following:

Step 9: Build the App

Your app is now ready to be built. There are two ways to build a Flogo^® App.

● As an executable file

● Build it as a Docker image in a Docker container

(22)

1. Open the FlightApp page.

2. Click the left arrow next to the flow name.

3. Click Build.

4. Select your target platform from the drop down list.

On the Macintosh and Linux Platforms

1. Select Darwin/amd64 on Macintosh or Linux/amd64 or Linux/86 on Linux from the list.

2. You should see the progress bar as your app is building.

3. After the build completes, depending on your platform, a file named of FlightApp-darwin_amd64,

FlightApp-linux_amd64 or FlightApp-linux_86 gets downloaded to your machine.

Docker Image

1. Click Docker Image from the drop down. You should see a progress bar.

2. Once the Docker image is created successfully you will see a message saying so.

Even though your app name contained camel caps, the name will be converted to all lowercase letters when the Docker image is named. For example, "FlightApp" will translate to "flightapp".

(23)

Step 10: 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, do the following:

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

In the above commands use the filename specific to your platform - FlightApp- linux_amd64 or FlightApp-linux_86 in the case of Linux.

3. Click Allow in the following dialog:

You will see the following logs in your console:

4. Make a note of the port number and path in the logs.

5. You can test your API in a REST client such as Postman by entering the port number and path. For example,

(24)

In the above example, note that since the request sent has the last name as "Jones", the Class in the response has been automatically set to Business Class.

6. Press Send. You should see the following in your terminal.

Docker Image

1. Open a terminal and run: docker run -p 9999:9999 flogo/flightapp

2. Test your API in a REST client such as Postman.

Press Ctrl + C to stop the docker container. Run docker ps -a to make sure that your container has stopped.

(25)

Developing TIBCO Flogo

^®

Apps

Flogo Enterprise offers a wizard driven approach to app development. You can create apps in Flogo Enterprise using only a browser.

Creating a TIBCO Flogo

^®

App

You can create a Flogo^® App from the Apps page in TIBCO Flogo^® Enterprise.

Follow these steps to create an app:

Procedure

The Create an app dialog is displayed.

3. Enter a name for your app in the Give your new app a name text box.

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.

The newly created app page opens.

(26)

You can now create one or more flows for the app. Refer to the section Exporting and Importing an App for details on how to import an app.

5. Click +Create. See the Creating a Flow topic and its sub topics for details on creating a flow.

Reverting Changes to an App

After editing an existing app, as long as you have not rebuilt the app, you can revert the app to the state that it was in after the latest build. This will revert the changes you just made. You can use the Revert to Last Build button to undo the changes. The changes will be lost.

To revert your edits to an existing app before rebuilding it, follow these steps:

Procedure

1. From the Apps page, click the the app to open its page.

2. Click Revert to Last Build. The Revert to Last Build is activated only if you have made edits to the app after the last build, but have not rebuilt the app with those edits.

Building the App

After you have created your app, you have the option to either export the app (without building it) or build it. Exporting an app allows you to import it elsewhere, for example in TIBCO Cloud^™

Integration. When you build the app, its deployable artifact gets created and downloaded to your local machine. Each operating system has its own build target. You must select the right target for your operating system when building the app. You can use the built artifact to run the app in Flogo Enterprise.

Be sure that you have Docker installed on your machine. Please refer to the product Readme for the supported versions of Docker.

Follow these steps to build an app:

For app binaries that were created in Flogo Enterprise 2.5 or older versions, if the app binary was created using an <app>.json file and contains a flow starting with a trigger and the app binary was created from the CLI using the build tool, the app gets successfully built but throws an error at runtime.

Procedure

2. Click the app that you want to build to open the page for that app.

3. Click Build.

You see the following build target options:

(27)

4. Click the option that is compatible with your operating system.

The app begins to build and when done, the deployable artifact gets downloaded to your local machine. In the case of Docker, a Docker image gets created in your Docker storage area.

Any uppercase letters in your app name get converted to lowercase in the Docker image name. For instance, if your app is named ^MyApp, the Docker image that gets generated will be named ^myapp.

5. To run the app:

On Macintosh and Linux 1. Open a terminal.

2. Run: chmod +x <app-file-name>

3. Run: ./<app-file-name>

For Docker Image

Any uppercase letters in your app name get converted to lowercase in the Docker image name. For instance, if your app is named ^MyApp, the Docker image that gets generated will be named ^myapp. So be sure to use all lowercase letters in the app-file-name in the command below.

1. Open a terminal.

2. Run: docker run -p <<host-port-number>>:<port-on-docker> flogo/<app-file-name>

Building the App From the CLI

You have the option to build an app using the Flogo Enterprise command line interface (CLI).

Prerequisites

Make sure that you have Go programming language version 1.11.4 or above installed on the machine from which you will be running the build command.

Procedure

1. Open a command prompt or terminal window depending on your platform.

2. Navigate to the <FLOGO_HOME>/2.x/bin folder.

If you saved the ^builder in a folder that is different from the default

<FLOGO_HOME>/2.x/bin folder, you must export the ^FLOGO_HOME environment variable before you run the command for the ^builder. Run the following:

export FLOGO_HOME=<FLOGO_HOME>/2.x ./builder-<platform> build <option(s)>

(28)

3. Run the following command (refer to the topic on the builder Command for details):

On Windows: builder-windows_amd64.exe help

On Macintosh: builder-darwin_amd64 help

On Linux: builder-linux_amd64 help

builder Command

Use the ^builder command to build a Flogo Enterprise app from the command line.

Binary Types

You can build either one of these binary types from the command line:

● Flogo app binary - contains the Flogo runtime + only those connectors used by that app.

● Flogo engine binary - contains the Flogo runtime + all the connectors that are present in your Flogo Enterprise installation. The advantage of creating such a binary is that it can run any Flogo app that uses one or more connectors included as a part of the binary. This will help reduce the number of binaries per application.

To view arguments and options for the build command, open a terminal, navigate to the <FLOGO_HOME>

\bin folder, and run the following:

On Windows: builder-windows_amd64.exe help build

On Macintosh: builder-darwin_amd64 help build

On Linux: builder-linux_amd64 help build

Command Name and Syntax Description

build

SYNTAX:

builder-<platform> build [options]

Build the Flogo app binary or the Flogo engine artifact.

Options Description

-f --file Path to the JSON file for the Flogo app. Use this option only if you want to build a Flogo app binary.

-n --name Name of the binary. If not provided, binary with name

<APPNAME>-<OS_NAME>_<OS_ARCH> will be generated.

-o --output Folder where binary gets created. By default, the binary gets created in the current directory.

-p --platform Build binary for specific platform. Value must be specified in the form of <OS_NAME>/<OS_ARCHITECTURE>, for example, linux/386, linux/amd64. Refer to https://golang.org/doc/install/

source#environment for all supported OS and architecture combinations.

-v --verbose Enable verbose progress and debug output.

(29)

Examples for creating the Flogo app binary

● builder_darwin_amd64 build -f MyAPP.json

● builder_darwin_amd64 build -p linux/amd64 -f /home/tibco/MyApp/

MyAPP.json -n Routing -o /home/tibco/MyApp/binary

Example for creating the Flogo engine binary

builder_darwin_amd64 build -o <path-to-flogoengine_binary>

If you do not provide any options the engine binary will be built with the default name in the format engine-<platform>-<architecture>

To run any compatible app using the <flogoengine_binary_name>, run the following command:

./<flogoengine_binary_name> --app <app-name.json>

Alternatively, you can create the Flogo engine binary by following these steps:

1. Rename <app-name.json> to ^flogo.json

2. Place ^flogo.json in same directory as <flogoengine_binary_name>

3. Run: ./<flogoengine_binary_name>

Building a Generic Flogo Enterprise Engine Binary

When you have multiple apps that use a common set of functionality, for example, if all of them use the same set of connectors, you need not build a separate binary for each app. Instead, you can generate a generic Flogo engine binary that bundles the common connectors. You can then run each app

individually with the generic engine binary.

The high-level benefits of using a Flogo engine binary instead of building one binary per app are:

● You reduce the number of binaries that you need to build

● If you need to make changes to your app after the engine binary is built, you need not re-generate the binary. You can simply run the updated app with the existing flogo engine binary. The

assumption here is that you have not added any new functionality or connectors to your app that were not present when you generated the flogo engine binary, hence not bundles with the engine binary.

● You can provide any <app>.json with the flogo engine binary and run it with the engine binary.

You do not need to generate the binary for the app separately To build the engine binary, run:

./builder-<platform> build

An engine binary with the default name, engine-<platform>-<architecture>, gets generated.

Note that you do not supply the <app>.json name or its file path. This command builds the engine binary without any embedded apps.

All connectors present in the ^/data folder of your Flogo Enterprise installation (all out-of-the-box connectors as well as any extensions you might have explicitly uploaded) are included in the engine binary at the time of its creation.

If you run an app that uses an extension that is not included in the engine binary, you receive a runtime error.

(30)

Once you have generated the engine binary, to run a specific app with the engine binary, use the ^{- -app} option and provide the path to your <app>.json file. For example:

./engine-<platform> --app /home/<user>/apps/<app>.json

Or

To run the above command without specifying the path to your app, rename your app to ^flogo.json. For example:

./engine-<platform> flogo.json

When you run the engine binary with the app, it runs the app. Refer to the builder Command section for more details.

(31)

Building APIs

Flogo Enterprise lets you take an API-first development approach to implement APIs from a GraphQL schema or a Swagger 2.0 specification. Once you upload a GraphQL schema or Swagger file, Flogo Enterprise validates the file and if the validation passes, it automatically creates the Flogo flows and trigger for you.

Using a Swagger Specification

Flogo Enterprise gives you the option to create the Flogo app logic (flows) by importing a Swagger 2.0 specification file. You simply drag and drop a Swagger file into the Flogo Enterprise UI and the flows for your app automatically get created based on the definitions in the Swagger file that you uploaded.

Flogo Enterprise supports Swagger 2.0.

Currently, Flogo Enterprise supports only the JSON format.

Cyclic dependency is not supported while creating flows from Swagger specifications. For example, if you have a type Book which contains an object element of type, Author. The type Author in turn contains an element of type Book which represents the books written by the author. To retreive the Author, it creates a cyclic dependency where the Author object contains the Book object and the Book type in turn contains the Author object.

To upload your Swagger file, follow these steps:

Procedure

1. Open the app details page and click + Create if this is your first flow or if a flow already exists click the Create button.

2. Select From Swagger specifications.

3. Upload your Swagger file by either dragging and dropping it or navigating to it using the browse to upload link.

Flogo Enterprise validates your file extension. If your file extension is ^.json, you see a green check mark and the Upload button appears.

4. Click Upload.

Flogo Enterprise validates the contents of your file and if it passes the validation, it creates the flows based on the definitions in the file. One flow gets created for each method and path combination defined in the file. If there are errors in your file, you get warning messages saying so, but you have the option to continue with creating the flows. If you click Continue, the flows get created for supported methods only. Other issues must be fixed before you can upload the file again.

Currently, the following are not supported:

● PATCH method

● Form data content type

● Same root having a static path and a parameterised path in the file, for

example, ^/foo/bar and ^/foo/{id}. But having two static paths are supported, for example, ^/foo/bar and^/foo/bar1

5. In each flow, do the following:

a) Open the flow by clicking on its name.

b) Click the trigger to open its configuration dialog.

c) Map the following:

(32)

● In the Map to Flow Inputs tab, map the Trigger Output to Flow Input.

● In the Map from Flow Outputs tab, map the Flow Output to Trigger Reply.

Using GraphQL Schema

GraphQL provides a powerful query language for your APIs enabling clients to get the exact data that they need. It has the ability to get data from multiple resources in a single request by aggregating the requested data to form one result set. GraphQL provides a single endpoint for accessing data in terms of types and fields.

Flogo Enterprise provides an out-of-the-box GraphQL Trigger which turns your Flogo app into a GraphQL server implementation. Each Flogo flow in the app acts like a GraphQL field resolver. So the output of the flow, must match the return type of the field in the schema.

Flogo Enterprise allows you to create GraphQL triggers by dragging and dropping your GraphQL schema file or by navigating to the file. A flow gets automatically created for every query and mutation type in your schema. You must then open the flow and define what kind of data you want the flow to return. This saves you the time and effort to programmatically define data structures on the server.

This section assumes that you are familiar with GraphQL. To learn about GraphQL, refer to the GraphQL documentation.

GraphQL server implementation in Flogo Enterprise

To obtain samples of GraphQL schemas and application JSON files, go to https://github.com/project- flogo/graphql.

To use GraphQL in Flogo Enterprise, you must create a GraphQL trigger and add it to your flow. Use one of the methods below to create a GraphQL trigger.

You can use only one schema per app. If you add another GraphQL Trigger to the app, you must use the same original schema.

The implementation of GraphQL server in Flogo Enterprise currently does not return the specified field ordering in a query when a request is received. It does not affect the correctness of the response

returned, but affects the readability and is non-compliant to current specification.

For details on the GraphQL Trigger refer to the "GraphQL Trigger" section in the TIBCO Flogo^® Activities and Triggers Guide.

Creating the trigger during new flow creation

When you create a new flow, you have the option to select From GraphQL Schema which will generate the GraphQL trigger and attach it to the flow. To generate the GraphQL Trigger during flow creation, follow these steps:

1. Create a file with your schema and name it with a ^.gql or ^.graphql extension.

2. In Flogo Enterprise, Open the app details page and click +Create.

3. Select From GraphQL Schema in the Create flows and triggers dialog.

4. Upload your <schema>.gql or <schema>.graphql file by either dragging and dropping it or navigating to it using the browse to upload link. Flogo Enterprise validates the file extension. If your file extension is either ^.gql or ^.graphql, 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 definitions in your schema file. One flow is created for each query or mutation field in your schema.

(33)

Manually adding the trigger to an existing flow

If you have an existing flow, you can manually add a GraphQL trigger to the flow. To do so, follow these steps:

1. Click the icon to the left of your flow.

2. Click GraphQL Trigger in the the Add a Trigger dialog.

3. Enter your GraphQL schema in the Enter a GraphQL Schema for the trigger box. The GraphQL Operation and Resolver For drop down menus automatically get populated based on the definitions in your schema.

4. Select a GraphQL operation from the drop down menu.

5. Select a resolver from the Resolver for drop down menu.

6. Click Continue. You will now see a dialog with two options, CopySchema and Just add the trigger.

Click CopySchema.

Once the trigger is created from the wizard, the trigger configuration is fixed and the Operation Field and Resolver For cannot be changed.

Limitations on constructs in a GraphQL schema

Flogo Enterprise currently does not supports the following GraphQL constructs:

● Custom scalar types

● Custom directives

● Subscription type

● Cyclic dependency in schema. For example, if you have a type ^Book which contains an object element of type, Âuthor. The type Âuthor in turn contains an element of type ^Book which represents the books written by the author. To retreive the Âuthor, it creates a cyclic dependency where the Âuthor object contains the ^Book object and the ^Book type in turn contains the Âuthor object.

(34)

Flogo Runtime

Flogo Enterprise supports runtime configuration and statistics.

Environment Variables

This section lists the environment variables that are associated with the Flogo Enterprise runtime environment.

Environment Variable

Name Default Values Description

FLOGO_HTTP_SERVICE_

PORT N/A Used to set the port number to enable runtime

HTTP service which provides APIs for healthcheck and statistics

FLOGO_LOG_LEVEL INFO Used to set a log level for the Flogo app.

Supported values are:

● INFO

● DEBUG

● WARN

● ERROR

FLOGO_LOG_FORMAT TEXT Used to switch logging format between text and JSON. For example, to use the JSON format, set FLOGO_LOG_FORMAT=JSON ./

<app-name>

Healthcheck API

Flogo Enterprise runtime allows you to enable healthcheck for a Flogo app that is running.

To enable healthcheck for your running app, do the following:

1. Set FLOGO_HTTP_SERVICE_PORT to enable runtime HTTP Service as follows:

FLOGO_HTTP_SERVICE_PORT=<port> ./<app_name>

2. Run the following command:

curl http://localhost:<port>/ping

Currently, healthcheck endpoint returns HTTP status 200 only when all triggers in the application are successfully started. Otherwise it returns HTTP status 500.

CPU and Memory Profiling

If you observe low throughputs or high memory usage, you can enable CPU and/or Memory profiling for your Flogo application. Enabling these profiling will impact performance. Hence, we do not recommend enabling them in a production environment.

Prerequisites

● You must have go version 1.9.0 or higher installed.

● Make sure that the pprof tool is installed on your machine. Refer to https://github.com/google/pprof for more details on the pprof tool.

(35)

Enabling CPU Profiling

To enable CPU profiling, follow these steps:

1. Open a command prompt or terminal.

2. Change directory to the folder in which your app binary is located.

./<app_binary> -cpuprofile <file>

where <file> is the profile file. For example, ./StockService -cpuprofile /home/users/

StockService_cpu.prof

Enabling Memory Profiling

To enable memory profiling, follow these steps:

./<app_binary> -memprofile <file>

where <file> is the profile file. For example, ./StockService -memprofile /home/users/

StockService_mem.prof

Enabling CPU and Memory Profiling in a Single Command

To enable cpu and memory profiling in a single command, follow these steps:

./<app_binary> -memprofile <file> -cpuprofile <file>

Analyzing your profiling data

Once you capture the profiling data, analyze it using the command go tool pprof by running the following command:

go tool pprof <profile file>

Runtime Statistics

You can obtain the runtime statistics in Flogo Enterprise pertaining to the Go language. You can also enable app metrics monitoring using Prometheus.

Go Language Runtime Statistics and Profiling

Flogo Enterprise allows you to gather runtime system statistics for a Flogo App that is running.

Your management port must be set for the , in order to call the API to gather Go language runtime statistics. To set a different management port for your Flogo App, run

FLOGO_HTTP_SERVICE_PORT=<port>./<app-name>/You can use curl to call this API.

To obtain the system statistics on your running app, do the following:

1. From the folder in which your app binary resides, enable the HTTP service using the following command:

FLOGO_HTTP_SERVICE_PORT=<port> ./<app_name>

(36)

curl http://localhost:<port>/debug/vars

The command returns the following statistics:

System Metric

Name Description

cmdline Command-line arguments passed to the application binary cpus Number of logical CPUs usable by the current process goroutines The number of Go routines that currently exist

memstats Memory statistics for the current process. Refer to https://golang.org/pkg/

runtime/#MemStats for more details.

processid System process ID

version Go language version used to build the application

Profiling your application runtime

You can collect and visualize runtime profiling data for Flogo Apps using the pprof tool as explained in https://golang.org/pkg/runtime/pprof/.

Endpoint Description

/debug/pprof List all profiles /debug/pprof/

profile Profile current CPU usage. By default, it is profiled for every 30 seconds. To change the profiling interval, set seconds query parameter to a desired value. For example,

go tool pprof http://localhost:<port>/debug/pprof/profile?

seconds=15

/debug/pprof/

heap A sampling of memory allocations of live objects. For example,

go tool pprof http://localhost:<port>/debug/pprof/heap

/debug/pprof/

goroutine Stack traces of all current Go routines. For example,

go tool pprof http://localhost:<port>/debug/pprof/goroutine

/debug/pprof/

trace A trace of execution of the current program. For example,

go tool pprof http://localhost:<port>/debug/pprof/trace

(37)

Application Metrics

For REST APIs, the following methods can be used to enable and disable application metrics at runtime.

Method Description Status Code

POST /app/metrics Enable instrumentation metrics

collection 200 - If successfully enabled

409 - If the metrics collection is already enabled

DELETE /app/metrics Disable metrics collection 200 - If successfully disabled 404 - If metrics collection is not enabled

GET /app/metrics/flows Retrieve metrics for all flows 200 - Successfully returned metrics data

404 - If the metrics collection is not enabled

500 - If there is an issue when returning metrics data GET /app/metrics/flow/

<flowname> Retrieve metrics for a given

flow 200 - Successfully returned

metrics data

400 - If the flow name is incorrect

500 - If there is an issue returning metrics data GET /app/metrics/flow/

<flowname>/activities Retrieve metrics for all

activities in a given flow 200 - Successfully returned metrics data

400 - If the flow name is incorrect

500 - If there is an issue returning the metrics data

Enabling Application Metrics

Set the FLOGO_HTTP_SERVICE_PORT environment variable to point to the port number of the HTTP service that provides APIs for collecting the application metrics. This will enable the runtime HTTP service.

To do so run the following:

(38)

Procedure

1. Run the following:

FLOGO_HTTP_SERVICE_PORT=<port> ./<application-binary>

2. Run the ^curl command for the appropriate REST method. Refer to Application Statistics for details on each method. Some examples are:

curl -X POST http://localhost:7777/app/metrics curl -X GET http://localhost:7777/app/metrics/flows curl -X DELETE http://localhost:7777/app/metrics

Enabling statistics collection using environment variables

To enable metrics collection through environment variable, do the following. FLOGO_APP_METRICS must be sepcified:

Procedure

1. Run the following:

FLOGO_HTTP_SERVICE_PORT=<port> FLOGO_APP_METRICS=true ./<appname>

2. Run the ^curl command for the appropriate REST method. Refer to Application Statistics for details on each method. Some examples are:

curl -X GET http://localhost:7777/app/metrics/flows curl -X DELETE http://localhost:7777/app/metrics/flows

Examples that shows how to retrieve specific metrics for an app

The following is an example of how you would run the above steps for a fictitious app named REST_Echo.

FLOGO_HTTP_SERVICE_PORT=7777 FLOGO_APP_METRICS=true ./REST_Echo-darwin-amd64

curl -X GET http://localhost:7777/app/metrics/flows {"app_name":"REST_Echo","app_version":"1.0.0","flows":

[{"started":127639,"completed":126784,"failed":0,"avg_exec_time":0,"min_exec_t ime":0,"max_exec_time":4,"flow_name":"PostBooks"}]}

curl -X GET http://localhost:7777/app/metrics/flow/PostBooks/activities {"app_name":"REST_Echo","app_version":"1.0.0","tasks":

[{"started":127389,"completed":126908,"failed":0,"avg_exec_time":0,"min_exec_t ime":0,"max_exec_time":4,"flow_name":"PostBooks","task_name":"Return"}]}

Fields returned in the response from the API call

The following table describes the fields that can be returned in the response you receive when you make an API call:

Flow

app_name Name of the application app_version Version of the application

(39)

flow_name Name of the flow

started Total number of times a given flow is started completed Total number of times a given flow is completed failed Total number of times a given flow has failed

avg_exec_time Average execution time of a given flow for successfully completed executions min_exec_time Minimum execution time for a given flow

max_exec_time Maximum execution time for a given flow Activity

app_name Name of the application

app_version Version of the application

flow_name Name of the flow

activity_name Name of the activity

started Total number of times a given activity is started completed Total number of times a given activity is completed failed Total number of times a given activity has failed

avg_exec_time Average execution time of a given activity for successfully completed executions

min_exec_time Minimum execution time for a given activity max_exec_time Maximum execution time for a given activity

Prometheus

Flogo Enterprise supports integration with Prometheus for app metrics monitoring. Prometheus is a monitoring tool which helps in analyzing the app metrics for flows and activities.

Prometheus servers scrape data from the HTTP /metrics endpoint of the apps.

Prometheus integrates with Grafana which provides better visual anlytics.

Flogo apps expose the following flow and activity metrics to Prometheus. These metrics are measured in milliseconds:

(40)

Labels Description

flogo_flow_metrics: Used for flow-level queries

ApplicationName Name of application ApplicationVersion Version of application

FlowName Name of flow

Started Total number of times flow is started Completed Total number of times flow is completed Failed Total number of times flow is failed flogo_activity_metrics: Used for activity-level queries

ApplicationName Name of application ApplicationVersion Version of application

FlowName Name of flow

ActivityName Name of Activity

Started Total number of times activity is started in given flow Completed Total number of times activity is completed in given flow Failed Total number of times activity is failed in given flow

For a list of some often-used flow-level queries, refer to the section, Often-Used Queries.

Using Prometheus to Analyze Flogo App Metrics

To enable Prometheus monitoring of Flogo apps, run the following:

FLOGO_HTTP_SERVICE_PORT=7779 FLOGO_APP_METRICS_PROMETHEUS=true ./<app-binary>

Setting FLOGO_APP_METRICS_PROMETHEUS variable to true enables Prometheus monitoring of Flogo apps. The variable, FLOGO_HTTP_SERVICE_PORT, is used to set the port number on which the Prometheus endpoint is available.

Use the following endpoint URL in Prometheus server configuration: http://

<APP_HOST_IP>:<FLOGO_HTTP_SERVICE_PORT>/metrics

for example, http:// 192.0.2.0:7779/metrics

TIBCO Flogo® Enterprise User's Guide

User's Guide

Software Release 2.6.0

May 2019

Contents

TIBCO Documentation and Support Services

Overview

Concepts

Tutorial on Building a Simple REST Service

Developing TIBCO Flogo

Apps

Creating a TIBCO Flogo

App

Reverting Changes to an App

Building the App

Building the App From the CLI

Building a Generic Flogo Enterprise Engine Binary

Building APIs

Using a Swagger Specification

Using GraphQL Schema

Flogo Runtime

Environment Variables

Healthcheck API

CPU and Memory Profiling

Runtime Statistics

Go Language Runtime Statistics and Profiling

Application Metrics