tibco microflow container edition user's guide€¦ · pivotal cloud foundry environment. see...

TIBCO Microflow™ Container EditionUser's GuideSoftware Release 1.2November 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

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

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

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

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

Testing Microflow Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Adding a Front-End API for API Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Show Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

Cat Service Swagger Specification Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Running Microflow Applications in Docker Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Creating Microflow Base Docker Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Creating Microflow Application Docker Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Testing Microflow Applications in Local Docker Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

Running Microflow Applications in Kubernetes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32

Testing Microflow Applications in a Kubernetes Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Customizing Microflow Runtime Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Customizing Build Package for Pivotal Cloud Foundry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Customizing Runtime Package for Docker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Stage Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Caching Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Throttling Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Transformation Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38

Request Transformation Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Response Transformation Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

Routing Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Routing Stage Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Custom JavaScript Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Async Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Custom Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47

Request Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

3


Figures

TIBCO Microflow Container Edition Home Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Pushing Microflow Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

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, 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, or in a Docker container that can be deployed on anysupported platform such as Google Kubernetes.

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 or any platform that supports Dockercontainers such as Google Kubernetes. See Starting TIBCO Microflow Container Edition DesignTime and Creating a Microflow App Based on Cloud API Service for more details.

● Run Time

At run time, you can either create a Microflow build package to deploy and run Microflowapplications on the Pivotal Cloud Foundry platform or create a Docker image to deploy and runMicroflow applications on any platform that supports Docker containers.

— Run Time for Pivotal Cloud Foundry

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

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

You can even customize this base build package to include third-party Node.js modules, whichcan be used in the Microflow Custom JavaScript stage. See Customizing Build Package forPivotal Cloud Foundry for more details.

— Run Time for Docker Container

You can also run the created Microflow application in a Docker container. The Docker containercan be deployed on any supported platform such as Google Kubernetes. For more details, see Running Microflow Applications in Docker Containers.

Microflow application Docker image is built based on the base Microflow Docker image.Dockerfiles and scripts are provided to build both the base Docker image and the applicationDocker image.

Before building the base Docker image, you can also customize the Microflow runtime packageused for building the base Docker image to include third-party Node.js modules. The addedthird-party Node.js modules are used in the Microflow Custom JavaScript stage to control theAPI behavior. See Customizing Runtime Package for Docker for more details.

6


Download TIBCO Microflow Container Edition artifacts from https://edelivery.tibco.com, including thedesign-time package mfce-studio-version.zip, the runtime package mfce-buildpack_cf-version.zip for Pivotal Cloud Foundry, and mfce-docker-version.zip for Docker support.

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; the variableMFCE_Buildpack points to the top-level directory where mfce-buildpack_cf-version.zip isextracted, for example, /home/epaasmf/mfce-buildpack; and MFCE_docker points to the top-leveldirectory where mfce-docker-version.zip is extracted, for example, /home/epaasmf/mfce-docker.

7


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.

In this tutorial, the Pivotal Cloud Foundry platform is used as the runtime environment. If you want touse Docker as the application container, see Running Microflow Applications in Docker Container formore details. But whatever the runtime environment is, the design time is the same.

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

8


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


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.

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.

9


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.

10


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.

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 jobperformed by the Pivotal Cloud Foundry administrator if there's no requirement of the build packagecustomization.

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 Build Package for Pivotal Cloud Foundry.

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 Build Package for Pivotal Cloud Foundry.

● 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

11



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

12


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.

13


Testing Microflow AppsAfter the Microflow application is running on Pivotal Cloud Foundry, you can test the Microflowapplication either by 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.

14


Make sure that application/json is chosen for Parameter content type.

Microflow supports the following content-types for POST and PUT requests:

● application/json: for sending JSON format data

● application/xml: for sending XML documents

● application/x-www-form-urlencoded: for sending name-value pair form data usingurlencoded format

● multipart/form-data: for sending form data that contains files in multipart MIME format

Not all content types are always available. For example, in the operation shown,application/json and application/xml are the only two options available.

2. Enter the following 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",

15


"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", "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 that the stage applied to the request pipeline takes effect;therefore, only the first three objects in the request JSON payload have been added.{ "code": 1, "type": "error", "message": "User not found"}

16


Adding a Front-End API for API Customization

