TIBCO Cloud™

(1)

(PAYG)

User's Guide

Software Release 2.8.0

January 2020

(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, TIBCO Cloud, 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)

Figures

Trigger View . . . .49 Flow View . . . .50

(8)

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 Cloud^™ Integration - Flogo^® (PAYG) is available on the TIBCO Cloud Integration - Flogo (PAYG) Product Documentation page.

Product-Specific Documentation

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

● TIBCO Cloud^™ Integration - Flogo^® (PAYG) Release Notes

● TIBCO Cloud^™ Integration - Flogo^® (PAYG) Getting Started

● TIBCO Cloud^™ Integration - Flogo^® (PAYG) User's Guide

● TIBCO Cloud^™ Integration - Flogo^® (PAYG) 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.

(9)

Overview

To use TIBCO Cloud Integration - Flogo (PAYG):

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

Concepts

The following describes some concepts that are used in the TIBCO Cloud Integration - Flogo (PAYG) 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. TIBCO Cloud Integration - Flogo (PAYG) 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.

(10)

Developing TIBCO Flogo

^®

Apps

TIBCO Cloud Integration - Flogo (PAYG) offers a wizard driven approach to app development. You can create apps in TIBCO Cloud Integration - Flogo (PAYG) using only a browser.

For more information about Project Flogo^™, go to http://flogo.io/.

Creating a TIBCO Flogo

^®

App

You can create a Flogo^® App from the Apps page in TIBCO Cloud^™ Integration - Flogo^® (PAYG).

Follow these steps to create an app:

Procedure

1. Open the Apps page in TIBCO Cloud Integration - Flogo (PAYG).

2. Click Create.

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.

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.

Reverting Changes to an App

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

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

Procedure

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

2. Click . The is activated only if you have made edits to the app after the last , but have not 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 - Flogo^®. 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 TIBCO Cloud Integration - Flogo (PAYG).

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

Follow these steps to build an app:

(11)

For app binaries that were created in TIBCO Cloud Integration - Flogo (PAYG) 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

1. Open the Apps page in TIBCO Cloud Integration - Flogo (PAYG).

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

3. Click Build.

4. Click the build target 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 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>

Renaming an App

You can rename an existing app.

To rename an existing app, do the following:

Procedure

1. Open the Apps page or the app details page by clicking on the app.

2. Click the menu.

3. Select Rename from the drop-down menu.

The Change app name dialog opens.

4. Enter a new name for the app in the Give a new name text box. Make sure that the app name is unique within the app.

5. Click Update.

The app name gets updated.

(12)

Searching for a Category or Activity

You can search for an activity or category by entering the activity name or category name in the Search activity and category box in the Add Activity dialog.

You can enter either the full name of the activity or category or you can enter its partial name (a string of characters appearing in the name) in the Search activity and category box.

● All categories whose names either wholly match the search string or contain the partial search string in their name get displayed.

● When a category displays in the search result, only those activities in the category whose name contain the search string get displayed. If the category also contains other activities whose names do not match or contain the search string, such activities are not displayed.

● For any activity whose name wholly or partially matches the search string, the category that contains that activity is displayed. For example, if you enter "delete" in the search box, since there are activities whose name contains the string "delete" in Marketo, Salesforce, Zoho-CRM, and so on, all these categories are displayed, even though the category names themselves do not contain the string "delete".

(13)

Building APIs

TIBCO Cloud Integration - Flogo (PAYG) 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, TIBCO Cloud Integration - Flogo (PAYG) validates the file and if the validation passes, it automatically creates the Flogo flows and trigger for you.

Using a Swagger Specification

TIBCO Cloud Integration - Flogo (PAYG) 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 TIBCO Cloud Integration - Flogo (PAYG) UI and the flows for your app automatically get created based on the definitions in the Swagger file that you uploaded.

TIBCO Cloud Integration - Flogo (PAYG) supports Swagger 2.0.

Currently, TIBCO Cloud Integration - Flogo (PAYG) 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.

TIBCO Cloud Integration - Flogo (PAYG) validates your file extension. If your file extension is ^.json, you see a green check mark and the Upload button appears.

4. Click Upload.

TIBCO Cloud Integration - Flogo (PAYG) 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.

(14)

c) Map the following:

● 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.

Configuring the REST Reply

