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

(1)

(PAYG)

User's Guide

Version 2.11.0

January 2021

(2)

Figures

Trigger View . . . .26 Flow View . . . .27

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

Product-Specific Documentation

Documentation for TIBCO Cloud^™ Integration - Flogo^® (PAYG) is available on the TIBCO Cloud Integration - Flogo (PAYG) Product Documentation page.

The following documents 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)

Introduction

Concepts

This section describes the main concepts 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 flows.

Trigger

Triggers receive events from external sources such as Kafka, Salesforce, GraphQL and so on. Handlers residing in the triggers, dispatch events to flows. 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 flow allows you to implement the business logic as a process. You can visually design and test the flows using the Web UI. A flow can consist of one or more activities that perform a specific task. Activities are linked in order to facilitate flow of data between them and can contain conditional logic for branching.

Each flow is also connected to a default error handler. A Flogo app can have one or more flows. A flow can be activated by one or more Triggers within the app.

Activity

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

How TIBCO Cloud Integration - Flogo (PAYG) Works

The trigger consists of one or more handlers that serve as the means of communication between the trigger and the flow. When the trigger receives an event, the trigger uses the respective flow handlers to pass the data from the event on to the flow in the form of flow input. The business logic in the flow then can use the event data coming in through the flow input. When the trigger expects a reply from the flow, the data from the flow is passed on to the trigger in the form of flow output. A flow can contain one or more conditional branches.

In a nutshell, to use TIBCO Cloud Integration - Flogo (PAYG), you have to follow these steps:

(10)

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.

Creating your First REST API

This tutorial walks you through building a simple REST service in TIBCO Cloud^™ Integration - Flogo^® (PAYG). It 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 on the flight for the passenger requesting it. 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 that you configure to log a custom message when a request has been received

successfully. The LogMessage activity has two branches. Each branch must have its own Return activity as the last activity in the branch.

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 Return 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 with the Class to Economy.

Creating the JSON Schema for REST Request and Response

In this tutorial, a simple JSON schema is created for the REST request that the service receives and the response that the service sends back. The following is the structure of the JSON schema used in this tutorial.

This JSON message is converted internally into a JSON schema:

{

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

"DepartureDate" : "2017-05-27",

(11)

"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 airline flight reservation service REST app in this tutorial are as follows:

1. Create a New TIBCO Flogo^® App

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

3. Map Trigger Output to Flow Input. This is the bridge between the trigger and the flow where the trigger

passes on the request data to the flow input.

4. Map Flow Output to Trigger Reply. This is the bridge between the flow output and the response that the

trigger sends back to the HTTP request it received. After the flow has finished executing, the output of the flow execution is passed back to the trigger by the Return activity. Hence, we map the flow output to the trigger reply. This mapping is done in the trigger configuration.

5. Add a Log Message Activity to the Flow and configure a message that the activity must log in the logs

for the app as soon as it receives a request.

6. Add the First Branch and Configure It to accept any last name that appears in the REST request.

7. Add a Second Branch to Check for Last Name "Jones". If the last name of the passenger is "Jones", this

branch is executed and the passenger is placed in Business Class.

8. Validate the App to make sure that there are no errors or warnings in any flows or activities.

9. Build the App

10.Test the App

Step 1: Create a New TIBCO Flogo^® App

Create a new TIBCO Flogo^® App in TIBCO Cloud Integration - Flogo (PAYG).

Follow these steps to create a new app:

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

2. Click Create/Import app.

3. By default, a Flogo app is named New_Flogo_App_<sequential-number> where the sequential-number is the next number of a new app being created. Click the default app name next to the Flogo app icon to make it editable. Edit the app name to ^FlightApp and click anywhere outside the name to persist your change.

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. The Flow option is selected by default in the Add triggers and flows dialog.

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

(12)

3. Click Start with a trigger.

4. Click the Receive HTTP Message card in the Triggers catalog.

(13)

5. In the Configure trigger: ReceiveHTTPMessage dialog, do the following:

a. Select POST as the Method.

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

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

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)