TIBCO Cloud Integration - Microflow provides the functionality to expose a customized front-end APIto a specific group of users based on a generic back-end API. The back end is the source of truth for thebusiness logic of your service, which defines the behavior of your service; while, the front end deliversthe APIs customized for specific groups of users. Microflow achieves this by linking the front-endspecification to the back-end specification.

Using this Backend-for-Frontend pattern, you can easily derive multiple services from a back-endapplication without any code effort.

For example, a shop hosts a service that sells all sorts of things. In order to maximize its marketing, theshop decides to create APIs specific to a certain type of items such as books or movies. Instead ofcreating multiple integration applications which are very costly, the shop decides to build specific APIsfor each of those items that in the end call the same integration application. Each Microflow applicationexposes a different front-end API and transforms the requests of all sorts into the generic format tosend to the back-end integration application.

The following tutorial shows how to create a Cat service by modifying one API operation from thePetstore service from http://petstore.swagger.io.

Prerequisites

● Start the design-time environment as described in Starting TIBCO Microflow Container EditionDesign Time

● Add a Microflow application as described in Creating a Microflow App Based on Cloud APIService. This example assumes an application named petstore_sample_microflow created fromhttp://petstore.swagger.io.

Procedure

1. Open a web browser and go to localhost:8001.The TIBCO Microflow Container Edition home page is displayed.

2. On the TIBCO Microflow Container Edition page, click the application,petstore_sample_microflow.The Microflow page is displayed.

17


3. In the left Operations section, click Frontend API > Import to import the front-end APIspecification.

You can model your Cat service in TIBCO Cloud Integration - API Modeler based on the existingPetstore API specification, and then export the Cat API specification in the Swagger JSON format.This Cat API specification is used as the front-end specification in this tutorial.

Cat Service Swagger Specification Reference is a copy of the Cat Swagger specification.

The API specification must be a Swagger specification.

4. Click Continue when you are prompted to confirm the importing.

5. Click the operation that you want to link a front-end operation to, POST/pet is selected in thistutorial; then move the cursor to the REQUEST button at the top of the flow.

6. Click the unlinked list and then select the /cat operation as the front-end operation.

18


A list of POST operations are displayed, including the one /cat in the new Cat API specification thatyou just imported.

If you do not choose another operation to replace the original one, it indicates that you stillwant to use the original back-end operation as the front-end operation. Therefore, makesure the original back-end operation is also added in your new front-end specification.

7. Export the JSON configuration file by clicking More > Export Stages.

8. Push and run the Microflow application by following the steps in Pushing and Running MicroflowApps on Pivotal Cloud Foundry. This also describes how to open the Swagger UI for the API inyour browser. Ensure that the Microflow runtime build package has been uploaded to PivotalCloud Foundry, as described in Uploading the Microflow Build Package to Pivotal Cloud Foundry.

9. On the Swagger page, click the Cat resource and then post a cat using the default model schema.The front-end API operations are shown up for testing, rather than the back-end API operations.

19


10. Click Try it out to send the request.

Result

The customer can now use a new operation to access the service by replacing the original operationwith a new front-end operation. Microflow translates the request to the front-end operation into arequest in the format of the back-end API and sends it to the back-end service.

For each operations in the front-end specification, you either make sure they are explicitly linked to aback-end operation, or they exist the same way in the back-end specification; otherwise sending requestto these front-end operation will fail.

Show RelationshipsAfter linking the front-end API operation to the corresponding back-end API operation, you can use theShow relationships function to view the mapping between the API operations, together with theMicroflow stages that have been applied to these operations.

Procedure

● On the Microflow editing page, click Frontend API > Show relationships in the Operations section,the API operation mapping is displayed along with the configured stages of the front-end APIoperation:

20


