FlowServices

Use FlowServices to encapsulate a sequence of services within a single service and manage the flow of data among them, and create complex, advanced integration scenarios involving multiple application endpoints.

FlowServices provide you with rich data mapping capabilities, a familiar debugging mechanism, a large collection of built-in services, and more.

What are FlowServices

webMethods.io Integration offers various features that enables you to automate tasks based on specific requirements. However, there are some scenarios where you want to create complex integrations that require advanced data transformation and custom logic implementation. Earlier you could do this by switching to the Flow Editor using the App Switcher and create the required integrations in the Flow Editor.

We have simplified this process by providing you with FlowServices directly in your webMethods.io Integration project, thus eliminating the need to access the Flow Editor through the App Switcher. With FlowServices, you can encapsulate a sequence of services within a single service and manage the flow of data among them, and create complex, advanced integration scenarios involving multiple application endpoints.

In the Flow Editor, you used a graphical drag and drop tool to create integrations. You set up your integrations by plugging blocks together in the workspace and coding concepts were represented as interlocking blocks.

In FlowServices, you can easily build a FlowService by adding steps and selecting the constructs including Connectors, Controls, FlowServices, and Services from within the steps. The editor is visually enhanced to offer ease of use and is more interactive. A FlowService step is a basic unit of work that webMethods.io Integration interprets and executes at run time. The steps are the building blocks of a FlowService and are shown as rectangular blocks prefixed with step numbers. Steps may be compared to an actual implementation of a service in a programming language, where the business logic or the algorithm is written. webMethods.io Integration lists steps sequentially from top to bottom and also executes them in that order.

Enabling FlowServices

Let us see how to enable the FlowServices capability in webMethods.io Integration.

When you login to webMethods.io Integration, you are redirected to the Projects page by default. You can either create a new project or select an existing project.

Create a new workflow inside a project by clicking the icon.

On the new workflow canvas, click Proceed to enable the FlowServices option as shown below. This switch is permanent. Once you enable FlowServices for a user, you cannot disable it.

Once you click Proceed, the FlowServices capability gets enabled and the FlowServices icon appears.

Click the FlowServices icon to view the list of FlowServices. You can click the icon to go to the FlowServices editor where you can start creating a FlowService.

Once you have created a FlowService, the FlowService will be automatically added in the FlowServices panel of the workflow canvas, and you can use the FlowService in any workflow of this project.

The FlowServices tab also appears as shown below once you enable FlowServices. You can click the icon to start creating a FlowService. Here, you will see the list of all FlowServices created under the selected project and all FlowServices created from here will be automatically added under the FlowServices panel in the Workflow canvas.

Note: Click here for information on how to manage roles and project permissions.

Migrating Flow Editor Integrations

If you are an existing customer and have created integrations in the Flow Editor, you can migrate those integrations to FlowServices in webMethods.io Integration using the Migrate Integrations functionality. You can migrate integrations from a Flow Editor project to the same project in FlowServices.

How it works

  1. In webMethods.io Integration, enable FlowServices. Ensure that you have the Developer and Admin roles assigned from the Settings > Roles page.

  2. In webMethods.io Integration, select the project where you want to migrate the Flow Editor integrations and click the FlowServices tab. webMethods.io Integration displays the number of integrations available for migration.

  3. Click Migrate Integrations.

A dialog box appears displaying the list of integrations that will be migrated. Click OK to continue.

A dialog box appears showing the migration results. Click OK.

All integrations available in the Flow Editor project are migrated and available in FlowServices in case of a successful migration. In case of any errors, it is recommended to recreate those integrations in FlowServices.

Notes

  • After you migrate the integrations, you will not be able to open or edit the same integrations in the Flow Editor.
  • If a Flow Editor integration refers to another integration, both the integrations will be migrated.

Core elements, constructs, and components of FlowServices

Let us see the core elements, constructs, and components that are used to create and run a FlowService.

On the new FlowService page, click on the rectangular box as shown below.

By default, the left panel lists the recently used Connectors, Controls, FlowServices, and Services.

You can type a keyword in the rectangular box and search for the available elements. webMethods.io Integration filters the data based on what you type in the search box.

Click All to view the categories available on the right panel, which you can use to build the FlowService.

Categories

CONNECTORS

Displays the connectors available to create the FlowService.

Connectors are grouped in the following categories on the FlowServices panel.

Predefined Connectors

Predefined and configurable connectors. These connectors allow you to connect to the SaaS providers.

REST Connectors

You can define REST Resources and Methods and create custom REST connectors. You can invoke a REST API in a FlowService by using a REST connector.

SOAP Connectors

Displays custom SOAP connectors. Custom SOAP connectors enable you to access third party web services hosted in the cloud or on-premises environment. You can also invoke a SOAP API in a FlowService by using a SOAP connector.

On-Premises Connectors

On-Premises applications uploaded from on-premises systems.

Flat File Connectors

Displays the Flat File connectors created either manually or from a sample file.

Note: A few connectors are deprecated in this release. A deprecated connector displays the Deprecated label just below the connector where ever it appears in the user interface. Deprecated connectors will continue to work as before and are fully supported by Software AG. If you are using deprecated connectors in your existing Workflows and/or FlowServices, they will work as expected. No new feature enhancements will be made for deprecated connectors. If you are creating new Workflows or FlowServices, it is recommended to use the provided alternative connectors instead of the deprecated connectors. The deprecation is applicable only for Actions. The deprecation is not applicable for Triggers, that is, Triggers are supported for both deprecated and alternative connectors. For the list of triggers, see the documentation for alternative connectors.

CONTROLS

Controls are the programming constructs in a FlowService. This allows you to run a specified sequence based on a field value, try a set of steps, and catch and handle failures. The panel displays conditional expressions, looping structures, and transform pipeline. Conditional expressions perform different computations or actions depending on whether a specified boolean condition evaluates to true or false.

Sequence

Use the Sequence step to build a set of steps that you want to treat as a group. Steps in a group are run in order, one after another.

Conditional Controls
Loops

Loops run a set of steps multiple times based on the block you have chosen. It repeats a sequence of child steps once for each element in an array that you specify. For example, if your pipeline contains an array of purchase-order line items, you could use a Loop to process each line item in the array. Loop requires you to specify an input array that contains the individual elements that are used as input to one or more steps in the Loop. At run time, the Loop runs one pass of the loop for each member in the specified array. For example, if you want to run a Loop for each line item stored in a purchase order, you would use the document list in which the order’s line items are stored as the Loop’s input array.

A Loop takes as input an array field that is in the pipeline. It loops over the members of an input array, executing its child steps each time through the loop. For example, if you have a FlowService that takes a string as input and a string list in the pipeline, use Loops to invoke the FlowService one time for each string in the string list. You identify a single array field to use as input when you set the properties for the Loop. You can also designate a single field for the output. Loop collects an output value each time it runs through the loop and creates an output array that contains the collected output values.

Note: In case of an infinite loop, there is a default timeout configured in webMethods.io Integration. If the time taken for execution exceeds this limit, the FlowService execution is terminated. Contact your administrator for customizing the default timeout.

Error Handling
Exit

This step exits the entire FlowService and signals success or failure as part of the exit.

Switch, Case

Switch allows a variable to be tested for equality against a list of values. Each value is called a case, and the variable being switched on is checked for each case, that is, Switch evaluates a variable and skips to the value that matches the case. For example, if the Switch variable evaluates as “A”, then case “A” is run.

A switch statement can have an optional default case, which must appear at the end of the switch. The default case can be used for performing a task when none of the cases are true. You cannot insert multiple default statements.

You can include case steps that match null or empty switch values. A switch value is considered to be null if the variable does not exist in the pipeline or is explicitly set to null. A switch value is considered to be an empty string if the variable exists in the pipeline but its value is a zero length string. Switch runs the first case that matches the value, and exits the block.

Branch

Branch is a conditional execution of steps and constitutes a group of expressions. Within a Branch, webMethods.io Integration runs the first expression that evaluates to true. Expressions are the conditions on the pipeline variables.

At run time, Branch evaluates the conditions provided and runs the first expression whose condition is evaluated to true. If none of the expressions are true, the default expression if included, is run.

The following figure is the default template of a Branch construct.

If you want to perform different actions on different values of one or more pipeline variables, use the Branch construct. In the following example, action is a pipeline variable created using the Define input and output fields dialog box.

The Branch contains two conditional expressions and a default expression.

Scenario 1

If the value of action starts with mult, webMethods.io Integration evaluates the first expression (action = /^mult/) and runs step 3, that is, performs the multiplication operation.

Scenario 2

If the value of action is addition (action == “addition”), then the Branch starts its execution from step 2. As step 2 is evaluated to false, the execution moves to the next expression, that is, step 4. Step 4 is evaluated to true, hence step 5 is run, that is, the addition operation is performed. Remaining expressions in the Branch, if any, are ignored and the execution falls through to the next step after the Branch in the FlowService.

Scenario 3

Let us assume that the value of action is subtraction. The Branch then starts its execution from step 2. As webMethods.io Integration evaluates step 2 to false, the execution moves to the next expression, that is, step 4. webMethods.io Integration evaluates Step 4 to false, hence evaluates step 6 ($default), that is, runs step 7, which makes the execution exit the FlowService.

Notes

  • If you are specifying a field in a document or in a document reference, format it as document/documentVariable. For example, if you want to specify a field name, from the document employeeProfile, then format it as employeeProfile/name.

  • If you specify a literal value in an expression, the value you specify must exactly match the run-time value of the pipeline variable. Further, the value must be case sensitive.

  • webMethods.io Integration runs only the first target step whose expression evaluates to true. If none of the expressions evaluate to true, none of the child steps are invoked, and the execution falls through to the next step in the FlowService, if there is no default expression.

  • If you want to prevent the execution from falling through a Branch step when an unmatched value occurs at run time, include a default target step to handle unmatched cases. Branch can have zero to many default expressions. webMethods.io Integration runs the first sequentially encountered default expression.

  • The default step does not need to be the last step of a Branch but webMethods.io Integration always evaluates the default step at the end.

Any step other than an expression cannot be a direct child of a Branch step. Further, you cannot add the expression step anywhere outside a Branch.
If you are branching on expressions, ensure that the expressions you assign to the target steps are mutually exclusive. In addition, do not use null or empty values when branching on expressions. webMethods.io Integration ignores such expressions and does not display any errors.

You can provide multiple conditions for each expression and can also use regular expressions, for example, /^mult/. The expressions you create can also specify a range of values for the variables. Specify the value of the variables in the expressions, as mentioned in the following table:

To Match… Specify…
That exact string A string
The string representation of the object’s value.
Example for Boolean object: true
Example for Integer object: 123
A constrained object value
Any string matching the criteria specified by the regular expression.
Example: /^REL/
A regular expression
An empty string A blank field
A null value $null
Any unmatched value (that is, run the step if the value does not match any other label) $default
Transform Pipeline

The purpose of transformers is to accomplish multiple data transformations on the pipeline data in a single step as compared to using normal steps one after another. As a result, transformers are well suited to use when mapping data from one document format to another. While mapping data between formats, you often need to perform several name, structure, and value transformations. With the use of transformers, the FlowService in which you map data between formats could potentially consist of a single Transform Pipeline step, where transformers and links between variables handle all of the data transformations. This provides a single view of a document-to-document mapping.