d. Click Continue.

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

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

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

● 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 attached to a REST trigger.

Your flow should look similar to the following:

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

(15)

Step 3: Map Trigger Output to Flow Input

When TIBCO Cloud Integration - Flogo (PAYG) receives a flight booking request from a passenger (a REST request), the data from the request is output by the ReceiveHTTPMessage REST trigger. For the request to be processed, this output must be consumed by the flow in the form of flow input. Hence, you must map the trigger output to the flow input.

To do so, follow these steps:

1. Click the REST 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 under Trigger Output to map the headers.

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

5. Click Save.

Step 4: Map Flow Output to Trigger Reply

When the flow has finished executing, its output must be sent back to the trigger for the trigger to send a reply to the REST request initiator. Hence, the flow output data must be mapped to the trigger reply which returns the result of the flow execution to the REST request initiator.

To map the flow output to the trigger reply:

1. Click the Map from Flow Outputs tab.

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

b. Click $flow > code under Flow Output.

c. Click data under Trigger Reply.

d. Click $flow > data under Flow Output.

e. Click Save to save your changes.

f. Click x to close the dialog.

The flow should look like the following:

(16)

Step 5: 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:

1. Add a new LogMessage activity from the General tab and configure it. To do so,

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

b. In the Add Activity dialog, click General, then click Log Message.

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

c. Configure a message to be logged by the LogMessage activity when the flow receives the input from the request that the trigger received and passed on to the flow. To configure the message, expand the string category under Functions and click concat(str, str2) to add this function to the message text box.

d. Select str in the and replace it by entering "We have received a message from " (include the quotes too).

e. Replace str2 with the last name of the passenger who booked the flight. The last name of the passenger is passed on from the trigger to the flow. We had mapped this trigger output to flow input in step 3 above. Hence it is now available for mapping under $flow in Upstream Output.

(17)

To map the LastName do the following:

1. Select str2.

2. Expand $flow > body under Upstream Output.

3. Click LastName.

4. Click Save to save your changes.

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

Your flow should now look like the following:

Step 6: Add the First Branch and Configure It

We want the flight seat booking to be based on the last name of the passenger. If the last name is "Jones" we want to book the passenger in the Business Class. If the passenger's last name is anything other than

"Jones", we want the passenger's seat to be booked in the Economy class. To accomplish this, use the conditional branching feature in TIBCO Cloud Integration - Flogo (PAYG). 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 .

(18)

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. Add a Return activity to the branch. To do so,

a. Hover your mouse cursor to the end of the branch and click the ( ) icon.

b. Scroll to the Default category and click it.

c. Click the Return card to add the activity.

d. Click the x to close the configuration dialog. You must now configure the Return activity with a condition to read the last name of the passenger.

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.

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 category under Functions 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.

(19)

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 is anything but Jones). To configure the activity, follow these steps:

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

2. Expand data under Flow Outputs.

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

4. Expand data under Flow Outputs.

5. Click Class and enter "Economy".

7. One by one, map all remaining elements of the flow outputs under data (Cost, DepartureDate, DeparturePoint, Destination, FirstName, and LastName) except Id, by first clicking on them under data and then clicking on the corresponding element under body. Do not map Id.

(20)

8. Click Id under data to configure it.

9. Expand the number category under Functions and click random().

10. Enter ⁹⁹⁹⁹⁹⁹ as an input parameter to the ^random() function.

11. Click Save.

12. Click x to close the dialog.

Your flow should continue to look like this:

Step 7: 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 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. Add a Return activity. To do so,

(21)

a. Hover your mouse cursor to the end of the branch and click the ( ) icon.

b. Scroll to the Default category and click it.

c. Click the Return card to add the activity.

d. Click the x to close the configuration dialog. You must now configure this branch with a condition to read the last name of the passenger and check to see if it is "Jones".

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 and click endsWith(str, substr).

