Skip to main content
Sign in

Global Functions

Vienna Valmont
  • Updated

In this article:

 
Overview

Global Functions are injectable lines of code that can be utilized in three locations in the portal: 

  • Custom Mappings - The mappings are then associated with a Flow. 
  • Custom processors - Add the function once to a Custom Mapping in the JSONata editor panel, and the function will be used in any process across the Workflow associated with the mapping.
  • XSL Transformation adapter - Code can be edited in the Stylesheet and used where the adapter is employed. 

They are best employed for data validation of data moving through your Flows within the portal. Examples of these data alterations that can be addressed using Global Functions are: 

  • Ensuring that currency values have a dollar sign 
  • Ensuring that currency values are strings with a period
  • Converting fixed width for numerical values
  • Rounding or truncating numerical values
  • Removing freight charges 
  • Converting the date from the ISO date format to a conventional format

Accessing Global Functions

To utilize Chain.io's Custom Mapping tool, first sign in to your Chain.io portal account at https://portal.chain.io/.

  1. At the top menu bar, click Workspaces.
  2. At the top right of the screen, click Workspace Settings from the hamburger menu.
  3. Navigate to the Developer Center subsection at the bottom of the page. 



  1. Click Global Functions.

    The page will refresh to show the Global Functions page. If you have not yet created any Global Functions, the list will appear blank. If you have already created Global Functions, they will appear in the list, displaying a link to edit or delete each function, and the following properties:
    • Function name
    • Description 
    • Embedded status 
    • Created date 
    • Created by
    • Latest deployment time stamp
    • Last updated by
    • Last updated time stamp



Create a New Global Function

  1. To create a new Global Function, click the blue New button in the top right of the page.
  2. In the Create New Function pop-up window, enter the function name and a description.



  1. In the bottom right corner, click the blue Create Function button to establish the new function. 
  2. Click the blue Create and Deploy button to deploy the function and make is usable in other areas of your Workspace. 

Edit an Existing Global Function

  1. To edit an existing Global Function, click Edit to the right of the Global Function name of interest.



  2. A pop-up window will display the details for the selected Global Function. On the left of the window, edit the description and the code for the JavaScript function in the Code box.




    The JavaScript function must follow the following format: 
    function_name parameter

    The following is a simple example of a JavaScript function to transform the contents of a string into upper-case letters:
    function uppercase(str){   
      return str?.toUpperCase()
    }

    In this article, we will use a cipher called ROT13 as the example Global Function. ROT13 is an algorithmic encryption method in which each letter in the alphabet is substituted with the letter 13 positions after it. For example, the letter A is replaced by the letter N, and the letter G is replaced by the letter T. 
    function rot13 (str) {
    // Return empty string if input is not provided
    if (!str) return ''

    return str.split('').map(char = {
    // Get the character code
    const code = char.charCodeAt(0)

    // Handle uppercase letters (A-Z: 65-90)
    if (code = 65 && code <= 90)="90)" {="{">
    // Apply ROT13 transformation and wrap around if necessary
      return String.fromCharCode(((code - 65 + 13) % 26) + 65)
    }
    
// Handle lowercase letters (a-z: 97-122)
if (code = 97 && code <= 97="97" 122)="122)" {
    //Apply ROT13 transformation and wrap around if necessary
      return String.fromCharCode(((code-97+13)%26+97)
    }

    //Return non-alphabetic characters unchanged
      return char
    }).join(")
    }


Syntax and formatting errors will display in red text below the code editor.          




On the upper right of the pop-up window, you can select the Testing Format, alter the script code, and view the test results in the Script Consult Output box. Error testing will appear in red in the Script Code Output box.




For the testing format, select between “Script” and “Mocha + Chai Unit Test”. The following is an example of the Mocha + Chai Unit Test testing format. 



  1. After adjusting the function, click the blue Save button in the bottom right corner.
  2. Click the blue Save and Deploy button to deploy the Global Function and make it available for use in other areas of your workflow within the portal. 

Using Global Functions in Custom Mappings

  1. At the top right of the screen, click Workspace Settings from the hamburger menu.
  2. To edit an existing Custom Mapping, click Edit to the right of the mapping name of interest. Visit the Custom Mapping Tool documentation for details on how to create a new Custom Mapping and edit an existing Custom Mapping.



  3. In the JSONata Expression panel, customize your code to include your Global Function. Visit the Guide to JSONata Mapping Expressions documentation to learn more about how to map and transform source data into a structured target format.

    You can reference the Global Function in your mapping using the name: 
    $function_name(parameters)


    Example:

    $rot13($.path.to.value)





    If a function is employed in a JSONata mapping, it can receive and return a boolean value, a number, a string, null, an object, or an array.

  4. In the upper right of the page, click Save Revision. 
  5. Click Deploy as New Version to make your JSONata expression accessible and usable in Flows. 

The Custom Mapping can then be used in Flows. Visit the Flows & How They Work documentation to learn more about using a Custom Mapping in a Flow. 

Using Global Functions in Custom Processors

  1. To add Global Functions to pre- and post-processors, navigate to the top menu bar and select the Integration of interest.
  2. At the top right of the screen, click Integration Settings from the hamburger menu.
  3. Within the Flows subsection, click Edit to the right of the Target Flow.




    The page will refresh with the settings details for the particular Flow.

  4. Navigate to the Custom Processors and Mappings subsection. Here, you can add code for the pre-processor and post-processor, and select specifications for the Input File Map and Output File Map. 




    To use Global Functions within the pre-processor and post-processor sections, the JavaScript function must follow the following format:
    cio:function_name('parameter')


    Example:

    cio:rot13('text to encrypt')




    A function employed in a pre- or post-processor, has more flexibility in the types of values that it can receive and return compared to a function in a JSONata Custom Mapping or an XSL Transformation adapter. When used in a pre- or post-processor, a function can receive and return any data type. 
  5. Within the menu bar on the right side of the page, click Save, and then click Deploy to utilize the pre-processor and post-processor code in your Integration.
  6. At the top menu bar, click Search. The page will now display a list of Flows associated with the Integration.




  7. To view the implementation of the pre-processor and post-processor code adjustments, select Edit on the right of a Flow with a green “Success” status label. The page will refresh to display the Execution page with details of the deployed Flow.   


Example 

The ROT13 encryption function, declared on the Global Functions page, encrypts the password within the Logs subsection of the Execution page. 



For more information on Custom Processors, visit the Custom Processors article. 

Using Global Functions with the XSL Transformation Adapter

  1. To use Global Functions with the XSL Transformation adapter, select the Integration of choice in the top menu bar.
  2. The page refreshes to display all of the Flows associated with the Integration. Click Edit on the right of the target Flow row.



  3. The page will refresh to display details of the selected flow. Navigate to the “Source File Type” subsection.




  4. Add the following code to import the Global Functions namespace to the adapter:

    xmlns:cio="http://chain.io/xslt/GlobalFunctions"

  5. To use the Global Function, reference the namespace and the function you wish to employ.



    Specify the namespace, function name, and parameter in XML.

    cio:function_name('parameter')


    Example: 

    cio:rot13('fake-password')


    If a function is employed in the XSL Transformation adapter, it can receive and return the following data types:

    • A number
    • A string
    • A boolean value
    • Null

  6. Within the menu bar on the right side of the page, click Save, and then click Deploy to utilize the Global Function within the XSL Transformation adapter. 

Related articles