Cat Service Swagger Specification ReferenceThe following is the front-end Cat service used in the Adding a Front-End API for API Customizationtutorial.{ "swagger": "2.0", "info": { "description": "This is a sample front-end swagger spec for Petstore microflow application: Once Dan updated his story of accessing petstore data with stages, he may want to make the APIs look easier to understand, in this sample, we assume Dan already setup a cat story of accessing cats in petstore, and made out a series of APIs which as alternative of original ones.", "version": "1.0.0", "title": "Front-end swagger spec (story of accessing cats in petstore)", "termsOfService": "http://swagger.io/terms/", "contact": { "email": "[email protected]" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "host": "petstore.swagger.io", "basePath": "/v2", "tags": [ { "name": "cat", "description": "Everything about your Cats", "externalDocs": { "description": "Find out more", "url": "http://swagger.io"

21


} }, { "name": "store", "description": "Access to Petstore orders" }, { "name": "user", "description": "Operations about user", "externalDocs": { "description": "Find out more about our store", "url": "http://swagger.io" } } ], "schemes": [ "http" ], "paths": { "/cat": { "post": { "tags": [ "cat" ], "summary": "Add a new cat to the store", "description": "", "operationId": "addCat", "consumes": [ "application/json", "application/xml" ], "produces": [ "application/xml", "application/json" ], "parameters": [ { "in": "body", "name": "body", "description": "Cat object that needs to be added to the store", "required": true, "schema": { "$ref": "#/definitions/Cat" } } ], "responses": { "405": { "description": "Invalid input" } }, "security": [ { "petstore_auth": [ "write:cats", "read:cats" ] } ] }, "put": { "tags": [ "cat" ], "summary": "Update an existing cat", "description": "", "operationId": "updateCat", "consumes": [ "application/json", "application/xml" ], "produces": [

22


"application/xml", "application/json" ], "parameters": [ { "in": "body", "name": "body", "description": "Cat object that needs to be added to the store", "required": true, "schema": { "$ref": "#/definitions/Cat" } } ], "responses": { "400": { "description": "Invalid ID supplied" }, "404": { "description": "Cat not found" }, "405": { "description": "Validation exception" } }, "security": [ { "petstore_auth": [ "write:cats", "read:cats" ] } ] } }, "/cat/{catId}": { "get": { "tags": [ "cat" ], "summary": "Find cat by ID", "description": "Returns a single cat", "operationId": "getCatById", "produces": [ "application/xml", "application/json" ], "parameters": [ { "name": "catId", "in": "path", "description": "ID of cat to return", "required": true, "type": "integer", "format": "int64" } ], "responses": { "200": { "description": "successful operation", "schema": { "$ref": "#/definitions/Cat" } }, "400": { "description": "Invalid ID supplied" }, "404": { "description": "Cat not found" } }, "security": [

23


{ "api_key": [] } ] }, "post": { "tags": [ "cat" ], "summary": "Updates a cat in the store with form data", "description": "", "operationId": "updateCatWithForm", "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/xml", "application/json" ], "parameters": [ { "name": "catId", "in": "path", "description": "ID of cat that needs to be updated", "required": true, "type": "integer", "format": "int64" }, { "name": "name", "in": "formData", "description": "Updated name of the cat", "required": false, "type": "string" }, { "name": "status", "in": "formData", "description": "Updated status of the cat", "required": false, "type": "string" } ], "responses": { "405": { "description": "Invalid input" } }, "security": [ { "petstore_auth": [ "write:cats", "read:cats" ] } ] } }, "/store/order": { "post": { "tags": [ "store" ], "summary": "Place an order for a cat", "description": "", "operationId": "placeOrder", "produces": [ "application/xml", "application/json" ], "parameters": [ {

24


"in": "body", "name": "body", "description": "order placed for purchasing the cat", "required": true, "schema": { "$ref": "#/definitions/Order" } } ], "responses": { "200": { "description": "successful operation", "schema": { "$ref": "#/definitions/Order" } }, "400": { "description": "Invalid Order" } } } }, "/user": { "post": { "tags": [ "user" ], "summary": "Create user", "description": "This can only be done by the logged in user.", "operationId": "createUser", "produces": [ "application/xml", "application/json" ], "parameters": [ { "in": "body", "name": "body", "description": "Created user object", "required": true, "schema": { "$ref": "#/definitions/User" } } ], "responses": { "default": { "description": "successful operation" } } } } }, "securityDefinitions": { "petstore_auth": { "type": "oauth2", "authorizationUrl": "http://petstore.swagger.io/oauth/dialog", "flow": "implicit", "scopes": { "write:cats": "modify cats in your account", "read:cats": "read your cats" } }, "api_key": { "type": "apiKey", "name": "api_key", "in": "header" } }, "definitions": { "Order": { "type": "object",

25


"properties": { "id": { "type": "integer", "format": "int64" }, "catId": { "type": "integer", "format": "int64" }, "quantity": { "type": "integer", "format": "int32" }, "shipDate": { "type": "string", "format": "date-time" }, "status": { "type": "string", "description": "Order Status", "enum": [ "placed", "approved", "delivered" ] }, "complete": { "type": "boolean", "default": false } }, "xml": { "name": "Order" } }, "User": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "username": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" }, "phone": { "type": "string" }, "userStatus": { "type": "integer", "format": "int32", "description": "User Status" } }, "xml": { "name": "User" } }, "Category": { "type": "object",

26


"properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } }, "xml": { "name": "Category" } }, "Tag": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } }, "xml": { "name": "Tag" } }, "Cat": { "type": "object", "required": [ "name", "photoUrls" ], "properties": { "id": { "type": "integer", "format": "int64" }, "category": { "$ref": "#/definitions/Category" }, "name": { "type": "string", "example": "catgie" }, "photoUrls": { "type": "array", "xml": { "name": "photoUrl", "wrapped": true }, "items": { "type": "string" } }, "tags": { "type": "array", "xml": { "name": "tag", "wrapped": true }, "items": { "$ref": "#/definitions/Tag" } }, "status": { "type": "string", "description": "cat status in the store", "enum": [ "available", "pending",

27


"sold" ] } }, "xml": { "name": "Cat" } }, "ApiResponse": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "type": { "type": "string" }, "message": { "type": "string" } } } }, "externalDocs": { "description": "Find out more about Swagger", "url": "http://swagger.io" } }

