TIBCO Microflow Container Edition User's Guide€¦ · Getting Started This tutorial shows ......

TIBCO Microflow™ Container EditionUser's GuideSoftware Release 1.0May 2016

Two-Second Advantage®

Important Information

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

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS ANDCONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTEDSOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THECLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOADOR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE)OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USERLICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THESOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, ANDYOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BEBOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright lawsand treaties. No part of this document may be reproduced in any form without the writtenauthorization of TIBCO Software Inc.

TIBCO and Two-Second Advantage, TIBCO Microflow Container Edition, and TIBCO BusinessWorksContainer Edition are either registered trademarks or trademarks of TIBCO Software Inc. in the UnitedStates and/or other countries.

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

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

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOTALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASEDAT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWAREVERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSOR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICALERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESECHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCOSOFTWARE 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 ORINDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE,INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

Copyright © 2016 TIBCO Software Inc. All rights reserved.

TIBCO Software Inc. Confidential Information

2

TIBCO Microflow™ Container Edition User's Guide

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

TIBCO Documentation and Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

Introduction to TIBCO Microflow Container Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

Starting TIBCO Microflow Container Edition Design Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

Creating a Microflow App Based on Cloud API Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Uploading the Microflow Build Package to Pivotal Cloud Foundry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Pushing and Running Microflow Apps on Pivotal Cloud Foundry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Testing Microflow Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Customizing Microflow Build Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Stage Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Caching Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Throttling Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Transformation Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

Request Transformation Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Response Transformation Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Routing Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Routing Stage Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Custom JavaScript Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Async Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

3


Figures

TIBCO Microflow Container Edition Home Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

Pushing Microflow Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4


TIBCO Documentation and Support Services

Documentation for this and other TIBCO products is available on the TIBCO Documentation site. Thissite is updated more frequently than any documentation that might be included with the product. Toensure that you are accessing the latest available help topics, please visit:

https://docs.tibco.com

Product-Specific Documentation

Documentation for TIBCO products is not bundled with the software. Instead, it is available on theTIBCO Documentation site at https://docs.tibco.com/products/tibco-microflow-container-edition.

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

● TIBCO Microflow Container Edition User's Guide

● TIBCO Microflow Container Edition Release Notes

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, contact TIBCO Support:

● For an overview of TIBCO Support, and information about getting started with TIBCO Support,visit this site:

http://www.tibco.com/services/support

● If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a user name, you canrequest one.

How to Join TIBCO Community

TIBCO Community is an online destination for TIBCO customers, partners, and resident experts. It is aplace to share and access the collective experience of the TIBCO community. TIBCO Community offersforums, blogs, and access to a variety of resources. To register, go to the following web address:

https://community.tibco.com

5


https://docs.tibco.com

https://docs.tibco.com/products/tibco-microflow-container-edition

http://www.tibco.com/services/support

https://support.tibco.com

https://community.tibco.com

Introduction to TIBCO Microflow Container Edition

TIBCO Microflow is the consumer-specific contract that you create for an application. It isolates theapp-facing API from your backend service and allows a single backend to provide the same service formultiple consumers. You can control the behavior of each operation in your API service by applyingvarious stages. A stage is a piece of reusable code that performs specific capabilities for the API.

TIBCO Microflow™ Container Edition provides the functionality to apply Microflow stages to the RESTservices that are exposed by TIBCO BusinessWorks™ Container Edition, or any other on-premise orcloud API service. The Microflow applications created in TIBCO Microflow Container Edition can berun on the Pivotal Cloud Foundry platform.

TIBCO Microflow Container Edition consists of a design-time environment and a runtime environment:

● Design Time

At design time, you can create a Microflow application and apply stages to each of the operations.The design-time artifact of TIBCO Microflow Container Edition is available in the mfce-studio-version.zip package.

After a Microflow application is created and configured, the application can then be deployed (alsocalled pushed) to the Pivotal Cloud Foundry environment. See Starting TIBCO Microflow ContainerEdition Design Time and Creating a Microflow App Based on Cloud API Service for more details.

● Run Time