When creating an app from a REST Swagger API specification, the ReceiveHTTPMessage reply data type is set to ^any by default. To explicitly configure the reply type add a ConfigureHTTPResponse activity in the flow. This activity must immediately precede the Return activity in the flow.

You can configure custom codes that you want to use in the HTTP reply in the Reply Settings tab of the ReceiveHTTPMessage trigger.

Follow these steps to configure your HTTP reply:

Procedure

1. In the Reply Settings tab of the ReceiveHTTPMessage REST trigger, configure the custom codes that you want to use. Refer to the section, "REST Trigger" in the Activities and Triggers Guide.

2. Add a ConfigureHTTPResponse activity immediately preceding the Return activity in the flow.

3. Configure the ConfigureHTTPResponse activity as follows:

a) In the Settings tab:

1. If your flow is attached to multiple REST triggers, select the trigger in which you have configured the code you want to use from the Trigger Name drop-down menu. The Trigger Name field does not display if your flow is attached to only one REST trigger.

2. Select a response code from the Code field menu. Only the codes configured in the selected trigger are displayed in the menu.

b) The Input tab displays the schema for the response code. Map the elements or manually enter a value for the elements.

4. Configure the Return activity by mapping the code and responseBody (which is currently of data type ^any).

(15)

5. In the Map from Flow Outputs tab in the ReceiveHTTPMessage trigger, map the code and responseBody to the corresponding elements from the flow output.

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.

TIBCO Cloud Integration - Flogo (PAYG) 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.

TIBCO Cloud Integration - Flogo (PAYG) 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 TIBCO Cloud Integration - Flogo (PAYG)

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

To use GraphQL in TIBCO Cloud Integration - Flogo (PAYG), you must create a GraphQL trigger. 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 TIBCO Cloud Integration - Flogo (PAYG) 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.

(16)

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. 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 TIBCO Cloud Integration - Flogo (PAYG), 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. TIBCO Cloud Integration - Flogo (PAYG) 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. TIBCO Cloud Integration - Flogo (PAYG) 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.

If required, you can later make changes to the GraphQL schema file and upload it using the GraphQL trigger without creating a new flow. For more information, see the "GraphQL Trigger" section in the TIBCO Flogo^® Activities and Triggers Guide.

Manually adding an existing flow to the trigger

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.

If required, you can later make changes to the GraphQL schema file and upload it using the GraphQL trigger without creating a new flow. For more information, see the "GraphQL Trigger" section in the TIBCO Flogo^® Activities and Triggers Guide.

Limitations on constructs in a GraphQL schema

TIBCO Cloud Integration - Flogo (PAYG) currently does not supports the following GraphQL constructs:

● Custom scalar types

● Custom directives

(17)

● 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.

(18)

Flogo Runtime

TIBCO Cloud Integration - Flogo (PAYG) supports runtime configuration and statistics.

Environment Variables

This section lists the environment variables that are associated with the TIBCO Cloud Integration - Flogo (PAYG) 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>

FLOGO_MAPPING_SKIP

_MISSING False By default, it is set to false. When mapping

objects, if one or more elements is missing in either the source or target object, the mapper throws an error when

FLOGO_MAPPING_SKIP_MISSING is set to ^false. Set this environment variable to ^true if you would like to return a null instead of receiving an error.

Healthcheck API

TIBCO Cloud Integration - Flogo (PAYG) 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.

(19)

Runtime Statistics

You can obtain the runtime statistics in TIBCO Cloud Integration - Flogo (PAYG) pertaining to the Go language. You can also enable app metrics monitoring using Prometheus.

Go Language Runtime Statistics and Profiling

TIBCO Cloud Integration - Flogo (PAYG) 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>

2. Run the following command:

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?

(20)

Endpoint Description /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

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

(21)

Method Description Status Code 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:

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

(22)

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 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

(23)

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

TIBCO Cloud Integration - Flogo (PAYG) 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:

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

(24)

Labels Description

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

Often-Used Queries

Prometheus uses the PromQL query language. This section lists some of the most commonly and often- used queries at the flow-level.

Flow-level Queries

To Get this Metric Use this Query Total number of flows that got

successfully executed per application

count(flogo_flow_metrics{Failed="0"}) by (ApplicationName)

Total number of flows that failed per

application count(flogo_flow_metrics{Failed!="0"}) by (ApplicationName)

Total number of flows that executed successfully across all apps