28


Running Microflow Applications in Docker Containers

Apart from Pivotal Cloud Foundry, you can also run your Microflow applications in Docker containers.The Docker container can be run anywhere it is supported such as the Kubernetes setup on GoogleCloud Platform.

Complete the following tasks to run Microflow Applications in a Docker container:

1. Creating Microflow Base Docker Image

Firstly, you have to build the Microflow base Docker image with the scripts provided in the mfce-docker_version.zip artifact. The base Docker image is the base where your Microflow applicationDocker image is built on.

For more details, see Creating Microflow Base Docker Image.2. Creating Microflow Application Docker Image

Then, use the JSON configuration file of your Microflow application to build your applicationDocker image based on the base image created in the previous task. The JSON file is exported whenconfiguring your Microflow application, as described in Creating a Microflow App Based on CloudAPI Service.The required scripts are also provided in the mfce-docker_version.zip artifact.

For more details, see Creating Microflow Application Docker Image.3. Testing and Running Microflow Applications in Docker Containers

After the application Docker image is built, you can run the application image in a Docker container.

For more details, see Testing Microflow Applications in Local Docker Container.

Creating Microflow Base Docker ImageMicroflow base Docker image contains all the code and libraries to run a Microflow application. It is thebase where a Microflow application Docker image is built on.

The base image includes Microflow runtime package installed under the MFCE_docker/resource/cache directory. If you want to use a third-party Node.js module in your custom JavaScript stage, youcan customize the runtime package to add your module by running the undateRuntime script beforecreating your base Docker image. For more details, see Customizing Runtime Package for Docker.

Prerequisites

● The scripts to build the Docker image are written in Bash. You have to run it on Unix/Linux or MacOS X.

● Download and install the Docker Toolbox on your system.

Before executing the command to build the base Docker image, ensure that your Docker Toolbox isinstalled successfully and the Docker machine is running and connected. The Docker machinemight be the "default" as part of the Docker Toolbox, or whatever the other Docker machineconnected with your local environment.

Procedure

1. Download TIBCO Microflow Container Edition artifacts from https://edelivery.tibco.com.2. Find the Microflow docker package mfce-docker_version.zip from the downloaded files, and

then extract it to temporary location, for example MFCE_docker.3. Open a command line and navigate to the extracted MFCE_docker folder.4. Run the following command:

./createBaseImage.sh base_image_tag

29



Where Base_image_tag is the tag of the base image to be built. This parameter is optional and thedefault value is mfce-runtime:latest.

If you want to use another tag, you have to replace the value of the FROM command in theDockerfile file located in the MFCE_docker/app folder. When you create your applicationDocker image, this Dockerfile for creating the application Docker image refers to thedefault base image tag.

Result