At run time, you can test and run the created Microflow application after it is pushed to the PivotalCloud Foundry environment. See Pushing and Running Microflow Apps on Pivotal Cloud Foundryand Testing Microflow Apps for more details.

Microflow applications running on Pivotal Cloud Foundry are based on the Microflow base buildpackage that must be pre-uploaded to the PCF environment by the PCF administrator. This basebuild package is available in the mfce-buildpack_cf-version.zip package. See Uploading theMicroflow Build Package to Pivotal Cloud Foundry for more details.

You can even customize this base build package to include third-party Node.js modules, which canbe used in the Microflow Custom JavaScript stage. See Customizing Microflow Build Package formore details.

You can download TIBCO Microflow Container Edition artifacts from https://edelivery.tibco.com,including the design-time package mfce-studio-version.zip and the runtime package mfce-buildpack_cf-version.zip.

In this document, the variable MFCE_Studio points to the top-level directory where mfce-studio-version.zip is extracted, for example, /home/epassmf/mfce-studio-v1.0.0.24; and the variableMFCE_Buildpack points to the top-level directory where mfce-buildpack_cf-version.zip isextracted, for example, /home/epaasmf/mfce-buildpack.

6


https://edelivery.tibco.com

Getting Started

This tutorial shows how to create a Microflow application based on the cloud API service exposed byhttp://petstore.swagger.io and how to use the Transformation stage to control the API operation.

Complete the following tasks to create, push, and run a Microflow application on Pivotal CloudFoundry from the very beginning:

1. Starting TIBCO Microflow Container Edition Design Time

2. Creating a Microflow App Based on Cloud API Service

3. Uploading the Microflow Build Package to Pivotal Cloud Foundry

4. Pushing and Running Microflow Apps on Pivotal Cloud Foundry

5. Testing Microflow Apps

Starting TIBCO Microflow Container Edition Design TimeBefore applying stages to your API, you must start the design-time environment of Microflow first. Atdesign time, you can apply various stages to control your API operations.

Prerequisites

Ensure that your system meets the following requirements:

● Amazon DynamoDB

The local edition of Amazon DynamoDB must be installed before starting the design-timeenvironment of TIBCO Microflow Container Edition. Microflow application data is stored inDynamoDB temporarily before the application is pushed to Pivotal Cloud Foundry. Visit AmazonDynamoDB local edition web page for more information.

● Java Development Kit

JDK version 1.7.0 or 1.8.0 is required to run DynamoDB local edition.● Node.js and NPM

Node.js 4.0.0 and NPM 3.3.3 are required. Visit https://nodejs.org for more information.

Procedure

1. Open a command line and navigate to the directory where DynamoDBLocal.jar is extracted; thenrun the following command to start DynamoDB:

java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -sharedDb

2. Download TIBCO Microflow Container Edition artifacts from https://edelivery.tibco.com andextract the design-time file mfce-studio-version.zip to a temporary directory.

3. On the command line, navigate to the extracted MFCE_Studio folder, and then enter the followingcommand to start the design time:

● Microsoft Windows: start_studio.bat http://hostname:port● Unix: ./start_studio.sh http://hostname:port

The http://hostname:port parameter is the service endpoint of the local DynamoDBinstance, which is optional. If you do not use the default values of DynamoDB, you canuse this parameter to define the DynamoDB information.

4. Open a web browser and go to localhost:8001 when the startup is completed.The TIBCO Microflow Container Edition page is displayed.

7


http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Tools.DynamoDBLocal.html

http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Tools.DynamoDBLocal.html

https://nodejs.org


TIBCO Microflow Container Edition Home Page

Creating a Microflow App Based on Cloud API ServiceA Microflow application is based on the Swagger API specification exposed by an API service such as aservice implemented by TIBCO BusinessWorks Container Edition, or any other on-premise or cloudAPI service. By adding stages to each of the operations of the specification, you can apply specificfunctionalities to each operation.

The following procedure shows how to create a Microflow application based on the cloud API serviceexposed by http://petstore.swagger.io/ and how to use the Transformation stage to change therequest and response behavior for the POST/user/createWithArray operation.

Procedure