4. Replace str 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 substr, then click LastName under body. This replaces the str with the last name extracted from the output of the ReceiveHTTPMessage trigger.

(22)

6. Click Save.

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

a. Click Return1 to open its configuration dialog.

b. Expand data under Flow Outputs.

c. Click code and enter ²⁰⁰ 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().

i. Enter ⁹⁹⁹⁹⁹⁹ as the input to the random() function.

j. Click Save.

(23)

k. Click x to close the dialog.

Your flow should look like the following:

Step 8: Validate the App

Your app is now ready. Before you push the app to the cloud, be sure to validate all the flows to confirm that there are no errors or warnings. To do so click the Validate button. TIBCO Cloud Integration - Flogo (PAYG) validates each flow and activity within the flow. If there are any errors or warnings, you see the respective icons next to the flow name or activity tab which contains the error or warning.

On successful validation, you get the following message:

(24)

App Development

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. It is powered by Project Flogo^™, a lightweight integration engine.

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

Editing the same app in two browser tabs is not supported.

Creating and Managing a Flogo App in the Web UI

This section describes how to create and manage Flogo apps.

Creating a TIBCO Flogo

^®

App

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

Procedure

1. Open the Apps page.

2. Click Create/Import app.

The app details page opens. By default, the app is named in a sequential order in the format

New_Flogo_App_<sequential_number>. For example, if you created three apps without renaming them, then the first one has a default name of New_Flogo_App_1, the second one is called

New_Flogo_App_2 and the third one is called New_Flogo_App_3. The version of a newly-created app is 1.0.0 and is displayed as ^{v: 1.0.0} beside the name of the app. You can edit the version of the app. For more information, refer to Editing the Version of an App.

3. Edit the app name to a meaningful string. To do so, click anywhere within the app name and edit it, then click anywhere outside the text box to persist your change.

The app name must not contain any spaces. It must start with a letter or underscore and can contain letters, digits, periods, dashes, and underscores.

4. Click Create.

The card for an app type is disabled if the plan you purchased does not entitle you to create certain types of apps such as BusinessWorks app, Flogo app, Mock app, or Node.js app, or use certain capabilities within an app type.

You can now create one or more flows for the app. See the Creating a Flow topic and its sub-topics for details on creating a flow.

Creating an App from a Saved Specification

If you have an existing specification saved in either the TIBCO Cloud^™ Integration - API Modeler or on your local machine, you can use the specification to create a Flogo App. Currently, TIBCO Cloud

Integration - Flogo (PAYG) supports app creation using a Swagger Specification 2.0, OpenAPI Specification 3.0, GraphQL Schema, or gRPC Protobuf.

The specification must exist prior to creating the Flogo App.

Refer to the appropriate topics under the Building APIs section for information on how to create a Flogo App using the specification:

Using an OpenAPI Specification Using GraphQL Schema

(25)

Using gRPC

Validating your App

After you have created the flows in your app, you must validate the app before you push it to the cloud.

To validate your app, click the Validate button on the app details page. This validates each flow and activity. If a flow or activity has an error, it displays an error or warning icon on the top right corner of the flow or activity.

TIBCO Cloud Integration - Flogo (PAYG) does not retain the results of the previous validation if you navigate into a flow after you have validated the app. For example, if two of your flows have errors, and you navigate into one of those flows to fix the error, when you get back to the app detail page, the results of the second flow validation are lost. If you navigate into a flow after you have validated the app, you must validate the app again irrespective of whether you have made changes to the flow or not.

Refer to Viewing Errors and Warnings section for more details.

Editing a TIBCO Flogo App

You can edit your Flogo^® App from the Apps page. You can edit flows, triggers, and so on.

Editing the same app in two browser tabs is not supported.

Renaming an App

You can rename an existing app.

To rename an existing app, do the following:

Procedure

1. Open the app details page by clicking the app name.

2. Click anywhere in the app name and edit the name.

3. Click away from the app name to persist your changes.

Editing the Version of an App

