Transformation functions

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Process wizard > Integrate > Application integration > Web services connector > Mapping features >

Transformation functions

Overview

Bizagi offers a set of comprehensive functions for the mapping of parameters in Web-based services invocations (both input and output parameters).

Such functions are helpful to interpret and perform manipulation of information, especially commonly used in XML transformations.

Furthermore, Bizagi provides functions to import and export the built mapping.

 

Special functions

Using of the special functions requires that the mapped fields must be inside of an Element node.

 

note_pin

Consider the following aspects when using these functions:

Element nodes can be seen as complex-type elements.

Special functions require that their input and output are contained in element nodes.

Not all functions are available for every web service configuration (i.e, while using a SOAP 1.1 based service port, some functions will not be presented).

 

Functions

 

 

Concatenate

This function concatenates two or more input (string type) into a single output (string type). A common example considering concatenation of a contact's first name and last name illustrates this function's use and reach:

 

Concat

 

 

To use this function, select from the functions (fx) bar, the Concat option located in the string category functions menu. Then, drag and drop this option into the main mapping window where your tables are.

 

You may now drag and drop the input's outgoing connection triangle into the Concat box as a parameter (param1).

 

ParameterMapping_advancedMapping_VendorConcatParam1

 

 

Repeat this step for the input you choose as param2.

Finally, select the Out line in the Concat box to define the output for the concatenation function.

 

In this example, VENDOR_NAME will have the information stored in the Vendor entity in Bizagi in 'First Name', followed by the information in 'Last Name'.

 

ParameterMapping_advancedMapping_VendorConcatParam2

 

 

Notice you may still concatenate more fields by including more Concat function boxes (as a cascade). This way, the output of a Concat function can be used as input for another Concat function to append a third parameter (in this case).

 

ParameterMapping_advancedMapping_VendorConcatMoreParams

 

 

Substring

This function obtains a string that is a substring of the original string.

Take into account that this special function in Bizagi do not require that its input is a string field. Bizagi will convert automatically into a string other data types' information such as that in an Integer or a DateTime field. Hence, this allows the use of the substring function with any other data type different from a string.

 

To use this function, select from the functions (fx) bar, the Substring option located in the string category functions menu. Then, drag and drop this option into the main mapping window where your tables are:

 

MappingFunctions07_Substring0

 

You may now drag and drop the input's outgoing connection triangle into the substring box as the "string" parameter (this is the original input string which is mandatory).

 

MappingFunctions05_Substring

 

For the other two parameters, the function expects a number which indicates:

 

Start parameter: the starting position in the original string from which the desired substring will be obtained. This parameter is mandatory.

 

This means that the function will have the character at this position be the start of the obtained output substring.

The first character and starting position of the original string is always "1".

 

MappingFunctions06_Warning

 

Length parameter: the number of characters included from the starting position.

The length parameter is optional (specifying no length will include all the characters from the starting position to the end of the original string).

 

Notice that for both these start and length parameters, the Constant function is routinely used.

 

A common example is to use the substring special function to get specific information from DateTime information. In this example, we get the year, month and day from a recorded DateTime attribute in Bizagi that originally contains the time as well:

 

MappingFunctions08_Substring1

 

Constant

This function inserts a definition of a constant value (string or number) into your mapping schema so that it can be used to set a default value into a field. For this example, we will suppose that five days are always updated as available vacation days when a new employee is registered.

 

To use this function, select from the functions (fx) bar, the Constant option located in the XSLT (Extensible Stylesheet Language Transformations) category functions menu.

Then, drag and drop this option into the main mapping window where your tables are.

 

Constant

 

You may now drag and drop the constant box outgoing connection triangle into the desired target field for your input mapping.

 

ParameterMapping_advancedMapping_ConstantOutput

 

Format Date

When Bizagi sends data to the service, this function transforms a date into a string according to the selected format. This function receives a Date input and returns the string with the corresponding formatted date. When Bizagi receives information from the service, this function transforms a string into a date. This function receives a string input in the selected format and returns a date.

 