(when you are collecting metrics for multiple apps)

count(flogo_flow_metrics{Failed="0"})

Total number of flows that failed across all apps

count(flogo_flow_metrics{Failed!="0"}

Total time taken by flows which got

executed successfully sum(flogo_flow_metrics{Failed="0"}) by (ApplicationName, FlowName)

(25)

To Get this Metric Use this Query Total time taken by flows which

failed sum(flogo_flow_metrics{Failed!="0"}) by

(ApplicationName, FlowName)

Minimum time taken by the flows that got executed successfully (what was the minimum time taken by a flow from amongst the flows that executed successfully)

min(flogo_flow_metrics{Failed="0"}) by (ApplicationName, FlowName)

Minimum time taken by flows which

failed min(flogo_flow_metrics{Failed!="0"}) by

Maximum time taken by flows

which executed successfully max(flogo_flow_metrics{Failed="0"}) by (ApplicationName, FlowName)

Maximum time taken by flows

which failed max(flogo_flow_metrics{Failed!="0"}) by (ApplicationName, FlowName)

Average time taken by flows which

executed successfully avg(flogo_flow_metrics{Failed="0"}) by (ApplicationName, FlowName)

Average time taken by flows which

failed avg(flogo_flow_metrics{Failed!="0"}) by

Activity-level Queries

To Get this Metric Use this Query Total number of activities that got

successfully executed per flow and application

count(flogo_activity_metrics{Failed="0"}) by (ApplicationName,FlowName)

Total number of activities that failed

per flow and application count(flogo_activity_metrics{Failed!="0"}) by (ApplicationName,FlowName)

Total number of activities that executed successfully across all apps (when you are collecting metrics for multiple apps)

count(flogo_activity_metrics{Failed="0"})

Total number of activities that failed across all apps

count(flogo_activity_metrics{Failed!="0"})

Total time taken by activities which got executed successfully per app and flow

sum(flogo_activity_metrics{Failed="0"}) by (ApplicationName, FlowName)

(26)

To Get this Metric Use this Query Total time taken by activities which

failed per app and flow sum(flogo_activity_metrics{Failed!="0"}) by (ApplicationName, FlowName)

Minimum time taken by the activity that got executed successfully within a given flow and app

min(flogo_activity_metrics{Failed="0"}) by (ApplicationName, FlowName,ActivityName)

Minimum time taken by a failed

activity within a given flow and app min(flogo_activity_metrics{Failed!="0"}) by (ApplicationName, FlowName,ActivityName)

Maximum time taken by an activity which executed successfully within a given flow and app

max(flogo_activity_metrics{Failed="0"}) by (ApplicationName, FlowName,ActivityName)

Maximum time taken by an activity which failed within a given flow and app

max(flogo_activity_metrics{Failed!="0"}) by (ApplicationName, FlowName,ActivityName)

Average time taken by an activity which executed successfully within a given flow and app

avg(flogo_activity_metrics{Failed="0"}) by (ApplicationName, FlowName,ActivityName)

Average time taken by an activity which failed within a given flow and app

avg(flogo_activity_metrics{Failed!="0"}) by (ApplicationName, FlowName,ActivityName)

Application Tracing

Application tracing allows you to log information when a program is executing. The trace log can then be used for diagnostic purposes such as debugging failures in the program execution.

Tracing is used to help you identify issues with your application (performance of the app or simply debugging an issue) instead of going through stack traces. The use of tracing is particularly useful in a distributed microservice architecture environment where all the apps are instrumented by some kind of tracing framework and while the tracing framework runs in the background, you can monitor each trace in the UI. You can use that to track any abnormalities or issues to identify the location of the problem.

Some Considerations

Keep the following in mind when using the tracing capability in TIBCO Cloud Integration - Flogo (PAYG):

● At any given point of time only one tracer can be registered - if you try to register multiple tracers, then only the first one that you register is accepted and used at runtime to trace all the flow's activities.

● All the traces starts at the flow level. There are two relations between spans - a span is either the child of a parent span or the span is a span that follows (comes after) another span. You should be able to see all the operations and the traces for the flows and activities that are part of an

application.

● Tracing can be done across apps by passing the tracing context from one app to another. To trace across multiple apps, you must make sure that all apps are instrumented with similar sort of tracing frameworks, for example, OpenTracing semantics so that they understand the framework language,

(27)

otherwise it will not be possible for you to get a holistic following of the entire trace through multiple services.

● When looping is enabled for an activity, each loop is considered one span since each loop calls the server which triggers a server flow.

● If a span is passed on to the trigger, then that span becomes the parent span. You should be able to see how much time is taken between the time the event is received by the trigger and the time the trigger replies back. This only works for triggers that support the extraction of the context from the underlying technology, for instance triggers that support HTTP headers.

The ReceiveHTTPMessage REST trigger and InvokeRESTService activity are supported for this release where the REST trigger is able to extract the context from the request and

InvokeRESTService activity is able to inject the context into the request. If two Flogo apps are both Opentracing-enabled, when one app calls the other, you can see the chain of events (invocation and how much time is taken by each invocation) in the Jaeger UI. If app A is calling app B, the total request time taken by app A is the cumulative of the time taken by all activities in app A plus the time taken by the service that it calls. If you open up each invocation separately, you can see the details of how much time was taken by each activity in that invocation.

● Triggers that support span (for instance the REST trigger) are always the parent, so any flows that are attached to that trigger are always the child of the trigger span. Trigger span is completed only after the request goes to the flow and the flow returns.

● A subflow becomes a child of the activity from which it is called.

OpenTracing

TIBCO Cloud Integration - Flogo (PAYG) supports OpenTracing for application tracing.

Jaeger

TIBCO Cloud Integration - Flogo (PAYG) provides an implementation of the OpenTracing framework using the Jaeger backend. In TIBCO Cloud Integration - Flogo (PAYG), the Flogo^® App binary is built with Jaeger implementation and can be enabled by setting the FLOGO_APP_MONITORING_OT_JAEGER

environment variable to ^true. You can track how the flow went through, execution time for each activity, or in case of failure, the cause of the failure.

Each app is displayed as a service in the Jaeger UI. In TIBCO Cloud Integration - Flogo (PAYG), each flow is one operation (trace) and each activity in the flow is a span of the trace. A trace is the complete lifecycle of a group of spans. The flow is the root span and its activities are its child spans.

Pre-requisites The following pre-requisites must be met before using the tracing capability in TIBCO Cloud Integration - Flogo (PAYG):

● By default, Jaeger is not enabled in TIBCO Cloud Integration - Flogo (PAYG), hence tracing is not enabled. To enable Jaeger, set the FLOGO_APP_MONITORING_OT_JAEGER environment variable to

true.

● Ensure that the Jaeger server is installed, running, and accessible to TIBCO Cloud Integration - Flogo (PAYG).

● If your Jaegar server is running on a machine other than the machine on which your app resides, be sure to set the JAEGER_AGENT_HOST and the JAEGER_AGENT_PORT environment variables. Refer to the https://github.com/jaegertracing/jaeger-client-go#environment-variables page for the

environment variables that you can set.

TIBCO Cloud Integration - Flogo (PAYG)-Related Tags in Jaegar

In OpenTracing, each trace and span have their own tags. Tags are useful for filtering traces, for example if you want to search for a specific trace or time interval.

(28)

Adding your own custom tags for any one span (activity) only is currently not supported. Any custom tags that you create will be added to all spans and traces.

TIBCO Cloud Integration - Flogo (PAYG) introduces the following Flogo-specific tags:

For flows

flow_id Unique instance IDs that are generated by the

Flogo engine. They are used to identify specific instances of a flow (such as when the same flow is triggered multiple times)

For activities

task_name Name of activity

taskInstance_id Unique instance ID that are generated by the Flogo engine. This identity is used to identify the specific instance of an activity when an activity is iterated multiple times. This ID is used in looping contructs such as iterator or Repeat while true.

For subflows

parent_flow Name of the parent flow

parent_flow_id Unique ID of the parent flow

flow_name Name of the subflow

The tag values are automatically generated by the TIBCO Cloud Integration - Flogo (PAYG) runtime.

You cannot override the default values. You have the option to set custom tags by setting them in the environment variable JAEGER_TAGS as key/value pair. Keep in mind that these tags will be added to all spans and traces.

Refer to the https://github.com/jaegertracing/jaeger-client-go#environment-variables page for the environment variables that you can set.

(29)

Using Connectors

The TIBCO Cloud Integration - Flogo (PAYG) offers the ability to use connectors that have enterprise support and also connectors that are custom developed extensions.

This section is applicable only if you have uploaded custom extensions for connectors. The Extensions tab displays your uploaded extensions.

To use the TIBCO Flogo connectors, follow these steps:

1. Create one or more connections.

2. If you do not already have an app, create an app.

3. Create a flow.

4. Add the activities pertaining to the connector you use as needed.

5. Build the app.

Creating Connections

You must create connections before using the connectors in a flow. TIBCO Cloud Integration - Flogo (PAYG) uses the configuration provided in these connections to connect to the respective app, data sources, systems, or SaaS.

Make sure that the pop-up blocker in your browser is configured to always allow pop-ups from an app site. On MacOS, clicking the link to the site will result in the connection details page hanging, so make sure to select the radio button for "Always allow pop-ups from <site>."

Prerequisites

You must have valid accounts for the SaaS apps to which you want to connect.

To create a connection, click the Connections tab on the TIBCO Cloud Integration - Flogo (PAYG) page.

If this is the first connection that you are creating, the Connections page displays the connector tiles from which you can create connections. Follow these steps to create a connection using a connector tile:

1. Click the connector tile for which you want to create a connection.

2. Follow the instructions when prompted. .

If you have existing connections and want to add a new connection, do the following from the Connections page:

1. Click Add Connection.

2. Click the connector tile for which you want to create a connection.

3. Follow the instructions when prompted.

Editing or Deleting Existing Connections

You can edit the name and other settings of your connection or delete the connection.

To edit or delete an existing connection, follow these steps:

Procedure

1. In TIBCO Cloud Integration - Flogo (PAYG), click the Connections tab to open the page.

(30)

3. Click Edit to edit the connection details or click Delete to delete the connection.

(31)

Flows

Each flow represents specific business logic in an app. An app can have one or more flows. A flow contains one or more activities. The flow is activated by a trigger. A new flow can be created only from the app details page. It can be created from either the Flow view or the Trigger view of the app details page.

Each flow is attached to one or more triggers. You can attach the flow to a trigger at the time of flow creation (by selecting the Start with a trigger option) or create a blank flow without a trigger (by selecting Configure flow inputs and outputs) to begin with and attach it to one or more triggers at any time after the flow has been created.

After you have created the flow, you can test it without having to activate the trigger. See the Flow Tester section for details on using the flow tester.

Creating a Flow

Every app has at least one flow. Each flow can be attached to one or more triggers. You have the option to begin by creating a blank flow (flow without a trigger) too and attaching the flow to one or more triggers at a later time. Use the +Create link on the app page to create the first flow in an app. If there are existing flows in an app, click the Create button to create additional flows attached to a new trigger or to create a flow that is attached to the existing trigger, hover over the trigger and click New flow.

Prerequisites

Before creating a flow for connectors, make sure that you have created the necessary connections.

If an app has multiple triggers that require a port to be specified, for example REST and/or GraphQL triggers, make sure that the port number is unique for each trigger. Two triggers in the same app cannot run on the same port.

(32)

A flow can be attached to multiple triggers. For such flows, you cannot disable a trigger, specify a particular trigger to execute, or specify the order in which the triggers execute. When a flow executes, all triggers get initialized in the order that they appear within the flow.

When using the Lambda, S3, or Gateway triggers, keep the following in mind:

● An app can contain only one Lambda trigger. An app that has a Lambda trigger cannot contain any other triggers including another Lambda trigger. Also, the Lambda trigger supports only one handler per trigger so it can have only one flow attached to it. However, the apps that contain a Lambda trigger can contain blank flows that can serve as subflows for the flow attached to the Lambda trigger.

● You can have only one S3 trigger in an app. An app that has an S3 trigger cannot contain any other triggers including another S3 trigger. The S3 trigger supports multiple handlers (flows), so you can have multiple flows in the app that are attached to the same S3 trigger. You can also have blank flows in the app which can serve as subflows for the flows that are attached to the S3 trigger.

● You can have only one Gateway trigger in an app. An app that has an Gateway trigger cannot contain any other triggers including another Gateway trigger. The Gateway trigger supports multiple handlers (flows), so you can have multiple flows in the app that are attached to the same Gateway trigger. You can also have blank flows in the app which can serve as subflows for the flows that are attached to the Gateway trigger.

The output of a trigger provides the input to the flow. Hence, it must be mapped to the flow input. In the absence of a trigger, when creating a flow, there must be a well-defined contract within the flow which specifies the input to the flow and the output expected after the flow completes execution. You define this contract in the Flow Inputs & Outputs dialog. The Flow Inputs & Ouputs contract works as a bridge between the flow and the trigger, hence every trigger has to be configured to map its output to the Input parameters defined in Flow Inputs & Ouputs.

A Return activity is not added by default. Depending on your requirements, you must add the Return activity manually. For example, if any trigger needs to send a response back to a server, its output must be mapped to the output of the Return activity in the flow.

Follow these steps to create a flow:

Procedure

1. Click an app name on the Apps page in TIBCO Cloud Integration - Flogo (PAYG) to open its page.

2. Click the +Create if this is the first flow in the app. If one or more flows exist, click the Create button.

The Create flows and triggers dialog opens.

3. Enter a name for the flow in the Name text box.

Flow names within an app must be unique. An app cannot contain two flows with the same name.

4. Optionally, enter a brief description of what the flow does in the Description text box. The New flow button is selected by default.

To create a flow from a Swagger specification, refer to Using a Swagger Specification for details. To create a flow from a GraphQL schema, refer to Using a GraphQL Schema for details. To create a flow from a gRPC Protobuf, see Using gRPC.

You will be prompted to select one of the following options:

(33)

● Start with a trigger - If you know the trigger with which you want to activate the flow, select this option. If this is the first flow, the Trigger catalog opens. Select a trigger from the catalog. Refer to the appropriate section under Starting with a Trigger for more details on the the type of trigger that you want to create. If there are existing flows attached to triggers, you get a dialog which gives you an option to either use an existing trigger or use a new trigger that has not been used in an existing flow within the app.

● Configure flow inputs and outputs - Select this option if you know the algorithm for the flow, but do not yet know the circumstances that will cause the flow to execute. It will create a blank flow that is not attached to any trigger. Flow inputs and outputs create a contract between the trigger and the flow. When you create a trigger, you must map the output of the trigger to the input to the flow. This contract serves as a bridge between the trigger and the flow. You have the option to attach your flow to one or more triggers at any later time after the flow has been created.

A flow gets created and it is attached to the selected trigger.

Selecting a Trigger When Creating a New Flow

When creating a new flow, you have the option to either select an existing trigger if one exists or if there are no exiting triggers, then you have the option to select one from the triggers catalog.

Trigger configuration fields are categorized into two groups as explained below. A single trigger can be associated with multiple handlers.

● Trigger Settings - these settings are common to the trigger across all flows that use that trigger. If and when a flow attached to the trigger changes any Trigger Settings field, the change gets propagated to all flows attached to the trigger. A warning message gets displayed saying so and asking you to confirm before the changes are committed.

● Handler Settings - these settings are applicable to a specific flow attached to the trigger. Hence, each flow can set its own values for the Handler Settings fields in the trigger. To do so, open the flow and click on the trigger to open its configuration dialog. Click the Settings tab and edit the fields in the Handler Settings section.

Deciding when to create a new trigger when there is an exsiting trigger of the same type There may be cases when a specific type of trigger already exists, for example, there might be a REST trigger that already exists. When creating a new REST flow, you will be prompted to select the existing REST trigger or create a new trigger by selecting it from the triggers catalog. If you want a REST trigger with a different trigger setting than the one that already exists, maybe a different port or different security options, you must select the Create new option and select the trigger from the ensuing trigger catalog. This will create a new REST trigger and attach your new flow to it.

TIBCO Cloud™

(PAYG)

User's Guide

Software Release 2.8.0

January 2020

Contents

Figures

TIBCO Documentation and Support Services

Overview

Concepts

Developing TIBCO Flogo

Apps

Creating a TIBCO Flogo

App

Reverting Changes to an App

Building the App

Renaming an App

Searching for a Category or Activity

Building APIs

Using a Swagger Specification

Configuring the REST Reply

Using GraphQL Schema

Flogo Runtime

Environment Variables

Healthcheck API

Runtime Statistics

Go Language Runtime Statistics and Profiling

Application Metrics

Application Tracing

OpenTracing

Using Connectors

Creating Connections

Editing or Deleting Existing Connections

Flows

Creating a Flow

Selecting a Trigger When Creating a New Flow