When you create an app, the default version of the app is 1.0.0. You can edit the version of an app.

The format of a valid app version is:

xxx.xxx.xxx

Alphabets or special characters are not allowed in an app version.

Some examples of valid app versions are:

1.1.1 11.22.13 111.222.333

(26)

Procedure

1. Open the app details page.

Beside the name of the app, the version of the app is displayed as follows:

New_Flogo_App_<sequential_number> v: 1.0.0

For a newly-created app, the version is 1.0.0.

2. To edit the version of the app, click on the version number and specify the new version.

The new version of the app is reflected everywhere. For example, in runtime logs.

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 reverts the changes you just made.

To revert your edits to an existing app before it:

Procedure

1. On the app details page, click the ( ) icon to reveal the options.

2. Click . The is enabled only if you have made edits to the app after the last , but have not the app with those edits.

Switching Between Display Views on the App Page

When you click an app name on the Apps page, the app details page opens. The flows in the app are listed on the app details page. You have the option to view this page in the Trigger View or Flow View. By default, it opens in the Trigger View. Click Trigger View and select Flow View from the drop-down menu to switch to the flow view. When you are in the flow view, click Flow View and select Trigger View from the drop-down menu to go back to the trigger view.

Trigger View

In this view, the flows are displayed attached to the trigger(s) that they use. If a flow is attached to multiple triggers, it is attached to each trigger separately. So, you can see it multiple times on the page but attached to different triggers. Flows that are not attached to any trigger display No trigger in place of the trigger name.

Trigger View

In the image above, MyRESTFlow2 is attached to both TimerTrigger and ReceiveHTTPMessage trigger as shown, hence it appears twice. The MyTimerTrigger flow was created with a new Timer trigger, hence it is

(27)

not attached to the top Timer trigger which has two flows attached to it and TimerTrigger appears twice on the page.

Hovering on a trigger displays the New flow option. Click the New flow option to create a new flow to attach the newly created flow to that trigger.

Hovering over No trigger displays the Add trigger option which takes you to the triggers catalog.

Flow View

In this view, each flow is shown separately and the trigger that it is attached to is shown on the extreme left of the flow. Shown below is a Flow View representation of the Trigger View image above:

Flow View

Notice that MyRESTFlow2 shows two triggers. That is because this flow is attached to two triggers as you can see in the Trigger View. A blank flow shows 0 triggers against it as it is not attached to any triggers.

Deleting an App

You can delete an app using the Delete app icon which appears when you hover your mouse cursor to the end of the app row.

To delete an app:

(28)

Procedure

1. On the Apps page, hover your mouse cursor to the end of the app row until the Delete app icon ( ) appears.

2. Click the Delete app icon.

3. On the confirmation dialog box, click Delete app.

Result

The selected app is deleted.

Exporting and Importing an App

You can export and import apps and use them as templates to quick start development, or simply put them in a version control system such as GitHub.

Exporting an App

Here are a few things to keep in mind before you export an app:

● When you export an app, all flows in your app get exported. You cannot pick and choose flows to export.

● Passwords configured in any activity within any flow or connection in the app to be exported are removed in the exported app. You must manually configure the credentials in the flows after importing such apps.

● Some apps created in Project Flogo^™ use the ^any data type. The ^any data type is not supported in TIBCO Cloud Integration - Flogo (PAYG). Such apps get imported successfully, but the element of type

any gets converted into an empty object. You must explicitly use the mapper to populate the empty object with member elements.

To export an app, follow these steps:

Procedure

1. On the Apps page, click the app to open the app details page.

2. Click the hamburger menu ( ).

3. Click Export.

Exporting an App's JSON File

When an App's binary is built, the ^.json file is embedded within the binary file. To export the ^.json file from the binary file to the disk, use the following command.

./<app-binary-name> --export app

The ^.json is exported as <app-binary-name>.json.

To provide a different file name to the exported ^.json, use the following command:

./<app-binary-name> --export -o <new-app-binary-name>.json app