To use this function, select from the functions (fx) bar, the Format Date option located in the Utilities category functions menu.

Then, drag and drop this option into the main mapping window where your tables are.

 

MappingFunctions09_FormatDate1

 

You may choose any of these options:

Generate output with date: This option indicates that the generated string will include the date in an specific format.

oDefault short date format: Uses the selected Short Date Format in Bizagi Business Configuration. If the previous format is (default), will set the format of the selected Global Culture.

oDefault long date format: Uses the selected Short Date Format in Bizagi Business Configuration. If the previous format is (default), will set the format of the selected Global Culture.

oAnother format: Corresponds to a list of the most common Date formats.

Generate output with time: This option indicates that the generated string will include the time in an specific format.

oTime format: Corresponds to a list of the most common Time formats.

Custom format: This field allows you to add your custom date format. It also has a list of some formats which are not easy to configure (JSON MVC, RFC 1123 or ISO 8601 format) or those without the whole date (i.e, year and month only, month and day only). When this option is selected, the options above are disabled.

 

Select the Date and Time format options as you desire. You may now drag and drop the input's outgoing connection triangle into the Date box as the input parameter (this is the original input date which is mandatory, the name of the input may vary).

 

MappingFunctions09_FormatDate2

 

You may now drag and drop into the desired target field into your input or output mapping.

 

MappingFunctions09_FormatDate3

 

note_pin

The format date function always receives a date and returns a string.

You may use this function in either your inputs or outputs configuration, though when running your processes in a .NET platform, the .NET framework will automatically parse date responses into Bizagi either to save in a date object or a string.

 

Example

The following examples shows how to configure Format Date to send from Bizagi some standard formats:

 

1.Date only in format dd/MM/yyyy, i.e for June 24th, 2016, the result will be 24/06/2016.

 

Once the Format Date window is opened, perform the following:

 

Check Generate output with date.

Select Default short date format.

Uncheck Generate output with time.

Click on Ok.

 

MappingFunctions09_FormatDate4

 

In the end, the result of the Date box will be:

 

MappingFunctions09_FormatDate5

 

2.Full Date and Time with time zone offset (yyyy-MM-ddtHH:mm:ssz), i.e June 24th, 2016 08:42:05 am in UTC-5, the result will be 2016-06-04a08:42:05-5.

 

Once the Format Date window is opened, perform the following:

 

Copy and paste the format yyyy-MM-ddtHH:mm:ssz in the Custom format combo box

Click on Ok.

 

MappingFunctions09_FormatDate6

 

In the end, the result of the Date box will be:

 

MappingFunctions09_FormatDate7

 

The values presented on the Date box as input, will vary according the values set in the configuration.

 

Export Mapping

Bizagi allows you to export current mapping in order to create a copy of it which can be used in when the service is used in another part of the process, encouraging reusability. It also can be used when web services or connectors that have already been mapped are updated or attributes are added.

 

This function saves the current mapping in an XML file which can be used wherever the services is called.

 

To use this function, select from the functions (fx) bar, the Export Mapping option located in the Utilities category functions menu.

 

MappingFunctions10_ExportMapping1

 

Select the path where the XML file will be saved and give a name to it, then click Save.

 

MappingFunctions10_ExportMapping2

 

Import Mapping

Bizagi allows you to import a previously saved mapping in reuse it in another Web service invocation. This function loads a mapping from an XML file.

 

To use this function, select from the functions (fx) bar, the Import Mapping option located in the Utilities category functions menu.

 

MappingFunctions11_ImportMapping1

 

Select the XML file with the previously saved mapping and then, click Open.

 

MappingFunctions11_ImportMapping2

 

Once loaded, Bizagi will replace the existing mapping with the information of the XML file.

 

note_pin

If a mapped attribute is not found when importing, it will be ignored, no error will be shown.

The mapped attribute's name has to be the same, if they are different they will be ignored if it matches it will be mapped.