1. On the Home page of TIBCO Microflow Container Edition, click Add a Microflow Application.

2. In the displayed Create a Microflow Application dialog, provide the following information:a) Enter a display name for the Microflow application to be created in the Display name field.b) Enter the URL of the Swagger specification for the endpoint API service that you want to use.

In this tutorial, the default Petstore API sample is used.c) Click Create.

The Add Microflow Stage page is displayed.

8


3. From the left Operations list, click the POST/user/createWithArray operation.

4. From the request pipeline on the right side of the flow, click the plus button and click the Transform

Request stage.

5. On the Transform request configuration page, provide the following information:a) Enter a stage name in the Name field.b) Enter the following code in the JavaScript payload transformation section.

var _ = require('lodash'); if(payload&&payload.length>=4){ var newPayload = _.slice(payload, 0, 3); payload = newPayload; } done(payload);

c) Click Add.

6. From the response pipeline on the left side of the flow, click the plus button and click Transform

Response .

7. On the Transform response configuration page, provide the following information:a) Enter a stage name in the Name field.b) Enter the following code in the Javascript Transformation section.

var _ = require( 'lodash' ); if ( !res ) { res = { "message": "If you pass more than 3 users, only the first 3 users are added, others will be dropped." }; } else if ( _.isObject( res ) ) { res.message = "If you pass more than 3 users, only the first 3 users are added, others will be dropped."; } done(res);

Add the message code in one line.

c) Click Add.

8. Click More > Export stages to export the configuration of the created Microflow application to aJSON file and save it to your file system.For example, /home/epaasmf/apps/petstore/tibco_mf_petstore.json.

9


Ensure that the exported JSON file is the only file existing in the specified folder.

You can also click More > Import stages to import the configured stages from a JSON file to theMicroflow application. The imported stages will overwrite the existing stages. Ensure that theSwagger API service in the imported file is the same as the current API service.

A sample configuration JSON file, microflow-petstore-sample.json, is provided in theMFCE_Studio/samples/ folder, which contains all the configurations covered in this tutorial. Youcan just import this configuration file rather than manually configuring the stages by yourself.

Uploading the Microflow Build Package to Pivotal Cloud FoundryTo push and run Microflow applications on Pivotal Cloud Foundry, you have to upload the Microflowruntime base build package to the Pivotal Cloud Foundry environment with the administrationpermission.

Microflow applications are actually built upon this base runtime build package before they are pushedto the runtime environment. The uploading of the base runtime build package is a one-time job by thePivotal Cloud Foundry administrator if there's no requirement of the build package customization.

Procedure

1. Download TIBCO Microflow Container Edition artifacts from https://edelivery.tibco.com.The Microflow runtime build package is compressed to a .zip file named mfce-buildpack_cf-version.

If you want to customize the runtime build package by including extra Node.js modules,run the updateBuildPack script to create a customized build package.

For more details, see Customizing Microflow Build Package.

2. Open a command line and log on to the Pivotal Cloud Foundry environment with youradministrator account.

3. On the command line, navigate to the extracted MFCE_Buildpack/build folder, and then enter thefollowing command to upload the build package:

./uploadBuildpack.sh Path_mfce-buildpack.zip buildpackName

where:

● Path_mfce-buildpack.zip: the location of the Microflow runtime build package. You caneither use the default Microflow build package downloaded in Step 1 or the customizedMicroflow build package created in Customizing Microflow Build Package.

● buildpackName: the build package name that you want to use on Pivotal Cloud Foundry.

For example, ./uploadBuildpack.sh /home/epaasmf/mfce-buildpack_cf-v1.0.0.24.zipmfce-buildpack24

4. Enter the following command to view the uploaded build package when the uploading iscompleted:cf buildpacks

10



Pushing and Running Microflow Apps on Pivotal Cloud FoundryAfter the Microflow application has been created at design time and exported to a file, and the runtimebuild package is available in the Pivotal Cloud Foundry environment, you can push and run Microflowapplications on Pivotal Cloud Foundry.

Prerequisites

Ensure that the Microflow runtime build package is uploaded to Pivotal Cloud Foundry, as described in Uploading the Microflow Build Package to Pivotal Cloud Foundry.