(29)

Importing an App

You can import the triggers and flows from an exported app into an existing app or into a new app. The target app into which you want to import must exist. You can import an app by dragging and dropping its ^.json file into the Web UI.

Flogo apps that are exported from TIBCO Cloud Integration - Flogo (PAYG) 2.5.0 and later cannot be imported into previous versions of TIBCO Cloud Integration - Flogo (PAYG).

Here are a few things to keep in mind before you import an app:

● If any flow in the app uses extensions developed by the community, those extensions must be available to the target app into which you are importing, at the time of the import. Flows that make use of extensions that are not available to the target app are not imported.

● Passwords configured in any activity within any flow or connection in the app to be exported are removed in the exported app. You must manually configure the credentials in the flows after importing such apps.

● Some apps created in Project Flogo^™ use the ^any data type. The ^any data type is not supported in TIBCO Cloud Integration - Flogo (PAYG). Such apps get imported successfully, but the element of type

any gets converted into an empty object. You must explicitly use the mapper to populate the empty object with member elements.

● When importing an app, be aware that the ^long and ^double data types get converted to the ^number data type.

(30)

The suffixes used in the Mapper have undergone some changes, because of which you may receive a mapper-related warning in the Import app dialog when importing an existing app. Click Continue and the app imports successfully. After the import completes, be sure to re-map the properties in the activities that show errors. This ensures that they switch to the new suffix format. The following table shows you the changes in the suffixes:

Original suffix appearing in imported apps

New suffix used by the

Mapper (after you re-map) For example...

Used when mapping...

activity_id.activity_par

ameter $activity[activity_id].activity

_parameter Old suffix:

$InvokeRESTService.re sponseBody.userId

New suffix after re- mapping property:

$activity[InvokeRESTS ervice].responseBody.

userId

When mapping to a parameter in the activity's output.

Used to resolve activity params.

$TriggerData $trigger Old suffix:

$TriggerData.queryPar ams.title

New suffix after re- mapping property:

$trigger.queryParams.

title

When mapping from the output of the trigger to flow input

N/A

There was no equivalent for this in the old mapper

$flow.headers.parameter

$flow.body.parameter

$flow is a newly introduced suffix which did not have an

equivalent suffix in the old mapper.

When mapping to any parameter in the flow's header or input schema (schema entered in the Input tab of Flow Inputs &

Outputs dialog) which is the same as the output of the trigger, since the output of the trigger is mapped to the input of the flow.

Used to resolve parameters from within the current flow. If a flow has a single trigger and no input parameters defined, then the output of the trigger is made available via

$flow.

(31)

● In imported apps, the passwords and secrets for any connections configured in the app do not get imported. You must reconfigure any password or secret for the connection after the app has been imported.

● When you import an app which does not have a Return activity in any flow (main or branched flow), the Return activity is not added automatically by default. However, if an existing app already has Return activities in main or branched flows, the app is imported as expected.

Importing into a new or empty app

1. Create a new app if you do not already have one. See Creating a Flogo App for details on creating an empty app.

2. On the app details page, select Import app.

3. Navigate to or drag and drop the ^.json file for the app that you want to import.

4. Click Upload. The Import app dialog displays some generic errors and warnings as well as any specific errors or warnings pertaining to the app you are importing. It validates whether all the activities and triggers used in the app are available in the Extensions tab.

5. You have the option to import all flows from the source app or selectively import flows.

● Import all - To import all the triggers and flows in the app, select Import All. If any activities or triggers are missing in the Extensions tab, the import process ignores the flows that contain those activities resulting in those flows not being imported. If the existing app already has activities or triggers with the same name as the ones you are importing, you see a warning that they will be overwritten. If you do not want to overwrite the flows, you can click Back and clear the selection then click Next. If you do so, the duplicate flows that you de-selected will not get imported. You have the option to rename the flows in the Web UI and export the app and re-import it.

● Selective import - Select Selective Import, to import only specific triggers and flows from the app.