Transformers are services that are inserted into and run within a Transform Pipeline step. Transformers act as a collection of normal steps embedded in a single Transform Pipeline step. However, transformers in a Transform Pipeline step are independent of each other, do not run in a specific order, and might not run in the same order each time the normal step runs. Therefore, you cannot use the output of one transformer as an input to another transformer. As transformers are contained within a Transform Pipeline step, they do not appear as a separate FlowService step in the editor. These characteristics make transformers different from a set of normal steps that run sequentially in a FlowService.

You can use built-in services and connectors (lookup transformer) as a transformer and can insert multiple transformers into a single Transform Pipeline step. By using multiple transformers, you can perform multiple data transformations on the pipeline contents in a single step.

To insert a Transform Pipeline step in a FlowService, search for Transform Pipeline in an empty step of a FlowService, and then select the Transform Pipeline step filtered from the step drop-down menu. You can add multiple transformers to do multiple data transformations by clicking the Add New Transformer option.

Example

Let’s see how transformers work with the help of an example. In the below example, we will transform the case of a string field label to upper case.

1.Provide a name and description of the new FlowService and click the I/O icon.

2.Define an input field Currency Code and click Done.

3.Select Transform Pipeline.

4.Click the pipeline mapping icon and open the pipeline mapping window.

5.On the pipeline mapping window, click the Add New Transformer option.

The Select Transformer panel appears.

6.Click ALL on the transformer panel.

7.Select the toupper service.

8.Click the Expand icon.

9.Map Currency Code to inString and value to Currency Code.

10.Save the FlowService and run it. In the Input values dialog box, type usd as the Currency Code.

11.Click Run on the Input values dialog box. The transformer converts the string field usd in lowercase to uppercase.

Note: You can delete a transformer by clicking the delete icon against each transformer. If a transformer is deleted, the mappings made to the service variables are also deleted.

FLOWSERVICES

Displays the FlowServices available in the selected project. This enables you to invoke other FlowServices from the current FlowService. The input and output of the referred FlowService must be accordingly mapped for a successful execution.

SERVICES

Displays the service categories. An extensive library of built-in services is available for performing common tasks such as transforming data values, performing simple mathematical operations, and so on.

Service input and output parameters are the names and types of fields that the service requires as input and generates as output and these parameters are collectively referred to as a signature.

Note: Related services are grouped in categories. Click here for information on the service categories.
Click here for information on the input parameters, output parameters, and usage notes if any for each service.

Tasks associated with FlowServices

You can perform the following tasks for FlowServices by clicking the icons available on the FlowServices panel.

Icons Task/Description
Provide a FlowService name and description. The asterisk denotes that the FlowService is modified.
Search for text in the FlowService, inside the editor, and within the steps.
Debug a FlowService and inspect the data flow during the debugging session. See Debug FlowServices for more information.
Run the FlowService after you save it. This enables you to test the FlowService execution in real time and view the test results.
Define the input and output fields of a FlowService. Input and output parameters are the names and types of fields that the FlowService requires as input and generates as output. These parameters are also collectively referred to as a signature. For example, a FlowService can take two string values, an account number (AcctNum ) and a dollar amount (OrderTotal ) as inputs and produces an authorization code (AuthCode ) as the output. On the Output tab, specify the fields that you want the FlowService to return.See Pipeline and Mapping for more information.
You can use a Document reference to define the input or output parameters for a FlowService. If you have multiple FlowServices with identical input parameters but different output parameters, you can use a Document Type to define the input parameters rather than manually specifying individual input fields for each FlowService. When you assign a Document Type to the Input or Output side, you cannot add, modify, or delete the fields on that part of the tab.
You can select a Document Type from the Document reference drop-down list.
You can create a Document Type from the webMethods.io Integration navigation bar by selecting a Project > Configurations > FlowService > Document Types.
You can create pipeline variables as document references, create document types comprising of document references, and also define the signature of FlowServices comprising of document references.
This option allows you to log business data at the FlowService level. You need to first click the I/O icon and define the input and output fields. Then click the Log business data icon and select the defined fields in the Log business data dialog box.
You can choose whether you want to log business data only when errors occur On Failure, or choose Always to always log business data. The default setting is On Failure.
When selecting fields for logging, you can specify the same display name for more than one field, but this is not recommended. Having the same display name might make monitoring the fields at run time difficult.
The business data log appears in the Execution Details page under Business Data.
See Log Business Data for more information.
Click the Navigator icon to view a summary of the FlowService steps, which appear on the right panel. Move the slider available on the navigator panel to move through the FlowService. If you move through the main FlowService page, the navigator view will automatically move. You can click on a navigator step to go to that step in the FlowService.
Press Ctrl and select a step or multiple steps in the FlowService. Then click the delete step(s) icon to delete the selected step or multiple steps in the FlowService. You can also delete steps by right-clicking on a step on the FlowService editor and selecting the delete option.
Press Ctrl and select a step or multiple steps in the FlowService. Then click the move step(s) icon and select the move steps up, down, right, or left options.
You can also move steps by right-clicking on a step on the FlowService editor and selecting the available options.
Cut, Copy, Paste, Duplicate, Enable, and Disable steps in the FlowService.
You can also right-click on a step on the FlowService editor and add a step or a child step for the selected step, cut, copy, and paste steps, copy the selected step(s) and paste the step(s) after the selected step(s) by clicking Duplicate, delete a step, and move steps up, down, right, or left.
Undo a step action.
Redo a step action.
Whenever you save a FlowService, a newer version is added to the Version History with the default commit message. You can also provide a custom commit message by clicking the drop-down arrow beside the Save option and selecting Save with message.
Access Help topics or take a tour.
The following options are available:
  • Schedule: Define a schedule for the FlowService execution. Select Once if you want to schedule the FlowService to run just once immediately or run once at a specified date and time. Select Recurring if you want to define a recurrence pattern. You can define a recurrence pattern daily, weekly, monthly, and in hours. Select the frequency (Hourly, Daily, Weekly, Monthly) with which the pattern recurs, and then select the options for the frequency. Click the + icon to repeat the execution for daily, weekly, and monthly schedules. Click the delete icon to delete the selected execution time for daily, weekly, and monthly schedules.
    Select Prevent concurrent executions to skip the next scheduled execution if the previous scheduled execution is still running except when the previous scheduled execution is running for some time. In this case, the next scheduled execution starts even if the previous scheduled execution is still running. If you do not select this option, the next scheduled execution starts, even if the previous scheduled execution has not yet completed. In the Input Value Set panel, provide inputs to the FlowService based on the defined input signature. Click Delete if you want to permanently remove the current recurrence schedule.
    Note: Any time stamp displayed in webMethods.io Integration is based on the time zone you have specified in Software AG Cloud. All time zones available in Software AG Cloud are currently not supported in webMethods.io Integration. If a time zone in Software AG Cloud is not supported, then the time stamp in webMethods.io Integration defaults to the Pacific Standard Time (PST) time zone.
    Note: You can pause a FlowService execution that was scheduled by clicking the Pause option on the Overview page of a FlowService.
  • Key Shortcuts: View keyboard shortcut keys.
  • Execution History: View successful and failed FlowService executions, operations, and business data logs.
  • Version History: View the version commit history of the FlowService.
An account is linked and configured.
Note: For a migrated or imported FlowService, the step-level validation might show that the account is not configured. This means that the steps are linked to an account alias but the account does not exist. In such a case, you can create the account inline and refresh the page, or you can go to the Connectors page and create the account with the same name as the alias.
An account is not linked.
A red circle on a step may appear for many error scenarios, for example, if an account is not configured, or the associated action is not selected, or for any invalid constructs.
Map or edit existing pipeline mappings.
Click the ellipsis icon and perform the following tasks:
  • Comment: Add a note for the selected step.
  • Disable: Disable or deactivate a step. You can enable the step by clicking the enable step icon . You can cut, copy, or delete a step after you disable it.
  • Log business data: This option allows you to log business data at the step level.
    Note: At the step level, the Log business data option is enabled only for connectors.
    In the Log business data dialog box, choose whether you want to log business data only when errors occur On Failure, or choose Always to always log business data. The default setting is On Failure. Expand the Input Fields and Output Fields trees to display the fields available in the signature, and select the check boxes next to the fields you want to log. If you want to define a display name for a field, type the display name beside the field. The display name defaults to the name of the selected field, but it can be modified. When selecting fields for logging, you can have the same display name for more than one field, but this is not recommended. Having the same display name might make monitoring the fields at run time difficult.
    The business data log appears in the Execution Details page under Operations > Business Data. See the Log Business Data section for more information.
  • Delete: Delete the step.
Click this icon to open the referenced FlowService if a FlowService references any other FlowService.
Indicates count of only the immediate child steps.

Mapping fields in a FlowService

As systems rarely produce data in the exact format that other systems need, you need to build FlowServices that perform data transformations. Data transformation resolves differences in the way data is represented within documents that applications and systems exchange. Data transformations are accomplished by mapping data.

The Pipeline offers a graphical representation of all of your data through which you can map data and inspect the contents of the pipeline. You use the tools on this view to route variables (data) between services or between document formats.

You can perform the following tasks while mapping the input and output fields in a FlowService. The icons are available at the top right-corner of the Mapping panel. See Pipeline and Mapping for more information.

Icons Task/Description
You can copy a field from the fields panel by clicking this icon. Depending on the context, you can either paste the field or the field path. For example, if you copy a field and paste the field in the Set Value window, (double-click a field to set a value), the field path will be pasted.
Note: You can set a value either in the Input (2nd column) or in the Pipeline Output (4th column) sections of the mapping panel.
Clear all actions done manually including values set in the pipeline.
Select a field and then click this icon to delete the field from the pipeline. Using this icon, you can also delete the values set for input and output fields, delete the link between variables, and delete the drop value.
Move fields left, right, up, or down in the pipeline.
webMethods.io Integration connects service and pipeline variables in the Pipeline with a line called a link. Creating a link between variables copies the value from one variable to another at run time. Select two input fields and click the link icon to link them. When you want to copy the value of a variable in a service or document format to another variable, you link the variables. You can delete a link by selecting it and then pressing the Delete key. A blue link in the Pipeline indicates that properties have been applied to a link between the fields.
Set values for input and output fields. A blue icon appears ) after a value is set.
Perform pipeline variable substitution
The Perform pipeline variable substitution check box indicates whether you want webMethods.io Integration to perform pipeline variable substitution at run time.

To use a variable when assigning a String value, you type the name of the pipeline variable enclosed in % symbols (for example, %Phone% or %/order/item[0]/name%). If you specify a pipeline variable enclosed in % symbols for a String value, you need to select the Perform pipeline variable substitution check box for the variable substitution to occur. While running the FlowService, webMethods.io Integration replaces the pipeline variable name with the run-time value of the variable.
Drop a field from the Pipeline In or Pipeline Out. The dropped variable shows on the mapping panel.
You can remove pipeline variables that are not used by subsequent services. Dropping unneeded variables reduces the size of the pipeline at run time and reduces the length and complexity of the Pipeline In and Pipeline Out displays, which can make the Pipeline view much easier to use when you are working with a complex flow.
Once you drop a variable from the pipeline, it is no longer available to subsequent services in the flow. At run time, webMethods.io Integration removes a dropped variable from the pipeline just before it executes the selected service (if you drop a variable in Pipeline In) or immediately after it executes the selected service (if you drop a variable in Pipeline Out).
You cannot drop a pipeline variable if the variable has a fixed value. Also, you cannot drop a pipeline variable in a child service if the variable exists in the parent service, that is, a child service cannot drop an upstream variable.
If you create a new variable, you must immediately link a variable to it, assign a value to it, or drop it, else the variable is automatically cleared from the pipeline.
If you right-click on a field in the pipeline, you can also copy a field, move fields up, down, left, or right in the pipeline, set a value for a field, remove the value set for a field, drop a field from the pipeline, undo the drop field action, delete, or edit a field.
Expand the mapping panel.
Close the mapping panel and go back to the FlowService.
Paste node in the pipeline after the copy field action.
Click to add variables to the pipeline. You can add variables that were not declared as input or output parameters of the FlowService.