Procedure

1. Open a command line and log in to Pivotal Cloud Foundry.

2. Enter the following command to push and run a Microflow application with the configured stagesto Pivotal Cloud Foundry:

cf push APP -p PATH -b BUILDPACK

where:

● APP: the name of the application to push.

● PATH: the location of the JSON configuration file that is exported in Creating a Microflow AppBased on Cloud API Service.

● BUILDPACK: the build package name of Microflow used on Pivotal Cloud Foundry.

This parameter is optional. If the no build package is specified, the program can detectthe corresponding build package to use.

For example, cf push tibcopetstoremfapp -p /home/epaasmf/apps/petstore -b mfce-buildpack24

11


Pushing Microflow Applications

3. After the push is successful and pushed Microflow application is running as shown in the PushingMicroflow Applications figure, open a web browser and go to Microflow runtime endpoint.

The Microflow runtime endpoint is returned as urls when the push is successful.The Swagger API UI of the Microflow application is displayed in the browser. You can test theapplied stages on Swagger UI. You can also open the Swagger specification of the Microflowapplication in the browser, for example, http://tibcopetstoremfapp.tibcoqa.com/swagger/swagger.json, and then download the API specification in the Swagger format to build clientapplications.

12


Testing Microflow AppsAfter the Microflow application is running on Pivotal Cloud Foundry, you can test the Microflowapplication either using the Swagger UI or other third-party tools such as Postman.

The following procedure shows how to test the Microflow application on Swagger UI. Ensure that theMicroflow application has been configured with the Transform Request and Transform Responsestages, as described in Creating a Microflow App Based on Cloud API Service.

Procedure

1. On the Swagger UI of the Microflow application, expand the user resource and click the Post /user/createWithArray operation.

13


2. Enter the following 4 objects in the body field:[ { "id": 1, "username": "Michael", "firstName": "Michael", "lastName": "Manno", "email": "[email protected]", "password": "131313", "phone": "131313", "userStatus": 0 }, { "id": 2, "username": "Jack", "firstName": "Jack", "lastName": "Liu", "email": "[email protected]", "password": "131313", "phone": "131313", "userStatus": 0 }, { "id": 3, "username": "John", "firstName": "John", "lastName": "Tian", "email": "[email protected]", "password": "131313", "phone": "131313", "userStatus": 0 }, { "id": 4, "username": "Lily", "firstName": "Lily",

14


"lastName": "Liu", "email": "[email protected]", "password": "131313", "phone": "131313", "userStatus": 0 } ]

3. Click Try it Out. A status code 200 with the following message is returned, which shows that thestage applied to the response pipeline takes effect."If you pass more than 3 users, we just save the first 3 users, others will be

dropped"

4. Click the GET /user/{username} operation and enter a user name; then click Try it Out.

● If Michael is entered as the value of the username parameter, a status code 200 is returned withthe user information.{ "id": 1, "username": "Michael", "firstName": "Michael", "lastName": "Manno", "email": "[email protected]", "password": "131313", "phone": "131313", "userStatus": 0}

● If Lily is entered as the value of the username parameter, a status code 404 is returned withthe following message, which shows the stage applied to the request pipeline takes effect;therefore, only the first 3 objects in the request JSON payload have been added.{ "code": 1, "type": "error", "message": "User not found"}

15


Customizing Microflow Build Package

The Microflow runtime base build package includes all the binaries required to run Microflowapplications. However, when using the Microflow Custom JavaScript stage, you might want to useextra JavaScript or Node.js modules in the scripts, you can customize the base build package to includethese modules.

TIBCO Microflow Container Edition supports the use of modules from https://www.npmjs.com. Thefollowing Node.js modules are already shipped with the Microflow build package. You do not have tocustomize the build package if these modules fulfill your custom script requirements:

● lodash

● moment

● q

● jsonwebtoken

● validator

● uuid

● compression

● async

● request

● jsdom

● xml2js

● ws

Prerequisites

Ensure that your computer has the access to internet, and Node 4.0.0 and NPM 3.3.3 are installed.