The Import app dialog displays a list of triggers with a check box next to each one. If any activities or triggers are missing in the Extensions tab, the activities or triggers missing in the Extensions tab are not listed in the Import app dialog, hence you will not be able to select them to import. By default, all check boxes are selected. Clear the check box next to the triggers that you do not want to import. All flows associated with the selected trigger(s) get imported by default. If you do not select a trigger, the flows and their subflows associated with the unselected trigger(s) are listed in the next screen.

6. Click Next.

If you had not selected a trigger in the previous dialog, the flows associated with that trigger are displayed. You have the option to select one or more of these flows such that the flows get imported as blank flows that are not attached to any trigger. By default, all flows are selected. Clear the check box for the flows that you do not want to import. If your flows have subflows, and you select only the main flow but do not select the subflow, the main flow gets imported without the subflow. Click Next.

Importing into an app that has existing flows

When importing the app into another app that has existing flows, keep the following in mind:

● If the existing app already has flows, activities or triggers with the same name as the ones you are importing, a warning is displayed. You can opt not to import those flows, activities, or triggers. You can go back and rename them in the Web UI and export the app again and re-import it.

● If any of the flows that were imported with the app had credentials such as a password or a connection, be sure to re-configure them.

1. Open the app details page by clicking the app name.

(32)

2. Click the hamburger menu ( ) and select Import.

3. Navigate to or drag and drop the .json file for the app that you want to import.

4. Click Upload. The Import app dialog displays some generic errors and warnings as well as any specific errors or warnings pertaining to the app you are importing. It validates whether all the activities and triggers used in the app are available in the Extensions tab.

5. You have the option to import all flows from the source app or selectively import flows.

● Import all - To import all the triggers and flows in the app, select Import All. If any activities or triggers are missing in the Extensions tab, the import process ignores the flows that contain those activities resulting in those flows not being imported. If the existing app already has activities or triggers with the same name as the ones you are importing, you see a warning that they will be overwritten. If you do not want to overwrite the flows, you can click Back and clear the selection then click Next. If you do so, the duplicate flows that you de-selected will not get imported. You have the option to rename the flows in the Web UI and export the app and re-import it.

● Selective import - Select Selective Import, to import only specific triggers and flows from the app.

The Import app dialog displays a list of triggers with a check box next to each one. If any activities or triggers are missing in the Extensions tab, the activities or triggers missing in the Extensions tab are not listed in the Import app dialog, hence you will not be able to select them to import. By default, all check boxes are selected. Clear the check box next to the triggers that you do not want to import. All flows associated with the selected trigger(s) get imported by default. If you do not select a trigger, the flows and their subflows associated with the unselected trigger(s) are listed in the next screen.

6. Click Next.

If you had not selected a trigger in the previous dialog, the flows associated with that trigger are displayed. You have the option to select one or more of these flows such that the flows get imported as blank flows that are not attached to any trigger. By default, all flows are selected. Clear the check box for the flows that you do not want to import. If your flows have subflows, and you select only the main flow but do not select the subflow, the main flow gets imported without the subflow.

7. Click Next.

Importing flows without importing the triggers that they are attached to 1. Select Selective Import when importing the app.

2. Clear the check box for the triggers that you do not want to import.

3. Click Next. A list of flows is displayed.

4. Select the flows that you would like to import and click Next. The flows are imported as blank flows without being attached to a trigger.

Handling connections when importing an app

Each connection in TIBCO Cloud Integration - Flogo (PAYG) contains a unique internal ID. The IDs are not exposed in the Web UI and are unique based on the user who created them.

When TIBCO Cloud Integration - Flogo (PAYG) compares connections, it does so by comparing their internal IDs. It considers two connections identical if they have the same connection type and same connection ID. It considers two connections as similar if they have the same connection type, but different connection ID.

Hence, if the app you are importing was not created by you, then any connections used in that app can not have the same ID as any existing connection of the same type that you might already have in your