Default Pipeline Rules for Linking to and from Array Variables

When you create links between scalar and array variables, you can specify which element of the array variable you want to link to or from. Scalar variables are those that hold a single value, such as String, Document, and Object. Array variables are those that hold multiple values, such as String List, Document List, and Object List.

For example, you can link a String to the second element of a String List. If you do not specify which element in the array variable that you want to link to or from, default rules in the Pipeline view are used to determine the value of the target variable.

The following table identifies the default pipeline rules for linking to and from array variables.

If you link… To… Then…
A scalar variable An array variable that is empty (the variable does not have a defined length) The link defines the length of the array variable; that is, it contains one element and has length of one. The first (and only) element in the array is assigned the value of the scalar variable.
If you link… To… Then…
A scalar variable An array variable with a defined length The length of the array is preserved and each element of the array is assigned the value of the scalar variable.
If you link… To… Then…
An array variable A scalar variable The scalar variable is assigned the first element in the array.
If you link… To… Then…
An array variable An array variable that does not have a defined length The link defines the length of the target array variable; that is, it is the same length as the source array variable. The elements in the target array variable are assigned the values of the corresponding elements in the source array variable.
If you link… To… Then…
An array variable An array variable that has a defined length The length of the source array variable must equal the length of the target array variable. If the lengths do not match, the link does not occur. If the lengths are equal, the elements in the target array variable are assigned the values of the corresponding elements in the source array variable.

Pipeline and Mapping

The pipeline is the general term used to refer to the data structure in which input and output values are maintained for a FlowService. The pipeline starts with the input to the FlowService and collects inputs and outputs from subsequent Connectors and services in the FlowService. When an operation of a Connector or a FlowService executes, it has access to all data in the pipeline at that point.

Input and output parameters are the names and types of fields that the FlowService requires as input and generates as output. These parameters are also collectively referred to as a signature.

The Pipeline offers a graphical representation of all of your data through which you can map data and inspect the contents of the pipeline. You use the tools on this view to route variables (data) between services or between document formats.

For example, a FlowService that takes two string values—an account number (AcctNum) and a dollar amount (OrderTotal) as input and produces an authorization code (AuthCode) as output, has the following input and output parameters:

Input Parameters: AcctNum (Data Type: String) and OrderTotal (Data Type: String)

Output Parameters: AuthCode (Data Type: String)