Procedure

1. Download the TIBCO Microflow Container Edition artifacts from https://edelivery.tibco.com.

2. Extract the mfce-buildpack_version.zip file to a temporary location.

3. Navigate to the extracted MFCE_Buildpack/build folder and open the package.json file.

4. Add your own Node.js modules in the package.json file.For example, you can install the gulp module by adding the following information to thedependencies element:"dependencies": { "gulp":"3.9.1" }

See https://docs.npmjs.com/files/package.json#dependencies for more details.

5. Optional: Back up the mfce-runtime-version.zip file located in the extracted MFCE_Buildpack/resources/cache folder.It is good practice to back up the runtime file before running the updateBuildpack.sh file, becausethe original runtime file will be replaced by the new generated one.

6. Open a command line and navigate to the extracted MFCE_Buildpack/build folder.

7. Enter the following command to create your own Microflow build package with the specifiedNode.js modules:

./updateBuildpack.sh path_Package.json buildpack_name

16


https://www.npmjs.com


https://docs.npmjs.com/files/package.json#dependencies

where:

● path_Package.json: the location of the package.json file that contains the added Node.jsmodules to be installed.

This parameter is optional. In this tutorial, you do not have to provide this parameter,because the package.json file in the same folder of the script is used when nopackage.json file is provided.

● buildpack_name: the name of the Microflow build package that you want to use.

For example: ./updateBuildpack.sh mfce-runtime-buildpack-customized

Result

A runtime Microflow build package with the specified name is generated in the build folder. You canupload this new generated build package to your Pivotal Cloud Foundry environment.

For more details, see Uploading the Microflow Build Package to Pivotal Cloud Foundry.

17


Stage Reference

A stage is a piece of reusable code that performs specific capabilities for the API. Stages are used toprovide capabilities as throttling, caching, and routing without requiring you to create any code.Besides, you can use custom JavaScript stage to create your own stages if no out-of-the-box stage exists.

The following stages are available to use:

● Caching Stage: use this stage to reduce the number of requests to the resource by caching data froma backend resource. Each GET operation can have only one Caching stage configured.

● Throttling Stage: use this stage to regulate the number of concurrent requests per second. Each GEToperation can have only one Throttling stage configured.

● Transformation Stage: use this stage to transform the incoming JSON object to another JSON objectusing JavaScript code.

● Routing Stage: use this stage to route the request to another destination according to the configuredrouting rules. Each operation can have only one Routing stage configured.

● Custom JavaScript Stage: use this stage to create custom stages for the request pipeline and responsepipeline using JavaScript code or the node JavaScript modules provided by TIBCO.

Caching StageUse the Caching stage to cache data from a backend resource, reducing the number of requests to theresource.

Configurations

The Caching stage contains the following configurations.

Field Description

Time The time interval that the cached response is kept.

The first time the API backend receives a request message, the response iscached. On the second request within the specified time interval, a cache hitoccurs. The cached response is returned to the application with no requestforwarded to the backend service. By default, the cache memory is 20 MB. Ifthe cached response data exceeds the default memory, the oldest data isdeleted.

Operation The operation that you want to apply this stage to. You can click the drop-down menu to change the operation or select more operations.

Throttling StageUse the Throttling stage to regulate the number of concurrent requests processed by the API persecond.

Configurations

The Throttling stage contains the following configurations.

Only one Throttling stage can be added to each GET operation in the request pipeline.

18


Field Description

TPS (transactionsper second)

The maximum number of requests that are handled per second.

Operation The operation that you want to apply this stage to. You can click the drop-down menu to change the operation or select more operations.

Transformation StageUse the Transformation stage to transform the incoming JSON object to another JSON object usingJavaScript code.

Configurations

The Transformation stage contains the following configurations.

Field Description

Name Name of the transformation stage.

Description Description of the transformation stage.

JSON input Model schema transferred from request or response.

● In the request flow, this is the model schema transferred from theoriginal request body of the operation.

● In the response flow, this is the model schema transferred from theoriginal response of the operation.

JavaScript payloadtransformation/JavaScriptTransformation