installation of TIBCO Cloud Integration - Flogo (PAYG). For example, if you import an app created by some other user that has some Salesforce connections, even though your installation of TIBCO Cloud Integration - Flogo (PAYG) might already have some existing Salesforce connections, the connections are considered

(33)

similar, because they are of the same type (Salesforce) but not identical because they do not have the same ID because they were not created by the same user.

When importing an app containing a connection, if your target app has an existing connection with an identical internal ID as the connection in the app being imported, a new connection does not get created.

The imported app uses the existing connection in such a case. The connection credentials do not get exported with the app. If a new connection gets created, you must re-configure the connection credentials after the app has been imported.

Keep the following in mind when you import an app with connections:

Import all

If you had selected Import all when importing the app, you have the following options:

● If you are the owner who created the app to be imported, if identical connections exist in your environment, the existing connections are automatically re-used.

● If identical connections do not exist, then new connections get created without passwords. You must set the password for such connections after the app has been imported.

● If there are similar connections (same type but different IDs) in the host app, TIBCO Cloud Integration - Flogo (PAYG) does not re-use those connections. It creates new connections without passwords. You must set the password for such connections after the app has been imported.

Selective import

If you chose to do a selective import when importing an app, the Import app dialog lists the connections that are used in the flows and triggers that you selected for import in the app to be imported. It displays a drop-down menu next to each connection. You have the following options:

● If you have any existing identical connections (same connection type and same connection ID) in the host app, that connection is automatically selected in the drop-down menu next to the connection. You have the option to re-use the existing identical connection by leaving it pre-selected.

● If there are any similar connections in the host app (same connection type but different connection ID), you can select the similar connection from the drop-down menu next to it.

● You always have the option to select Create new connection from the drop-down menus for any of the connections. TIBCO Cloud Integration - Flogo (PAYG) creates new connections with no passwords. You must manually create a password for the new connection after importing the app.

Resolving Missing Activities and Triggers

When you import an app that contains one or more activities or triggers that are not installed in your environment, you see a warning in the Import App dialog.

When importing an app that has a connection configured in it, but the connector is not installed in your environment, after you install the connector, the connection configuration field values of type SECRETS are retained post installation as long as they were not configured using application properties. If you had configured your SECRETS as application properties, you will need to reconfigure them after installing the missing connector. This is because all application properties in the app are wiped out when the app is imported.

To resolve missing activities or triggers for which TIBCO provides connectors

When an activity or trigger used in an app being imported is missing from your TIBCO Cloud Integration - Flogo (PAYG) environment, the flows in the app get imported, but you see a warning in the Import App dialog.

(34)

When you validate your app by clicking on the Validate button in the app details dialog, you see an error marker ( ) next to the flow name. This indicates that one or more activities or triggers are missing. The number next to it indicates how many activities or triggers that are missing appear in the flow. When you click on the missing activities or triggers, you are prompted to refer to connector installation guide.

Do not upload a TIBCO connector using Upload Extension. For more information on how to install a TIBCO connector, refer to connector installation guide.

This is also true when you copy an app into the designated folder (the folder you specified when you started your Web UI) for your apps on your local machine.

To resolve your custom activities or triggers that are missing

When one or more of your custom activities or triggers used in the app being imported are missing from your TIBCO Cloud Integration - Flogo (PAYG) installation, you see a warning in your Import App dialog similar to the following:

Once the app is imported, you see an error marker ( ) next to the flow name. After you install the missing activity of trigger, this marker goes away. The number next to the error indicates how many activities or triggers are missing in the flow.

To install the missing custom activities or triggers, do the following:

1. Click the flow name to open the flow details page. The Upload an extension dialog opens. You upload custom activity or trigger from the Git repository, hence only the From Git repository option is enabled.

2. Click From Git repository. The Git repository URL text box is pre-populated.

3. Click Import. TIBCO Cloud Integration - Flogo (PAYG) downloads the activity or trigger from the Git repository and uploads it into your Extensions tab. Refer to the section, Uploading Extensions for details on this option.