The Microflow base Docker image is built on the Docker machine with the provided tag.

Creating Microflow Application Docker ImageAfter creating the Microflow base Docker image, you can build your Microflow application to anapplication Docker image.

For more details about how to create a Microflow application, see Getting Started.

Prerequisites

● The scripts to build the Docker image are written in Bash. You have to run it on Unix/Linux or MacOS X.

● The Microflow base Docker image has been built and existed on the connected Docker machine.

For more details, see Creating Microflow Base Docker Image.

● The configuration JSON file of the Microflow application has been exported.

For more details, see Creating a Microflow Application.

Procedure

1. Copy the exported configuration JSON file of your Microflow application to the MFCE_docker/appfolder.MFCE_docker is the root folder where the downloaded mfce-docker_version.zip file is extracted.

2. Open a command line and navigate to MFCE_docker/app.

3. Run the following command to build the application image:./createAppImage.sh app_image_tag

Where app_image_tag is the tag of the application image to be built. This parameter is optionaland the default value is my-mfce-app:latest.

The application Docker image is built based on the base Docker image created earlier, asdescribed in Creating Microflow Base Docker Image. If the created base Docker imageuses a custom tag other than the default mfce-runtime:latest, you have to replace thevalue of the FROM command in the Dockerfile file located in the MFCE_docker/app folder.

Result

The application Docker image is created and exists in the connected Docker machine.

30


Testing Microflow Applications in Local Docker ContainerAfter creating your Microflow application Docker image with the Docker machine, you can test it onthe connected Docker machine.

Procedure

1. Open a command line and navigate to the MFCE_docker/app folder.

2. Enter the following command to run the application image:./runApp.sh -i image_ID -p port_on_host -n app_name

where:

● Image_ID: the ID of the application image. You can get this by running the ./docker imagescommand.

● Port_on_host: the port number of the application to be exposed by the Docker machine. Thisparameter is optional and default value is 8081.

● App_name: the name of the Docker container running the application. This parameter is optional.If no value is provided, an arbitrary name is assigned to the Docker container running theapplication.

After the script is successfully executed, a Docker container running the Microflow application isstarted on the connected Docker machine.

3. After the Docker container is successfully started, open a web browser and go to Microflow runtimeendpoint.The Microflow runtime endpoint is http://<docker_machine_ip>:<port>.

where:

● docker_machine_ip: the IP address of the connected Docker machine.

● port: the port number exposed by the Docker machine for the Docker container running theMicroflow application. This must be the same as the Port_on_host parameter specified in Step2.

4. Test the Microflow application.

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://<docker_machine_ip>:<port>/swagger/swagger.json, and then download the API specification in the Swagger format to build clientapplications.

You can then test the applied stages on Swagger UI, as described in Testing Microflow Applications.

31


Running Microflow Applications in Kubernetes

You can run your Microflow applications by pushing a local Docker container to Kubernetes.containers.

Prerequisites

● A Google Cloud account with a project and cluster

● The Google Cloud SDK

● The kubectl command-line interface

Procedure

1. From a terminal, follow these steps:gcloud auth logingcloud config set project <your project>gcloud config set container/cluster <your cluster>gcloud container clusters get-credentials <your cluster> --zone <your cluster zone>kubectl get nodes

2. Tag the Microflow application image created in the local Docker:docker tag <local mfce image name> gcr.io/<your project>/<local mfce image name>

3. Push your local Microflow application image to the Google Container Registry:gcloud docker push gcr.io/<your project>/<local mfce image name>

4. Confirm that the image is present in the Google Container Registry.

5. Open the manifest.yml file and update the application image name. Ensure the image namefollows the format:gcr.io/<your gcloud project name>/<image name>

Microflow applications use port 8081.

6. Navigate to the samples directory where the manifest file is present and type in the belowcommand to create the service:kubectl create -f manifest.yml

7. To check that application is started successfully, type in below command:kubectl get services

32


Manifest.yml Example

The following is an example of the manifest.yml file:apiVersion: v1kind: Servicemetadata: name: <app name> labels: app: <app name>spec: type: LoadBalancer ports: - port: 80 targetPort: 8081 selector: app: <app name>---apiVersion: v1kind: ReplicationControllermetadata: name: <app name>spec: replicas: 1 selector: app: <app name> template: metadata: name: <app name> labels: app: <app name> spec: containers: - name: <app name> image: <tagged local docker image name starting with grcr.io hostname> imagePullPolicy: Always env: - name: BW_LOGLEVEL value: "ERROR" - name: BW_PROFILE value: "docker" ports: - containerPort: 8081