JavaScript code to process the request.

● In the request flow, the parameters passed to the custom JavaScriptfunction are payload and done, where done is the callback function tobe invoked by users with processed result, whenever the code finishesits execution.

● In the response flow, the parameters passed to the custom JavaScriptfunction are res and done, where done is the callback function to beinvoked by users with processed result, whenever the code finishes itsexecution.

JavaScript in the Transformation stage has similar features as in theCustom JavaScript stage, see Custom JavaScript Stage for more details.

JSON output Sample schema generated based on the given input JSON and JavaScriptcode.

19


Request Transformation ExampleThe following sample code shows how to add a prefix tibco- to the name field when calling thePOST/pet API of the Petstore sample.

Configuration

The following is request transformation configuration:var _ = require('lodash');if (_.isObject(payload)) { payload.name = 'tibco-'+payload.name;}done(payload);

Result

After running the Microflow application on Pivotal Cloud Foundry with the configured stage, send aPOST request to <Microflow_endpoint>/v2/pet, for example, http://tibcopetstoremfapp.tibcoqa.com/v2/pet with the following data:

{ "id":0, "category": { "id":0, "name":"string" }, "name":"doggie", "photoUrls": [ "string" ], "tags":[ { "id":0, "name":"string" } ],

20


"status":"available"}

From the response, you can find that the prefix tibco- is added to the pet name.

Response Transformation ExampleThe following sample code shows how to add a field vendor with the value TIBCO to the response ofthe GET/pet/{petId} operation of the Petstore sample.

Configuration

The following is response transformation configuration:var _ = require('lodash');if (_.isObject(res) && !_.isArray(res)) { res.vendor = 'TIBCO';}done(res);

21


Result

After running the Microflow application on Pivotal Cloud Foundry with the configured stage, send arequest to <Microflow_endpoint>/v2/pet/{petId} , for example, http://tibcopetstoremfapp.tibcoqa.com/v2/pet/1 .

From the response, you can find that a vendor field with the value TIBCO is added in the response.

Routing StageUse the Routing stage to route the request to another destination according to the configured routingrules. Each routing rule includes a condition, a customized request, a destination, and a customizedresponse.

Routing stage evaluates the routing rules by using the if...else if...else statement, like thefollowing pseudo-code:

22


Each operation can contain only one Routing stage at the end of the request flow.

if condition 1 is true if pre-destination transformation exists do the transformation

get the data from the destination

if post-destination transformation exists do the transformation

else if condition 2 is true ......

else get the data from the default destination

Configurations

The routing stage contains the following configurations.

Field Description

Condition A condition expression is evaluated against the if statement ofJavaScript.

In the context of evaluation, a parameter req is available, with the query,params, headers, and payload fields of the request object exposed.

REQUEST The JavaScript code to process the request.

The parameter passed to the custom JavaScript function is payload,which is the payload field of the request object. This behavior is the sameas Transformation Stage in the request flow.

Destination A relative URL or an absolute URL of the destination.

If a relative URL is provided, the original host, port, and protocolinformation is used to process the request. For example, if /v2/pet isprovided, and the original host is petstore.cloud.tibco.com, portnumber is 2222, and protocol is http, the request with the routing stageapplied is directed to http://petstore.cloud.tibco.com:2222/v2/pet.

RESPONSE The parameter passed to the custom JavaScript function is res, which isthe response data sent from the destination.

This behavior is the same as Transformation Stage in the response flow.

Routing Stage ExampleThe following sample code shows how to redirect the pet/findByStatus?status=all request sent tothe GET/pet/findByStatus operation to http://petstore.swagger.io/v2/pet/findByStatus?status=available,pending,sold.

Configuration

The following are the configurations of the routing stage:

23


● Conditionreq.query.status && /all/.test(req.query.status)

● Destination/pet/findByStatus?status=available,pending,sold

Result

After running the Microflow application with the configured stage on Pivotal Cloud Foundry, send aGET request to <Microflow_endpoint>/v2/pet/findByStatus?status=all, the result is the same asquerying <Microflow_endpoint>/v2/pet/findByStatus?status=available,pending,sold.