App File Persistence

Your Flogo app files get persisted to the directory that you specify on your local machine. You can use an external source control system such as Git or SVN to store your apps. You can then check in and check out your apps locally from the remote repository. This makes it possible for you to implement the Continuous Integration/Continuous Deployment (CI/CD) pipeline by leveraging any tool available in the market to integrate your app development with the app deployment.

When you start the Flogo Web UI, you are prompted to point to the directory where you have checked out your apps. If you do not provide any path, the apps are stored in the default directory which is:

<FLOGO_HOME>/data/localstack/apps.

(35)

If you restart your Web UI, at the Web UI restart, if you want to continue using the same directory that you had specified, click Enter on your keyboard when it prompts you to set the path. It stores your path preference that you set the last time.

After the UI starts, you should be able to see all your apps on the app list page in the UI. From this point on, when you create a new app or make a change to an existing app, the changes are saved to the directory location that you provided when starting TIBCO Cloud Integration - Flogo (PAYG).

Each app that you store on your local machine has its own folder and the folder name must be identical to the app name. If another user makes changes to your app, you must sync your local repository with the remote repository (do a pull) in order to get the changes made by that user.

● The app file name must be called ^flogo.json.

● The folder name containing the app must be identical to the app name appearing in the ^flogo.json file for the app.

Loading new apps from the disk - When a new app is added to the directory, refreshing the browser loads the app into the Web UI. You do not need to restart the Web UI.

Loading updated app from the disk - In case the ^flogo.json on the disk is updated (due to minor changes or checkout newer version from the source control system), click the Reload from Disk to load updated app into the Web UI. Be aware that this action overrides existing changes in the app. Reload from Disk option is available under the hamburger menu that is next to the other buttons on the app page.

If another user adds a new app to your remote repository, the app gets downloaded to your local repository when you do a pull from the remote repository. For the new app to display in your TIBCO Cloud

Integration - Flogo (PAYG) Web UI, you must refresh your browser. You do not need to restart either the browser or TIBCO Cloud Integration - Flogo (PAYG).

You can import any exported app to TIBCO Cloud Integration - Flogo (PAYG). To do so, create a folder with an identical name as the app name in your local repository, then copy the ^flogo.json file for the app to the folder. For apps that are created in the Web UI, TIBCO Cloud Integration - Flogo (PAYG) automatically generates a unique ID for each app. But, if you load an existing ^flogo.json file, the app may or may not have an app ID defined in it. TIBCO Cloud Integration - Flogo (PAYG) checks to see if an ID exists in the

flogo.json file for the app. If an ID does not exist for the app, TIBCO Cloud Integration - Flogo (PAYG) generates a unique ID and adds an ID attribute in the ^flogo.json file before loading the app.

Note the following:

● If you change the ID of the app in your flogo.json file, you see a duplicate app in the Web UI. Refresh your browser to fix this issue. If you continue to work on the app with old app ID, your changes are lost when you restart the Web UI.

● All apps that exist in the path that you provided during TIBCO Cloud Integration - Flogo (PAYG) installation get loaded in the Web UI. You cannot selectively choose the apps to be loaded in the Web UI.

● Any Launch Configurations (containing your test data for the app) associated with the app are stored in the <app_folder> > test folder along with the ^flogo.json file for the app.

● File permissions - You must have "write" permission for the app directory on your local machine.

Otherwise, the app is not loaded and displayed in the UI. An error is displayed in the log located in .

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

(PAYG)

User's Guide

Version 2.11.0

January 2021

Contents

Figures

TIBCO Documentation and Support Services

Introduction

Concepts

Creating your First REST API

App Development

Creating and Managing a Flogo App in the Web UI

Creating a TIBCO Flogo

App

Editing a TIBCO Flogo App

Renaming an App

Editing the Version of an App

Reverting Changes to an App

Switching Between Display Views on the App Page

Deleting an App

Exporting and Importing an App

App File Persistence