Testing Microflow Applications in a Kubernetes ContainerAfter pushing your Microflow application to Kubernetes, you can test it on the Kubernetes container.

Procedure

1. Get the service external IP address with the following command:kubectl get services

2. Open a web browser and type in the external IP address.The Swagger API UI of the Microflow application is displayed. You can test the applied stages onSwagger UI.

33


Customizing Microflow Runtime Package

The Microflow runtime base build package for PCF and the runtime package for building base Dockerimage include all the binaries required to run Microflow applications. However, when using theMicroflow Custom JavaScript stage, you might want to use extra JavaScript or Node.js modules in thescripts. You can customize the Microflow runtime package (the base build package or the dockerpackage) to include these 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 or the dockerpackage. You do not have to customize the build package if these modules fulfill your custom scriptrequirements:

● lodash● moment● q● jsonwebtoken● validator● uuid● compression● async● request● jsdom● xml2js● ws

For more details, see:

● Customizing Build Package for Pivotal Cloud Foundry● Customizing Runtime Package for Docker

Customizing Build Package for Pivotal Cloud FoundryTo use additional third-party Node.js modules in the Custom JavaScript Stage of Microflow, you canadd the modules by customizing the build package provided for the Pivotal Cloud Foundry.

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 the entries of the Node.js modules you want to use 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" }

34


https://www.npmjs.com


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 in thestep, because the original runtime file will be replaced by the newly generated one after running thescript.

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 -f path_Package.json -t buildpack_name

where:

● buildpack_name: the name of the target Microflow build package to be customized.

This parameter is optional. mfce-buildpack-customized is used as the name of thetarget runtime build package when this parameter is not provided.

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

This parameter is optional. The package.json file in the same folder of the script isused when no package.json file is provided.

For example: ./updateBuildpack.sh -t my-mfce-buildpack

The package.json in the same build sub-folder is used for customizing the build pack, which willbe packaged as my-mfce-buildpack.zip.

Result

A runtime Microflow build package with the specified name is generated in the same folder where theoriginal build package zip file is located. You can upload this new generated build package to yourPivotal Cloud Foundry environment.

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

Customizing Runtime Package for DockerTo use additional third-party Node.js modules in the Custom JavaScript Stage of Microflow, you canadd the modules by customizing the runtime package provided for building the Microflow base Dockerimage.

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-docker_version.zip file to a temporary location, for example MFCE_docker.

3. Open the package.json file in the extracted MFCE_docker/update folder.

4. Add the entries of the Node.js modules you want to use 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" }

35


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


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_docker/resources/cache folder.It is good practice to back up the runtime file before running the updateBuildpack.sh file in thisstep, because the original runtime file will be replaced by the newly generated one after running thescript.

6. Open a command line and navigate to the extracted MFCE_docker/update folder.

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

./updateRuntime.sh -t target_runtime_package_filename -f fullpath_of_package.json

where:

● target_runtime_package_filename: the name of the target Microflow runtime package to becustomized.

This parameter is optional. The runtime package mfce_runtime_versions.zip in theMFCE_docker/resources/cache folder is used as the target runtime package whenthis parameter is not provided.

● fullpath_of_package.json: the full path of the package.json file that contains the addedNode.js modules to be installed, for example: /home/epaasmf/package.json.

This parameter is optional with the default being MFCE_docker/update/package.json. In this tutorial, you do not have to provide this parameter, because thedefault JSON file is used.

For example: ./updateRuntime -t mfce-runtime-customized.zip

Result

A customized Microflow runtime package with the specified name is generated in the folderMFCE_docker/resources/cache. This runtime package can be used later when you build your baseDocker image. The original Microflow runtime package named mfce_runtime_version.zip isreplaced by this customized package.

If you want to do further updates to the runtime package, you can either start from scratch by copyingthe original runtime package backed up in Step 5 and running the script again, or you can continue touse the runtime package that has been updated previously if you just want to do additions.

36


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

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

37


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.

38


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" } ],

39


"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);

40


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:

