Best Practices in TIBCO Cloud Integration - Flogo (PAYG)
TIBCO recommends below best practices for efficient development of Flogo apps.
Development
Flow Design
- Re-use with subflows
If you are executing the same set of activities within multiple flows of the Flogo app, you should put them in a subflow instead of adding the same logic in multiple flows again and again. For example error handling and common logging logic.
Sub-flows can be called from other flows, thus enabling the logic to be reused. A subflow does not have a trigger associated with it. It always gets triggered from another flow within the same app.
- Terminate the flow execution using a Return activity
Add a Return activity at the end of the flow, when you want to terminate the flow execution and the flow has some output which needs to be returned to either the trigger (in case of REST flows) or the parent flow (in the case of a branch flow). An Error Handler flow must also have a Return activity at the end.
- Copying a flow or an activity
In scenarios where you want to create a flow or an activity that is very similar to an existing flow in your app, you can do so by duplicating the existing flow then making your minimal changes to the flow duplicate. You need not create a new flow. For details on how to duplicate a flow, see Duplicating a Flow. You can also copy activities. For details on how to copy an activity, see Duplicating an Activity.
- Use of ConfigureHTTPResponse activity
If you define a response code in your REST trigger, ReceiveHTTPMessage, configure the return value for the response code in the Configure HTTP Response activity.
The Return activity is a generic activity to return data to a trigger. However, when developing a REST/HTTP API, you may need to use different schema for different HTTP response codes. You can configure the ReceiveHTTPMessage trigger to use different schema for different response codes either using the Swagger(OAS) specification or manually adding them on the trigger configuration.
In such scenario, you should add the ConfigureHTTPResponse activity in the flow before the return activity to construct the response data for a specific response code. ConfigureHTTPResponse activity allows you to select a response code, generate the input based on the schema defined on the trigger for that code and map data from the upstream activities to the input.
You can then map output of the ConfigureHTTPResponse activity to the Return activity to return the data and response code.
When you are calling a REST API from a Flow using the InvokeRESTService activity, you can enable the 'Configure Response Codes' option to handle the response codes returned by the API. You can add specific codes e.g. 200, 404 and define schema for each of them using this option. You can also define status code range in the format such as 2xx if same schema is being used for all codes in that range.
- Reserved keywords
TIBCO Cloud™ Integration - Flogo® (PAYG) uses some words as keywords or reserved names. Do not use these words in your schema. For a complete list of the keywords to be avoided, see the section, Reserved Keywords to be Avoided in Schemas.
Mapper
- Synchronizing schema
If you make any changes to the trigger configuration after the trigger was created, you must click the Sync button in order for the schema changes to be propagated to the flow parameters. Refer to the section, Synchronizing Schema Between Trigger and Flow for more details.
- Using Expressions and Functions
Within any one flow, use the mapper to pass data between the activities, and between the trigger and the activities or the trigger and the flow. When mapping, you can use data from the following sources:
- Literal values - Literal values can be strings or numeric values. These values can either be manually typed in or mapped to a value from the output of the trigger or a preceding activity in the same flow. To specify a string, enclose the string in double quotes. To specify a number, type the number into the text box for the field. Constants and literal values can also be used as input to functions and expressions.
- Direct mapping of an input element to an element of the same type in the Upstream Output.
- Mapping using functions - The mapper provides commonly used functions that you can use in conjunction with the data to be mapped. The functions are categorized into groups. Click a function to use its output in your input data. When you use a function, placeholders are displayed for the function parameters. You click a placeholder parameter within the function, then click an element from the Upstream Output to replace the placeholder. Functions are grouped into logical categories. Refer to Using Functions section for more details
- Expressions - You can enter an expression whose evaluated value will be mapped to the input field. Refer to Using Expressions for more details.
- Complex data mappings
- Using the array.forEach() mapper function, you can map complex nested arrays, filter elements of an array based on a condition or map array elements to non-array elements or elements of another array with a different structure. See the following sections for more details.
- You can extract a particular element from a complex JSON object. The json.path() function takes JSONPath expression as an argument. JSONPath is an XPATH like query language for querying an element from JSON data. Refer to Using the json.path function for more details.
Branches
- Branch conditions
You can design conditional flows by creating one or more branches from an activity and defining the branch types as well as the conditions for executing these branches. Refer to the Creating a Flow Execution Branch section for details on how to create branches, the type of branches you can create, and the order in which the branches execute in a flow.
Error handling
Errors can be handled at the activity level or at the flow level. To catch errors at the activity level use an error branch. In this case, the flow control transfers to the main branch when there is an error during activity execution. Refer to the section, Catching Errors for more details on error handling. To catch errors at the flow level (when you want to catch all errors during the flow execution regardless of the activities from which the errors are thrown), use the Error Handler at the bottom left on the flow page to create an error flow. Since this flow must have a Return activity in the end, the flow execution gets terminated after the Error Handler flow executes. The control never goes back to the main flow. Refer to the section on Catching Errors for more details.
In order to handle network faults TIBCO Cloud Integration - Flogo (PAYG) provides ability to configure Timeout and Retry on Error settings for some specific activities such as InvokeRESTService and TCMMessagePublisher. Refer to the TIBCO Flogo® Activities and Triggers Guide for details on each General category activity and trigger.
Deployment and Configuration
Using environment variables
When deploying a Flogo app, you can override values of the app properties using environment variables. For details on using environment variables, see the section on Environment Variables.
Externalize configuration using app properties
When developing a Cloud-Native microservices it is recommended to separate the configuration from the app logic. You should avoid hard-coding values for configuration parameters in the Flogo app and use the app properties instead.
The use of app properties allows you to externalize the app configuration. Externalizing the configuration in turn allows you to change the value for any property without having to update the app. This is particularly useful when testing your app with different configurations and automating deployments across multiple environments as part of the CI/CD strategy configurations and automating deployments across multiple environments as part of the CI/CD strategy. For details on using app properties, see the section, App Properties.