Although you are not required to declare input and output parameters for a FlowService, there are good reasons to do so:

  • Declaring parameters makes the FlowService’s input and outputs visible in the user interface. Without declared input and output parameters, you cannot:
  • Declaring parameters makes the input and output requirements of your FlowService known to other developers who may want to call your FlowService from their programs.
  • For these reasons, it is strongly recommended that you make it a practice to declare a signature for every FlowService that you create.

    webMethods.io Integration supports several data types for use in FlowServices. Each data type supported by corresponds to a Java data type and has an associated icon. When working in the FlowService editor, you can determine the data type for a field by looking at the icon next to the field name.

    The input side describes the initial contents of the pipeline. In other words, it specifies the fields that this FlowService expects to find in the pipeline at run time. The output side identifies the fields produced by the FlowService and returned to the pipeline.

    Guidelines for specifying input parameters

    When you define the input parameters for a FlowService, keep the following points in mind:

  • Specify all inputs that a calling program must supply to this FlowService. For example, if a FlowService invokes two other FlowServices, one that takes a field called AcctNum and another that takes OrderNum, you must define both AcctNum and OrderNum as input parameters for the FlowService.
  • Note: The purpose of declaring input parameters is to define the inputs that a calling program or client must provide when it invokes this FlowService. You do not need to declare inputs that are obtained from within the FlowService itself. For example, if the input for one FlowService is derived from the output of another FlowService, you do not need to declare that field as an input parameter.

  • When possible, use variable names that match the names used by the FlowServices. Variables with the same name are automatically linked to one another in the pipeline. Remember that variable names are case sensitive. If you use the same variable names used by FlowService’s constituent services, you reduce the amount of manual data mapping that needs to be done. When you specify names that do not match the ones used by the constituent FlowServices, manually link them to one another.
  • Avoid using multiple inputs that have the same name. Although the user interface permits you to define multiple input parameters with the same name, during execution, one field might overwrite the other. The fields will not be processed correctly within the FlowServices or by other FlowServices that invoke this FlowService.
  • Ensure that the variables match the data types of the variables they represent in the FlowService. For example, if a FlowService expects a document list called LineItems, define that input variable as a document list.
  • Declared input variables appear automatically as inputs in the pipeline. When you select the Transform Pipeline step in a FlowService, the declared inputs appear under Pipeline Input.
  • Guidelines for specifying output parameters

    On the output side, you specify the variables that you want the FlowService to return to the calling program or client. The guidelines for defining the output parameters are similar to those for defining input parameters:

  • Specify all the output variables that you want this FlowService to return to the calling program or client.
  • Ensure that the names of output variables match the names used by the FlowServices that produce them. Like input variables, if you do not specify names that match the ones produced by the FlowService’s constituent services, you must manually link them to one another.
  • Avoid using multiple outputs that have the same name. Although the user interface permits you to define multiple output parameters with the same name, the fields may not be processed correctly within the FlowService or by other FlowServices that invoke this FlowService.
  • Ensure that the variables match the data types of the variables they represent in the FlowService. For example, if a FlowService produces a String called AuthorizationCode, ensure that you define that variable as a String.
  • Declared output variables appear automatically as outputs in the pipeline. For example, when you select the Transform Pipeline step in a FlowService, the declared output variables appear under Pipeline Output.
  • Declaring Input and Output Parameters

    Click the Define I/O icon to define the input and output parameters. On the Input tab, you define the variables that the FlowService requires as input. On the Output tab, you define the variables that the FlowService returns to the client or calling program. You can create pipeline variables as document references, create document types comprising of document references, and also define the signature of FlowServices comprising of document references.

    If you select the Type as String, in the Display Type field, select Text Field if you want the input entered in a text field. Select Password if you want the input entered as a password. Select Large Editor if you want the input entered in a large text area instead of a text field. This is useful if you expect a large amount of text as input for the field, or you need to have new line characters in the input. In the Pick List field, define the values that will appear as choices when webMethods.io Integration prompts for input at run time.

    Ways to declare a signature

  • Reference a document type. You can use a document type to define the input or output parameters for a FlowService. When you assign a document type to the Input or Output side, you cannot add, modify, or delete the variables on that half of the tab.
  • Manually insert input and output variables. Click the icon to manually insert variables to the Input or Output sides.
  • Using a Document Type to specify FlowService input or output parameters

    You can use a document type as the set of input or output parameters for a FlowService. If you have multiple FlowServices with identical input parameters but different output parameters, you can use a document type to define the input parameters rather than manually specifying individual input fields for each FlowService. When a document type is assigned to the input or output of a FlowService, you cannot add, delete, or modify the fields on that tab.

    For a FlowService, the input side describes the initial contents of the pipeline. In other words, it specifies the variables that the FlowService expects to find in the pipeline at run time. The output side identifies the variables produced by the FlowService and returned to the pipeline.

    Smart Mapping

    Software AG leverages the collective intelligence of the webMethods.io Integration community to suggest which fields should be mapped in a data map by learning from the mappings you create.

    Smart mapping provides you with recommendations while mapping the pipeline data and utilizes a series of algorithms to determine the likely accuracy of a given suggestion, enabling you to toggle between high, medium, and low levels of mapping confidence. A Machine Learning (ML) algorithm is applied to provide the suggestions. The ML algorithm learns from the mappings you create and provides suggestions automatically to map similar fields. The algorithm benefits from having more data from more number of users.

    Smart mapping is anonymous and does not store any customer-specific information or actual data of any kind and is available to only those tenants who provide their consent to share their mapping information. Individual fields contained within the records are indexed. Specifically, the field names and their hierarchy are indexed, as well as the mapping relationships between them.

    After providing consent, if you have the relevant role permissions, you can choose to opt-out of smart mapping. Your maps will not be indexed, that is, if you opt out of smart mapping, you will not be able to see or utilize any mapping suggestions and your maps will no longer be indexed. However, as the index is anonymous, any maps and profiles indexed during the opt-in period will remain in the database. Further, the data collected is confined to that particular data center where the tenant resides.

    Mapping recommendations are not tenant specific, so mapping inputs from one tenant maybe used to make recommendations for another tenant. When you do the mapping, the data collected does not reflect immediately as a recommendation for another user as the information is recorded and processed in our database only at specified intervals.

    Note: For trial tenants, the mapping data is collected by default. Further, for trial tenants and for the Free Forever Edition, smart mapping is always enabled and cannot be changed. For paid tenants, only an Administrator has the permission to enable or disable smart mapping.

    The following information is not indexed:

    How it works

    1. To provide your consent to share the mapping information, from the webMethods.io Integration navigation bar, click on the profile icon located at the top-right corner of the home page, and select Settings > Preferences.

    2. On the Configure Tenant Preferences page, select the Publish integration mappings to recommendations engine option and click Save to enable smart mapping. This provides you mapping recommendations whenever you do mapping. By enabling this option, you are also providing us your consent to collect your mapping information. For trial tenants and for the Free Forever Edition, this option is always enabled by default and cannot be changed.

    3. Select a project and then the FlowService for which you want to do smart mapping.

    4. On the pipeline mapping screen, select Recommend Mappings to see the recommended mappings. If you select the Show only mapped option, the Recommend mappings option is automatically cleared.
      When the screen is initially loaded, only high recommendations appear by default.

    5. Drag the recommendation accuracy slider to view the mapping recommendations and filter the recommendations based on their recommendation accuracy. The recommendation accuracy or confidence number appears when you hover the pointer over a mapping and is the level of mapping confidence of that specific recommendation.

      Based on the level of mapping confidence, the recommendations are grouped into High, Medium, and Low categories:

      • Mappings have the highest probability
      • Mappings have medium probability
      • Mappings have the least probability

      You can select more than one category by moving the slider. In the following example, mappings that have medium and high probability are displayed.

    6. Select a mapping and click Accept to hard map it. You can select one or more recommendations and accept only those recommendations (Selected (x)), or you can accept all the recommendations that appear on the screen (All shown (x)). The accepted recommendation behaves like an actual mapping.

    7. To unmap a hard mapping, select the hard mapping and then click the delete icon available on the pipeline action bar. Once the hard mapping is deleted, the recommendations appear again. To hard map the recommendations again, click Accept and select the desired option.

    Note: If you an Administrator of a paid tenant, and have cleared the Publish Integration Mappings to Recommendations Engine option, webMethods.io Integration displays a message to inform you whether you want to enable the smart mapping feature. If you select Yes, the Predict Mappings option appears in the pipeline mapping screen.

    Creating FlowServices

    Click the following links to learn how to create FlowServices with the help of examples.

    Note: Click here for information on how to manage roles and project permissions.

    Providing input values to a FlowService

    In this example, let us see how to provide input values to a FlowService. We will create a FlowService slacktest, which will post a user defined message on a specific Slack channel.

    1.Create the FlowService.

    2.Click the icon and define the input fields channel and message as shown below.

    3.Click the mapping icon as shown below and define the pipeline mapping.

    4.Click the Run icon.
    The Input values dialog box appears. If you do not define any input fields in a FlowService, then the Input values dialog box does not appear and the FlowService executes directly.

    5.Specify the input values as general and Hello Team !!! and save the value set as slack_valueset_1 as shown below. You can run the FlowService without saving the value set too. A value set is a placeholder to store run time input values. You can use the same value set if you want to run the same FlowService with the same input values. This is useful when you have multiple input fields. Value sets are stored in your browser’s local storage and the value sets are retained till the local storage is cleared.

    Include empty values for string types: If you do not provide an input value for a string field, then at run time, the value will be null by default. If you select this option, then at run time, the value will be an empty string.

    6.Click Run.

    View the execution result. The values for the input fields channel and message are displayed.

    Cloning FlowServices

    You can copy FlowServices across projects. Click the ellipsis icon available on a FlowService and select Clone.

    Ensure that you create the account or reference data associated with the respective asset in the target project.

    Creating Custom Operations in FlowServices

    webMethods.io Integration provides predefined connectors, which contain SaaS provider-specific information that enables you to connect to a particular SaaS provider. Further, each connector uses an account to connect to the provider’s back end and perform operations. Each connector comes with a predefined set of operations. You can also create your own custom operations while creating a FlowService.


    Let us see how to create a custom operation while creating a FlowService and then use that custom operation to create a Salesforce CRM back end account.

    1.After you log in, select a project or create a new project where you want to create the FlowService.

    2.Click the FlowServices tab and on the FlowServices page, click the icon.

    3.Provide a name SalesforceCreateAccountCustom and description of the new FlowService.

    4.Type Salesforce in the search box, select Salesforce CRM, and then select Add Custom Operation.

    5.On the Connect to account page, select the supported Authentication type and the Salesforce CRM account created from the drop-down list. Provide a name and description of the custom operation.

    6.Select the create operation.

    For REST-based connectors, after selecting the operation, you can click Headers to add input Headers, if required. webMethods.io Integration displays the default HTTP transport headers for the operation, along with their default values. At run time, while processing the headers, webMethods.io Integration substitutes the values as necessary.

    In order to customize the headers, do the following:

    a. Click + Add to add a custom Header.

    b. Click the icon to specify the header name and an optional default value for the header variable. If the variable is null in the input pipeline, this value will be used at run time. If the variable already has an existing default value defined, this value will overwrite the existing value at run time.

    c. If headers appear in the signature, select Active to activate the headers in the signature.

    d. To delete a custom header that you have added, click Delete.

    Note: You cannot delete the required headers.

    You can also customize the parameters for REST-based connectors after selecting the operation, by clicking the Parameter option. Review the operation parameter details. webMethods.io Integration displays the parameter Name and Description, the Data Type used to represent the kind of information the parameter can hold, the parameterization Type of the request, and the default value needed to access the operation. To specify a default value for the parameter, click the icon and then type or paste the default value. The default value is used at run time. You cannot add or delete request parameters. You can only modify the default value of a parameter. All parameters appear in the signature.

    Now let us go back to our example.

    7. After you select the create operation, click Next, and then select the Business Object Account. Business Objects appear only for certain connectors and operations.

    8.Select the data fields and confirm the action to create the custom operation. Data fields appear only for certain connectors and operations.

    9.On the FlowService editor, click the icon to define the input and output fields.

    10.Create two Input Fields, AccountName and CityName.

    11.Click to edit the FlowService mapping. Only fields selected earlier are shown in the input panel.

    12.Save the FlowService and click Run. Provide the custom field values in the AccountName and CityName fields, for example, Software AG and Bangalore respectively, and then run the FlowService.

    As the results show, the Software AG account is created.

    Create FlowServices - Example 1

    Summary

    Get leads from Salesforce CRM and create corresponding customer leads in Microsoft Dynamics 365 CRM.

    Before you begin

  • Log in to your tenant and enable FlowServices.
  • Check if you have the Developer and Admin roles assigned from the Settings > Roles page.
  • Note: Click here for information on how to manage roles and project permissions.

  • Obtain the credentials to log in to Salesforce CRM and Microsoft Dynamics 365 CRM back end accounts.
  • In webMethods.io Integration, create Salesforce CRM and Microsoft Dynamics 365 CRM accounts.
  • Basic Flow

    1.Select the project where you want to create the new FlowService. You can also create a new project.

    2.Click the FlowServices tab and on the FlowServices page, click the icon.

    3.Provide a name, for example, SalesforceToMSDynamics365CRM, and an optional description for the new FlowService.

    4.Type Salesforce in the search box and select Salesforce CRM.

    5.Select the queryleads operation.

    6.Select the SalesforceCRM_1 account. You can also create or configure an account inline.

    7.Click the icon to add a new step.

    8.Type repeat, select Repeat to create a repeat step, and then select the /Lead option.

    9.Select Microsoft Dynamics 365 CRM and then select the associated createLead action.

    10.Select the msdynamics_1 account. You can also create or configure an account inline.

    11.Click the mapping icon to map the input and output fields.

    12.Click the Pipeline Input fields (FirstName and LastName) and drag it to the service input (firstname and lastname). The service output is automatically mapped to the Pipeline Output by a dotted line.

    13.Save the FlowService and run it by clicking the Run icon.

    14.View the FlowService execution results for a successful run. The lead ID generated is acf4f843-2970-ea11-a811-000d3a4da920.
    Note: If a value is null for a field or if the datatype is unknown, then the obj (object) icon is displayed.

    15.Download the results.

    16.You can also view the previous FlowService execution results.
    Note: By default, all FlowService execution results are retained for 30 days. You can optionally specify the number of days (up to 30 days) for which you would like to retain the FlowService execution logs by clicking the Modify Retention Period link available at Monitor > Execution Results > FlowService Execution. Once the retention period is over, the FlowService execution logs are deleted automatically.

    Create FlowServices - Example 2

    Summary

    Get attendees from Concur and create contacts in Salesforce CRM.

    Before you begin

  • Log in to your tenant and enable FlowServices.
  • Check if you have the Developer and Admin roles assigned from the Settings > Roles page.
  • Note: Click here for information on how to manage roles and project permissions.

  • Obtain the credentials to log in to Concur and Salesforce CRM back end accounts.
  • In webMethods.io Integration, create Concur (Concur_1) and Salesforce CRM (SalesforceCRM_1) accounts.
  • Basic Flow

    1.Select the project where you want to create the new FlowService. You can also create a new project.

    2.Click the FlowServices tab and on the FlowServices page, click the icon.

    3.Provide a name, for example, ConcurAttendeeToSalesforce, and an optional description for the new FlowService.

    4.Type Concur in the search box, select Concur, and then in the Type to choose action field, select Add Custom Operation.

    5.Do the steps as shown in the following images to create the GetConcurAttendees custom operation.

    6.Select GetConcurAttendees, click the icon, and select the Concur_1 account. You can also create this account inline.

    7.Click the icon to add a new step.

    8.Type repeat, select Repeat to create a repeat step, and then select the /item option.

    9.Select Salesforce CRM and then select the associated createcontact action.

    10.Select the SalesforceCRM_1 account. You can also create or configure this account inline.

    11.Click the mapping icon to map the input and output fields.

    12.Map the input and output fields as shown below. Double-click the OtherCity and OtherCountry fields and set the required input values. You can also select the field and click the Set Value icon . The service output is automatically mapped to the Pipeline Output by a dotted line.

    13.Save the FlowService and run it by clicking the Run icon.

    14.View the FlowService execution results.

    Create FlowServices - Example 3

    Summary

    Retrieve files stored in Amazon Simple Storage Service (S3) bucket and log the content of the files.

    Before you begin

  • Log in to your tenant and enable FlowServices.
  • Check if you have the Developer and Admin roles assigned from the Settings > Roles page.
  • Note: Click here for information on how to manage roles and project permissions.

  • Obtain the credentials to log in to Amazon S3 back end account.
  • In webMethods.io Integration, create an Amazon S3 account, for example, AmazonSimpleStorageServiceS3_1.
  • Amazon S3 Bucket name to retrieve the files.
  • Basic Flow

    1.Select the project where you want to create the new FlowService. You can also create a new project.

    2.Click the FlowServices tab and on the FlowServices page, click the icon.

    3.Provide a name, for example, AmazonS3, and an optional description for the new FlowService.

    4.Type Amazon Simple Storage Service (S3) in the search box, select it, and then select the action or operation, getBucket.

    5.Select the AmazonSimpleStorageServiceS3_1 account. You can also create or configure an account inline.

    6.Click the mapping icon to set a value for getbucketinput.

    7.Expand getBucketInput and click bucketName.

    8.Type softwareagbucketaws as the value for bucketName.

    9.Click the icon to add a new step. Then type repeat to select the Repeat step and select the /content option.

    10.Select Amazon Simple Storage Service (S3) and choose the getObject action to retrieve the object from the specified bucket.

    11.Click the mapping icon to map the input and output fields.

    12.As shown below, click the pipeline input fields (name and key) and drag it to the service input (bucketName and objectName). The service output (getObjectOutput) is automatically mapped to the pipeline output by a dotted line.

    .

    13.Click the + icon to add a new step as shown below.

    14.Select the Flow function and then select the logCustomMessage service. You can also type logCustomMessage and select it. This logs a message, which you can view in the FlowService execution results screen.

    15.Map the input (stream) to message. This step logs the contents of the files in the bucket.

    16.Save the FlowService and then run it.

    17.You can also view the execution result in the Monitor > FlowService Execution page. Click the execution result name link to view the execution details.

    Services

    Note: Click here for information on the input parameters, output parameters, and usage notes if any for each service under the following service categories.

    Service Category Description
    Date Use Date services to generate and format date values.
    Document Use Document services to perform operations on documents.
    Flat File Use Flat File services to convert data bytes, data stream, and data string to a document and vice versa.
    Flow Use Flow services to perform utility-type tasks.
    Hashtable Use Hashtable services to create, update, and obtain information about the hashtable.
    IO Use IO services to convert data between byte[ ], characters, and InputStream representations. These services are used for reading and writing bytes, characters, and streamed data to the file system. These services behave like the corresponding methods in the java.io.InputStream class. These services can be invoked only by other services. Streams cannot be passed between clients and the server, so these services will not execute if they are invoked from a client.
    JSON Use JSON services to convert JSON content into a document and to convert a document into JSON content.
    List Use List services to retrieve, replace, or add elements in an Object List, Document List, or String List, including converting String Lists to Document Lists.
    Math Use Math services to perform mathematical operations on string-based numeric values. Services that operate on integer values use Java’s long data type (64-bit, two’s complement). Services that operate on float values use Java’s double data type (64-bit IEEE 754). If extremely precise calculations are critical to your application, you should write your own Java services to perform math functions.
    MIME Use MIME services to create MIME messages and extract information from MIME messages.
    Storage Use Storage services to insert, retrieve, update, and remove entries from a data store.
    String Use String services to perform string manipulation and substitution operations.
    Transaction Use Transaction services only in conjunction with the Database Application operations. These services are applicable when the Database Application account is of type Transactional.
    Utils Contains utility services.
    XML Use XML services to convert a document to XML content and XML content to a document.

    Support for Multipart Request Body

    Though application/x-www-form-urlencoded is a more natural way of encoding, it becomes inefficient for encoding binary data or text containing non-ASCII characters. The media type multipart/form-data is the preferred media type for request payloads that contain files, non-ASCII, and binary data. webMethods.io Integration supports this media type using which you can embed binary data such as files into the request body. For example, if you want to create a user as well as upload a photo, the request has to be a multipart request where one part is an image file while the other part is a JSON request body.

    Example of a multipart request

    A multipart/form-data request body contains a series of parts separated by a boundary delimiter, constructed using Carriage Return Line Feed (CRLF), “–”, and also the value of the boundary parameters. The boundary delimiter must not appear inside any of the encapsulated parts.

    Each part has the Name, Type, Content-Type, and Part ID fields.

    --BOUNDARY
    
    
    Content-Type: application/json
    
    
    Content-Disposition: form-data; name="job"
    
    
    {
    
    
    "object":"Contact",
    
    
    "contentType":"CSV",
    
    
    "operation":"insert"
    
    
    }
    
    
    --BOUNDARY
    
    
    Content-Type: text/csv
    
    
    Content-Disposition: form-data; name="content"; filename="content"
    
    
    (Content of your CSV file)
    
    
    --BOUNDARY—

    Part Configuration

    The configured parts to be sent to the service provider appear in the input signature.

  • name - The Name field displays the name of the file part as documented in the SaaS provider API documentation.
  • contentType - The contentType field displays the content type of the file you are uploading.
  • type:
  • Example - Create bulk accounts in Salesforce using a multipart predefined operation

    For some connectors and operations, for example, for the Salesforce(R) Bulk v2 Data Loader connector and createAndUploadDataUsingMultipart predefined operation, webMethods.io Integration supports multipart request body.

    Before you begin

  • Log in to your tenant and enable FlowServices.
  • Check if you have the Developer and Admin roles assigned from the Settings > Roles page.
  • Obtain the credentials to log in to the Salesforce back end account.
  • In webMethods.io Integration, create the Salesforce(R) Bulk v2 Data Loader account, SFBulkV2_02Apr.
  • Basic Flow

    1.Select the project where you want to create the new FlowService. You can also create a new project.

    2.Click the FlowServices tab and on the FlowServices page, click the icon.

    3.Provide a name and an optional description for the new FlowService.

    4.Type IO in the search box, select IO, and then select the stringToStream service.

    5.Click the mapping icon to map the input and output fields.

    6.Set the below value for string:

    7.Set the value for encoding as UTF-8.

    8.Click the icon to add a new step.

    9.Select the Salesforce(R) Bulk v2 Data Loader connector and the createAndUploadDataUsingMultipart predefined operation. Select the SFBulkV2_02Apr account.

    10.Click the mapping icon to map the input and output fields.

    11.Map inputStream to value. The service output is automatically mapped to the Pipeline Output by a dotted line.

    12.Set values for fileroot as shown below:

    13.For fileRoot1, set values for name as content, contentType as text/csv, type as FILE, and filename as content.

    14.Save the FlowService and run it by clicking the Run icon.

    15.View the FlowService execution results for a successful run.

    Log Business Data

    While executing a FlowService, webMethods.io Integration allows you to log business data at the step level as well as at the FlowService level.

    Log business data at the step level

    1.Provide a name and description of the FlowService.

    2.As we will query contacts from Salesforce CRM and log the business data, select the Salesforce CRM connector, queryContacts operation, and SalesforceCRM_2 as the account.

    3.Select the Log business data option available at the step level as shown below. At the step level, the Log business data option is enabled only for connectors.

    4.In the Log business data dialog box, choose Always to always log business data. As we will query the contacts from Salesforce CRM, select the output fields and specify the display names for AccountId, LastName, and FirstName as shown below.

    5.Run the FlowService and go to the Execution History page by clicking the Execution history option.

    6.Click on the execution history entry to view the execution details page. As you can see below, the business data is logged.

    Log business data at the FlowService level

    1.Click the icon.
    Let us define the input field FirstName as shown below.

    2.Click the Log business data option available at the FlowService level.

    3.In the Log business data dialog box, choose Always to always log business data.

    4.In an earlier step, you had defined the input field FirstName. Select the input field FirstName as shown below and specify the display name as First Name of Customer.

    5.Run the FlowService. For the FirstName field, enter the value John and again click Run.

    6.Click the Execution history option to go to the Execution History page.

    7.Click on the execution history entry to view the execution details page. As you can see below, the business data is logged.

    Reference Data

    Reference data is data that defines the set of permissible values to be used by other data fields. It is a collection of key-value pairs, which can be used to determine the value of a data field based on the value of another data field. For example, the value of a status field in an Application can be “Canceled” and that needs to be interpreted as “CN” in another Application.

    webMethods.io Integration allows you to upload reference data from a text file containing tabular data separated by a character, for example, a comma, semicolon, and so on. The uploaded file should not have an empty column heading or space in the first row, and the first row cannot be empty.

    Reference data appears under Services in the FlowServices workspace. You can access the uploaded reference data in FlowServices as a list of documents by using the reference data service and providing an appropriate name. You can filter the documents returned into the pipeline by the reference data service.

    You can Delete, Download, or Edit a reference data from the Reference Data screen. If a reference data is used in a FlowService, you will not be able to delete that reference data. You must remove the reference data from the FlowService and then delete the reference data. The Download option allows you to download the previously uploaded reference data, edit it, and then upload the modified file.

    Reference Data Signature

    Reference data signature is derived from the column names of the uploaded text file. You can filter the Reference data by providing an appropriate matchCriteria. The output of Reference data is a list of documents that match the specified matchCriteria.

    Input Parameters

    matchCriteria: Document. Criteria on which documents from the Reference data are matched.
    Parameters for matchCriteria are:

    joins: List of join criteria. Each join criteria consists of:

    Output Parameters

    Reference Data Name: Document List. List of documents that match the retrieve criteria.

    Creating a Reference Data

    Let us see how to create a reference data and use it in a FlowService with the help of an example.
    In this example, we will upload a file that contains a list of courier vendors as reference data in webMethods.io Integration, and then import the list of vendors as contacts into Salesforce CRM.

    Before you begin

  • Log in to your tenant and enable FlowServices.
  • Check if you have the Developer and Admin roles assigned from the Settings > Roles page.
  • Obtain the credentials to log in to the Salesforce CRM back end account.
  • Create a Salesforce CRM account in webMethods.io Integration. You can also create this account inline at a later stage.
  • Basic Flow

    1.Select the project where you want to create the reference data. You can also create a new project.

    2.Click Configurations > FlowService > Reference Data > Add Reference Data.

    3.Provide a name (CourierVendors) and an optional description for the reference data.

    4.For the Reference Data File, click Browse file and select the file. Both csv and a text file having tabular data are supported. The maximum file size you can upload is 1 MB. As shown in the sample, the file should not have an empty column heading or space in the first row and that row cannot be empty. This is because the first row of data is read as column headings.

    5.Click Next to define the reference data. Select the Field separator and the Text qualifier. Determine the encoding of the reference data file and from the File Encoding drop down list, select the same encoding.

    6.Click Next to preview the data. If you select an incorrect encoding, garbage characters may appear in the preview pane.

    7.Click Done to create the reference data. The new reference data appears in the Reference Data page. The reference data also appears under the Services category in the FlowServices workspace.

    8.Go to FlowServices and create a new FlowService. Provide a name ImportCourierVendorsAsContacts and description of the FlowService. Then type reference data in the first step and select Reference Data.

    9.Select CourierVendors. Click the icon to add a new step. We need to create a contact for each vendor, so type Repeat to select the Repeat step, and then select the CourierVendors option.

    10.Select Salesforce CRM, the action as createcontact and associate the SalesforceCRM_1 account.

    11.Click the mapping icon and map the input and output fields as shown below.

    12.Save and run the FlowService, and view the results.

    Document Types

    What is a document type?

    A document type contains a set of fields used to define the structure and type of data in a document. You can use a document type to specify the input or output parameters for a FlowService. Input and output parameters are the names and types of fields that a FlowService requires as input and generates as output. These parameters are collectively referred to as a signature.

    For example, a FlowService takes two string values, an account number (AcctNum ) and a dollar amount (OrderTotal ) as inputs and produces an authorization code (AuthCode ) as the output. If you have multiple FlowServices with identical input parameters but different output parameters, you can use a document type to define the input parameters rather than manually specifying individual input fields for each FlowService.

    Benefits of creating a document type

    Document types provide the following benefits:

  • Using a document type as the input or output signature for a FlowService reduces the effort required to build a FlowService.
  • Using a document type to build document or document list fields reduces the effort and time needed to declare input or output parameters or build other document fields.
  • Document types improve accuracy because there is less possibility to introduce a typing error while typing field names.
  • Document types make future changes easier to implement because you make a change at one place (the document type) rather than everywhere the document type is used.
  • How do I create a document type?

    You can create a document type in the following ways from Projects > select a project > Configurations > FlowService > Document Types > Add Document Type:

  • Build from scratch: Create an empty document type and define the structure of the document type yourself by inserting fields to define its contents and structure.
  • Build from XML Schema Definition: Create a document type from an XML Schema Definition. The structure and content of the document type matches that of the source file.
  • You can also create document types for already created REST connectors from Projects > select a project > Connectors > REST > Document Types option or from the Request Body and Response Body panels while creating a REST connector.

    Document types created for a REST connector do not appear in the Projects > select a project > Configurations > FlowService > Document Types page but appears in the Document Types panel for the selected REST connector.

    Note: You can copy a document type from the Document Types page or from the Document Type page for a REST connector. Currently you cannot copy a document type across projects. When you copy a FlowService or a Workflow across projects, the document type associated with it is also copied.

    Note: If a Document Type is used in any other Document Type or a FlowService, you will not be able to delete the Document Type. Other than direct dependencies, if there are document types that are created along with the selected document type from the same xsd source, and if any of these documents types are used in any FlowServices or document types (other than these generated document types), then also you will not be able to delete the document type.

    Creating Document Types from Scratch

    Creating a document type from scratch allows you to create an empty document type, and specify the structure of the document type by inserting fields to define its contents and structure.

    To add or edit a document type from scratch

    1.From the webMethods.io Integration navigation bar, click Projects. Select a project and click Configurations > FlowService > Document Types. From the Document Types page, you can add, edit, delete, or copy a document type. To edit an existing document type, on the Document Types page, click the Edit icon for the document type.

    2.To create a new document type from scratch, from the Document Types page, click Add Document Type > Build from scratch.

    3.Provide a name and description of your document type. Required fields are marked with an asterisk on the page.

    4.Click Load XML to generate a document type from the XML structure or click Load JSON to generate a document type from the JSON structure.

    5.Click the icon to add a new field and update the field properties.

    Provide the Name and Type of the field to define the structure and content of the document type. The type can be a String, Document, Document Reference, Object, Boolean, Double, Float, Integer, Long, or Short. If you select the Type as Document Reference, select a Document Reference. Types are used to declare the expected content and structure of the signatures, document contents, and pipeline contents.

    If you select the Type as String, in the Display Type field, select Text Field if you want the input entered in a text field. Select Password if you want the input entered as a password, with asterisks reflected instead of characters. Select Large Editor if you want the input entered in a large text area instead of a text field. This is useful if you expect a large amount of text as input for the field, or you need to have new line characters in the input. In the Pick List field, define the values that will appear as choices when webMethods.io Integration prompts for input at run time.

    In addition to specifying the name and type of the field, and whether the type is an Array, you can set properties that specify an XML Namespace and indicate whether the field is required at runtime by selecting the Required field option. Select the Content Type you can apply to String, String list, or String table variables. See Content Types and Variable Constraints for information.

    You can add a field from the fields panel by clicking the duplicate field icon. You can also copy a field from the fields panel and depending on the context, you can either paste the field or the field path. For example, if you copy a field and paste the field in the Set Value window in a FlowService, the field path will be pasted. If you copy an array item, the path that is pasted includes the item index. You cannot modify or paste the child fields of a Document Reference. When defining a document type, it is recommended to avoid adding identically named fields to the document. In particular, do not add identically named fields that are of the same data type.

    You can assign an XML namespace and prefix to a field by specifying a URI for the XML namespace property and by using the prefix:fieldName format for the field name. For example, suppose a field is named eg:account and the XML namespace property is set to http://www.example.com. The prefix is eg, the localname is account, and the namespace name is http://www.example.com.

    Keep the following points in mind when assigning XML namespaces and prefixes to a field:

  • The field name must be in the format: prefix:fieldName.
  • You must specify a URI in the XML namespace property.
  • Do not use the same prefix for different namespaces in the same document type, input signature, or output signature.
  • 6.Click Save after you have entered the details and constraints for each field.

    Note: When you edit a document type, any change is automatically propagated to all FlowServices that use or reference the document type.

    The new document type appears in the Document Types page.

    Creating Document Types from an XML Schema Definition

    Let us see how to create a document type from an XML Schema Definition with the help of an example. We will create a document type from an XML Schema Definition and then use the document type to create Accounts in Salesforce CRM.

    Before you begin

  • Check if you have the Developer and Admin roles assigned from the Settings > Roles page.
  • Obtain the credentials to log in to the Salesforce CRM back end account.
  • Create the Salesforce Account (SalesforceCRM_1) in webMethods.io Integration. You can also create this account inline at a later step.
  • 1.Log in to your tenant and from the webMethods.io Integration navigation bar, click Projects. Select a project and then select Configurations > FlowService > Document Types. From the Document Types page, you can add, edit, delete, or copy a document type. To edit an existing document type, on the Document Types page, click the Edit icon for the document type.

    2.To create a new document type from an XML Schema Definition, from the Document Types page, click Add Document Type > Build from XML Schema Definition.

    3.Provide a name and description of your document type, for example, customerOrder. Required fields are marked with an asterisk on the page.

    4.On the Source selection panel, under XML schema source, do one of the following to specify the source file for the document type:

  • To use an XML Schema Definition that resides on the Internet as the source, select URL. Then, type the URL of the resource. The URL you specify must begin with http: or https:.
  • To use an XML Schema Definition that resides in your local file system as the source, select File. Then click Browse and select the file. You can add additional imported or included XML schema files.

    Note: The maximum file upload size is 5 MB which includes the primary source file and additional files, if any.

  • 5.Click Next and on the Processing options panel, under Content model compliances, select a content model compliance to indicate how strictly webMethods.io Integration represents content models from the XML Schema Definition in the resulting document type. Let us select None.

    6.You can specify whether webMethods.io Integration enforces strict, lax, or no content model compliance when generating the document type. Content models provide a formal description of the structure and allowed content for a complex type. The type of compliance that you specify can affect whether webMethods.io Integration generates a document type from a particular XML Schema Definition successfully. Currently, webMethods.io Integration does not support repeating model groups, nested model groups, or the any attribute. If you select strict compliance, webMethods.io Integration does not generate a document type from any XML Schema Definition that contains those items.

    Select… To…
    Strict Generate the document type only if webMethods.io Integration can represent the content models defined in the XML Schema Definition correctly. Document type generation fails if webMethods.io Integration cannot accurately represent the content models in the source XML Schema Definition. Currently, webMethods.io Integration does not support repeating model groups, nested model groups, or any attribute. If you select strict compliance, webMethods.io Integration does not generate a document type from any XML Schema Definition that contains those items.
    Lax When possible, generate a document type that correctly represents the content models for the complex types defined in the XML Schema Definition. If webMethods.io Integration cannot correctly represent the content model in the XML Schema Definition in the resulting document type, webMethods.io Integration generates the document type using a compliance mode of None. When you select lax compliance, webMethods.io Integration generates the document type even if the content models in the XML Schema Definition cannot be represented correctly.
    None Generate a document type that does not necessarily represent or maintain the content models in the source XML Schema Definition.

    7.If you select strict or lax compliance, do one of the following to specify whether document types generated contain multiple *body fields to preserve the location of text in instance documents.

  • Select the Preserve text position check box to indicate that the document type generated preserves the locations for text in instance documents. The resulting document type contains a *body field after each field and includes a leading *body field. In instance documents for this document type, webMethods.io Integration places text that appears after a field in the *body.
  • Clear the Preserve text position check box to indicate that the document type generated does not preserve the locations for text in instance documents. The resulting document type contains a single *body field at the top of the document type. In instance documents for this document type, text data around fields is all placed in the same *body field.
  • 8.If you want webMethods.io Integration to use the Xerces parser to validate the XML Schema Definition, select the Validate schema using Xerces check box.

    Note: webMethods.io Integration automatically uses an internal schema parser to validate the XML Schema Definition. However, the Xerces parser provides more strict validation than the internal schema parser. As a result, some schemas that the internal schema parser considers to be valid might be considered invalid by the Xerces parser.

    9.Click Next and on the Select root nodes panel, select the elements that you want to use as the root elements for the document type. The resulting document type contains all of the selected root elements as top-level fields in the generated document type.

    10.Click Save.

    webMethods.io Integration creates the document type. As you can see, other document types are created automatically from the same xsd source file.

    Note: If an element in the XML Schema Definition is a complex type, webMethods.io Integration creates the document type that defines the structure of the above complex type automatically, along with the main document type. For example, in the below EmployeeDetails.xsd file, the field address is a complex type containing Doorno, street, city, and pincode as its fields.

    Then two document types are created when we create the document type with this xsd source. One document type is the main document type, Employeedetails and the other document type is docTypeRef_AddressType, which represents the structure of the complex type.

    Notes

    11.Now let us use the document type customerOrder to create Accounts in Salesforce CRM.
    Go to the FlowServices page, click the + icon to create a new FlowService, and then provide a name CreateAccountsDocType and description of the FlowService.

    Click the I/O icon as shown above, and define the input and output fields. Select the document reference and save it.

    12.Select Salesforce CRM and link the SalesforceCRM_1 account.

    13.Click the mapping icon and map the input and output fields.

    14.Close the mapping panel by clicking the icon, click the run icon and enter the input values.

    15.Click Run and inspect the results.

    Content Types

    The following table identifies the content types you can apply to String or String list variables. Each of these content types corresponds to a built-in simple type defined in the specification XML Schema Part 2: Datatypes.

    Content Types Description
    anyURI A Uniform Resource Identifier Reference. The value of anyURI may be absolute or relative. Constraining Facets
    enumeration, length, maxLength, minLength, pattern
    Note: The anyURI type indicates that the variable value plays the role of a URI and is defined like a URI. URI references are not validated because it is impractical for applications to check the validity of a URI reference.
    base64Binary Base64-encoded binary data. Constraining Facets
    enumeration, length, maxLength, minLength, pattern
    boolean True or false. Constraining Facets
    pattern
    Example
    true, 1, false, 0
    byte A whole number whose value is greater than or equal to –128 but less than or equal to 127. Constraining Facets
    enumeration, fractionDigits, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern, totalDigits
    Example
    -128, -26, 0, 15, 125
    date A calendar date from the Gregorian calendar. Values need to match the following pattern: CCYY-MM-DD
    Where CC represents the century, YY the year, MM the month, DD the day. The pattern can include a Z at the end to indicate Coordinated Universal Time or to indicate the difference between the time zone and coordinated universal time.
    Constraining Facets
    enumeration, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern
    Example
    1997-08-09 (August 9, 1997)
    dateTime A specific instant of time (a date and time of day). Values need to match the following pattern: CCYY-MM-DDThh:mm:ss.sss
    Where CC represents the century, YY the year, MM the month, DD the day, T the date/time separator, hh the hour, mm the minutes, and ss the seconds. The pattern can include a Z at the end to indicate Coordinated Universal Time or to indicate the difference between the time zone and Coordinated Universal Time.
    Constraining Facets
    enumeration, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern
    Example
    2000-06-29T17:30:00-05:00 represents 5:30 pm Eastern Standard time on June 29, 2000. (Eastern Standard Time is 5 hours behind Coordinated Universal Time.)
    decimal A number with an optional decimal point. Constraining Facets
    enumeration, fractionDigits, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern, totalDigits
    Example
    8.01, 290, -47.24
    double Double-precision 64-bit floating point type. Constraining Facets
    enumeration, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern
    Example 6.02E23, 3.14, -26, 1.25e-2
    duration A length of time. Values need to match the following pattern: PnYnMnDTnHnMnS
    Where nY represents the number of years, nM represents the number of months, nD is the number of days, T separates the date and time, nH the number of hours, nM the number of minutes and nS the number of seconds. Precede the duration with a minus (-) sign to indicate a negative duration.
    Constraining Facets
    enumeration, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern
    Example
    P2Y10M20DT5H50M represents a duration of 2 years, 10 months, 20 days, 5 hours, and 50 minutes
    ENTITIES Sequence of whitespace-separated ENTITY values declared in the DTD. Represents the ENTITIES attribute type from the XML 1.0 Recommendation. Constraining Facets
    enumeration, length, maxLength, minLength
    ENTITY Name associated with an unparsed entity of the DTD. Represents the ENTITY attribute type from the XML 1.0 Recommendation. Constraining Facets
    enumeration, length, maxLength, minLength, pattern, whiteSpace
    float A number with a fractional part. Constraining Facets
    enumeration, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern
    Example
    8.01, 25, 6.02E23, -5.5
    gDay A specific day that recurs every month. Values must match the following pattern: —DD
    Where DD represents the day. The pattern can include a Z at the end to indicate Coordinated Universal Time or to indicate the difference between the time zone and Coordinated Universal Time.
    Constraining Facets
    enumeration, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern
    Example
    ---24 indicates the 24th day of each month
    gMonth A Gregorian month that occurs every year. Values must match the following pattern: –MM
    Where MM represents the month. The pattern can include a Z at the end to indicate Coordinated Universal Time or to indicate the difference between the time zone and Coordinated Universal Time.
    Constraining Facets
    enumeration, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern
    Example
    --11 represents November
    gMonthDay A specific day and month that recurs every year in the Gregorian calendar. Values must match the following pattern: –MM-DD
    Where MM represents the month and DD represents the day. The pattern can include a Z at the end to indicate Coordinated Universal Time or to indicate the difference between the time zone and Coordinated Universal Time.
    Constraining Facets
    enumeration, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern
    Example
    --09-24 represents September 24th
    gYear A specific year in the Gregorian calendar. Values must match the following pattern: CCYY
    Where CC represents the century, and YY the year. The pattern can include a Z at the end to indicate Coordinated Universal Time or to indicate the difference between the time zone and Coordinated Universal Time.
    Constraining Facets
    enumeration, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern
    Example
    2001 indicates the year 2001.
    gYearMonth A specific month and year in the Gregorian calendar. Values must match the following pattern: CCYY-MM
    Where CC represents the century, YY the year, and MM the month. The pattern can include a Z at the end to indicate Coordinated Universal Time or to indicate the difference between the time zone and Coordinated Universal Time
    Constraining Facets
    enumeration, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern
    Example
    2001-04 indicates April 2001.
    hexBinary Hex-encoded binary data. Constraining Facets
    enumeration, length, maxLength, minLength, pattern
    ID A name that uniquely identifies an individual element in an instance document. The value for ID needs to be a valid XML name. The ID datatype represents the ID attribute type from the XML 1.0 Recommendation. Constraining Facets
    enumeration, length, maxLength, minLength, pattern, whiteSpace
    IDREF A reference to an element with a unique ID. The value of IDREF is the same as the ID value. The IDREF datatype represents the IDREF attribute type from the XML 1.0 Recommendation. Constraining Facets
    enumeration, length, maxLength, minLength, pattern, whiteSpace
    IDREFS Sequence of white space separated IDREFs used in an XML document. The IDREFS datatype represents the IDREFS attribute type from the XML 1.0 Recommendation. Constraining Facets
    enumeration, length, maxLength, minLength
    int A whole number with a value greater than or equal to -2147483647 but less than or equal to 2147483647. Constraining Facets
    enumeration, fractionDigits, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern, totalDigits
    Example
    -21474836, -55500, 0, 33123, 4271974
    integer A positive or negative whole number. Constraining Facets
    enumeration, fractionDigits, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern, totalDigits
    Example
    -2500, -5, 0, 15, 365
    language Language identifiers used to indicate the language in which the content is written. Natural language identifiers are defined in IETF RFC 1766. Constraining Facets
    enumeration, length, maxLength, minLength, pattern, whiteSpace
    long A whole number with a value greater than or equal to -9223372036854775808 but less than or equal to 9223372036854775807. Constraining Facets
    enumeration, fractionDigits, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern, totalDigits
    Example
    -55600, -23, 0, 256, 3211569432
    Name XML names that match the Name production of XML 1.0 (Second Edition). Constraining Facets
    enumeration, length, maxLength, minLength, pattern, whiteSpace
    NCName Non-colonized XML names. Set of all strings that match the NCName production of Namespaces in XML. Constraining Facets
    enumeration, length, maxLength, minLength, pattern, whiteSpace
    negativeInteger An integer with a value less than or equal to –1. Constraining Facets
    enumeration, fractionDigits, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern, totalDigits
    Example
    -255556, -354, -3, -1
    NMTOKEN Any mixture of name characters. Represents the NMTOKEN attribute type from the XML 1.0 Recommendation. Constraining Facets
    enumeration, length, maxLength, minLength, pattern, whiteSpace
    NMTOKENS Sequences of NMTOKENS. Represents the NMTOKENS attribute type from the XML 1.0 Recommendation. Constraining Facets
    enumeration, length, maxLength, minLength
    nonNegativeInteger An integer with a value greater than or equal to 0. Constraining Facets
    enumeration, fractionDigits, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern, totalDigits
    Example
    <br> 0, 15, 32123
    nonPositiveInteger An integer with a value less than or equal to 0. Constraining Facets
    enumeration, fractionDigits, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern, totalDigits, whiteSpace
    Example
    -256453, -357, -1, 0
    normalizedString Represents white space normalized strings. Set of strings (sequence of UCS characters) that do not contain the carriage return (#xD), line feed (#xA), or tab (#x9) characters. Constraining Facets
    enumeration, length, maxLength, minLength, pattern, whiteSpace
    Example
    MAB-0907
    positiveInteger An integer with a value greater than or equal to 1. Constraining Facets
    enumeration, fractionDigits, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern, totalDigits
    Example
    1, 1500, 23000
    short A whole number with a value greater than or equal to -32768 but less than or equal to 32767. Constraining Facets
    enumeration, fractionDigits, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern, totalDigits
    Example
    -32000, -543, 0, 456, 3265
    string Character strings in XML. A sequence of UCS characters (ISO 10646 and Unicode). By default, all white space is preserved for variables with a string content constraint. Constraining Facets
    enumeration, length, maxLength, minLength, pattern, whiteSpace
    Example
    MAB-0907
    time An instant of time that occurs every day. Values must match the following pattern: hh:mm:ss.sss
    Where hh indicates the hour, mm the minutes, and ss the seconds. The pattern can include a Z at the end to indicate Coordinated Universal Time or to indicate the difference between the time zone and Coordinated Universal Time.
    Constraining Facets
    enumeration, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern
    Example
    18:10:00-05:00 (6:10 pm, Eastern Standard Time) Eastern Standard Time is 5 hours behind Coordinated Universal Time.
    token Represents tokenized strings. Set of strings that do not contain the carriage return (#xD), line feed (#xA), or tab (#x9) characters, leading or trailing spaces (#x20), or sequences of two or more spaces. Constraining Facets
    enumeration, length, maxLength, minLength, pattern, whiteSpace
    unsignedByte A whole number greater than or equal to 0, but less than or equal to 255. Constraining Facets
    enumeration, fractionDigits, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern, totalDigits
    Example
    0, 112, 200
    unsignedInt A whole number greater than or equal to 0, but less than or equal to 4294967295. Constraining Facets
    enumeration, fractionDigits, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern, totalDigits
    Example
    0, 22335, 123223333
    unsignedLong A whole number greater than or equal to 0, but less than or equal to 18446744073709551615. Constraining Facets
    enumeration, fractionDigits, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern, totalDigits
    Example
    0, 2001, 3363124
    unsignedShort A whole number greater then or equal to 0, but less than or equal to 65535. Constraining Facets
    enumeration, fractionDigits, maxExclusive, maxInclusive, minExclusive, minInclusive, pattern, totalDigits
    Example
    0, 1000, 65000

    Customizing a String Content Type

    Instead of applying an existing content type or simple type to a String or String list, you can customize an existing type and apply the new, modified type to a variable. You can customize a content type or simple type by changing the constraining facets applied to the type.

    When you customize a type, you actually create a new content type. The constraining facets you can specify depend on the content type. Note that content types and constraining facets correspond to datatypes and constraining facets defined in XML Schema. For more information about constraining facets for a datatype, see the specification XML Schema Part 2: Datatypes (http://www.w3.org/TR/xmlschema-2/).

    To customize a content type

    1.Select the variable to which you want to apply a customized content type and click the edit icon.

    2.Click the Content type drop-down arrow and then in the Content type list, select the content type you want to customize. The constraining facet fields below the Content type list are made available for data entry.

    3.In the fields below the Content type field, specify the constraining facet values you want to apply to the content type and click Save.

    Note: The constraining facets displayed below the Content type list depend on the primitive type from which the simple type is derived. Primitive types are the basic data types from which all other data types are derived. For example, if the primitive type is string, the constraining facets Enumeration, Length, Minimum Length, Maximum Length, Whitespace, and pattern are displayed. For more information about primitive types, see XML Schema Part 2: Datatypes at http://www.w3.org/TR/xmlschema-2/.

    Variable Constraints

    You apply content constraints to variables in the document types that you want to use as blueprints in data validation. Content constraints describe the data a variable can contain. At validation time, if the variable value does not conform to the content constraints applied to the variable, the validation engine considers the value to be invalid.

    When applying content constraints to variables, do the following:

    Select a content type: A content type specifies the type of data for the variable value, such as string, integer, boolean, or date. A content type corresponds to a simple type definition in a schema.

    Set constraining facets: Constraining facets restrict the content type, which in turn, restrict the value of the variable to which the content type is applied. Each content type has a set of constraining facets. For example, you can set a length restriction for a string content type, or a maximum value restriction for an integer content type.

    For example, for a String variable named itemQuantity, specify a content type that requires the variable value to be an integer. You could then set constraining facets that limit the content of itemQuantity to a value between 1 and 100.

    The content types and constraining facets correspond to the built-in data types and constraining facets in XML Schema. The World Wide Web Consortium (W3C) defines the built-in data types and constraining facets in the specification XML Schema Part 2: Datatypes (http://www.w3c.org/TR/xmlschema-2).

    Applying Constraints to a Variable

    You can apply content constraints to variables in the document types that you want to use as blueprints in data validation.

    To apply constraints to a variable

    1.On the Document Types page, for a document type, click the Edit icon. Select a field and click the edit field icon to view the field properties panel.

    You can apply constraints to the fields of a document type, and also the fields declared on the Input/Output page after you click the Define I/O option in a FlowService. If the selected variable is a String or String list, and you want to specify content constraints for the variable, do the following:

    If you want to use a content type that corresponds to a built-in simple type in XML schema, in the Content type list, select the type for the variable contents. To apply the selected type to the variable, click Save.

    2.Repeat this procedure for each variable to which you want to apply the constraints in the document type and click Save.

    Lock and Unlock FlowServices

    webMethods.io Integration allows you to manage a FlowService during the development life cycle by auto locking. When you edit a FlowService, it is automatically locked for you. This restricts multiple users from editing the FlowService at the same time. After you edit a FlowService and save the changes, you can exit the edit mode to unlock the FlowService and make it available for other users.

    Note: The lock and unlock capabilities for FlowServices are currently supported only for AWS tenants.

    If you are editing a FlowService and if another user opens the FlowService, then that user sees the following message.

    A FlowService cannot be edited in view mode.

    After you edit a FlowService and save the changes, the other user sees the following message:

    If you are editing a FlowService and another user tries to delete the FlowService, the other user sees the following message:

    If you have kept the user session idle for quite sometime or because of any other issues a FlowService lock remains and is not resolved, then only a user with Admin role can unlock the FlowService and make it available for editing.

    To unlock a FlowService, click the ellipsis icon available on a FlowService and select Unlock.

    If the Admin unlocks the FlowService, all editing permissions are automatically revoked for the user who has locked the Flowservice, and any unsaved changes will be lost. The following message appears after the Admin unlocks the FlowService:

    Further, all users who are currently editing or viewing the FlowService, see the following message:

    Version Management of FlowServices

    webMethods.io Integration allows you to view the version history of a FlowService. Click the ellipsis icon and select the Version history option available on the FlowServices tool bar panel to view the version history.

    When you save a FlowService, a new version is added to the Version History with the default commit message. You can also provide a custom commit message by clicking the drop-down arrow beside the Save option and selecting Save with message.
    You can click on any version on the Version history panel and view the corresponding FlowService version.
    To restore an earlier version, select the earlier version of the FlowService, and click the Restore icon .
    If you have reverted to an earlier version and there is a scheduled execution for the FlowService, the reverted version runs as per the defined schedule.

    Note: If a FlowService references any other FlowService, then the pipeline mapping of the referenced FlowService is also restored to that particular version. But if the pipeline mapping of the referenced FlowService has been modified in a later version, the modification might break the mappings and the FlowService execution will not be successful.
    Further, if a FlowService references any document types, reference data, REST connectors, and SOAP connectors, and if those references have been modified, then those references will not be restored.

    Note: If you delete a FlowService and then create another FlowService with the same name, the version history of the deleted FlowService will be available.

    Debug FlowServices

    You can debug a FlowService and can inspect the data flow during the debugging session. The FlowService gets automatically saved when you start the debug session.

    You can do the following in debug mode:

  • Start a FlowService in debug mode, specify the input values, and inspect the results.
  • Examine and edit the pipeline data before and after executing the individual steps.
  • Monitor the execution path, execute the steps one at a time, or specify breakpoints where you want to halt the execution.
  • To start the Debug session, from the FlowServices page, select a FlowService, insert the breakpoints, and then click the Debug icon . The debug session halts at the first step even if you have not inserted a breakpoint.

    If you have defined input fields for the FlowService, the Input Values dialog box appears where you can specify the input values, else the Debug panel appears if no input fields are defined.

    Note: If you have not defined any input fields or if there are no pipeline output variables, then while debugging, a message appears as the pipeline is empty. Further, if you disable a step, that step will not be considered while debugging. The FlowService Execution page (Monitor > FlowService Execution) as well as the Execution History page do not display any execution logs for a debug session.

    Note: If a FlowService has a child FlowService, webMethods.io Integration will not step into the child FlowService during a debug session.

    The following table describes the options available while debugging the FlowService:

    Icon Applicable for… Action/Description
    Insert Breakpoints Insert a breakpoint in a FlowService by clicking on the step number.
    To remove a breakpoint, click on the step number where the breakpoint is inserted.
    Breakpoints are recognized only when you run a FlowService in debug session.
    A breakpoint is a point where you want processing to pause when you debug the FlowService. Breakpoints can help you isolate a section of code or examine data values at a particular point in the execution path. For example, you might want to set a pair of breakpoints before and after a particular step, so that you can examine the pipeline before and after that step executes.When you run a FlowService that contains a breakpoint, the FlowService is executed up to, but not including the designated breakpoint.
    Icon Applicable for… Action/Description
    Disable Breakpoints Ignores all breakpoints inserted in the FlowService steps.
    Icon Applicable for… Action/Description
    Enable Breakpoints Enables all breakpoints inserted in the FlowService steps.
    Icon Applicable for… Action/Description
    Resume Resumes the debug session but pauses at the next breakpoint.
    Icon Applicable for… Action/Description
    Stop Terminates the debug session. A debug session might also stop by itself for the following reasons:
    • The FlowService that you are debugging executes to completion (error or success).
    • You select Step over for the last step in the FlowService.
    • You Exit the FlowService.
    Icon Applicable for… Action/Description
    Restart Restarts the debug session from the first step.
    Icon Applicable for… Action/Description
    Step over Executes the FlowService on a step-by-step basis. For conditional controls:
    • Conditions are evaluated
    • If values are true, then the steps inside it are executed on the next step over.
    Icon Applicable for… Action/Description
    Clear all breakpoints Removes all breakpoints inserted in the FlowService.
    Icon Applicable for… Action/Description
    Close Closes the Debug panel and goes back to the FlowService.

    Modifying the current pipeline data while debugging

    While debugging, you can modify the contents of the pipeline by clicking on the field values as shown below. The changed values are not applied on the current step but on successive steps when you do a Step over or Resume.

    While modifying the pipeline, keep the following points in mind:

  • You can modify the pipeline data only during an active debug session.
  • When you modify values in the pipeline, the changes apply only to the current debug session. The FlowService is not permanently changed.
  • You can modify existing variables but cannot add new variables to the pipeline.
  • Note: While running or debugging FlowServices and testing operations, if the input has any duplicate keys, or if the service returns an output with duplicate keys, you can view those keys.

    Restart and Resume FlowServices

    webMethods.io Integration allows you to restart or resume failed FlowService executions. If an execution fails, you can resume that execution from the point where it had failed. Resuming an execution does not execute the previously successful operations but executes only the failed operations and operations that are not yet executed. When a FlowService execution is restarted, the execution occurs from the beginning.

    Note: The Restart and Resume options are available only if you have the required capability for restarting and resuming FlowServices. Contact Global Support to enable the Restart and Resume capability as these options are not available by default in the user interface.

    The following table provides information on when you can restart or resume a FlowService execution:

    Execution Result Status Restartable Resumable
    Successful Executions Yes No
    Failed Executions Yes Yes
    Completed with Errors Yes No
    Running Executions No No

    How It Works

    1.From the webMethods.io Integration navigation bar, click Projects. Select a project and then select FlowServices.

    2.Click the ellipsis icon available on the FlowService and select Overview.

    3.On the Overview page, select the Enable FlowService to be restarted option. Enabling this option increases the execution time of a FlowService. If the FlowService is updated, you cannot restart or resume its executions that have occurred before the update.
    Further, FlowServices using Operations and other FlowServices, which have fields of type Object in their signature, may not execute properly when restarted or resumed.

    4.Select the FlowService and run it.

    5.Provide the input values, if needed, and then click Run.

    6.Go to the Monitor > Execution Results > FlowService Execution page. Click on the execution log and on the execution details page, click the Restart or Resume options.

    7.Provide the input values, and then click Run to restart the execution from the beginning. Click the Resume option, edit the input data, and resume the execution from the point where it had failed in the previous run.

    Invoke FlowServices over HTTP

    webMethods.io Integration allows you to trigger the execution of a FlowService from an external system. This option provides you with another way to trigger FlowService executions from a software application, for example, a REST client, apart from manual and scheduled executions from the user interface.

    On the external program, provide the HTTP URL, Method, required JSON body, and necessary header parameters, including the required security credentials (user name and password) to invoke the FlowService. After the FlowService is executed, the response contains the pipeline data.

    How it Works

    1.Log in to your tenant and from the webMethods.io Integration navigation bar, click Projects. Select a project and then click FlowServices.

    2.Click the ellipsis icon available on a FlowService and select Overview.

    The Overview page appears.

    3.On the Overview page, select the Enable FlowService to be invoked over HTTP option. Once the FlowService is enabled to be invoked over HTTP, the HTTP request URL appears.

    4.Click the Advanced details section to view the HTTP Method, sample JSON input, and the parameters that are required to invoke the FlowService from an external system.

    Synchronous URL

    You can execute FlowServices synchronously using the run URL:

    https://sub-domain.domain/integration/rest/external/integration/run/stagename/integrationname

    run - FlowService executes and the response contains the pipeline data.

    sub-domain is a domain that is part of the primary domain.

    run - FlowService executes and the response contains the pipeline data.

    stagename is the name of the active stage.

    integrationname is the name of the FlowService.

    Note: You must provide your user name and password to execute the FlowService from the external program, else you may encounter the 401 - Unauthorized User Error.

    Asynchronous URL

    You can execute FlowServices asynchronously using the submit URL:

    https://sub-domain.domain/integration/rest/external/integration/submit/stagename/integrationname

    submit - FlowService has been submitted for execution and the response contains a status indicating whether the FlowService has been submitted for execution. When the request is submitted for execution using the submit option, the response contains a reference to the execution result identifier so that a new HTTP call can be made later to get the execution results.

    Application Status Codes for submit

  • 0 - SUCCESS: Successfully submitted the FlowService for execution.
  • -1 - ERROR: Problem while submitting the FlowService for execution.
  • To get the execution results, construct the URL of the new HTTP call from the URI field available in the Response section.

    To construct the URL of the new HTTP call, add the response URI obtained from resultReference in the Response section to: https://sub-domain.domain.com

    Response URI format: https://sub-domain.domain/integration/rest/external/integration/execution/result?resultReference=765733-6a21-4b02-864f-e958f698373

    HTTP Status Codes

    5.Download the Postman app (Windows 64-bit) from https://www.postman.com/downloads, install the app, and then sign-in to Postman.

    6.On the Postman page, click Create a request.

    7.On the Postman app Request page, select POST. Then copy the Synchronous URL from the webMethods.io Integration FlowService Overview page and paste it in the Enter Request URL field as shown below.

    8.Go to the webMethods.io Integration FlowService Overview > Advanced details page and get the Content-Type and Accept header parameters.

    9.Go to the Postman app Request page, click Headers, and enter the Content-Type and Accept values as shown below.

    10.On the Postman app Request page, select POST, click Authorization, select the Type as Basic Auth, enter your webMethods.io Integration login user name and password, and click Send as shown below.

    The result appears in the Body section at the lower part of the Postman Request page. The execution result also appears on the webMethods.io Integration FlowService Execution History page and on the Monitor > Execution Results > FlowService Execution page under Execution Logs.

    Export FlowServices

    webMethods.io Integration allows you to export FlowServices from the FlowServices page. You can export FlowServices only if you have the required capability for exporting FlowServices. You can export a FlowService from one tenant and import that FlowService to another tenant.

    How It Works

    1.From the webMethods.io Integration navigation bar, click Projects. Select a project and then click FlowServices. The FlowServices page appears.

    2.Click the ellipsis icon available on the FlowService and select Export. If the FlowService you are exporting uses Reference Data, Document Types, SOAP, or REST Connectors, then those components are also exported along with the FlowService.

    The Confirm Export dialog box appears.

    3.Click Export to export the FlowService. The FlowService is downloaded as a zip file to your default download folder. The zip file has the same name as that of the FlowService. Do not modify the contents of the exported zip file. If you modify the contents of the zip file, the FlowService cannot be imported back to webMethods.io Integration.

    Exporting a FlowService having an On-Premises Connector

    After exporting a FlowService that has an on-premises connector, if you want to import the FlowService, then before importing the FlowService, ensure that you upload the same on-premises connector to webMethods.io Integration. Else you will not be able to import the FlowService.

    Import FlowServices

    webMethods.io Integration allows you to import FlowServices from a zip file that was earlier exported from webMethods.io Integration. You can export FlowServices from one tenant and import those FlowServices to another tenant. You can import FlowServices provided you have the required capability.

    Note: If you want to import a FlowService that has an on-premises connector, before importing the FlowService, ensure that you upload the same on-premises connector to webMethods.io Integration, else you will not be able to import the FlowService.

    How It Works

    1.From the webMethods.io Integration navigation bar, click Projects. Select a project and then click FlowServices. The FlowServices page appears.

    2.Click Import and select the zip file that contains the exported FlowService.

    While importing a FlowService, if a dependent FlowService conflicts with an existing FlowService in the same project, you can:

    Notes

    • If the FlowService you are importing use SOAP or REST connectors and if those connectors do not exist in your system, continue importing the FlowService. The connectors are imported along with the FlowService. After importing, create the Accounts and then configure them in the imported FlowService.
    • If a FlowService you are importing uses an on-premises connector and if the connector does not exist in your system, the Account appears only after you have uploaded the on-premises connector.
    • If an Account is used in multiple steps in a FlowService, after importing the FlowService in a different project, the Account name appears in the relevant steps as shown.


      In the FlowService step as shown, the account appears as configured, but is not available in the project.


      In such cases, create the Account with the same name. The Account will be automatically configured in the relevant steps. If you create the Account with a different name, you have to configure the Account manually at each step. If an Account with the same name already exists in the project, then the Account will be automatically linked in the relevant steps.