From Business Process Management, BPM and Workflow Automation Wiki | BizAgi BPMS

Jump to: navigation, search

<keywords content="keywords"> webservice, webservices, web services, complex webservice, complex web service, web service complex data types, webservice complex data types, XML, XSD, XSLT, interface, interfaces, WebService, Webservice, Web Service, WebServices, Webservices, Web Services, parameter mapping, transformation, mapping, SOAP, SOAP Header, SOAP Headers. </keywords>

Special mapping features and functions for services invocations

Bizagi offers the possibility to include frequently used mapping functions such as: concatenation of fields, or assignment of constant (default) values. This eases and allows data-matching in the integration, by having Bizagi apply a transformation to guarantee that both systems (Bizagi and the external system) have an "understanding" of the exchanged data.

In addition to this, Bizagi supports integration with web services using SOAP Headers in its Xpress and Enterprise .Net editions.

Mapping functions and options

While the mapping window is maximized, it is possible to use the new buttons and functions from the Home tab bar as shown:

Quick-mapping Options

Using the 'Map all' button

This feature will set an automatic mapping so that the left table's fields are connected into your right table's fields. This mapping is matched according to the fields' names when equal.

Using the 'Unmap all' button

Pressing this button will reset the mapping done for all of the fields.

Using the 'Undo' button

Pressing this button will undo the latest action made.

Using the 'Redo' button

Pressing this button will redo the latest action undone.

Mouse options

Resizing the tables

Alongside the quick-configurations options such as: Map all, Unmap all, Undo and Redo; it is also possible to change the size of the tables by clicking on the system's name (which is seen as the table's header caption).

While the table is selected, various squared green dots will appear to enable edition of the table's size (using these green squares to enlarge or decrease the table):

Mapping attributes

To manually map an attribute or parameter on the left-side table, to an attribute or parameter on the right-side table, you may choose to use any of these 2 options: using clicks or using drag and drop.

Using clicks

You may create the mapping connection by: clicking first on the left table's attribute or parameter.

You will notice that the attribute becomes highlighted:

Then, clicking on the right table's attribute or parameter will draw a connection representing the mapping between these 2 attributes or parameters.

Using drag and drop

You may drag a connection by holding the click from the attribute or parameter on the left table's outgoing connection triangle:

Dropping this connection into the attribute or parameter incoming connection triangle, at the right table, will create the mapping as well.

Special functions

Alert: Using the special functions requires that the mapped fields belong to complex elements. This means that the input and output fields involved in a special function must be inside of a node.

Using 'concat' function

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:

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

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

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

Using the 'constant' function

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 5 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 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 constant box outgoing connection triangle into the desired target field for your input mapping.

Using 'substring' function

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:

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

For the other 2 parameters, the function expects a number which indicates: - For the "start" parameter, the starting position in the original string from which the desired substring will be obtained.
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". This parameter is mandatory.

- For the "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 lenght parameters, the constant function is commonly 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 in Bizagi will originally contains the time as well:

REST options

Only for invocation configurations in which REST is selected as the "Service type", there are additional options for the tables. These options are presented to aid the definition construction for the service's input or output structure.

The options presented below are found by right-clicking on the REST service's table.

Note that REST services invocation from Bizagi's interfaces wizard in its 9.1.9 version, support XML-formatted responses (not JSON-formatted responses).

For manual structure definition

When choosing to input the structure definition in a manual manner, the first option to select is the "Add Root Node" to start the XML definition.

Add Root Node

This option will add the root node for the XML structure.

To see this option, right-click anywhere in the table:

Once the root node is added, by right-clicking on it, several other options will be seen:

Add Element Node

This option will add an element which is a child element of the selected node.

The added element is initially represented as a string attribute, right below its father node and with its text in black color.

Once this added element contains inner nodes, then it is automatically represented as a node.

The image below shows info1 and info2 as added elements:

Add Attribute Node

This option will add an attribute for the selected node.

The added attribute is always represented as a string attribute, right below its father node and with its text in blue color:

Rename Node

This option will allow renaming the selected node:

Delete Node

This option will delete the selected node and all its child elements and inner attributes.

You will need to confirm the delete operation:

Import (for automatic structure loading)

When choosing to input the structure definition in an automatic manner, you may choose to import the XML definition from either: a XSD schema file, or an XML sample file:

Alert: Any previous inputted structure will be deleted when importing a new structure definition.

Load from XSD

This option will load the entire XML structure from the selected .xsd file:

Load Sample XML

This option will load the entire XML structure from a sample .xml file:

Alert: When loading from a sample XML, you may need to ensure that the sample file does not contain any XML reserved character (such as the ampersand "&"). If these reserved characters are present as a value in any node inside this file, ensure that this is contained inside a CDATA section (otherwise, you may get a "An error occurred while parsing..." error).

Export

Once you have inputted the XML structure, you may choose to save this definition for a future use:

Export to XSD

This option will save the current XML structure as a .xsd file:

SOAP Headers (Applies to XPRESS and ENTERPRISE .NET editions)

While invoking web services, it is often required to send out information that is unrelated to the business data itself, such as authentication information to validate that the user invoking the service has proper authorization. For these cases, it is usefult to send this information inside a SOAP header (in the SOAP message protocol).

It is necessary that the definition and creation of that web service covers specifically which data is expected in the message header. Bizagi supports sending data in the SOAP header, as well as receiving it from this header with an uncomplicated handling. To achieve this, just mapping the connections is required (incoming or outgoing as applicable) from or to the corresponding fields in Bizagi.

Therefore, Bizagi recognizes if a web service expects certain information in the header. Mapping the data involved for this integration is specified the same as it is done with the data from the web service method:

Personal tools

Views

Advanced web services mapping features and functions