How to write and use custom Mapper Function Contribution in TIBCO Flogo® Enterprise or TIBCO® Cloud Integration

TIBCO Flogo® Enterprise and TIBCO® Cloud Integration have added support for mapper function contributions giving you flexibility to create your own custom mapper functions, install them as extensions and use within the mapping expressions.

Sometimes we require a specific mapper function to solve our use case.
You don’t find the mapper function you’re looking for? Well, you can write your own :)

For eg, If I want to convert current date time to timestamp in milliseconds,
and if I do not find that function then I can write one. So using mapper function contribution, I can build my own custom mapper functions, upload it from extensions tab and use it in my Flogo application.

Prerequisites: Knowledge about FLOGO product, Go programming language.

Steps:

For creating custom mapper function, you will require 3 files -

1.descriptor.json :

Descriptor.json actually defines what is the category of the function, name of the function, how many arguments it will take, function description, function example, what will be the return type. The function category, name, description, arguments, example will be shown in UI once you upload this contribution. Descriptor.json looks something like below.

{
“name”:”customdatetime”,
“type”:”flogo:function”,
“version”:”0.0.1",
“title”:”customdatetime”,
“description”:”customdatetime function”,
“functions”:[
{
“name”:”totimestamp”,
“description”:”Converts current date time to timestamp”,
“example”:”customdatetime.totimestamp()\nReturns\n1573809431645",
“args”:[

],
“return”:{
“type”:”int64"
},
“display”:{
“visible”:true
}
}
]
}

2. customdatetime.go:

This is the actual code. When the function is called, this code gets called. You will have to import any packages that are required by your code. You will have to register your function in the init method. Name() method will actually return the fuction name. Sig() will define the signature of the function. Eval() will have the logic what your mapper function is supposed to do.

3. go.mod:

This file will have which modules to import. Typically you give the location where the above files reside. For eg. If these files are present on github repo, you can mention something like below -

module github.com/nshahn/contrib/function/customdatetime

4. customdatetime_test.go:

This is a test file which you can use to test the function you have written. This is optional.

Once you are done wirting and testing your own custom functions, zip the folder containing these files and upload the zip file from Extensions Tab in the FLOGO Web UI. You will see the mapper function contribution zip uploaded successfully as below.

You will be able to see the newly added function under Functions as below -

If you go to the mapper and look at mapper functions, you will see the newly added function “totimestamp” under the category “customdatetime” as below -

Note that the function category, name, arguments, example all come from descriptor.json

You can test it in flow tester or by pushing the app in TIBCO® Cloud Integration or generating binary in TIBCO Flogo® Enterprise.

You can find the above code at this github location for your reference.

If your mapper function requires input parameters like for the below function, it requires date and format from the user -

datetime.formatDate（”02/08/2017", “dd-MM-yyyy”）=> 08–02–2017

In such cases, you have to declare input parameters in descriptor.json as below -

{
“name”: “formatDate”,
“description”: “Format the date according to the specified format. The format uses MM(month), DD(day) and YYYY(year) and they are case insensitive”,
“example”: “datetime.formatDate（\”02/08/2017\”, \”dd-MM-yyyy\”）=> 08–02–2017",
“args”: [
{
“name”: “date”,
“type”: “string”
},
{
“name”: “format”,
“type”: “string”
}
],
“return”: {
“type”: “string”
}
}

To check the source code of the function, you can have a look at formatdate.go and descriptor.json located at this github repo