TIBCO Cloud™

(1)

User's Guide

Software Release 2.4.0 February 2019

(2)

Important Information

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

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

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

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

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

FOREGOING DISTINCTIONS BETWEEN THESE ITEMS AND TIBCO PRODUCTS.

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

TIBCO, the TIBCO logo, Two-Second Advantage, TIBCO Cloud Integration, TIBCO Flogo, TIBCO Flogo Apps, TIBCO Flogo Enterprise, and TIBCO Cloud^™ Integration- Flogo^® (PAYG) are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform Enterprise Edition (J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corporation in the U.S. and other countries.

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

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

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

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

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

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

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

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

(3)

TIBCO Software Inc. Confidential Information

(4)

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

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

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

How to Contact TIBCO Support

You can contact TIBCO Support in the following ways:

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

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

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

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

How to Join TIBCO Community

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

(8)

Overview

To use TIBCO Cloud Integration- Flogo (PAYG):

1. Create an app.

2. Create a flow in your app.

3. Add a trigger to the flow and configure it.

4. Add one or more activities to the flow and configure them.

5. your app.

Concepts

The following describes some concepts that are used in the TIBCO Cloud Integration- Flogo (PAYG) environment.

Apps

Flogo apps are like containers that hold the logic of your application. The logic of the application is defined in a flow. A Flogo app can contain one or more flows.

Flow

A flow is a process that contains the business logic of the app. Every TIBCO Flogo^® App must contain at least one flow. An app can consist of multiple flows. A flow is activated by one or more triggers.

Each flow can contain one or more activities. A flow can have logical conditional branches. Each flow has default error handlers.

Trigger

Triggers are used to activate a flow. A trigger can also be activated by an external system, such as Salesforce.com, in which case the TIBCO Flogo^® App listens for changes happening in that external system.

Activity

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

(9)

TIBCO Flogo

^®

App

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.

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.

4. Click Create.

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 . 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 link for 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 (PAYG). 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. Please refer to the product Readme for the supported versions of Docker.

Follow these steps to build an app:

Procedure

(10)

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

3. Click Build.

You see the following build target options:

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

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

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

5. To run the app:

On Macintosh and Linux 1. Open a terminal.

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

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

For Docker Image

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

1. Open a terminal.

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

(11)

Application Properties

You can configure select supported fields with application properties in triggers and activities.

Connection-related application properties cannot be used for configuration anywhere within an app.

Their only purpose is to allow you to change a connection value if need be during runtime.

Configuration fields in your flow that require their values to be changed when the app goes from a testing stage to production are best configured using application properties instead of hard coding their values. Application properties for triggers and activities reside within the app. Application properties for connections are not modifiable from the App Properties dialog in the app.

The URL field in an activity is a good example of a field for which you would want different values – maybe an internal URL when testing the app and an external URL when the app goes into production.

You may want the URL for an activity used in the activity to change when the app goes from a test environment to production. In such a case, it is best to configure the URL field in the activity with an application property instead of hardcoding the URL. This way, you can change the URL by changing the value of the application property used to configure the URL field.

An application property value can be any of the following data types:

● string

● boolean

● number

● password

Values for the password data type is encrypted and will not be visible by default. But when configuring the password value, you can click on the Show/Hide password property value icon ( ) to see the value temporarily in order to verify that it has been entered correctly.

Application properties are saved within the app, so when you export or import an app, application properties configured in the app also get exported or imported with the app. Properties of data type password do not retain their values when an app is exported. So, you must reconfigure the password after importing the app.

Creating Application Properties

You can create an application property as a standalone property or as a part of a group. Use a group to organize application properties under a parent. A parent acts as an umbrella to hold related application properties and is basically a label with a meaningful name. A parent does not have a data type

associated with it. For instance, if you want to group all application properties associated with a particular activity, you can create a group with a parent that has the activity name and create all that activity-related application properties under that parent.

As an example, you can create LOG_LEVEL as a standalone application property without a parent. Or you can create it as a part of a hierarchy such as LOG.LOG_LEVEL with the parent of the hierarchy being LOG and LOG_LEVEL being the application property under LOG. Keep in mind that if you group properties, you must refer to them using the dot notation starting from the parent. For example, the LOG_LEVEL property must be referred to as LOG.LOG_LEVEL. You can nest a group within a group.

Once you create an application property either as a standalone property or under a group, you cannot move the property around to another location in the properties list.

The App Properties dialog allows you to view your application properties in two formats (views).

Refer to App Properties Dialog Views for details.

(12)

view format. By default, the App Properties dialog opens in the tree view. To toggle between views click Switch view mode.

Tree view

The tree view is the default view in which the App Properties dialog opens. In this view, you can add a new property, delete an existing property as well as edit the data type and value of a property.

List view

In the list view, you can edit the data type and value of a property but cannot add a new property or delete an existing property. The image below shows you how the properties in the above tree view image are presented in the list view.

Creating a Standalone Application Property

To create a standalone application property for your app, follow the steps below.

(13)

To create a group see Creating a Group.

No two standalone properties (properties that are not in a group) can have identical names. Also, property names within the same group must be unique.

Procedure

1. If your app does not exist, create a new app, and click App Properties when you get to the screen below.

If your app already exists, then open the app details page as shown below and click App Properties.

The App Properties dialog opens.

If you already have existing properties, they will be displayed. Click Add to add another property.

2. Enter a meaningful name for the property you want to create.

The property name must not contain any spaces or special characters other than a dash (-) or an underscore (_).

3. Click Add property to create a standalone property.

The property gets created. When you create a property, by default, the property list is presented in a tree view. To view the properties in a list view mode, click Switch view mode.

4. Select the data type for the new property from its drop-down list.

5. Enter a default value for the property in the text box next to the property.

6. Click Save.

TIBCO Cloud Integration- Flogo (PAYG) runs validation in the background as you create a property.

The validation takes into consideration the property type and default value of the property that you entered. The Save button gets enabled only when the validation is successful. Make sure you do not skip this step of saving your newly created property or group.

Creating a Group

(14)

so in the Application Properties dialog. When creating a group you must add the parent first then create the application properties under the parent.

Group names within an app must be unique. Also, property names within a group must be unique.

Procedure

1. Open the app details page and click App Properties.

2. Click Add on the upper right corner to add the parent.

3. Enter a meaningful name for the parent and click Add group.

The parent gets created. The parent is simply a label and cannot be used by itself. So, you must add properties within the parent.

4. To add a property within the parent, hover your mouse to the extreme right until the Add button appears against the parent.

5. Enter a name for the property and click Add property.

6. Select a data type for the property and enter a default value. Entering a default value and selecting a data type are mandatory. The Save button will remain disabled without them.

7. Click Save.

The property gets created under the parent.

Deleting a Group or Property

You must delete an existing property from the tree view in the App Properties dialog. The list view does not allow you to add or delete properties. Deleting a child property does not delete its parent, but deleting a parent will delete all properties under it.

To delete a property, follow these steps:

Procedure

1. Open the App Properties dialog from the app details page.

2. Hover your mouse to the extreme right end of the property and click Delete. To delete a parent, hover your mouse to the extreme right end of the parent and click Delete.

(15)

3. Clcik Save.

Using Application Properties in a Flow

Configuring a field with an application property is recommended for fields that require their values to be overridden when the app goes into production. Hence, the decision as to which fields in an activity should support application properties (which fields can be configured using an application property) must be decided at the time when the extension for the category is being developed. The fields that can be configured using an application property display a slider button against their names in the UI.

Connection-specific application properties are visible in the App Properties dialog after you select a connection when configuring the activity or trigger, but they appear in read-only mode. This is because connections are reusable across apps and connection-related app properties are managed (refreshed) automatically. Connection-related application properties cannot be used for configuration anywhere within an app. Their only purpose is to allow you to change a connection value if need be during runtime. For more details on how the connection properties get created and used, see Using Application Properties in Connections.

To configure a field with an application property, follow these steps:

Procedure

1. Open the flow details page.

2. Click the activity whose field you want to configure with an application property.

This opens the configuration pane for the activity.

3. Click the slider ( ) against the name of the field you want to configure with an application property. If the field does not display a slider, the field can not be configured with an application property.

The App Properties dialog opens. Only those application properties whose data type match the data type of the field are displayed.

4. Click the property you want to configure for the field.

The property name appears in the text box for the field and the default value of the property gets implicitly assigned to the field.

After configuring the property, if you want to change a field to use a different property, hover your mouse over the end of text box for the field until the Select another property value icon appears.

Click the Select another property value icon.

(16)

For a field that has been configured with an application property, you can unlink the property from the field. Refer to Unlinking an Application Property from a Field Value for more details.

Using Application Properties in the Mapper

You can use application properties when mapping an input field. The application properties available for mapping are grouped under the $property domain-specific scope in the mapper. All mapper rules and conditions apply to the use of application properties as well. For example, the data type of the application property value must match with the input field data type when mapping. Connection- related application properties that are used by any connection field in an activity do not appear under

$property since they cannot be accessed. Connection-related application properties cannot be used for configuration anywhere within an app. Their only purpose is to allow you to change a connection value if need be during runtime. Hence, they cannot be used to map input fields.

Refer to the section on Mapper for details on how to use the mapper.

Unlinking an Application Property from a Field Value

For a field that has been configured with an application property, if you decide at a later time not to use the application property, you can click and slide its slider ball ( ) to the left. This will remove the application property from the field (unlink it from the field) but will leave the field configured with the default value of the application property. The field with retain the default value of the application property, but it will be disassociated from the application property and will appear as a manually entered value. Hence, if you change the default value of the application property beyond this point, it will not affect the value of the field.

Using Application Properties in Connections

Connection-related application properties cannot be used for configuration anywhere within an app.

Their only purpose is to allow you to change a connection value if need be during runtime. Hence, you cannot use connection-related applications properties to map an input field as these properties are not visible in the mapper. You can only view them in the App Properties dialog, but cannot edit, update, or delete them. Before you your app, their values can only be edited in the connection details dialog, the dialog where you provided the credentials for the connection. You can open this dialog by editing the connection from the Connections page in the UI. Connection-related properties are useful when you want to change the value for one of the connection fields, for example a URL, when an app goes from the testing stage to production.

How the connection-related application properties get created

You cannot explicitly create connection-related properties. When you select a connection in the

Connection field of an activity, the supported properties associated with that connection automatically get created and populated in the App Properties dialog.

While creating a connection, the fields in the connection details dialog that support application

properties are marked with icon. One property gets created for each field that is marked with in

(17)

the connection details dialog The values you enter for such fields in the connection details dialog become the default values for the connection properties. The properties take their name from the connection field they represent in the connection details dialog.

You begin by creating a connection. In the example below only the Connection URL and

Authentication Key fields support application properties. These are the only two fields that display against them.

Once the connection is created, you can use it to configure the Connection field in an activity. In the example below, the connection created above is being used to configure the Connection field of the TCMMessagePublisher activity.

(18)

After configuring the Connection field with the connection, if you open the App Properties dialog, you should see the connection properties for the field (enclosed in the red box) displayed. Notice that only the supported properties (Connection URL and Authentication Key) are displayed in a read-only mode.

(19)

The properties that get displayed in the App Properties dialog change dynamically based on your selection of the connection to use. You can only view the connection properties but cannot edit or delete them from the App Properties dialog. Deleting the activity that uses the connection will automatically remove the associated connection properties that the activity used from the App Properties dialog.

Using connection-related application properties

Connection-related applcation properties are not available for use from the mapper. You can use these properties to change a connection value (for example, a URL or password) just before an app goes from a testing stage to production. Their values cannot be changed from the App Properties dialog. Change their values in the connection details dialog before the app.

Editing an Application Property

You can change the default value or data type of an application property at any time.

Changing the Default Value of a Property from the App Properties Dialog

You can change the default value of an existing application property at any time after creating the property. Before you , you can change the default value in the App Properties dialog. See

To change the default value of an existing application property, follow these steps:

Procedure

1. Open the App Properties dialog by clicking on App Properties in the app details page.

2. Click in the text box for the property value you want to change and edit the value.

3. Click Save.

Changing the Name or Data Type of an Application Property after Using It

If you change either the name of an application property or its data type after you have used the property to configure a field in an activity or trigger, the field displays an error message. You must explicitly reconfigure the field to use the modified property by deleting the property from the text box for the field and adding the modified property.

When Importing an App

An app being imported could have its own app properties. The app properties get imported along with the app. If an app property in the app being imported has a name that is identical to a property in the host app, you will see a warning message saying so with a choice to either overwrite the existing host property (by clicking Continue) with the property definition from the imported app or cancel the import process altogether.

Application properties of type password do not retain their values when the app is exported, hence you will need to reconfigure the default values of all application properties of data type password after you import the app.

Exporting Application Properties to a File

You can export the application properties to a JSON file or a .properties file. The exported JSON file can be used to override application property values. The .properties file can be used to create a ConfigMap in Kubernetes. When using the exported properties file, the values in the properties file get validated by the app during runtime. If a property value in the file is invalid, you get an error saying so

(20)

Exporting the application properties to a JSON file

Exporting the application properties to a JSON file allows you to override the default application property values during app runtime. It is useful if you want to test your app by plugging in different test data with successive test runs of your app. You can set the application properties in the exported file to a different value during each run of the app. The default application property values get overridden with their values that you set in the exported file.

To export the application properties to a JSON file, run the following command from the directory where your app resides:

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

The properties get exported to <app-binary-name>-props.json file.

Exporting application properties to a .properties file

You cannot use a .properties file format to override the application properties that were externalized using environment variables. The .properties file is useful when creating the ConfigMap in

Kubernetes. To export the application properties to a .properties file, run the following command from the directory where your app resides:

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

The properties get exported to <app-binary-name>-env.properties file. The names of the application properties appear in all uppercase in the exported env.properties file. For example, a property named ^Message will appear as ^MESSAGE. A hierarcy such as ^x.y.z will appear as ^X_Y_Z.

(21)

Application Configuration Management

TIBCO Cloud Integration- Flogo (PAYG) allows you to externalize application configuration using application properties, so that you can run the same application binary in different environments without making changes to your app. It integrates with configuration management systems such as Consul and AWS Systems Manager Parameter Store to get the values of application properties at runtime.

You can switch between configuration management systems without making changes to your application. You can do this by running the command to set the configuration-management-system- specific environment variable from the command line. Since the environment variables are set for the specific configuration management system, at runtime the application connects to that specific configuration management system to pull the values for the application properties.

Consul

The Consul provides a key/value store for managing application configuration externally. TIBCO Cloud Integration- Flogo (PAYG) allows you to fetch values for application properties from Consul and override them at runtime.

This document assumes that you have set up Consul and know how Consul is used to store service configuration. Refer to the Consul documentation for Consul specific information.

A Flogo app connects to the Consul server as its client by setting the environment variable,

FLOG_APPS_PROPS_CONSUL. At runtime, you must provide the Consul server endpoint in order for your app to connect to a Consul server. You have the option to enter the values for the Consul connection parameters either by typing in their values as JSON strings, or creating a file that contains the values and using the file as input.

Consul can be started with or without ^acl_token. If using ACL token, make sure to have ACL configured in Consul.

Using Consul with TIBCO Cloud Integration- Flogo (PAYG)

Below is a high-level workflow for using Consul with your Flogo app.

Prerequisites

You must have access to Consul before following this procedure. This document assumes that you have set up Consul and know how Consul is used to store service configuration. For information on Consul, refer to the Consul documentation.

At a high level, to use Consul to override application properties in your app (properties that were set in TIBCO Cloud Integration- Flogo (PAYG)), do the following:

Procedure

1. You begin by exporting your app binary from TIBCO Cloud Integration- Flogo (PAYG). Refer to Exporting and Importing an App for details on how to export the app.

2. Configure key/value pairs in Consul for the application properties whose values you want to override. At runtime, the app fetches these values from the Consul and uses them to replace their default values that were set in the app.

When setting up the Key in Consul, make sure that the Key name matches exactly with the corresponding application property name in the Application Properties dialog in TIBCO Cloud Integration- Flogo (PAYG). If the property name does not match exactly, you will

(22)

3. Set the FLOGO_APP_PROPS_CONSUL environment variable to set the Consul server connection parameters. See Setting the Consul Connection Parameters for details.

Consul Connection Parameters

Provide the following configuration information during runtime to connect to the Consul server.

Property Name

Require

d Description server_addre

ss Yes Address of the Consul server which could be run locally or elsewhere in the cloud.

key_prefix No Prefix to be prepended to the lookup key. This is essentially the hierarchy that your app follows to get to the Key location in the Consul. This is helpful in case key hierarchy is not fixed and may change based on environment during runtime. This is also helpful in case you want to switch to a different configuration service such as AWS param store.

Although it is a good idea to include the app name in the key_prefix, it is not required. key_prefix can be any hierarchy that is meaningful to you.

As an example of a key_prefix, if you have an app property (for example, Message) which has two different values depending on the environment from which it is being accessed (for example dev or test

environment), your <key_prefix> for the two values can be /dev/

<APPNAME>/ and /test/<APPNAME>/. At run time, the right value for

Message will be picked up depending on which <key_prefix> you specify in the FLOGO_APP_PROPS_CONSUL environment variable. Hence, setting a key_prefix allows you to change the values of the app properties at runtime without modifying your app.

(23)

Require

d Description

acl_token No Use this parameter if you have key access protected by ACL. Tokens specify which keys can be accessed from the Consul. You create the token on the ACL tab in Consul.

During runtime, if you use the ^acl_token parameter, Key access to your app will be based on the token you specify.

To protect the token, encrypt the token for the ^key_prefix where your Key resides and provide the encrypted value of that token by prefixing the ^acl_token parameter with SECRET. For example, "acl_token":

"SECRET:QZLOrtN3gOEpXgUuud6jprgo/WzLR7j+Twv28/4KCp7573snZWo +hGuQauuR2o/7TJ+ZLQ==". Note that the encrypted value follows the

key_prefix format.

Provide the encrypted value of the token as the SECRET. SECRETS get decrypted at runtime. To encrypt the token, you obtain the token from the Consul and encrypt it using the application binary by running the following command from the directory in which your app binary is located:

./<app_binary> --encryptsecret <token_copied_from_Consul>

The command outputs the encrypted token which you can use as the SECRET.

Since special characters (such as `! | < > & `) are shell command directives, if they appear in the token string, when encrypting the token, you must use a back slash (\) to escape such characters.

insecure_con

nection No By default set to False. Set to true if you want to connect to a secure consul server without specifying client certificates. This should only be used in test environments.

Setting the Consul Connection Parameters

You set the values for application properties that you want to override by creating a Key/Value pair for each property in Consul. You can create a standalone property or a hierarchy that groups multiple related properties.

Prerequisites

This document assumes that you have access to Consul and are familiar with its use.

To create a standalone property (without hierarchy), you simply enter the property name as the name of the Key when creating the Key in Consul. To create a property within a hierarchy enter the hierarchy in the following format in the Create Key field in Consul: <key_prefix>/<key_name> where

<key_prefix> is a meaningful string or hierarchy that serves as a path to the key in Consul and

<key_name> is the name of the application property whose value you want to override. For example, in

dev/Timer/Message and test/Timer/Message, ^dev/Timer and ^test/Timer are the <key_prefix>

which could stand for the dev and test environments and ^Message is the key name. During runtime, you provide the <key_prefix> value which tells your app the location in Consul from where to access the property values.

(24)

The Key name in Consule must be identical to its counterpart in the Application Properties dialog in TIBCO Cloud Integration- Flogo (PAYG). If the key name does not match exactly, you will receive a warning message and the app will use the default value that you configured for the property in TIBCO Cloud Integration- Flogo (PAYG).

A single application property, for example ^Message, will be looked up by your app as either ^Message or

<key_prefix>/Message in Consul. An application property within a hierarchy such as ^x.y.z will be looked up as ^x/y/z or <key_prefix>/x/y/z in Consul. Note that the dot in the hierarchy is

represented by a forward slash (/) in Consul.

After you have configured the application properties in Consul, you need to set the environment variable, FLOGO_APP_PROPS_CONSUL with the Consul connection parameters in order for your app to connect to the Consul. When you set the environment variable, it triggers the app to run, which

connects to the Consul using the Consul connection parameters you provided and pulls the application property values from the ^key_prefix location you set by matching the application property name with the ^key_name. Hence, it is mandatory for the Key names to be identical to the application property names defined in the Application Properties dialog in TIBCO Cloud Integration- Flogo (PAYG).

You can set the FLOGO_APP_PROPS_CONSUL environment variable either by directly entering the values as a JSON string on the command line or placing the properties in a file and using the file as input to the FLOGO_APP_PROPS_CONSUL environment variable.

Entering the Consul Parameter Values as a JSON String

To enter the Consul parameters as a JSON string, enter the parameters as key/value pairs using the comma delimiter. The following examples illustrate how to set the values as JSON strings. You would run the following from the location where your app resides:

An example when not using security without tokens enabled:

FLOGO_APP_PROPS_CONSUL="{\"server_address\":\"http:\/\/127.0.0.1:8500\"}" ./Timer- darwin-amd64

where Timer-darwin-amd64 is the name of the app binary.

An example when tokens are enabled and application properties are within a hierarchy:

FLOGO_APP_PROPS_CONSUL="{"server_address":"http://

127.0.0.1:8500","key_prefix":"/dev/Timer","acl_token":"SECRET:b0UaK3bTyD9wN +ZJkmlKRmojhAv+"}"

where ^/dev/Timer is the path and ^SECRET is the encrypted value of the token obtained from the Consul.

This command directs your app to connect to the Consul at the server_address and pull the values for the properties from the Consul and run your app with those values.

Refer to Consul Connection Parameters section for a description of the parameters. Refer to Encrypting Password Values for details on how to encrypt a value.

Setting the Consul Parameter Values Using a File

To set the parameter values in a file, create a ^.json file, for example, consul_config.json containing the parameter values in key/value pairs. Here's an example:

{

"server_address": "http://127.0.0.1:32819", "key_prefix": "/dev/<APPNAME>/",

"acl_token": "SECRET:b0UaK3bTyD9wN+ZJkmlKRmojhAv+"

}

You would place the consul_config.json file in the same directory which contains your application binary.

(25)

You would then run the following from the location where your app binary resides to set the

FLOGO_APP_PROPS_CONSUL environment variable. For example, to use the consul_config.json file from the example above, you would run:

FLOGO_APP_PROPS_CONSUL=consul_config.json ./<app_binary_name>

The command extracts the Consul server connection parameters from the file and connects to the Consul to pull the application properties values from the Consul and run your app with those values.

Consul properties can also be run using docker by passing the same arguments for the docker image of a binary application.

AWS Systems Manager Parameter Store

AWS Systems Manager Parameter Store is a capability provided by AWS Systems Manager for managing configuration data. You can use the Parameter Store to centrally store configuration parameters for your applications.

Your Flogo app connects to the AWS Systems Manager Parameter Store server as its client. At runtime, you are required to provide the Parameter Store server connection details by setting the

FLOGO_APP_PROPS_AWS environment variable in order for your app to connect to the Parameter Store server. You have the option to enter the values for the Parameter Store connection parameters either by typing in their values as JSON strings, or creating a file that contains the values and using the file as input.

Using the Parameter Store with Flogo Enterprise

Below is a high-level workflow for using AWS Systems Manager Parameter Store with your Flogo app.

Prerequisites

This document assumes that you have an AWS account, have access to the AWS Systems Manager and know how to use the AWS Systems Manager Parameter Store. Refer to the AWS documentation for the information on the AWS Systems Manager Parameter Store.

Overview

To use the Parameter Store to override application properties set in TIBCO Cloud Integration- Flogo (PAYG), do the following:

1. You begin by building an app binary which has the app properties already configured in TIBCO Cloud Integration- Flogo (PAYG). Refer to Building the App for details on how to build the app.

2. Configure the application properties that you want to override in the Parameter Store. At runtime, the app fetches these values from the Parameter Store and uses them to replace their default values that were set in the app.

3. Set the FLOGO_APP_PROPS_AWS environment variable to set the Parameter Store connection parameters from the command line.

When you run the command for setting the FLOGO_APP_PROPS_AWS environment variable, it runs your app, connects to the Parameter Store, and fetches the overridden values for the application properties from the Parameter Store. Only the values for properties that were configured in the Parameter Store will be overridden. The remaining application properties will get their values from the Application Properties dialog.

See the Setting the Parameter Store Connection Parameters and Parameter Store Connection Parameters sections for details.

(26)

Parameter Store Connection Parameters

To connect to AWS Systems Manager Parameter Store, provide the below configuration at runtime.

Require d

Data

Type Description access_key_i

d Yes String Access ID for your AWS account. To protect access key, an encrypted value can be provided in this configuration. See Encrypting Password Values section for information on how to encrypt a string.

The encrypted value must be prefixed with SECRET: e.g. SECRET:b0UaK3bTyD9wN +ZJkmlKRmojhAv+

This configuration is optional if use_iam_role is set to true.

secret_access

_key Yes String Secret access key for your AWS account. This account must have access to the Parameter Store. To protect secret access key, an encrypted value can be provided in this configuration.

See Encrypting Password Values section for information on how to encrypt a string.

The encrypted value must be prefixed with SECRET: for example, SECRET:b0UaK3bTyD9wN +ZJkmlKRmojhAv+

This configuration is optional if use_iam_role is set to true.

region Yes String Select a geographic area where your Parameter Store is located. This configuration is optional if use_iam_role is set to true and your Parameter Store is configured in the same region as the running service. When running in AWS services (for example, EC2, ECS, EKS), this configuration is optional if the Parameter Store is in the same region as these services.

param_prefix No String This is essentially the hierarchy that your app follows to get to the application property location in the Parameter Store. It is the prefix to be prepended to the lookup parameter. This is helpful in case the parameter hierarchy is not fixed and may change based on the environment during runtime.

This is also helpful in case you want to switch to a different configuration service such as Consul KV store.

As an example of a param_prefix, if you have an app property (for example, ^Message) which has two different values depending on the environment from which it is being accessed (for example dev or test environment), your

param_prefix for the two values can be /dev/<APPNAME/ and /test/<APPNAME/. At run time, the right value for

Message will be picked up depending on which param_prefix you specify in the FLOGO_APP_PROPS_AWS environment variable. Hence, setting a param_prefix allows you to change the values of the app properties at runtime without

modifying your app.

(27)

Require d

Data

Type Description

use_iam_role No Boolea

n Set to true if the Flogo app is running in the AWS services (such as EC2, ECS, EKS) and you want to leverage IAM role (such as instance role or task role) to fetch parameters from the Parameter Store. In that case, access_key_id, and

secret_access_key are not required.

Setting the Parameter Store Connection Parameters

You can use the AWS Systems Manager Parameter Store to override the property value set in your Flogo app. You do so by creating the property in the Parameter Store and assigning it the value with which to override the default value set in the app. You can create a standalone property or a hierarchy (group) in which your property resides.

Prerequisites

This document assumes that you have an AWS account and the Parameter Store and are familiar with its use. Refer to the AWS documentation for more information on the Parameter Store.

To create a standalone property (without hierarchy), you simply enter the property name when creating it. To create a property within a hierarchy enter the hierarchy in the following format when creating the property: <param_prefix>/<property_name> where <param_prefix> is a meaningful string or hierarchy that serves as a path to the property name in Parameter Store and <property_name> is the name of the application property whose value you want to override. For example, in ^dev/Timer/

Message and test/Timer/Message/dev/Timer and ^test/Timer are the <param_prefix> which could stand for the dev and test environments and ^Message is the key name. During runtime, you provide the

<param_prefix> value which tells your app the location in Parameter Store from where to access the property values.

The parameter name in Parameter Store must be identical to its counterpart (application property) in the Application Properties dialog in TIBCO Cloud Integration- Flogo (PAYG). If the parameter names do not match exactly, you will receive a warning message and the app will use the default value that you configured for the property in TIBCO Cloud Integration- Flogo (PAYG).

A single application property, for example ^Message, will be looked up by your app as either ^Message or

<param_prefix>/Message in Parameter Store. An application property within a hierarchy such as

x.y.z will be looked up as ^x/y/z or <param_prefix>/x/y/z in Parameter Store. Note that the dot in the hierarchy is represented by a forward slash (/) in the Parameter Store.

After you have configured the application properties in the Parameter Store, you need to set the

environment variable, FLOGO_APP_PROPS_AWS with the Parameter Store connection parameters in order for your app to connect to the Parameter Store. When you set the environment variable, it triggers your app to run, which connects to the Parameter Store using the Parameter Store connection parameters you provided and pulls the app property values from the param_prefix location you set by matching the application property name with the ^param_name. Hence, it is mandatory for the property names to be identical to the application property names defined in the Application Properties dialog in TIBCO Cloud Integration- Flogo (PAYG).

You can set the FLOGO_APP_PROPS_AWS environment variable either by manually entering the values as a JSON string on the command line or placing the properties in a file and using the file as input to the

FLOGO_APP_PROPS_AWS environment variable.

(28)

If your Container is Not Running on ECS or EKS

If the container in which your app resides is running external to ECS, you must enter the values for

access_key_id and secret_access_key parameters when setting the FLOGO_APP_PROPS_AWS

environment variable.

Entering the Parameter Store Values as a JSON String

To enter the Parameter Store connection parameters as a JSON string, enter the parameters and their value using the comma delimiter. The following example illustrates how to set the values as JSON strings. This would be run from the location where your app resides:

FLOGO_APP_PROPS_AWS="{"access_key_id":"SECRET:XXXXXXXXXXXXX","secret_access_key":"SE CRET:XXXXXXXXXXX","region":"us-west-2","param_prefix":"/MyFlogoApp/Dev/"}"

where /MyFlogoApp/Dev/ is the param_prefix (path to the properties) and ^SECRET is the encrypted version of the key or key_id obtained from the Parameter Store.

This will connect to the Parameter Store and pull the values for the properties and override their default values that were set in the app.

Refer to Parameter Store Connection Parameters section for a description of the parameters.

Setting the Parameter Store Values Using a File

To set the parameter values in a file, create a ^.json file, for example, aws_config.json containing the parameter values. Here's an example:

{

"access_key_id": "SECRET:b0UaK3bTyD9wN+ZJkmlKRmojhAv+", "param_prefix": "/MyFlogoApp/dev/",

"secret_access_key": "SECRET:b0UaK3bTyD9wN+ZJkmlKRmojhAv+", "region": "us-west-2",

}

Place the aws_config.json file in the same directory which contains your application binary.

You would then run the following from the location where your app binary resides to set the

FLOGO_APP_PROPS_AWS environment variable. For example, to use the aws_config.json file from the example above, run:

FLOGO_APP_PROPS_AWS=aws_config.json ./<app_binary_name>

This will connect to the Parameter Store to pull the overridden application properties values from the Parameter Store and run your app with those values.

If your Container is Running on ECS or EKS

In case your Flogo apps are running in ECS and intend to leverage the EC2 instance credentials, set

use_iam_role to true . The values for access_key_id and secret_access_key will be gathered from the running container. Ensure that the ECS task has the permission to access the param store.

The IAM role that you use must have permissions to access parameter(s) from the AWS Systems Manager Parameter Store. The following policy must be configured for IAM role:

{

"Version":"2012-10-17", "Statement":[

{

"Action":[

"ssm:GetParamater",

"ssm:GetParamatersByPath", ],

"Effect":"Allow", "Resource":"*"

} ] }

(29)

The following is an example of how to set the FLOGO_APP_PROPS_AWS environment variable when your container is running on ECS. Notice that the values for access_key_id and secret_access_key are omitted:

FLOGO_APP_PROPS_AWS="{\"use_iam_role\":true, \"region\":\"us-west-2\"}" ./Timer- darwin-amd64

Evironment Variables

TIBCO Cloud Integration- Flogo (PAYG) allows you to externalize the configuration of application properties using environment variables.

Using environment variables with application properties is a two-step process:

1. Create one environment variable per application property.

2. Set the FLOGO_APP_PROPS_RESOLVERS=env environment variable, which runs your app and directs it to fetch the values of the application properties for which you have created environment variables.

App binaries that were generated from a version of TIBCO Cloud Integration- Flogo (PAYG) older than 2.4.0 do not support application properties override using environment variables. For example, if you attempt to run an older app binary from Flogo Enterprise 2.4.0 (which supports the environment variable functionality) and override application properties in the app using environment variables, the binary runs normally but the application property override gets ignored.

Using Environment Variables to Override Application Property Values

The use of environment variables to assign new values to your application properties at runtime is a handy method that you can use to test your application with multiple data sets.

Using environment variables to override application properties in Lambda apps is not currently supported.

Follow these two steps to set up the environment variables and use them during app runtime.

Step 1: Create environment variables for your application properties

You start by creating one environment variable for each application property that you want to externalize. To do so, run:

export <app-property-name>="<value>"

For example, if your application property name is ^username, run export username="[email protected]" or

export USERNAME="[email protected]"

A few things to note about this command:

● Since special characters (such as `! | < > &@ `) are shell command directives, if they appear in value, enclosing the value in double quotes tells the system to treat such characters as literal values instead of shell command directives.

● The app-property-name must match the application property exactly or it can use all uppercase letters.

For example, the application property, ^Message, can either be entered as ^Message or ^MESSAGE, but not as ^message.

● If you want to use a hierarchy for your application property, be sure to use underscores (_) between each level instead of the dot notation. For example, for an application property named ^x.y.z, the environment variable name should be either ^x_y_z or ^X_Y_Z.

Step 2: Set FLOGO_APP_PROPS_RESOLVERS environment variable

(30)

To do so, run:

FLOGO_APP_PROPS_RESOLVERS=env ./<app-binary>

For example, FLOGO_APP_PROPS_RESOLVERS=env MESSAGE="This is variable 1."

LOGLEVEL=DEBUG ./Timer-darwin-amd64

When setting variables of type password be sure encrypt its value for security reasons. See Encrypting Password Values for more details.

Setting the FLOGO_APP_PROPS_RESOLVERS=env runs your app. It directs your app to search the list of environment variables for each application property by matching the environment variable name to the application property name. When it finds a matching environment variable for a property, the app pulls the value for the property from the environment variable and runs the app with those values. Hence, it is mandatory that the application property name exactly match the environment variable name for the property.

Application properties that were not set as environment variables will pick up the default values set for them in the app. You will see a warning message similar to the following in the output:

<property_name> could not be resolved. Using default values.

Reverting the Application Property Value to Its Default

You can revert the application property value to its default value that was set in the app. You do this by unsetting the altered value.

To revert to the default value run unset <app_property_name>

Encrypting Password Values

When entering passwords on command line or in a file, it is always a good idea to encrypt their values for security reasons. TIBCO Cloud Integration- Flogo (PAYG) has a utility that you can use to encrypt passwords.

Prerequisites

You must have the password to be encrypted handy in order to run the utility.

To encrypt a password, run the following:

Procedure

1. Open a command prompt or a terminal.

2. Navigate to the location of the app binary and run the following command:

./<app_binary> --encryptsecret <value_to_be_encrypted>

The command outputs the encrypted value which you can use when setting the password in a file or setting the password from the command line or using environment variables,. For example,

export PASSWORD="SECRET:t90Ixj+QYCMFbqCEo/UnELlPPhrClMzv".

Note that the password value is enclosed in double quotes. Since special characters (such as `! | <

> & `) are shell command directives, if such characters appear in the encrypted string, using double quotes around the encrypted value will direct your system to treat them as literal characters.

Also, the encrypted value must be preceded by ^SECRET:

Keep in mind that when you run the ^env command to list the environment variables, the command does not output the environment variable for the password.

TIBCO Cloud™

User's Guide

Contents

TIBCO Documentation and Support Services

Overview

Concepts

TIBCO Flogo

App

Creating a TIBCO Flogo

App

Reverting Changes to an App

Building the App

Application Properties

Creating Application Properties

Creating a Standalone Application Property

Creating a Group

Deleting a Group or Property

Using Application Properties in a Flow

Using Application Properties in the Mapper

Unlinking an Application Property from a Field Value

Using Application Properties in Connections

Editing an Application Property

Changing the Default Value of a Property from the App Properties Dialog

Changing the Name or Data Type of an Application Property after Using It

When Importing an App

Exporting Application Properties to a File

Application Configuration Management

Consul

Using Consul with TIBCO Cloud Integration- Flogo (PAYG)

Consul Connection Parameters

Setting the Consul Connection Parameters

AWS Systems Manager Parameter Store

Using the Parameter Store with Flogo Enterprise

Parameter Store Connection Parameters

Setting the Parameter Store Connection Parameters

Evironment Variables

Using Environment Variables to Override Application Property Values

Reverting the Application Property Value to Its Default

Encrypting Password Values