41


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:

42


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

43


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. See Async Module for more details.

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 already shipped Node.js modules that can be used off the shelf are as follows:

● lodash

● moment

● q

● jsonwebtoken

● validator

● uuid

● compression

● async

● request

● jsdom

● xml2js

● ws

In addition to these modules, an internal module mf-headers is provided by TIBCO Cloud Integration -Microflow. You can use this module to customize which HTTP headers can be passed on from the clientto the back-service side, and vice versa. You can also use this module to add any custom headers toeither the request or the response. See Custom Headers for more information.

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.

44


https://www.npmjs.com/

Field Description

JSON input Model schema transferred from a 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.

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, info,headers andpayload fields of the request object exposed. See Request Propertiesfor more details of these properties.

● 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. This function isused by the custom script to notify the invoker of this custom scriptthat all works have been done, and the control is returned back to theinvoker. This done callback is invented to facilitate the asynchronousscripting mode, and is also used by synchronous scripting forconsistency. See Async Module for more details.

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:

45


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, this function is called from within a special function where all theasynchronous executions end up.

The following sample code shows how to add a piece of async JavaScript code to customize theresponse data. This code uses a Node module async and the series() function to send requests to twowebsites in series and asynchronously waits for the responses to come back. After both responses arereceived from the two websites, 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 iscompleted, with the modified response being returned along with the vendor and total number ofresults.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);

46


} });}],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.

Custom HeadersMicroflow does not forward all the headers of the incoming request to the back-end services, butmaintains an internal white list of the headers to be passed on by default. Headers other than those inthe white list are either irrelevant, or we cannot tell the exact behavior at present if they are passed on.This white list can be expanded to include more headers if they are believed to be relevant and notharmful per customer request or our researches.

The following is the white list of request headers. By default, Microflow only forwards those headers:

● Accept

47


● Accept-Language

● Referer

● Connection

● Authorization

● Accept-Charset

Microflow allows you to pass the custom headers that is not included in the white list, which includethe headers that we cannot tell the exact behaviors at present, or the custom headers sent from theclient. This is achieved by leveraging a Microflow internally implemented module mf-headers.

To forward the custom headers to the backend system or from the backend system to the client, youhave to use the mf-headers module available in the Custom JavaScript stage, or Transformation andRouting stages.

Passing on Custom Headers

The allowHeader function is introduced to pass on a header in the incoming request but is notincluded in the white list.

The following sample code shows how to allow an AS2-Version custom header, used in AS2 B2Bprotocol, to be passed on to the back-end service.var headers = require('mf-headers');headers.allowHeader('AS2-Version');done(req);

Adding Custom Headers

The addHeader function is introduced to add your own headers when the request is forwarded to thebackend system or when the response from backend system is forwarded to the client.

The following sample code shows how to add the `authorization` header to the backend system.var headers = require('mf-headers');headers.addHeader('authorization', 'basic: WEwwewe232de');done(req);

If a REST service is configured with the basic authorization, with the Custom JavaScript stage appliedas shown, the authorization token can be provided by Microflow as the mediator. The end user doesnot have to provide authorization again when using the Microflow endpoint to send the request.

48


Request PropertiesSeveral request object properties are available to use when writing JavaScript code for custom stages.

When using the JavaScript code to create your own stages, the following request object properties areavailable to use:

● info: request information.

● query: an incoming request URI query component (the key-value part of the URI between '?' and'#'). The query is parsed into its individual key-value pairs (using the qs module) and stored inrequest.query. For example: req.query.status && /all/.test(req.query.status).

● headers: the raw request headers. For example: console.log(req.headers).

● payload: request payload.

req.info

Microflow exposes the req.info property for the request object in the Custom Request stage. Use thisproperty with the console.log function, you can obtain the following request information from theMicroflow application log after sending a request to the Microflow endpoint:

● host: content of the HTTP 'Host' header (e.g. 'example.com:8080').

● hostname: the host name of the Host header (for example, example.com).

● received: request reception timestamp.

● referrer: content of the HTTP Referrer (or Referer) header.

● remoteAddress: remote client IP address.

● remotePort: remote client port.

● responded: request response timestamp (0 is not responded yet).

49


tibco microflow container edition user's guide€¦ · pivotal cloud foundry environment. see...

Documents