24


Custom JavaScript StageUse the Custom JavaScript stage to create your own stages if no out-of-the-box stage exists. You canconfigure different custom stages for request and response pipelines.

Microflow allows you to create JavaScripts working in either synchronous or asynchronous mode. Oneof the JavaScript's strength is the way it handles asynchronous (async) code. Instead of getting blocked,the thread is pushed in an event queue which gets fired after the execution of all the other codes. Thismeans that you can let your code do several things at the same time without stopping or blocking yourmain thread.

You can also leverage the Node.js modules available on https://www.npmjs.com/ in the customJavaScript. By default, TIBCO Microflow Container Edition ships a set of widely used Node.js modulesthat can be used off the shelf. However, you can also use whatever the modules you like by customizingthe Microflow runtime build package. See Customizing Microflow Build Package for more details.

The following list is the already shipped Node.js modules that can be used off the shelf:

● lodash

● moment

● q

● jsonwebtoken

● validator

● uuid

● compression

● async

● request

● jsdom

● xml2js

● ws

Configurations

The Custom JavaScript stage contains the following configurations.

Field Description

Name Name of the custom JavaScript stage.

Description Description of the custom JavaScript stage.

JSON input Model schema transferred from request or response.

● In the request flow, this is the model schema transferred from theoriginal request body of the operation.

● In the response flow, this is the model schema transferred from theoriginal response of the operation.

Examples JavaScript code sample.

25


https://www.npmjs.com/

Field Description

Custom code JavaScript code to process the request.

● In the request flow, the parameters passed to the custom JavaScriptfunction are req and done, with the query, params, headers andpayload fields of the request object exposed.

● In the response flow, the parameters passed to the custom JavaScriptfunction are res and done. In both the request and response cases,done is an internal implemented callback function. It is used by thecustom script for notifying the invoker of this custom script that allworks have been done, so the control is returned back to the invoker.This done callback is invented to facilitate the asynchronous scriptingmode, and is also used by synchronous scripting for consistency.

Example

The following sample code adds a vendor parameter in the response for the GET/pet/findByStatusoperation of the Petstore sample.var _ = require('lodash');if (_.isArray(res)) { res = { raw: res, total: res.length, vendor: 'TIBCO' }; done(res);}

After running the Microflow application on Pivotal Cloud Foundry with the configured stage, query<Microflow_endpoint>/v2/pet/findByStatus?status=sold, you can get the following response asshown.

26


Async ModuleTo support asynchronous scripting, a callback function done is provided. It has to be called from thecustomer script at the right time, normally when the code execution is finished. In a typicalasynchronous scripting, it is called from within a special function where all the asynchronousexecutions end up with.

The following sample code shows how to add a piece of async JavaScript code to customize theresponse data. It uses a Node module async and the series() function to send requests to two websitein series and asynchronously waits for the responses to come back. After both of the responses arereceived from the two website, the callback function function(err, results) is called, and thestatusCode of the two responses are to be added to the response object. The done() callback is thencalled inside this function to notify the Microflow logic that the running of this custom JavaScript isdone, with the modified response being returned along with the vendor and total number of results.var _ = require('lodash');var async = require('async');var request = require('request');async.series([function(callback) { request('http://www.outlook.com', function(error, response, body) { if (!error && response.statusCode == 200) { callback(null, response.statusCode); } });},function(callback) { request('http://www.yahoo.com', function(error, response, body) { if (!error && response.statusCode == 200) { callback(null, response.statusCode); } });

27


}],function(err, results) { if (_.isArray(res)) { res = { raw: res, total: res.length, vendor: 'TIBCO', result: results }; } else { res.vendor = 'TIBCO'; res.result = results; } done(res);});

After running the Microflow application with the configured stage on Pivotal Cloud Foundry, query<Microflow_endpoint>/v2/pet/findByTags?tags=tag3, you can get the result as shown.

28


TIBCO Microflow Container Edition User's Guide€¦ · Getting Started This tutorial shows ......

Documents

Transcript of TIBCO Microflow Container Edition User's Guide€¦ · Getting Started This tutorial shows ......