Flow services

Overview

IBM webMethods 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 flow services directly in your IBM webMethods Integration project, thus eliminating the need to access the Flow Editor through the App Switcher. With flow services, 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 flow services, you can easily build a flow service by adding steps and selecting the constructs including Connectors, Controls, flow services, and Services from within the steps. The editor is visually enhanced to offer ease of use and is more interactive.

A flow service step is a basic unit of work that IBM webMethods Integration interprets and runs at run time. The steps are the building blocks of a flow service 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. IBM webMethods Integration lists steps sequentially from top to bottom and also runs them in that order.

You can simultaneously open five flow services in different tabs in a browser.

Comparing Workflows and Flow services

Workflows and flow services enable you to automate and optimize monotonous tasks based on a set of predefined rules and business logic. These features give you the power to connect apps, devices, and on-premises systems with only clicks and zero code. Although workflows and flow services help you to accomplish the same goal, there are significant differences between both the features.

The following table showcases the differences between workflows and flow services.

Migrating Flow Editor Integrations to Flow services

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

How it works

1. In IBM webMethods Integration, ensure that you have the Developer and Admin roles assigned from the Settings > Roles page.

2. In IBM webMethods Integration, select the project where you want to migrate the Flow Editor integrations and click the Flow services tab. IBM webMethods 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 Flow services in case of a successful migration. In case of any errors, it is recommended to recreate those integrations in Flow services.

Core elements, constructs, and components of Flow services

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

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

By default, the left panel lists the recently used Connectors, Controls, Project services, and Built-in services.

You can type a keyword in the rectangular box and search for the available elements. IBM webMethods 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 Flow service.

Categories

Displays the following categories:

• Connectors
• Controls
• Project Services
• Built-in Services

Connectors

Displays the connectors available to create the Flow service.

Connectors are grouped in the following categories on the flow services 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 flow service 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 flow service 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.

Controls

Controls are the programming constructs in a flow service. 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

• If: Use the If statement to return one value if a condition is true and another value if it’s false.

• If Else: Use the If statement to return one value if a condition is true and another value if it’s false. Else runs if the result of a previous test condition evaluates to false.

• Else If: The If step is used to evaluate a boolean condition and if the condition is true, statements inside the If step are run. The If step can be followed by an optional else step, which runs when the boolean expression is false. The If statements are run from the top towards the bottom. You can use one If or Else..If.. statement inside another If or Else..If..statement(s).

• Nested Condition: Nested conditions comprise condition statements contained within other condition statements. Conditions consisting of multiple statements are connected using the logical AND and OR operators.

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 flow service that takes a string as input and a string list in the pipeline, use Loops to invoke the flow service 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.

• Repeat

  • Repeat: The repeat step iterates only on an array and the number of executions is equal to the size of the array.

  • Repeat for Count: Repeat for Count specifies the maximum number of times IBM webMethods Integration re-runs the child steps in the Repeat step. If the count is set to 0, the Repeat step does not re-run the child steps. If the count is set to any value > 0, the Repeat step re-runs the child steps up to this number of times.
    Children of a Repeat step always run at least once. The count property specifies the maximum number of times the children can be re-run. The concept is the same as Repeat for each. The only difference here is that you iterate for a specific count. It can be specified directly on a step or through a variable (I/O or Pipeline).

  • Repeat for Input Output: The concept is same as Repeat for each. The only difference here is that you can iterate on two different arrays concurrently.

• While: While loop is used to iterate a part of the program several times. If the number of iterations are not fixed, it is recommended to use the While loop.

• Do Until: Do Until loops are similar, except that they repeat their bodies until some condition is false.

• Break: Use the Break step only within a loop. This allows you to break out of the containing loop, that is, it allows you to break the program execution out of the loop it is placed in. In case of nested loops, it breaks the inner loop first and then proceeds to outer loops. You cannot attach child steps to the Break step.

Example: Loop through nested arrays in flow services

Given the following nested document structure in JSON, retrieve the node6 element and apply an IF condition to it.

JSON Nested Structure

{
  "node1": {
    "node2": {
      "node3": [
        {
          "node4": {
            "node5": [
              {
                "node6": "Hello"
              }
            ]
          }
        }
      ]
    }
  }
}

1. In Flow Editor, define the data fields in the signature.

   

   For more information on defining input and output fields, see Input and Output Field Declaration

2. In the flow step, add a Repeat for node3.

3. Inside the node3 loop, add another Repeat for node5.

4. Add the IF condition, and select node6. Hover over the node and confirm the full path of the node in case of duplicate node names.

   

Error Handling

• Try, Catch, Finally: You can use these steps to try a sequence of flow service steps, catch and handle any failures that occur, and then perform any cleanup work. When adding the Try, Catch, and Finally steps to a flow service, decide which usage pattern you want to use. This can be a Try-Catch, a Try-Finally, or a Try-Catch-Finally. Identify the logic for which you want to provide exception handling. The steps for this logic belongs in the Try step. Then decide whether you want to handle exceptions and if so, which ones. Catch steps can handle all exceptions or specific exceptions. If the service handles exceptions, what recovery logic or logging needs to be added? Lastly, identify any cleanup logic that you want the service to perform, that is, decide if you need to include a Finally step.
  
  The general usage pattern for try-catch-finally is a single Try step followed by zero or more Catch steps, followed by zero or one Finally step. Catch steps can be configured to handle specific failures. The Finally step runs a set of steps after a Try step completes successfully or fails. If a Catch step runs, IBM webMethods Integration runs the Finally step after the Catch step completes.
  
  The Try-Catch usage pattern consists of a single Try step followed by one or more Catch steps. The Try step contains any number of child steps to be run. The Catch step contains any number of child steps to be run if the Try step fails.
  
  The Try-Finally usage pattern consists of a single Try step followed by a Finally step. The Try step contains any number of child steps to be run. The Finally step contains any number of child steps to run regardless of the outcome of the Try step. The Try-Finally usage pattern does not handle any failures that occur in the Try step. As a result, any failure from the Try step remains pending. After the Finally step completes, IBM webMethods Integration propagates the failure to the parent flow step of the Try step if the Finally step completes normally.
  
  The Try-Catch-Finally usage pattern is a combination of Try-Catch and Try-Finally. A Try-Catch-Finally consists of a Try step that contains logic to be attempted, followed by one or more Catch steps to handle any failure that occurs and run recovery logic. This is followed by a single Finally step to perform any clean up.
  
  The Finally step contains logic that is run regardless of whether the Try step succeeds or fails. Often, the Finally step contains clean up logic that needs to run regardless of the outcome of the preceding Try or Catch steps.

• Throw Error: You can attach the throwerror step inside any step except the catch section of the try catch step. You can explicitly throw an exception with a custom error message. If you use this step inside the try section of the try catch step, the error is caught in the catch section. If you use the value of a pipeline variable for this custom error message, type the variable name between % symbols, for example, %mymessage%. The variable you specify must be a String. You cannot attach child steps to the Throwerror step.
  If you add a Throwerror step inside a try catch step, any changes done to the pipeline variables inside the try step are reset to the previous values existing in the pipeline.

Exit

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

• Exit Flow service signaling success step allows you to successfully terminate and exit from the currently running flow service. You cannot attach child blocks to the Exit flow service signaling success step.

• Exit Flow service signaling failure step abnormally terminates the currently running flow service with a failure message. You can specify the text of the failure message that is to be displayed. If you want to use the value of a pipeline variable for this flow service message, type the variable name between % symbols, for example, %mymessage%. The variable you specify must be a String. You cannot attach child steps to the Exit flow service signaling failure step.

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, IBM webMethods 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, IBM webMethods 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 flow service.

Scenario 3

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

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. IBM webMethods 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:

Transform Pipeline

As systems rarely produce data in the exact format that the other systems need, at times you need to transform data in terms of format, structure, or values of data. Using the Transform Pipeline control in the flow service you can do transformations on data in the Pipeline.

You can insert multiple transformers in a single Transform Pipeline step, to perform multiple data transformations. When multiple transformers are added, the Transform Pipeline step behavior is as follows:

• All transformers are contained within a Transform Pipeline step and do not appear as a separate flow service step in the editor.

• All transformers are independent of each other and do not execute in a specific order.

Consequently, the output of one transformer cannot be used as the input to another transform. These characteristics make the Transform Pipeline step different than that of a normal step in a flow service.

Inserting a Transform Pipeline Step in a Flow service

1. Create a flow service. A flow service step is created initially without any data.

2. Select Transform Pipeline from the step drop-down list. The Transform Pipeline step is added.

Adding Transformers

1. Create a flow service. A flow service step is created initially without any data.

2. Select Transform Pipeline from the step drop-down list.

3. Click on the flow service step. The Pipeline panel appears.

4. Click on the Transformers column header. The Select Transformer step is added under the Transformers column.

5. Select the function from Select Transformer. The input field values are modified based on the selected transformer.

Mapping Pipeline Fields to Transformer Fields

The pipeline fields can be mapped to the service fields of the transformers added.

1. Go to the Transformer step (for which the transformers have been added) in the Pipeline panel.

2. Click in the Transformer step. The fields are displayed.

3. Link the fields as per your requirements.

Mapping Fields Directly

The Pipeline Input fields can be directly mapped to any of the Pipeline Output fields. This is known as Direct Mapping.

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 flow service 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 flow service 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.

Project Services

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

Built-in 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.

Tasks associated with Flow Services

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

Icons	Task/Description
	Provide a flow service name and description. The asterisk denotes that the flow service is modified.
	Search for text in the flow service, inside the editor, and within the steps.
	Debug a flow service and inspect the data flow during the debugging session. For more information, see Debug Flow services.
	Run the flow service after you save it. This enables you to test the flow service execution in real time and view the test results.
	View the runtime log entries for a selected runtime directly within the Flow Editor.
	Define the input and output fields of a flow service. For more information, see Input and Output Fields Declaration.
	This option allows you to log business data at the flow service 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. For more information, see Log Business Data.
	Click the Navigator icon to view a summary of the flow service steps, which appear on the right panel. Move the slider available on the navigator panel to move through the flow service. If you move through the main flow service page, the navigator view will automatically move. You can click on a navigator step to go to that step in the flow service.
	Click the Default mode to view more spacious, visual representation of the integration flow. Each step or action is displayed with ample space around it, making it easier to visualize and interact with each element.
	Click the Compact mode option to display actions and steps in a more condensed format. This mode minimizes the space between elements, allowing more steps to be visible on the screen without scrolling.
	Press Ctrl and select a step or multiple steps in the flow service. Then click the delete step(s) icon to delete the selected step or multiple steps in the flow service. You can also delete steps by right-clicking on a step on the flow service editor and selecting the delete option.
	Press Ctrl and select a step or multiple steps in the flow service. 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 flow service editor and selecting the available options.
	Cut, Copy, Paste, Duplicate, Enable, and Disable steps in the flow service. You can also right-click on a step on the flow service 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. Note You can perform cut, copy, and paste actions within the same flow service or another flow service in the same project. However, if you perform these actions from one flow service to another in a different project, you might encounter deployment errors.
	Undo a step action.
	Redo a step action.
	Whenever you save a flow service, 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.
	- Whenever you save a flow service, 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 Source Control option and selecting Save with message. -Version History: View the version commit history of the flow service.
	Access Help topics or take a tour.
	The following options are available: - Schedule: Define a schedule for the flow service execution. Select Once if you want to schedule the flow service 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 option to skip the next scheduled execution if the previous scheduled execution is still running, except when the previous scheduled execution is running for more than 60 minutes (default). In this case, the next scheduled execution starts even if the previous scheduled execution is running. IBM support if you want to change the 60 minutes default value. If you do not select the Prevent concurrent executions 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 flow service based on the defined input signature. Click Delete if you want to permanently remove the current recurrence schedule. Note Any time stamp displayed in IBM webMethods Integration is based on the time zone you have specified in IBM webMethods iPaaS. All time zones available in IBM webMethods iPaaS are currently not supported in IBM webMethods Integration. If a time zone in IBM webMethods iPaaS is not supported, then the time stamp in IBM webMethods Integration defaults to the Pacific Standard Time (PST) time zone. You can pause a flow service execution that was scheduled by clicking the Pause option on the Overview page of a flow service. - Key Shortcuts: View keyboard shortcut keys. Note Occasionally, there may be instances where keyboard shortcuts in the Flow Editor coincide with those of the browser. If this occurs, it is advisable to avoid using the shortcuts and instead follow the regular methods to access the editor. - Execution History: View successful and failed flow service executions, operations, and business data logs. - Version History: View the version commit history of the flow service.
	An account is linked and configured. Note: For a migrated or imported flow service, 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 flow service if a flow service references any other flow service.
	Indicates count of only the immediate child steps.

Input and Output Fields Declaration

The Define I/O feature allows you to define the input and output fields for a flow service. You can define the input and output fields from the Define input and output fields screen. You can access the screen by clicking the Define I/O icon () from the flow services action bar.

The Define input and output fields screen has two tabs:

• Input Fields - Allows you to define the fields that the flow service requires as input.

• Output Fields - Allows you to define the fields that the flow service returns to the client or calling program.

You can declare the fields of a flow service in one of the following ways:

• Add a new set - Specify the input and output fields manually. For more information, see Declaring Fields Manually.

• Document Reference - Specify the input and output fields through a document type. When you assign a document type, you cannot add, modify, or delete the fields. For more information, see Declaring Fields using Document Reference.

  Note

  The declared input and output fields are automatically displayed in the Pipeline Input and Pipeline Output columns of the Pipeline panel. The field names are case sensitive. For more information about the data types supported for the input and output fields, see Default Pipeline Mapping Rules and Behavior.

Guidelines for Defining Input and Output Fields

Although declaring input and output fields for a flow service is optional, it is strongly recommended that you make it a practice to declare the fields for every flow service that you create due to the following reasons:

• Declaring fields makes the flow service’s input and output fields available in the pipeline.

• Declaring fields allows you to:

  • link data to and (or) from the flow service.

  • assign default input values to the flow service.

  • run the flow service and enter initial input values.

• Declaring fields makes the input and output requirements of your flow service known to other developers might want to call your flow service from their programs.

Input Fields

• Specify all inputs that a calling program must supply to this flow service. For example, if a flow service invokes two other flow services, one that takes a field called AcctNum and another that takes OrderNum, you must define both AcctNum and OrderNum as input fields for the flow service.

  Note

  The purpose of declaring input fields is to define the inputs that a calling program or client must provide when it invokes this flow service. You do not need to declare inputs that are obtained from within the flow service itself. For example, if the input for one flow service is derived from the output of another flow service, you do not need to declare that field as an input field.

• When possible, use field names that match the names used by the flow services. Fields with the same name are automatically linked to one another in the pipeline. If you use the same field names used by flow service’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 flow services, you must manually link them to one another.

• Avoid using multiple inputs that have the same name. Although the application permits you to define multiple input fields with the same name, during execution, one field might overwrite the other. The fields are not processed correctly within the flow services or by other flow services that invoke this flow service.

• Ensure that the fields match the data types of the fields they represent in the flow service. For example, if a flow service expects an integer called AcctNo, define that input field as an integer.

Output Fields

• Specify all output fields that you want this flow service to return to the calling program or client.

• Specify all output fields that you want this flow service to return to the calling program or client.

• Ensure that the names of output fields match the names used by the flow services that produce them. Like input fields, if you do not specify names that match the ones produced by the flow service’s constituent services, you must manually link them to one another.

• Avoid using multiple outputs that have the same name. Although the application interface permits you to define multiple output fields with the same name, the fields may not be processed correctly within the flow service or by other flow services that invoke this flow service.

• Ensure that the fields match the data types of the fields they represent in the flow service. For example, if a flow service produces a string called AuthorizationCode, ensure that you define that variable as a string.

Declaring Fields Manually

You can declare fields manually in one of the following ways: - Using Add a new set

• Loading through XML or JSON

Using Add a new set

Here, the instructions are explained for input fields. You can follow the same instructions to add output fields from the Output Fields tab.

1. Go to the Define input and output fields screen.

2. Select Add a new set in the Input Fields tab.

3. Click Add in the Data Fields section. The fields are listed under Data fields.

4. Enter the details as per your requirements.

5. Click Done. The input fields are declared.

   Note

   • When you select the Type as String in the Display Type field, select:

     • Text Field if you want the input entered in a text field.

     • 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 IBM webMethods Integration prompts for input at run time.

     • In the Content Type field, you can define constraints for the field such as, minimum value of a field or maximum length of a string. For example,

       

     • Password if you want the input entered as a password.

     • 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 IBM webMethods Integration prompts for input at run time.

     • In the Content Type field, you can define constraints for the field such as, minimum value of a field or maximum length of a string. For example,

     • Avoid using characters like ‘/’, ‘&‘, and ‘$rootArray’ in field names, as they will cause errors. Use field names that consist only of alphanumeric characters and underscores.

Loading through XML or JSON

Here, the instructions are explained for input fields. You can follow the same instructions to add output fields from the Output Fields tab.

1. Go to the Define input and output fields screen.

2. Select Add a new set in the Input Fields tab.

3. Perform one of the following actions:

   • Load XML - Click Load XML in the Data Fields section to define the content in XML. The Type or paste XML content text box appears.

   • Load JSON - Click Load JSON in the Data Fields section to define content in JSON. The Type or paste JSON content text box appears.

4. Type the details as per your requirements. Alternatively, you can paste the details from an XML or JSON file.

5. Perform one of the following actions:

   • Load XML - Click Load XML if you have defined the fields in the XML format.

   • Load JSON - Click Load JSON if you have defined the fields in the JSON format.

   The input fields are defined.

Declaring Fields using Document Reference

You can use a document type to define the input or output fields for a flow service. For example, if there are multiple flow services with identical input fields but different output fields, you can use a document type to define the input fields rather than manually specifying individual input fields for each flow service. 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 Document Type from the Document reference drop-down list. A Document Type can be created using the Document Types option under Project > Configurations > Flow service.

You can create pipeline fields as document references, create document types comprising of document references, and also define the signature of flow services comprising of document references.|

1. Go to the Define input and output fields screen.

2. Select Document Reference in the Input Fields tab. The Choose Document Reference drop-down list appears listing all documents available in the project.

3. Select the document from the Choose Document Reference drop-down list.

4. Click Done. The input fields are declared.

Input and Output Field Validations

The Input and Output Field Validations feature enables you to validate the input and output fields during runtime. While declaring the input and output fields you can provide constraints such as, minimum value a field can accept, maximum length of a string, and so on. During runtime, IBM webMethods Integration validates the values and if the constraints are not satisfied, then the flow service execution fails.

You can enable this feature using the options Validate input and Validate output in the Input Fields and Output Fields tabs of the Define input and output fields screen.

Value Set

When running a service using IBM webMethods Integration, you frequently need to submit input values. A value set allows you to save these input values. If you need to execute the same flow service again in the future with the same input values, you can use the previously saved value set instead of manually inputting the input values.

Example

In this example, you will learn about defining a value set for a service. Assume, you use a *Slacktest service, to create an integration that posts a user defined message on a specific slack channel.

Let us see how to provide input values to a flow service. We will create a flow service slacktest that posts a user defined message on a specific Slack channel.

Basic Flow

1.Create the flow service.

2.Click the Define IO () icon and define the input fields channel and message.

3.Click the mapping icon () and define the pipeline mapping as shown in the following illustration.

4.Click the Run icon (). The Input values dialog box appears.

5.Specify the input values as general and Hello Team !!! and save the value set as slack_valueset_1.

You can run the flow service without saving the value set too.

5.Specify the input values as general and Hello Team !!! and save the value set as slack_valueset_1.

You can run the flow service 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 flow service 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.

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

Upload Input Values

The Upload Input Values feature allows you to upload a JSON file containing a value set that needs to be provided as input to a service.

When uploading a JSON file, if there is a value set with the same name, the following warning appears:

• To overwrite an existing value set, select Overwrite values in {valueSetName}

• To rename the existing value set, select Rename to save as new value set.

Download Input Values

The Download input values feature allows you to download the input values used in a service as a JSON file. When you click Download input values, the input values are downloaded as a JSON file in the {flowServiceName}-{valueSetName}.json format and saved in the default download folder on your local system.

This downloaded file can be exported or used later based on your requirements.

Pipeline Mapping

The Pipeline feature offers a graphical representation view for all of your data and allows you to map the data between flow service’s user input, and connectors or services. Pipeline is the general term used to refer the data structure in which the input and output values are maintained for each step of a flow service. The pipeline starts with the user defined input to the flow service and collects inputs and outputs from every step to the next step in the flow service. When the flow service executes, pipeline has access to data until the previous step’s output.

Pipeline Panel

The Pipeline panel enables you to map the input and output fields. You can access the Pipeline panel by clicking the mapping icon () on the flow services step. The Pipeline panel appears only when you select any operation of the connector or service and an account must be configured in case of connector. The flow service generates the fields based on the operation and the service or connector selected. You can define the input or output fields in the Define IO section and map them to the service or connector fields.

The Pipeline panel has the following columns:

• Pipeline Input - Displays the results from the previous step. For the first step, the input fields defined in the Define IO section are listed. The fields listed in the Pipeline Input column are sent as inputs to the Service Input fields.

• Service Input - Displays input fields of the service or connector selected in the step.

• Service Output - Displays output fields of the service or connector selected in the step.

• Pipeline Output - Displays the results produced for the step. These results are sent as inputs to the next step’s Pipeline Input . The last step results indicate the output of the pipeline.

You can map the fields in the following order:

1. Pipeline Input fields to Service Input fields

2. Service Output fields to Pipeline Output fields

   Note

   For easy identification purpose, services are indicated with fn text in the column header and the connector icon is displayed for connectors.

Pipeline Taskbar

You can perform the following actions while mapping the input and output fields in a flow service. The Taskbar is available at the top right-corner of the Pipeline panel.

Name and Icon	Description
Recommended Mappings ( )	Recommends mappings based on the pattern of previous mappings. The recommended mappings are represented with dotted lines. For more information, see Smart Mapping.
Show only Mapped ()	Displays only the mapped fields.
Copy ()	Copies a field from the Pipeline Input and Pipeline Output sections. This icon is enabled only when a field is selected. For more information, see Copy and Paste Fields.
Clear ()	Clears all mappings and values set for fields in the pipeline. This icon is enabled always. For more information, see Clear Values.
Delete ()	Deletes the selected mapping. You can also delete the values set for input and output fields, delete the map between fields, and delete the drop value. This icon is enabled if a particular mapping is selected by clicking on the mapping line. For more information, see Delete Mappings.
Move ()	Moves the selected field to either left, right, up, or down in the pipeline. The left and right icons are enabled only when the selected field has a possibility to move to the immediate parental hierarchy (if any). The up and down icons are enabled only when the selected field has a possibility to move one level up or down its sibling field.
Map ()	Connects service and pipeline fields in the pipeline with a line called a map (link). For more information, see Map Pipeline Fields.
Set Value ()	Sets the values for input and output fields. For more information, see Set Values.
Drop ()	Drops a field from the Pipeline Input or Pipeline Output sections. For more information, see Drop Fields.
Map by Condition ()	Sets a condition on a pipeline map. Only when the condition is satisfied the target field is assigned a value. For more information, see May by Condition.
Expand ()	Expands the Pipeline panel. For more information, see Expand Mapping Panel.
Toggle Pipeline Panel ()	Allows you to efficiently manage and inspect pipeline data. Provides a flexible way to control screen space.
Close ()	Closes the mapping panel and returns to the flow service. This icon is always enabled. Whatever the state of mappings or data manipulations done till that point are saved.
Paste ()	Pastes the field in the pipeline after a copy field action. For more information, see Copy and Paste Fields.
Add ()	Adds a field to the pipeline. You can add fields that were not declared as input or output fields (through Define IO) of the flow service. For more information, see Add Fields.

Set Values

The Set Values feature allows you to set values for the fields by clicking on the field in the Pipeline panel.

The behavior of the Set Value feature is as follows:

• For String type fields

  • Accepts any non null value such as alphabets, numbers, and symbols.

  • Sets the field with an empty (blank) value if you open the Set Value screen and do not specify any value.

• For PickList

  • PickList is a drop-down list where you can choose one of the values from a predefined list. Based on the operation selected, you can either provide custom values or select a value from the predefined list. This operation is decided by the Service for the respective fields.
    

  When User is Allowed to Enter Custom Values	On Default Set Value	On Clear All
  True	“(empty)	“
  False	options[0]	options[0]

  Note

  When running a set value operation on the root document node, if the document node contains more than 60 child nodes, the set value operation may experience slight performance issues.

For example, let us see the Adding Integers (AddInts) functionality using the Math service.

1. Create a flow service. For example, AddingIntegers. A flow service step is created initially without any data.

2. Select the AddInts operation in the flow service step.

   

3. Click on the flow service step. The Pipeline panel appears. Two service input fields num1 and num2 are listed in the Service Input column.

   

4. Click any of the fields, for example, num1. The Set Value dialog box appears.

   

5. Enter the value in the num1 field.

   Note

   When you paste data equal to or exceeding 0.5 MB in the text box, the system disables editing due to performance limitations. However, you can still use the respective buttons to copy and paste the data and perform editing in an external tool.

6. Click Save. The value is set and the corresponding field is represented with the SetValue icon. If you export this step, the set value of this field is exported.

   

7. Repeat the above steps to set values for the required fields.

Pipeline Variable Substitution

The Perform pipeline variable substitution check box indicates whether you want the application to perform pipeline variable substitution at runtime. If selected, the application replaces the pipeline variable with the runtime value of the variable while running the flow service.

The Perform pipeline variable substitution check box indicates whether you want the application to perform pipeline variable substitution at runtime. If selected, the application replaces the pipeline variable with the runtime value of the variable while running the flow service.

Clear Values

The Clear Values feature allows you to reset the field values. If the field is a document or document reference type, Clear All resets the nested fields as well. The default values of different types on Set Value (without giving any input, just opening the Set Value screen and save) and Clear All are as follows:

Map Pipeline Fields

The Map Pipeline Fields feature allows you to connect service and pipeline fields in the pipeline with a line called a map (link). You can select two input fields and click the Map icon to create a map between them. Creating a map between fields copies the value from one field to another at run time. There are two types of mapping:

• Implicit Mapping

• Explicit Mapping

  Note

  When migrating integrations from Flow Editor to flow services, the existing mappings with references to fields whose definition has changed become invalid. For example, if a mapping references a field test which was originally an integer, but later became a float, then the existing mapping to the field test as integer is invalid. Following migration, you are prompted to remove these invalid references. You have to either remove those references or reassign correctly in order to proceed.

Implicit Mapping

Within a flow service, IBM webMethods Integration implicitly maps fields whose names are the same and whose data types are compatible. flow service connects implicitly mapped fields with a dotted line.

Explicit Mapping

You can map input fields from the Pipeline Input column to Service In fields, and also can map the output from the Service Out to a different field in the Pipeline Out column. Explicit Mapping can be achieved in the following ways:

• Drag and Drop - Drag the mouse pointer from the source field and drop on the target field.

  

  Note

  In order to map fields, you must drag the mouse pointer from the source field on to the text of the target field. Otherwise, the mapping does not happen.

• Map Icon - Select a source field and target field by clicking on it and then click in the toolbar. The fields are mapped.

  

Delete Mappings

The Delete Mappings feature allows you to remove mappings . You can delete each map individually or all mappings at a time.

• Remove each mapping - You can do this in one of the following ways:

  • Using Toolbar - Select a map by hovering on the map line (arrow) and click in the toolbar.
    

  

  • Keyboard - Select a map by hovering on the map line (arrow) and press the Delete key.
    
    

• Removing all Mappings - Click the icon in the toolbar to delete all maps at a time.

Search Fields

The Search feature allows you to search fields. When you type field names in the Search text box, IBM webMethods Integration performs a dynamic search across all fields (including nested fields), and displays the resultant fields in the respective panels. Additionally, each column has its own search bar that allows you to search in the respective column.

Expand Mapping Panel

The Expand feature allows you to resize the Pipeline panel. On clicking the Expand icon, the Pipeline panel size increases and you can resize the column widths as per your requirements to view the mappings clearly.

When any parent node is in expanded mode, then the button name is changed to Collapse All until all nodes are in collapsed state

Copy and Paste Fields

The Copy and Paste feature allows you to copy any field and paste in the pipeline. 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 dialog box, the field path is pasted. Alternatively, you can use keyboard shortcuts Ctrl+C to copy and Ctrl+V to paste fields. You can perform the copy and paste actions in the following ways:

• Copy fields within the Pipeline panel

• Copy and paste fields between the Define IO screen and Pipeline panel

• Copy across flow services

Drop Fields

The Drop feature allows you to remove fields from a pipeline that are no longer used by the subsequent steps. You can drop fields from only the Pipeline Input and Pipeline Out columns.

By dropping the unwanted fields you can reduce the size of the pipeline at run time. Also, the length and complexity of the Pipeline Input and Pipeline Out columns is reduced, thus making the pipeline panel much easier to use when you are working with a complex flow service. If any output field is dropped, then that particular field is not sent as Pipeline Input to the next step. This way you can restrict the flow of fields from one step to another.

For easy identification purpose, the Drop icon appears after a field is dropped. For example, .

You cannot drop a field in the following scenarios:

• If the field has a value set.

• If the field belongs to another flow service that is a parent of the existing flow service.

Add Fields

The Add Fields feature allows you to add fields to a pipeline.

Map by Condition

The Map by Condition feature allows you to define conditions for the maps (links) drawn between fields in a pipeline. A condition consists of one or more expressions that allows you to:

• check for the existence of a field in the pipeline

• check for the value of a field

• compare a field to another field

For example, map the fields BuyersTotal and OrderTotal only if BuyersTotal has a value, that is, Not Null.

During runtime, the application runs all conditional mappings and assigns a value to the target field only when the condition is true. Otherwise, the application ignores the mapping. In scenarios where the fields are mandatary and the conditions are not satisfied, you might observe flow service runtime failure issues.

You can map multiple source fields to the same target field if the mappings to the target have conditions. In some scenarios, where you have mapped multiple source fields to a single target field, at most, only one of the conditions you define can be true at run time. If more than one condition to the same target field evaluates to true, then the result is not definite because the order in which the conditions are run is not guaranteed.

You can define conditions for a map using the Condition Editor screen. The Condition Editor screen can be accessed by selecting the map and clicking the Map by Condition () icon on the Pipeline panel or by double-clicking the map.

The Condition Editor screen functionality is similar to that of the Expression Editor screen. For more information about the Condition Editor screen description, see Expression Editor.

Points to Consider when Defining Conditions for Maps

• Conditions cannot be defined for the implicitly mapped fields.

• Conditions assigned to each map must be mutually exclusive when mapping multiple source fields to one target field.

The condition expression given for the map behaves similar to the flow service containing a Branch condition. For more information on Branch steps, see Branch.

Adding Conditions to a Map

Example

Assume that there is a flow service CentimetertoMeterConversion that converts the values provided by you from centimeters to meters. If the meter value is zero, then a custom message is logged. The flow service includes the following:

• Service: Math multiplyFloats

• Service Input - num1 and num2

  • num1 takes the input values provided by you. num2 is a constant conversion unit, 0.01
    

• Service Output - value

• Pipeline Input - centimeters, minValue, maxValue, default

• Pipeline Output - meters

• Conditional Step: If meters value is equal to zero, then display a custom message

Let us modify the logic of the flow service such that it converts only specific values instead of all values based on the following conditions:

• num1 = minValue > 1 and maxValue < 9999

• default = minValue < 1

Before you Begin

• Log in to your tenant.

• Ensure that you have created the flow service as described in the example.

Basic Flow

1. Go to the CentimetertoMeterConversion flow service.

2. Select the centimeters to num1 map and click from the pipeline tool bar. The Condition Editor screen appears.

   

   By default, the first field is selected and displayed in the editor.

3. Ensure that the Enable Condition during execution check box is selected. Otherwise, the condition is not considered during runtime.

4. Define the conditions. For more information on how to define conditions and sub conditions, see Creating Complex Expressions.

   As per the example, the condition minValue > 1 and maxValue < 9999 is defined for the selected mapping as shown in the following iluustration:

   

5. Click Save. The condition is added to the map and the icon is added to indicate that the map has a condition defined.

   

6. Map the default pipeline Input field to num1.

7. Define condition for the Default pipeline Input field.

   

   Note

   To remove a condition from a map:
   1. Select the map and click the Map By Condition icon. The Condition Editor appears.
   2. Click Remove Condition.

8. Click Run. The results are displayed based on the values you provide.

   

Default Pipeline Mapping Rules and Behavior

Before you start mapping fields, it is recommended to go through the mapping guidelines to avoid runtime issues due to incorrect mappings.

• If a field has a Set Value, you cannot either map or drop fields and vice-versa.

• If a field is defined in pipeline and if the field is not mapped or a value is not set, then the field is not available in subsequent steps.

• Set Value cannot be configured in the Pipeline Input and Service Output columns.

• If a parent is mapped, child field of that parent cannot be mapped.

• If a child field is mapped, parent of that child field cannot be mapped.

• Target field can be mapped only once, except in case of array indices and map by condition.

• Fields with different Object constraints cannot be mapped. If you map fields with different Object constraints and the Validate Input or Validate Outputoptions are selected, the runtime result is undetermined.

• Data type mappings that are allowed between pipeline fields is as follows:

  • Character Data Type

    
    

    Source Field	Target Field	Behavior
    Char	Boolean, Char, Double, Object, Float, Integer, Long, Short, Date, Byte Array (b[]),Big Integer, Big Decimal	Mapping occurs. Target field data type is typecasted to Character. For example, if there is a mapping between Character A and Integer X, then Integer X is typecasted as Character and the value of A is mapped to X.
    Char	String	Mapping does not occur at run time.
    Char	Char[], Object[]	Mapping occurs. Target field is type casted to Character data type and by default zeroth index (Index[0]) is mapped with Character value.
    Char	Boolean[], Char[], Date[], Double[], Float[], Integer[], Long[], Short[], BigInteger[], BigDecimal[],String[], String[][]	Mapping does not occur at run time.
    Char	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at run time.
    Char[]	Boolean, Char, Double, Object, Float, Integer, Long, Short, Date, Byte Array (b[]),Big Integer, Big Decimal	Target field data type is typecasted to Character. For example, if there is a mapping between Character A and Integer X, then Integer X is typecasted as Character and the value of A is mapped to X.
    Char[]	Char[], Object[],Short[], Long[], Integer[], Float[], Double[], Boolean[], BigDecimal[], BigInteger[]	Mapping Occurs. For more information, see Default Pipeline Rules for Mapping Array Fields.
    Char[]	String	Mapping does not occur at run time.
    Char[]	String[], String[][]	Mapping does not occur at run time.
    Char[]	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at run time.

  • Date Data Type

    Source Field	Target Field	Behavior
    Date	Boolean, Char, Double, Object, Float, Integer, Long, Short, Date, Byte Array (b[]),Big Integer, Big Decimal	Mapping occurs. Target field data type is typecasted to Date. For example, if there is a mapping between Date A and Integer X, then Integer X is typecasted as Date and the value of A is mapped to X.
    Date	String	Mapping does not occur at run time.
    Date	Date[], Object[]	Mapping occurs. Target field is type casted to Date data type and by default zeroth index (Index[0]) is mapped with Date value.
    Date	Boolean[], Char[],Double[],Float[],Integer[],Long[],Short[],BigInteger[], BigDecimal[],String[], String[][]	Mapping does not occur at run time.
    Date	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at run time.
    Date[]	Boolean, Char, Double, Object, Float, Integer, Long, Short, Date, Byte Array (b[]),Big Integer, Big Decimal	Mapping occurs. Target field data type is typecasted to Date.For example, if there is a mapping between Date A and Integer X, then Integer X is typecasted as Date and the value of A is mapped to X.
    Date[]	Boolean[], Char[], Double[], Object[],Float[],Integer[],Long[],Short[], BigInteger[],BigDecimal[]	Mapping Occurs. For more information, see Default Pipeline Rules for Mapping Array Fields.
    Date[]	String	Mapping does not occur at run time.
    Date[]	String[], String[][]	Mapping does not occur at run time.
    Date[]	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at run time.

  • String Data Type

    Source Field	Target Field	Behavior
    String	String, Short, Long, Integer, Float, Double, Boolean, Byte Array (b[]), Big Decimal, Big Integer, Object, Char, Date	Mapping occurs. Target field data type is typecasted to String. For example, if there is a mapping between String ABC and Integer X, then Integer X is typecasted as String and the value of ABC is mapped to X.
    String	String[], Object[]	Mapping occurs. Target field is type casted to String data type and by default zeroth index (Index[0]) is mapped with String value./td>
    String	Short[], Long[],  Integer[], Float[], Double[], Boolean[], BigDecimal[], BigInteger[], Char[], Date[]	Mapping does not occur at run time.
    String	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at run time.
    String	String[], Object[], StringTable[][]	Mapping occurs. Target field is type casted to string data type and by default zeroth index (Index[0]) is mapped with the string value.
    String[]	Short[], Long[], Integer[], Float[], Double[], Boolean[], BigDecimal[], BigInteger[], Char[],Date[]	Mapping does not occur at run time.
    String	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at run time.

  • Float Data Type

    Source Field	Target Field	Behavior
    Float	String	Mapping does not occur at runtime.
    Float	Short, Long, Integer, Float, Double, Boolean, ByteArray (b[]), BigDecimal, BigInteger, Object, Cahr, Date	Mapping occurs.  Target field data type is typecasted to Float. For example, if there is a mapping between Float F = 55.25 and Integer X, then Integer X is typecasted as Float and the value of 55.25 is mapped to X.
    Float	Float[], Object[]	Mapping Occurs.  Target field data type is typecasted to source field data type and by default the zeroth index (Index[0]) is mapped with the Float value.
    Float	String[], Short[], Long[],  Integer[], Double[], Boolean[], BigDecimal[], BigInteger[],Char[],Date[],StringTable[][]	Mapping does not occur at runtime.
    Float	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at runtime.
    Float[]	Float[], Object[], Short[], Long[],  Integer[], Double[], Boolean[], BigDecimal[], BigInteger[], Char[],Date[]	Mapping Occurs. For more information, see Default Pipeline Rules for Mapping Array Fields.
    Float[]	String[\, String[][]	Mapping does not occur at runtime.
    Float[]	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at run time.

  • Integer Data Type

    Source Field	Target Field	Behavior
    Integer	String	Mapping does not occur at runtime.
    Integer	Short, Long, Integer, Float, Double, Boolean, ByteArray (b[]), BigDecimal, BigInteger, Object, Char, Date	Mapping occurs.  Target field data type is typecasted to Integer. For example, if there is a mapping between Integer I = 55 and Float  F, then Float F is typecasted as Integer and the value of 55 is mapped to X.
    Integer	Integer[], Object[]	Mapping Occurs.  Target field data type is typecasted to Integer and by default the zeroth index (Index[0]) is mapped with the Integer value.
    Integer	String [], Short [], Long [], Float[], Double [], Boolean [], BigDecimal[], BigInteger[],Char[],Date[], String[][]	Mapping does not occur at runtime.
    Integer	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at runtime.
    Integer[]	Integer[], Object[], Short[], Long[], Float[], Double[], Boolean[], BigDecimal[], BigInteger[], Char[],Date[]	Mapping Occurs. For more information, see Default Pipeline Rules for Mapping Array Fields.
    Integer[]	String[], String[][]	Mapping does not occur at runtime.
    Integer[]	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at run time.

  • Short Data Type

    Source Field	Target Field	Behavior
    Short	String	Mapping does not occur at runtime.
    Short	Short, Long, Integer, Float, Double, Boolean, Byte Array (b[]), Big Decimal, Big Integer, Object, Char, Date	Mapping occurs. Target field data type is typecasted to Short. For example, if there is a mapping between Short 325 and Integer X, then Integer X is typecasted as Short and the value of 325 is mapped to X.
    Short	Short [], Object []	Mapping Occurs. Target field data type is typecasted to Short and by default the zeroth index (Index[0]) is mapped with the Short value.
    Short	String[], Long[],  Integer[], Float[], Double[], Boolean[], BigDecimal[], BigInteger[], Char[],Date[], StringTable[][]	Mapping does not occur at runtime.
    Short	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at runtime.
    Short[]	Integer[], Object[], Long[],  Integer[], Float[], Double[], Boolean[], BigDecimal[], BigInteger[], Char[],Date[]	Mapping Occurs. For more information, see Default Pipeline Rules for Mapping Array Fields.
    Short[]	String[], StringTable[][]	Mapping does not occur at runtime.
    Short[]	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at run time.

  • Long Data Type

    Source Field	Target Field	Behavior
    Long	String	Mapping does not occur at runtime.
    Long	Short, Long, Integer, Float, Double, Boolean, Byte Array (b[]), Big Decimal, Big Integer, Object, Char, Date	Mapping occurs. Target field data type is typecasted to Long. For example, if there is a mapping between Long L and Integer X, then Integer X is typecasted as long and the value of L is mapped to X.
    Long	Long [], Object []	Mapping Occurs. Target field data type is typecasted to Long and by default the zeroth index (Index[0]) is mapped with the Long value.
    Long	String[], Short[],  Integer[], Float[], Double[], Boolean[], BigDecimal[], BigInteger[], Char[],Date[], StringTable[][]	Mapping does not occur at runtime.
    Long	Document, Document[], Document Reference, DocumentReference[]	Mapping does not occur at runtime.
    Long[]	Long[], Object[],Short [],  Integer [], Float[], Double [], Boolean [], Big Decimal [], Big Integer [], Char[],Date[]	Mapping Occurs. For more information, see Default Pipeline Rules for Mapping Array Fields.
    Long[]	String [], StringTable[][]	Mapping does not occur at runtime.
    Long[]	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at runtime.

  • Double Data Type

    Source Field	Target Field	Behavior
    Double	String	Mapping does not occur at runtime.
    Double	Short, Long, Integer, Float, Double, Boolean, Byte Array (b[]), Big Decimal, Big Integer, Object, Char, Date	Mapping occurs. Target field data type is typecasted to Double. For example, if there is a mapping between Double D1 = 4.673854 and Float F, then Float F is typecasted as Double and the value of 4.673854 is mapped to F.
    Double	Double[], Object[]	Mapping Occurs. Target field data type is typecasted to Double and by default the zeroth index (Index[0]) is mapped with the Double value.
    Double	String[], Short[],  Integer[], Float[], Long[], Boolean[], BigDecimal[], BigInteger[], Char[],Date[], StringTable[][]	Mapping does not occur at runtime.
    Double	Document, Document[], Document Reference, DocumentReference[]	Mapping does not occur at runtime.
    Double[]	Double [], Object [], Short [],  Integer [], Float [], Long [], Boolean [], Big Decimal [], Big Integer [], Char[],Date[]	Mapping Occurs. For more information, see Default Pipeline Rules for Mapping Array Fields.
    Double[]	String [], StringTable[][]	Mapping does not occur at runtime.
    Double[]	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at runtime.

  • Boolean Data Type

    Source Field	Target Field	Behavior
    Boolean	String	Mapping does not occur at runtime.
    Boolean	Short, Long, Integer, Float, Double, Boolean, ByteArray (b[]), BigDecimal, BigInteger, Object, Char, Date	Mapping occurs. Target field data type is typecasted to Booelan. For example, if there is a mapping between Boolean B = True and Double D, then Double D is typecasted as Boolean and the value of True is mapped to D.
    Boolean	Boolean [],  Object[]	Mapping Occurs. Target field data type is typecasted to Boolean and by default the zeroth index (Index[0]) is mapped with the Boolean value.
    Boolean	String [], Short [], Long [],  Integer [], Float[], Double [], Big Decimal [], Big Integer [], Char[],Date[], StringTable[][]	Mapping does not occur at runtime.
    Boolean	Document, Document[], Document Reference, DocumentReference[]	Mapping does not occur at runtime.
    Boolean[]	Boolean[],  Object[], Short[], Long[],  Integer[], Float[], Double[], BigDecimal[], BigInteger[], Char[],Date[]	Mapping Occurs. For more information, Default Pipeline Rules for Mapping Array Fields.
    Boolean[]	String [], StringTable[][]	Mapping does not occur at runtime.
    Boolean[]	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at runtime.

  • Big Decimal Data Type

    Source Field	Target Field	Behavior
    BigDecimal	String	Mapping does not occur at runtime.
    BigDecimal	Short, Long, Integer, Float, Double, Boolean, ByteArray (b[]), BigDecimal, BigInteger, Object, Char, Date	Mapping occurs. Target field data type is typecasted to Big Decimal. For example, if there is a mapping between Big Decimal D1 = 4.673854 and Float F, then Float F is typecasted as Big Decimal and the value of 4.673854 is mapped to F.
    BigDecimal	BigDecimal[],  Object[], BigInteger[]	Mapping Occurs. Target field data type is typecasted to Boolean and by default the zeroth index (Index[0]) is mapped with the Boolean value.
    BigDecimal	String[], Short[], Long[],  Integer[], Float[],  Double[], Boolean[],Char[],Date[], StringTable[][]	Mapping does not occur at runtime.
    BigDecimal	Document, Document[], Document Reference, DocumentReference[]	Mapping does not occur at runtime.
    BigDecimal[]	BigDecimal[],  Object[], Short[], Long[], Integer[], Float[],  Double[], Boolean[], BigInteger[], Char[],Date[]	Mapping Occurs. For more information, see Default Pipeline Rules for Mapping Array Fields.
    BigDecimal[]	String [], StringTable[][]	Mapping does not occur at runtime.
    BigDecimal[]	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at runtime.

  • BigInteger Data Type

    Source Field	Target Field	Behavior
    BigInteger	String	Mapping does not occur at runtime.
    BigInteger	Short, Long, Integer, Float, Double, Boolean, ByteArray (b[]), BigDecimal, BigInteger, Object, Char, Date	Mapping occurs. Target field data type is typecasted to Big Integer. For example, if there is a mapping between Big Integer B1 = 4673854 and Float F, then Float F is typecasted as Big Integer  and the value of 4673854 is mapped to F.
    BigInteger	BigInteger[],  Object[], BigDecimal[]	Mapping Occurs. Target field data type is typecasted to Big Integer and by default the zeroth index (Index[0]) is mapped with the Big Integer value.
    BigInteger	String[], Short[], Long[],  Integer[], Float[], Double[], Boolean[], Char[],Date[], StringTable[][]	Mapping does not occur at runtime.
    BigInteger	Document, Document[], Document Reference, DocumentReference[]	Mapping does not occur at runtime.
    BigInteger[]	Big Integer[], Object[],Short[], Long[],  Integer[], Float[], Double[],  BigInteger[], BigDecimal[], Char[],Date[]	Mapping Occurs. For more information, see Default Pipeline Rules for Mapping Array Fields.
    BigInteger[]	String[], StringTable[][]	Mapping does not occur at runtime.
    BigInteger[]	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at runtime.

• String Table[][] Data Type

  Source Field	Target Field	Behavior
  String[][]	String, Boolean, Char, Float, Double, Integer, Long, Short, Date, Byte Array (b[]),Big Integer, Big Decimal	Mapping occurs.
  String[][]	Date[], Object[],Boolean[], Char[],Double[],Float[],Integer[], Long[], Short[], BigInteger[], BigDecimal[],String[], String[][]	Mapping occurs. Target field data type is typecasted to String[] and the first row elements are considered.
  String[][]	Document, Document[], DocumentReference, DocumentReference[]	Mapping does not occur at run time.

Indexed Mapping

The Indexed Mapping feature allows you to map array fields and specify which element in the array you want to map. Few examples are:

• For String Lists and Object Lists, you can specify the index for the list element you want to link. For example, you can map the third element in a String List to a String.

• For Document Lists, you can specify the index for the Document that you want to link. For example, you can map the second Document in a Document List to a Document field.

• For a field in a Document List, you can specify the index of the Document that contains the value that you want to link. For example, if the Document List POItems contains the String ItemNumber, you can link the ItemNumber value from the second POItems Document to a String.

The mapping between array indexes can be performed using the Indexed Mapping dialog box. The Indexed Mapping dialog box automatically appears when you map array fields in the Pipeline panel.

The Indexed Mapping dialog box has the following options:

• Map on array level - Allows you to map arrays without providing indexes. This is the default option.

• Map specific elements in an array - Allows you to map specify the mapping between arrays at an index level. On selecting this option, the indexes are listed for you to specify the mapping. For example, you can link the second element in a String List to a String or link the third Document in a Document List to a Document field. You can map either all indexes or only few of them. If you do not map all indexes, the mapping between the indexed items is only displayed and the mapping for the main array is not shown in the Pipeline panel.

Guidelines for Mapping Array Fields

• To map array elements, you need to know the index for the element’s position in the array. Array index numbering begins at 0 (the first element in the array has an index of 0, the second element has an index of 1, and so on).

• If you map to an array and specify an index that does not exist, IBM webMethods Integration increases the length of the array to include the specified array index. For example, suppose a String List has length 3. You can map to the String List and specify an index of 4; that is, you can map to the fifth position in the String List. At run time, IBM webMethods Integration increases the length of the String List from 3 to 5.

• Each element in an array can be the source or target of a map; that is, each element in the array can be the start or end of a map. For example, if a source String List variable contains three elements, you can map each of the three elements to a target field.

• If the source and target fields are arrays, you can specify an index for each field. For example, you can map the third element in a source String List to the fifth element in the target String List.

• If you do not specify an array index for an element when mapping to or from arrays, the default behavior of the Pipeline panel is used. For information about the default behavior of the Pipeline, see Default Pipeline Rules for Mapping Array Fields.

• At run time, the map (copy) fails if the source array index contains a null value or if you specify an invalid source or target index (such as a letter or non-numeric character). IBM webMethods Integration generates journal log messages (at debug level 6 or higher) when maps to or from array fields fail.

• Mapping Document, Document List, Document Reference, or Document Reference List fields - When working with Document types in the pipeline, you can link a source field to the Document or to the children of the Document field:

  • A Document and its children cannot be targets at the same time. That is, if you have mapped a Document as the target, the Document’s child fields cannot be mapped as target. The same is applicable for Document List.

  • If you have mapped to a child field of a Document, then the child’s parent Document cannot be mapped as target at the same time. The same is applicable for Document List.

  • If you map two Document fields and specify an index that does not exist, IBM webMethods Integration overwrites the structure of the target Document with the structure of the source Document. For example, suppose there are two Document fields D1 and D2 and both have length 3. If you map D1 with D2 and specify an index of 4; that is, map to the fifth position in the D2, then at run time, IBM webMethods Integration increases the length of D2 from 3 to 5.

  • You cannot map a nested Document List to a target Document List when the Document Lists have different sizes. A nested Document List is one that is contained within a parent Document List. Document Lists are considered to have different sizes when they have a different number of entries within the lists. If you need to move values from the source Document List to the target, create a user code that uses a LOOP flow step to assign values from the source to the target one by one.

  • When a Document Reference or Document Reference List refers to an Integration Server (IS) document type that contains identically named fields that are of the same data type and both identically named fields are assigned a value or are linked to another field, the application might not maintain the order of the document contents in the pipeline when the service runs. For example, the application might group all the identical fields at the end of the document. To prevent the change in the order of document contents, set default values for the identically named fields, insert a MAP step in the service before the step in which you want to map or assign a value to the fields. In the MAP step, under Pipeline Out, select the Document Reference field and assign default values to the identically named fields.

Default Pipeline Rules for Mapping Array Fields

When you create maps between scalar and array fields, you can specify which element of the array field you want to map to or from. Scalar fields are those that hold a single value, such as String and Object. Array fields are those that hold multiple values, such as String List and Object List. For example, you can map a String to the second element of a String List.

If you do not specify which element in the array that you want to map to or from, the application uses the default rules in pipeline to determine the value of the target field. The following table lists the default pipeline rules considered for mapping to and from array fields:

Smart Mapping

IBM leverages the collective intelligence of the IBM webMethods 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.

The following information is not indexed:

• Business Data log
• Static values that you set in the pipeline map
• Accounts
• Reference Data
• Pipeline Data
• Certificates
• User Details
• Static values in any application operations

How it works

1. To provide your consent to share the mapping information, from the IBM webMethods 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 flow service 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 are an Administrator of a paid tenant, and have cleared the Publish Integration Mappings to Recommendations Engine option, IBM webMethods 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.

Expression Editor

The Expression Editor is an interface that allows you to define complex expressions (conditions) using the conditional controls such as If, Else If, While, and Do Until. A complex expression is formed by combining simple conditions (rules) with logical operators AND and OR or negating these conditions with logical negation operator NOT.

You can access Expression Editor by clicking the Expression () icon on the Flow service step. The Expression icon appears only when you select a conditional construct control in the Flow service step.

Components of Expression Editor

Expression Editor consists of two sections:

• Expression View

• Expression Builder

Expression View

The Expression View section displays the conditions defined. Additionally, when you hover the mouse pointer on operator of the condition, the condition’s scope is highlighted for easy reference as shown in the following illustration:

Expression Builder

The Expression Builder section allows you to create complex conditions by defining rules. By default, a rule step is displayed to start with the condition definition. A rule step consists of Left Operand, Operator, and Right Operand to define a condition. The operands list the fields available in the Pipeline. You can group multiple rules to define sub conditions.

Expression Builder contains the following controls that aid you in defining the complex conditions:

• Group-level Controls

  • Operator - lists the set of logical operators used to join the rules.
  • Add Group - groups a set of rules to define sub conditions.
  • Add Rule - displays the fields to define a rule.
  • Remove Group - deletes a group (sub condition) from the complex condition.
  • Negate Group - reverses a sub condition’s meaning. This control is a toggle button control. When you negate a group, the Negate Group button is renamed as Remove Negation and allows you to remove the negation for that group.
    

• Rule-level Controls

  • Add Rule () - displays the fields for you to define a rule.
  • Negate Rule () - reverses a rule’s meaning.
  • Delete Rule () - deletes a rule.
    

At any time you can either modify or delete a part or whole of the complex condition using these controls.

When you hover on the operands, the complete path of the operand appears.

Creating Complex Expressions

Example

Let us create a complex expression for checking the vaccination slot availability with the following conditions:

• Location is Washington
• Zipcode is 20010
• Vaccine can be either Pfizer, Moderna, or Sputnik
• Age is less than or equal to 45 and slot is available
• Venue is Howard University Hospital
  

Before you Begin

• Log in to your tenant.
• Ensure that the fields are defined.
  

Basic Flow

1. Go to Flow services.

2. Select the project where you want to create the new flow service. You can also create a new project.

3. Click to create a flow service. The Start Creating the Flow service screen appears.

4. Provide a name for the flow service. For example, GetVaccinationSlotStatus and an optional description for the new flow service.

5. Select a conditional control in the flow service step. For example, If.

6. Click the Expression () icon on the conditional flow service step. The Expression Editor screen appears.

7. Perform the following steps to define a rule:

   1. Select a left operand.

   2. Select an operator.

   3. Select a right operand.

   The rule is defined. As per the example, the rule 1 - Location is Washington is defined as follows:

8. [Optional] Click or Add Rule. A new rule step is added.

9. Repeat the above steps to define more rules as per your requirement.

10. Select the operator (group-level) from the And drop-down list to conjunct the previous and new rules. As per the example, rule 2 - Zipcode is 20010 is defined and both are combined with an And operator as follows:

11. Perform the following steps to define a group:

    1. Click Add Group. A new rule step appears and is grouped under a separate block.

    2. Select the operands and operator to define the rule.

    3. [Optional] Click or Add Rule (group-level). A new rule step is added to the group.

    4. [Optional] Select the operator from the And drop-down list (group-level) to conjunct the previous and new rules in the group.

    5. Repeat the above steps to define all rules in the group. The sub condition is defined.

    As per the example, group 1 - Vaccine can be either Pfizer, Moderna, or Sputnik, group 2 - Age is less than or equal to 45 and slot exists are defined as follows. The groups and other rules are combined with an And operator.

    

12. Define the rule 3 - Venue is Howard University Hospital as per the example. The expression created is as follows:

13. [Optional] Perform the following steps to remove a rule or rule group:

    • Rule - Click adjacent to the rule that must be deleted. The rule is deleted from the complex condition.

    • Rule Group - Click Remove Group in the group that must be deleted. The rule group is deleted from the complex condition.

    Tip

    You can use the keys Ctrl+Z and Ctrl+Y to undo and redo the delete actions.

14. [Optional] Perform the following steps to negate a rule or rule group:

    • Rule - Click adjacent to the rule that must be negated. The rule is deleted from the complex condition.

    • Rule Group - Click Negate Group in the group that must be negated. The rule group is deleted from the complex condition. The button is renamed as Remove Negation and allows you to remove the negation for that group.

15. Click on the Expression Editor screen. The condition is added to the flow service step. You can click the down and up arrows in the flow service step to view and hide the complete expression.

The complex condition is created and you can proceed with the other flow service steps.

Creating Flow services

See the following examples to learn how to create flow services. Click here for information on how to manage roles and project permissions.

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

• Get attendees from Concur and create contacts in Salesforce CRM

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

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

Summary

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

Before you begin

• Log in to your tenant.

• 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 IBM webMethods Integration, create Salesforce CRM and Microsoft Dynamics 365 CRM accounts.

Basic Flow

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

2. Click the Flow services tab and on the Flow services page, click the icon.

   

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

   

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

   

   Tip

   In a flow service step, you can perform search in one of the following ways:
   - Alias-based search: Type a keyword and the matching results are displayed. List of supported keywords for alias-based search are as follows:
   - map: Transform pipeline - iteration/loop: While, Do Until, Repeat, Repeat for Count, Repeat-Input-Output - selection/condition: If, Else, If Else, Else If, Switch, Branch, Case - jump: Break, Exit - exception: Try, Catch, Finally, Try Catch, Try Finally, Try Catch Finally
   - Restricted scope search: Type a keyword followed by a pipe symbol or space or tab to search within a specific scope, for example, to search within flow services, type fs|. List of supported keywords for restricted scope search are as follows:
   - ctrl: Controls - con: Connectors - fs: Flow services - svc: Services

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 flow service and run it by clicking the Run icon.

    

14. View the flow service 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 flow service execution results.

Get attendees from Concur and create contacts in Salesforce CRM

Summary

Get attendees from Concur and create contacts in Salesforce CRM.

Before you begin

• Log in to your tenant.

• 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 IBM webMethods Integration, create Concur (Concur_1) and Salesforce CRM (SalesforceCRM_1) accounts.

Basic Flow

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

2. Click the Flow services tab and on the Flow services page, click the icon.

   

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

   

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 flow service and click Run.

    

14. View the flow service execution results.

    

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

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.

• Check if you have the Developer and Admin roles assigned from the Settings > Roles page.

• Obtain the credentials to log in to Amazon S3 back end account.

• In IBM webMethods 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 flow service. You can also create a new project.

2.Click the Flow services tab and on the Flow services page, click the icon.

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

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 flow service execution results screen.

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

16.Save the Flow service and click Run.

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

Creating Custom Operations in Flow services

IBM webMethods 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 flow service.

Let us see how to create a custom operation while creating a flow service 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 flow service.

2.Click the Flow services tab and on the Flow services page, click the icon.

3.Provide a name SalesforceCreateAccountCustom and description of the new flow service.

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.

Note that for REST-based connectors, after selecting the operation, you can click Headers to add input Headers, if required. IBM webMethods Integration displays the default HTTP transport headers for the operation, along with their default values. At run time, while processing the headers, IBM webMethods 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.

You can also customize the parameters for REST-based connectors after selecting the operation, by clicking the Parameter option. Review the operation parameter details. IBM webMethods 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 Flow service editor, click the icon to define the input and output fields.

10.Create two Input Fields, AccountName and CityName.

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

12.Save the flow service and click Run. Provide the custom field values in the AccountName and CityName fields, for example, Software

As the results show, the Software account is created.

Support for Multipart Request Body

IBM webMethods Integration supports the multipart/form-data media type using which you can embed binary data such as files into the 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.

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. Further, uploading the CRM individual contact data to Salesforce is time consuming, so using the MIME/Multipart attachments capability, you can upload the csv/json file containing multiple contacts data into Salesforce in a single run.

For some connectors and operations, for example, for Salesforce^R Bulk v2 Data Loader, DocuWare, Google Drive, Amazon S3, and FreshService, IBM webMethods Integration supports multipart 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

While adding a custom action, for example, for the Freshservice Create Child Ticket With Attachments operation, you can click Attachments to view the list of all the configured parts to be sent to the service provider. You can send a multipart/form-data payload which contains either a file, or text, or a document type.

The parts to be sent to the service provider appear in the input signature. All options including the Add option to add a custom part are disabled if the resource is not of type multipart/form-data. Currently, multipart/form-data payload is supported only at the request level, that is, only in the input signature.

• Name - Name of the file part as documented in the SaaS provider API documentation.

• Content Type - Content type of the part’s content (if the Type is TEXT), or the file you are uploading (if the Type is FILE) or the serialization type to which the document will be serialized and become the part content (if the Type is DOCUMENT).

• Type - IBM webMethods Integration defines the following three part types:

  • TEXT - Represents a simple text part of a multipart/form-data payload where the content of the part is of type text/plain. You can use this part to send raw text data as the content of a part, in a multipart request. From a file upload perspective, this part is generally used to convey extra information about the upload behavior, like target folder paths/folder names where the file has to be uploaded.
  • DOCUMENT - Some back ends expect application/json or application/xml content in the part body. This represents a part where the content of the part is of type application/json or application/xml.
  • FILE - Represents a binary part of a multipart/form-data payload where the content of the part is binary or the content of the file itself. To upload a file, you will normally use this part. For file upload kind of use cases, this part is the main or mandatory part required by the service provider.
    

• Active/Inactive - Represents whether this part will be included as part of the service signature.

Example to create a ticket with attachments (multipart data) in Freshservice

Before you begin

• Log in to your tenant.
• Check if you have the Developer and Admin roles assigned from the User Management > Roles page.
• Obtain the credentials to log in to the Freshservice back-end account.
• In IBM webMethods Integration, create a File Transfer Protocol (FTP/FTPS) account FTPS_4 and a Freshservice account Freshservice_1.

Basic Flow

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

2. Click the Flow services tab and on the Flow services page, click the icon.

   

3. Provide a name for the flow service, for example, CreateTicketWithAttachment, and an optional description for the new flow service.

4. Upload a file from the FTP server to Freshservice. Select the File Transfer Protocol (FTP/FTPS) connector, the getFile operation, and the FTPS_4 account.

   

5. Let us upload the hello.txt file available on FTP server in Freshservice. Click Set Value for remoteFile and select the same file in the Set Value - remoteFile dialog box. Click Save.

6. 

   

7. Select the Freshservice connector. As you are creating a ticket with an attachment, select the createTIcketWithAttachment operation and the account as Freshservice_1.

   

8. Click the Edit Mapping icon. Under Pipeline Input, map contentStream to value.

   

9. Set the following values on the mapping screen:

   • Set the value for filename as hello.txt.
   • Set the value for email as abc@xxxx.com.
   • Set the value for subject as create ticket.
   • Set the value for description as create ticket with attachment.
   • Set the value for priority as 1.
   • Set the value for status as 2.
   • Set the value for requester_id as 27000450816. This is the agent ID in Freshservice.
   • Set the value for phone as 123456789.
   • Set the value for source as test.

10. Save and run the flow service.

    

11. Go to Freshservice, click Tickets, and check that the ticket is generated.

    

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, IBM webMethods Integration supports multipart request body.

Before you begin

• Log in to your tenant.

• Check if you have the Developer and Admin roles assigned from the User Management > Roles page.

• Obtain the credentials to log in to the Salesforce back end account.

• In IBM webMethods 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 flow service. You can also create a new project.

2.Click the Flow services tab and on the Flow services page, click the icon.

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

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 flow service and run it by clicking the Run icon.

15.View the flow service execution results for a successful run.

Built-in Services

IBM webMethods Integration has an extensive library of services for performing common integration tasks such as transforming data values, performing simple mathematical operations, and so on.

Services are invoked at run time. While creating a flow service, you can sequence services and manage the flow of data among them.

Related services are grouped in categories. 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.

Alert services

Use the Alert services to notify users when predefined conditions, such as password expiry, license key updates, rule violations, or service errors, are met, ensuring timely awareness and response to critical system events.

The following Alert services are available:

emit

Generates an alert when a pre-configured condition is met. For example, User or Master Password Expiry, License Key Update, Enterprise Gateway Rule Violation, Service Error, and so on. This service is invoked by IBM webMethods Integration components to raise alerts.

Input Parameters

channelID: Integer. Identifier of the channel associated with the alert.

severity: String. Severity associated with the alert channel.

subject: String. Subject of the alert message.

contentType: String. Type of information in the alert. For example, text/plain.

content: String. Content of an alert. For example, Alert {0} Message Size Limit filter failed.\nClient IP Address: {1}\n Request URL : {2}\n Date & Time : {3} content

Output Parameters

alertId: Long. A unique identifier assigned to each alert emitted.

channels

Gets all alert channels in the system. Channels help classify alerts and let you subscribe to a specific type of alert.

Input Parameters

None.

Output Parameters

Channels: Document List. The list of alert channels in IBM webMethods Integration. By default, there are 13 channels. All channels have the following keys:

• id: Integer. Identifier of a channel. This is a system assigned value and cannot be modified.

  Note

  Channel IDs for custom channels start with 1001.

• displayName: String. Name of the alert channel.

• description: String. Description for the channel.

• emissionEnabled: Boolean. Indicates whether an alert is generated for the channel and stored in the database or not. A value of:
  

  • true indicates that alerts are emitted for the channel and stored in the database.

  • false indicates that alerts are disabled for the channel.

• systemNotificationEnabled: Boolean. Indicates whether an alert generated for the channel is displayed as a notification or not.
  

  • true indicates that notifications are generated for the channel.

  • false indicates that notifications are disabled for the channel.

Usage Notes

The default channels, events when alerts are raised for a channel, and the corresponding severity are described in the following table:

countAll

Gets the count of all alerts in the system, read and unread, or a subset of alerts that meet the filter criteria.

Input Parameters

• filter: Document. Optional. To get the count of a subset of alerts, specify the criteria using the following keys:
  

  • startTime: Long. Optional. Start of the time interval in which alerts are emitted. Specify the value in UNIX epoch format in milliseconds.

  • endTime: Long. Optional. End of the time interval in which alerts are emitted. Specify the value in UNIX epoch format in milliseconds.

  • severities: String[]. Optional. List of severities.

  • channelIds: Object[]. Optional. List of channel identifiers.

  • user: String. Optional. The IBM webMethods Integration user who triggered the alerts or Administrator for alerts emitted by the server. For example, specify Administrator for Password Management alerts.

  • keyword: String. Optional. A keyword that identifies the alerts.

Output Parameters

• count: Long. The count of all alerts in the system, read and unread, or a subset of alerts, if the filter criteria are passed as inputs.

Usage Notes

To get the count of all alerts in the system, read and unread, do not specify the filter criteria as inputs.

fetchAll

Fetch all alerts in the system, including read and unread, or a subset based on filter criteria.

Input Parameters

• filter: Document. Optional. To fetch a subset of alerts, specify the criteria using the following keys:

  • startTime: Long. Optional. Start of the time interval in which alerts are emitted. Specify the value in UNIX epoch format in milliseconds.

  • endTime: Long. Optional. End of the time interval in which alerts are emitted. Specify the value in UNIX epoch format in milliseconds.

  • severities: String[]. Optional. List of severities.

  • channels: Object[]. Optional. List of channel identifiers.

  • user: String. Optional. The IBM webMethods Integration user who triggered the alerts or Administrator for alerts emitted by the server. For example, specify Administrator for Password Management alerts.

  • keyword: String. Optional. A keyword that identifies the alerts.

• sortOrder: String. Optional. The order in which the fetched alerts are sorted. Select ASC or DESC. The default is DESC.

• sortBy: String. Optional. The criteria to sort the fetched alerts. Select one of the following options:
  

  • channel

  • severity

  • subject

  • timestamp

The default is timestamp.

• pageSize: Integer. The number of notifications on a page.

• pageNumber: Integer. In a paginated list of notifications, the page where IBM webMethods Integration loads the notifications.

  Note

  Page number starts with 0.

Output Parameters

• alerts: Document List. A list of the alerts retrieved by the service. Each alert has the following details:

  • id: Long. Alert identifier.

  • ts: Long. Date and time when the alert is generated, in the UNIX epoch time format.

  • serverId: String. IP address of the host where IBM webMethods Integration is running.

  • memberName: String. Member name of the machine that hosts IBM webMethods Integration in a cluster.

  • user: String. IBM webMethods Integration user who triggered the alert.

  • channelId: Integer. Channel identifier for the alert.

  • channel: String. Channel for the alert.

  • severityId: Integer. Severity identifier of the alert.

  • severity: String. Severity of the alert.

  • subject: String. Subject of the alert message.

  • contentType: String: Text that identifies the type of content in the alert such as text/plain and text/html.

  • content String. Content of the alert.

Usage Notes To fetch all read and unread alerts in the system, do not specify the filter criteria as inputs. The number of notifications on a page is identified by pageSize and the current page is identified by pageNumber.

getSettings

Gets the settings of the system notifier.

Input Parameters
None.

Output Parameters

• enabledEmissionChannels: Object[]. List of channels for which alerts can be generated and stored in the database.

• enabledSystemNotifierChannels: Object[]. List of channels for which alerts are generated and displayed as notifications.

• systemNotifierSeverityCutoff: String. Notifications are generated only for alerts with severity equal to, or more than this value.

• retentionPeriodInDays: Integer. Determines how long the alerts are stored in the database.

• certificateExpiryWarningInDays: Integer. Number of days before the certificate expiry date, when the alert should be generated.

setSettings

Updates the settings of the system notifier.

Input Parameters

• enabledEmissionChannels: Object[]. List of channels for which alerts can be generated and stored in the database.

• enabledSystemNotifierChannels: Object[]. List of channels for which alerts are generated and displayed as notifications.

• systemNotifierSeverityCutoff: String. Notifications are generated only for alerts with severity equal to, or more than this value.

• retentionPeriodInDays: Integer. Determines how long the alerts are stored in the database.

• certificateExpiryWarningInDays: Integer. Number of days before the certificate expiry date when the alert should be generated.

Output Parameters

message: String. Indicates whether the system notifier settings are updated or not.

Usage Notes

Based on the value of the retentionPeriodInDays parameter, a purge job clears the alerts stored in the database.

deregisterChannel

Deregisters a registered custom channel.

Input Parameters

channelId Integer: Identifier of the channel that you want to deregister.

Output Parameters

• deregistered: Boolean. Indicates whether the channel is deregistered or not. A value of:
  

  • true indicates that the channel is deregistered.

  • false indicates that the channel is not deregistered.

Usage Notes

Channel IDs for custom channels are generated by the system and cannot be modified. The first custom channel gets 1001 as the channel ID and subsequent custom channels have consecutive numbers. Once a custom channel is deregistered, the channel ID is no longer available for a new custom channel until IBM webMethods Integration is restarted.

Deregistering a channel also deletes all the alerts for that channel.

getChannel

Gets the details of a specific channel.

Input Parameters

channelId Integer: Identifier of the channel that you want to retrieve.

Output Parameters

• displayName String. Name of the channel.

• description String. Description for the channel.

• emissionEnabled: Boolean. Indicates whether an alert is generated for the channel and stored in the database or not. A value of:
  

  • true indicates that alerts are emitted for the channel and stored in the database.

  • false indicates that alerts are disabled for the channel.

• systemNotificationEnabled: Boolean. Indicates whether an alert generated for the channel is displayed as a notification or not.

  • true indicates that notifications are generated for the channel.

  • false indicates that notifications are disabled for the channel.

registerChannel

Registers a custom channel.

Input Parameters

• displayName: String. Name of the channel that you want to register.

• description: String. Optional. Description of the channel.

• emissionEnabled: Boolean. Optional. Indicates whether an alert is generated for the channel and stored in the database or not. Set to:
  

  • true to emit alerts for the channel and store them in the database.

  • false to disable alerts for the channel.

The default value is true for custom channels as well as system channels other than Service Error and Server Error.

• systemNotificationEnabled: Boolean. Optional. Indicates whether the alert generated for the channel is displayed as a notification or not. Set to:
  

  • true to generate notifications for the channel.

  • false to disable notifications for the channel.

The default value is true for custom channels as well as system channels other than Service Error and Server Error.

Output Parameters

• channelId: Integer. Identifier of the registered channel.
  Note

  Channel IDs for custom channels start with 1001.

Usage Notes
For custom channels, channel IDs are generated by the system and cannot be modified. The first custom channel gets 1001 as the channel ID and subsequent custom channels have consecutive numbers. Once a custom channel is deregistered, the channel ID is no longer available for a new custom channel until IBM webMethods Integration is restarted.

updateChannel

Updates the settings of a channel.

• channelId: Integer. Identifier of the alert channel that you want to update.

  Note

  Channel IDs for custom channels start with 1001.

• description: String. Optional. Description of the channel.

• emissionEnabled: Boolean. Optional. Indicates whether an alert is generated for the channel and stored in the database or not. Set to:
  

  • true to emit alerts for the channel and store them in the database.

  • false to disable alerts for the channel.

  The default value is true for custom channels as well as system channels other than Service Error and Server Error.

• systemNotificationEnabled: Boolean. Optional. Indicates whether the alert generated for the channel is displayed as a notification or not. Set to:
  

  • true to generate notifications for the channel.

  • false to disable notifications for the channel.

  The default value is true for custom channels as well as system channels other than Service Error and Server Error.

Output Parameters

message: String. Indicateswhether the channel is successfully updated or not.

Usage Notes

Invoke the alert:updateChannel service to ignore a notification of a specific type or restore an ignored notification from IBM webMethods Integration Administrator.

severities

Lists the pre-defined severities that you can associate with an alert channel. The severity associated with an alert lets you assess the relative impact of a business event on the system.

Input Parameters None.

Output Parameters

• Severities: Document List. The list of default severities available in the system. By default, 4 severities are configured.

  • id: Integer. Identifier for a severity. The default severities and their IDs are as follows:
    

     0: Critical, 1: Error, 2: Warning, 3: Information

  • displayName: String. The severity name.

B2B Utils services

generateResponse

Generates a response for the processing rule Call an integration action.

Input Parameters

• inputContent: Object. Content data sent as part of integration response after encoding.

• readContentAs: String. Data type in which inputContent field value is passed.

  • bytes.inputContent is read as bytes.
  • string. inputContent is read as a string.

• contentType: String. Content-Type passed corresponds to inputContent field. For example, application/EDI, application/x12, text/plain and so on.

• attachments: Document List. (optional) List of attachments sent as part of integration response, if any.

• name: String. Name of the attachment.

• inputContent: Object. Content of the attachment.

• readContentAs: String. Data type in which inputContent field value is passed.

  • bytes. inputContent is read as bytes.
  • string. inputContent is read as String.
    

• contentType: String. Content type of the attachment. For example, application/zip if the attachment is a ZIP file.

• encoding: String. (Optional) Encoding of the attachment. Default value is UTF-8.

• otherHeaders: Document. (Optional) Add key and value strings of the header to the attachment.

  • headers: Document. (optional) Headers sent as part of the integration response, if any.

  • errorCode: String. Value of error code passed as part of integration response.

  • errorMessage: String. Value of error message passed as part of integration response.

  • encoding: String. Type of character set used for encoding inputContent value. This can be any IANA registered character set. Default UTF-8.

Output Parameters

• response: Document. Response is a composite object containing the parameters:

  • content: String. Encoded in Base64. Value is specified in encoding.

  • type: String. Value specified in contentType.

  • encoding: String. Type of encoding used to encode the inputContent. Value is specified in encoding.

  • attachments: Document. List of attachments received from the input parameter * attachments*, if any.

  • headers: Document. Headers received from the input parameter headers.

• error: Document. Error is a composite object containing the fields:

  • code: String. Error code received from the input. Value is specified in errorCode.
  • message: String. Error message associated with the input. Value is specified in errorMessage.

constructSubmitInput

Prepare the necessary input used for submitting the business documents to IBM webMethods B2B product instance.

Input Parameters

• type: String. The input parameter type that is generated for AS2, AS4, RNIF20, RNIF11, or cXML.

• DoctypeName: String. The name of the document type. This is case-sensitive.

  • For AS4 Push, use ebMS 3.0 UserMessage.

  • For AS4 Pull, use ebMS 3.0 PullRequest Signal.

  • For RNIF, it is the xml document type based on the PIP.

  • For cXML, it is the xml document type.

• SenderID: String. Required for AS4, and cXML. Sender Identity value from the partner profile. For example, 123456789.

• SenderIDType: String. Required for AS4, and cXML. Sender Identity type from the partner profile. For example, DUNS, DUNS+4.

• ReceiverID: String. Required for AS4, and cXML. Receiver Identity value from the partner profile. For example, 123456789.

• ReceiverIDType: String. Required for AS4, and cXML. Receiver Identity type from the partner profile. For example, DUNS, DUNS+4.

• ConversationID: String. Required for RNIF when acting as a responder. The set of related messages that create a conversation between two partners.

• preferredOutboundChannelID: String. Overrides the channel to send the document from the receiver’s preferred channel selected in IBM webMethods B2B to a channel ID added in this parameter.

  In an AS4 message, when the value is not specified, the system generates a unique ID. The value maps to Messaging/UserMessage/CollaborationInfo/ConversationId.

• otherParams: Document. (Optional) Other keys that you need to pass as Params in the submit service.

• as2: Document. Required for AS2 type document. Configure the following AS2 parameters:

  • body: Document. (Optional) AS2 body document. For more information to configure inputContent, readContentAs, contentType and encoding see, Input parameters of Submit.

  • attachments []: Document List. (Optional). For more information to configure AS2 attachments (name, inputContent, readContentAs, contentType, encoding and otherHeaders).

  • headers: Document. (Optional) Add key and value strings of the header to the payload.

  • params: Document. A document that provides parameters on how IBM webMethods B2B recognizes and processes a AS2 document.

    • as2SenderID: String. Sends the EDIINT AS2 identity as AS2-From value when using AS2 out channel in IBM webMethods B2B.

    • as2ReceiverID: String. Sends the EDIINT AS2 identity as AS2-To value when using AS2 out channel in IBM webMethods B2B.

• as4: Document. Required for AS4 type document. Configure the following AS4 parameters:

  • body: Document. (Optional) AS4 body document. See Configuring AS4 body.

  • attachments []: Document List. (Optional) AS4 attachments. See Configuring AS4 attachments.

  • params: Document. A document that provides parameters on how IBM webMethods B2B recognizes and processes a AS4 document. See Configuring AS4 params.

• rnif: Document. Required for RNIF type document. Configure the following RNIF parameters:

  • body: Document. RNIF body document. See Configuring RNIF body.

  • attachments []: (Optional) Document List. List of attachments to be used in RNIF message. See Configuring RNIF attachments.

  • params: Document. A document that provides parameters on how IBM webMethods B2B recognizes and processes a RNIF document. Configuring RNIF params.

• cXML: Document. Required for cXML type document. Configure the following cXML parameters:

  • body: Document. cXML body document. For more information on configuring inputContent, readContentAs, contentType and encoding see, Input parameters of Submit.

  • attachments []: Document List. (Optional). For more information on configuring cXML attachments (name, inputContent, readContentAs, contentType, encoding and otherHeaders) see, attachments of Submit.

  • params: Document. A document that provides parameters on how IBM webMethods B2B recognizes and processes a cXML document.

    Configuring cXML params.

    • payloadID: String. A unique number of the document.

    • userAgent: String. Optional. The software or application that processes the cXML data. For example, Ariba Network, Procure Software 3.3.

    • sharedSecret: String. The password the sender shares with the receiver for security or authentication purpose.

    • sync: String. Indicates if the message is synchronous or asynchronous. Valid values are:

      true. Synchronous message (Two-way/Sync for replying). false. Asynchronous message (One-way messages).

    • deploymentMode: String. Optional. Indicates whether the request is a test request or a production request. The valid values are test or production.

    • sender []: Document. Optional. Sender of the cXML document. Sends the sender identity as cXML-From value when using cXML out channel in IBM webMethods B2B. Add the idType and idValue to recognize and verify the identity of the sender who has initiated the HTTP connection for processing the cXML message.

      idType: String. Identity type from the partner profile. For example, DUNS, DUNS+4. idValue: String. Identity value from the partner profile. For example, 123456789.

    • receiver []: Document. Optional. Receiver of the cXML document. Sends the receiver identity as cXML-To value when using cXML out channel in IBM webMethods B2B. Add the idType and idValue to recognize and verify the identity of the receiver of the cXML message.

      idType: String. Identity type from the partner profile. For example, DUNS, DUNS+4. idValue: String. Identity value from the partner profile. For example, 123456789.

Configuring an AS4 body

Document. To configure an AS4 body document. This is optional.

• name: String. (Optional when only body is sent) Name of the payload content.

• xmlInputContent: Object. XML content to submit to the IBM webMethods B2B product instance for processing. This is sent as SOAP BODY.

• readContentAs: String. Data type in which xmlInputContent field value is accepted.

  • bytes. xmlInputContent is read as bytes.
  • string. xmlInputContent is read as string.
  • stream. xmlInputContent is read as stream. IBM recommends you to use readContentAs as stream if the size of the payload is over 5 MB.

• encoding: String. (Optional) Type of character set used for encoding xmlInputContent value. This can be any IANA registered character set. The default value is UTF-8.

• partInfo: Document. (Optional) AS4 payload part information.

  • schemaLocation: String. (Optional) URI of the schema. The value of this parameter maps to the location attribute of the Messaging/UserMessage/PayloadInfo/PartInfo/Schema element.

  • schemaVersion: String. (Optional) Version of the schema. The value of this parameter maps to the version attribute of the Messaging/UserMessage/PayloadInfo/PartInfo/Schema element.

  • schemaNamespace: String. (Optional) Target namespace of the schema. The value of this parameter maps to the namespace attribute of the Messaging/UserMessage/PayloadInfo/PartInfo/Schema element.

  • description: String. (Optional) Description of the content. The value of this parameter maps to the Messaging/UserMessage/PayloadInfo/PartInfo/Description element.

  • properties[]: Document List. (Optional) List of name and value pairs that are sent along with the message. The value of this parameter maps to the Messaging/UserMessage/PayloadInfo/PartInfo/PartProperties element.

    Note

    For the final AS4 payload of MimeType application/octet-stream, then add the property name PayloadMimeType and value as application/octet-stream.

  • name: String. Name of the property. The value of this parameter maps to the name attribute of the Messaging/UserMessage/PayloadInfo/PartInfo/PartProperties/Property element.

  • value: String. Value of the property. The value of this parameter maps to the Messaging/UserMessage/PayloadInfo/PartInfo/PartProperties/Property element.

Configuring AS4 attachments [ ]

Document List. To configure AS4 attachments. This is optional.

• name: String. Name of the attachment content.

• inputContent: Object. Content of the attachment. It is sent as SOAP attachments.

• readContentAs: String. Data type in which inputContent field value is passed.

  • bytes. inputContent is read as bytes.
  • string. inputContent is read as string.
  • stream. inputContent is read as stream. IBM recommends you to use readContentAs as stream if the size of the payload is over 5 MB.

• contentType: String. Content type of the attachment. For example, application/zip if the attachment is .zip file.

• encoding: String. (Optional) Encoding of the attachment. The default value is UTF-8.

• partInfo: Document. (Optional) AS4 attachment part information.

  • schemaLocation: String. (Optional) URI of the schema. The value of this parameter maps to the location attribute of the Messaging/UserMessage/PayloadInfo/PartInfo/Schema element.

  • schemaVersion: String. (Optional) Version of the schema. The value of this parameter maps to the version attribute of the Messaging/UserMessage/PayloadInfo/PartInfo/Schema element.

  • schemaNamespace: String. (Optional) Target namespace of the schema. The value of this parameter maps to the namespace attribute of the Messaging/UserMessage/PayloadInfo/PartInfo/Schema element.

  • description: String. (Optional) Description of the content. The value of this parameter maps to the Messaging/UserMessage/PayloadInfo/PartInfo/Description element.

  • properties[]: Document List. (Optional) List of name value pairs that are sent along with the message. The value of this parameter maps to the Messaging/UserMessage/PayloadInfo/PartInfo/PartProperties element.

    Note

    For the final AS4 payload of MimeType application/octet-stream, then add the property name PayloadMimeType and value as application/octet-stream.

  • name: String. Name of the property. The value of this parameter maps to the name attribute of the Messaging/UserMessage/PayloadInfo/PartInfo/PartProperties/Property element.

  • value: String. Value of the property. The value of this parameter maps to the Messaging/UserMessage/PayloadInfo/PartInfo/PartProperties/Property element.

Configuring AS4 params

Document. A document that provides parameters on how IBM webMethods B2B recognizes and processes a AS4 document. Configure AS4 params.

• messageId: String. (Optional) Unique identifier of the message. When value is not specified, the system generates a unique messageId. When the messageID is generated, the value of this parameter maps to Messaging/UserMessage/MessageInfo/MessageId.

• soapAction: String. (Optional) Value of the action parameter in the MIME type.

• pmodeId: String. (Optional for Push request) TPA agreement ID.

• push: Document. (Required when DoctypeName is ebMS 3.0 UserMessage) AS4 push document.

  • sync: Boolean. (Optional) Synchronous or Asynchronous push request. Default value is false. Valid values are:

    • true. Synchronous push reply (Used in MEP binding Two-Way/Sync for replying).
    • false. Asynchronous push request (Used in MEP bindings for requesting).
      

  • refToMessageId: String. (Required when sync is true). Identifier used in two-way MEPs where the responding MSH user message refers to the initiating MSH user message.

  • toPartyIdRole: String. (Required when pmodeId or agreementRef is not specified) Initiator or responder role of the party in the message exchange.

  • fromPartyIdRole: String. (Required when pmodeId or agreementRef is not specified) Initiator or responder role of the party in the message exchange.

  • agreementRef: String. (Required when pmodeId is not specified) The value to use for the submit request. When pmodeId and agreementRef value is empty, then a tuple of From/ PartyId, From/Role, To/PartyId, To/Role, Service, and Action is used to identify the TPA agreement. For noagreementRef element in the final payload, agreementRef and pmodeId values in the service input and TPA agreement field should be empty.

  • service: String. (Required when PmodeId or agreementRef is not specified) Name of the service use to identify the RequestUM leg used for the current transaction. IBM webMethods B2B uses the service and action parameters to determine which RequestUM leg to use for the current transaction. IBM webMethods B2B compares the value of this parameter to the value of leg/businessInfo/service that is configured in all RequestUM legs of the TPA. The RequestUM leg that contains a match for both the service and action parameters is the leg that will be used for the current transaction. When there is only one RequestUM leg configured in the TPA, the service parameter does not have to be defined.

  • action: String. (Required when PmodeId or agreementRef is not specified) Name of action use to identify the RequestUM leg used for the current transaction. IBM webMethods B2B uses the service and action parameters to determine which RequestUM leg to use for the current transaction. IBM webMethods B2B compares the value of this parameter to the value of leg/businessInfo/action that is configured in all RequestUM legs of the TPA. The RequestUM leg that contains a match for both service and action is the leg that will be used for the current transaction. When there is only one RequestUM leg configured in the TPA, the action parameter does not have to be defined.

  • serviceType: String. (Optional) Name of the service type that indicates how the sender and receiver will interpret the service element. When no value is enter for this parameter, the service parameter must be a URI.

  • messageProperties: Document List. (Optional) List of name and value pairs that are sent along with the message. These pairs map to the zero or more Property child elements within Messaging/UserMessage/MessageProperties.

    • name: String. The name of property.

    • value: String. The value of property.

    • type: String. (Optional) The type of property.

  • endpointUrl: String. Endpoint address of the recipient. It retrieves from the operation retrievePeppolParticipantDetails.

    Note

    When exchanging documents over the peppol network, configuring the endpointUrl is mandatory, as it is used to send the documents in real-time.

• pull: Document. (Required when DoctypeName is ebMS 3.0 PullRequest Signal) AS4 pull document.

  • mpc: String. (Optional) Indicates MPC (Message partitioning channel) from where to pull the queued message. Default MPC is used when not specified.

  • simpleSelectionItems[]: Document List. (Optional) Select a list of simple elements.

    • element: String. The name of the element that has to be retrieved. This parameter refers to refToMessageId, conversationId, agreementRef, service, and action.

    • elementvalue: String. The value of the element.

    • attributeList[]: Document List. (Optional) A list of attributes.

      • element: String. The name of the attribute.
      • elementvalue: String. The value of the attribute.

  • complexSelectionItems[]: Document List. (Optional) Select a list of complex elements.

    • element: String. The name of the element that has to be retrieved. This parameter refers to From, To, and MessageProperties.

    • elementvalue: String. The value of the element.

    • attributeList: Document List. (Optional) A list of attributes.

      • element: String. The name of the attribute.

      • elementvalue: String. The value of the attribute.

    • childItems[]: Document List. (Optional) A list of child items.

      • element: String. The name of the child item.

      • elementvalue: String. The value of the child item.

      • attributeList[]: Document List. (Optional) List of attributes.

        • element: String. The name of the attribute.

        • elementvalue: String. The value of the attribute.

Configuring an RNIF body

Document. To configure an RNIF body document.

• xmlInputContent: Object. XML content to submit to the IBM webMethods B2B product instance for processing.

• readContentAs: String. Data type in which inputContent field value is passed.

  • bytes. xmlInputContent is read as bytes.
  • string. xmlInputContent is read as string.
  • stream. xmlInputContent is read as stream. IBM recommends you to use readContentAs as stream if the size of the payload is over 5 MB.
    

• encoding: (Optional) String. Encoding of the content body.

Configuring an RNIF attachments [ ]

Document List. To Configure a list of attachments to be use in RNIF message. This is optional.

• name: String. Name of the attachment content

• inputContent: Object. Content of the attachment.

• readContentAs: String. Data type in which inputContent field value is passed.

  • bytes. inputContent is read as bytes.
  • string. inputContent is read as string.
  • stream. inputContent is read as stream. IBM recommends you to use readContentAs as stream if the size of the payload is over 5 MB.
    

• contentType: String. Content type of the attachment.

• encoding: (Optional) String. Encoding of the attachment.

Configuring an RNIF params

Document. A document that provides parameters on how IBM webMethods B2B recognizes and processes a RNIF document. Configure RNIF params.

• rnif20: Document Configure the following parameters:

  • pipInfo: (Optional) Document. Document that represents RNIF 2.0 Partner Interface Processes Information (PIP)

    • senderFocalRole: String. Validator of GlobalPartnerRoleClassificationCode tag describing fromRole in the service header. For valid values, see the fromService and fromRole details in the PIP specification corresponding to the executing PIP, activity, or action.

    • receiverFocalRole: String. Validator of GlobalPartnerRoleClassificationCode tag describing toRole in the service header. For valid values, see the toService and toRole details in the PIP specification corresponding to the executing PIP, activity, or action.

    • processCode String. Code or name of the PIP. For example, 3A4.

    • processVersion: String. Version of the PIP process. Select either 1.1 or 1.4.

    • transactionCode: String. Transaction associated with each RosettaNet PIP document.

    • actionCode: String. Query action associated with each RosettaNet PIP document.

    • enableSyncResponse: (Optional) Boolean. The flag to indicate that the transaction is expecting a sync response. Valid values are:

      • true: The transaction is expecting a sync response.

      • false: The transaction is not expecting a sync response. This is by default.

  • response: (Optional) Document. Response is a composite object containing the parameters.

    • messageTrackingID: String. Unique instance identifier to identify message.

    • inReplyToGlobalBusinessActionCode: (Optional) String. Action associated with request RosettaNet PIP document, for which IBM webMethods B2B sends the response.

    • initiatingPartnerLocationID: String. Location ID of the partner. The initiating partner location ID: //ServiceHeader/ProcessControl/KnownInitiatingPartner/PartnerIdentification/locationID/Value for which IBM webMethods B2B sends the response.

• rnif11: Document. Configure the following parameters:

  • pipInfo: (Optional) Document. Document that represents RNIF 1.1 Partner Interface Processes Information (PIP).

    • senderFocalRole: String. Validator of the GlobalPartnerRoleClassificationCode tag describing fromRole in the service header. For valid values, see the fromService and fromRole details in the PIP specification corresponding to the executing PIP, activity, or action.

    • receiverFocalRole: String. Validator of the GlobalPartnerRoleClassificationCode tag describing toRole in the service header. For valid values, see the toService and toRole details in the PIP specification corresponding to the executing PIP, activity, or action.

    • processCode: String. Code or name of the PIP. For example, 3A4.

    • processVersion: String. Version of the PIP process. Select either 1.1 or 1.4.

    • transactionCode: String. Transaction associated with each RosettaNet PIP document.

    • actionCode: String. Query action associated with each RosettaNet PIP document.

  • response: (Optional) Document. Response is a composite object containing the parameters.

    • actionIdentityInstanceIdentifier: String. Unique instance identifier to identify message.

    • inReplyToGlobalBusinessActionCode: (Optional) String. Action associated with request RosettaNet PIP document, for which IBM webMethods B2B sends the response.

Output Parameters

Output of constructSubmitInput operation is the input parameters for submit operation. See Submit.

parseContent

Parses request content passed by the processing rule Call an integration action as bytes or string data type. For more information, see Call an integration.

Input Parameters

• inputContent: String. Content passed in the integration request.

• loadContentAs: String. Data type in which outputContent field value is passed.

  • bytes. outputContent is generated as bytes.
  • string. outputContent is generated as a string.
    

• encoding: String. Type of character set used for encoding inputContent value. This can be any IANA registered character set. Default UTF-8.

Output Parameters

• outputContent: Object. Content data corresponds to the data type option set for the loadContentAs field.

Compress Services

Use Compress services to compress the data before sending the HTTP request and decompress it after receiving the HTTP response.

The following Compress services are available:

compressData

Compresses the data before sending the HTTP request using any of the specified compression schemes.

Input Parameters

• data: Document - Data that you want the compressData service to compress. Specify data using one of the following keys. When you use more than one key, string is appended first, bytes is appended second, and stream is appended last. IBM webMethods Integration uses the first key that it encounters.

  • string: string Optional - Text that you want the compressData service to compress.
  • bytes: byte[] Optional - Data that you want the compressData service to compress.
  • stream:java.io.InputStream Optional - Data that you want the compressData service to compress.
    

• encoding: String. Optional - Name of a registered, IANA character set that specifies the encoding to use when converting the String to an array of bytes (for example: ISO-8859-1).

• compressionScheme: String - The compression method you want the compressData service to apply to compress the data. The supported compression schemes are gzip and deflate.

• loadAs: string - Form in which you want the compressData service to store the output data. Set to:

  • bytes to store the data as a byte[].
  • stream to store the data as a java.io.InputStream.

Output Parameters

• compressedData: Document - Compressed data after applying the compression scheme.

  • bytes: byte[] Conditional - Compressed data represented as a byte[ ]. bytes is returned only when the loadAs input parameter is set to bytes.
  • stream: java.io.InputStream Conditional - Compressed data represented as an InputStream. stream is returned only when the loadAs input parameter is set to stream.

decompressData

Decompresses the data based on the response header of the HTTP response.

Input Parameters

• data: Document. Data that you want the decompressData service to decompress. Specify data using one of the following keys.

  • bytes: byte[] Optional - Data that you want the decompressData service to decompress.
  • stream: java.io.InputStream Optional - Data that you want the decompressData service to decompress.
    

• compressionScheme: String - The compression scheme you want the decompressData service to apply to decompress the data. The supported compression schemes are gzip and deflate.

• loadAs: string - Form in which you want the decompressData service to store the returned document. Set to:

  • bytes to return the data as a byte[].
  • stream to return the data as a java.io.InputStream.

Output Parameters

• decompressedData: Document. Decompressed data after applying the compression algorithm.

  • bytes: byte[] Conditional - Decompressed data represented as a byte[]. bytes is returned only when the loadAs input parameter is set to bytes.
  • stream: java.io.InputStream Conditional - The decompressed data represented as an InputStream. stream is returned only when the loadAs input parameter is set to stream.
    

Date Services

Use Date services to generate and format date values.

Pattern String Symbols - Many of the Date services require you to specify pattern strings describing the data’s current format and/or the format to which you want it converted. For services that require a pattern string, use the symbols in the following table to describe the format of your data. For example, to describe a date in the January 15, 1999 format, you would use the pattern string MMMMM dd, yyyy. To describe the format 01/15/99, you would use the pattern string MM/dd/yy.

Time Zones - When working with date services, you can specify time zones. The Earth is divided into 24 standard time zones, one for every 15 degrees of longitude. Using the time zone including Greenwich, England (known as Greenwich Mean Time, or GMT) as the starting point, the time is increased by an hour for each time zone east of Greenwich and decreases by an hour for each time zone west of Greenwich. The time difference between a time zone and the time zone including Greenwich, England (GMT) is referred to as the raw offset.

The following table identifies the different time zones for the Earth and the raw offset for each zone from Greenwich, England. The effects of daylight savings time are ignored in this table.

Examples - You can specify timezone input parameters in the following formats:

• As a full name. For example:

  • Asia/Tokyo: America/Los_Angeles
    
    

  You can use the java.util.TimeZone.getAvailableIDs() method to obtain a list of the valid full name time zone IDs that your JVM version supports.

• As a custom time zone ID, in the format GMT[+ | -]hh[ [:]mm]. For example:

  • GMT+2:00: All time zones 2 hours east of Greenwich (that is, Central Africa Time, Eastern European Time, and Egypt Standard Time)
  • GMT-3:00: All time zones 3 hours west of Greenwich (that is, Argentina Standard Time and Brazil Eastern Time)
  • GMT+9:30: All time zones 9.5 hours east of Greenwich (that is, Australian Central Time)
    
    

• As a three-letter abbreviation from the table above. For example:

  • PST: Pacific Standard Time
    
    Note

    • Three-letter abbreviations
      • All three-letter abbreviations are deprecated. This is because some three-letter abbreviations can represent multiple time zones, for example, “CST” could represent both U.S. “Central Standard Time” and “China Standard Time”. Hence, use the full name or custom time zone ID formats instead.
    • Invalid Dates
      The dates you use with a date service must adhere to the java.text.SimpleDateFormat class.
      • If you use an invalid date with a date service, the date service automatically translates the date to a legal date. For example, if you specify 1999/02/30 as input, the date service interprets the date as 1999/03/02 (two days after 2/28/1999).
      • If you use 00 for the month or day, the date service interprets 00 as the last month or day in the Gregorian calendar. For example, if you specify 00 for the month, the date service interprets it as 12. If the pattern yy is used for the year, the date service uses a 50-year moving window to interpret the value of yy. The date service establishes the window by subtracting 49 years from the current year and adding 50 years to the current year. For example, if you are running IBM webMethods Integration in the year 2000, the moving window would be from 1951 to 2050. The date service interprets 2-digit years as falling into this window (for example, 12 would be 2012, 95 would be 1995).
    
    

The following Date services are available:

calculateDateDifference

Calculates the difference between two dates and returns the result as seconds, minutes, hours, and days.

Input Parameters

• startDate: String - Starting date and time.

• endDate: String - Ending date and time.

• startDatePattern: String - Format in which the startDate parameter is to be specified (for example, yyyyMMdd HH:mm:ss.SSS).

• endDatePattern: String - Format in which the endDate parameter is to be specified (for example, yyyyMMdd HH:mm:ss.SSS).

Output Parameters

• dateDifferenceSeconds: String - The difference between the startingDateTime and endingDateTime, truncated to the nearest whole number of seconds.

• dateDifferenceMinutes: String - The difference between the startingDateTime and endingDateTime, truncated to the nearest whole number of minutes.

• dateDifferenceHours: String - The difference between the startingDateTime and endingDateTime, truncated to the nearest whole number of hours.

• dateDifferenceDays: String - The difference between the startingDateTime and endingDateTime, truncated to the nearest whole number of days.

Usage Notes

Each output value represents the same date difference, but in a different scale. Do not add these values together. Make sure your subsequent flow service steps use the correct output, depending on the scale required.

compareDates

Compares two dates and returns the result as an integer.

Input Parameters

• startDate: String - Starting date to compare against endDate.

• endDate: String - Ending date to compare against startDate.

• startDatePattern: String - Format in which the startDate parameter is specified (for example, yyyyMMdd HH:mm:ss.SSS).

• endDatePattern: String - Format in which the endDate parameter is specified (for example, yyyyMMdd HH:mm:ss.SSS).

Output Parameters

• result: String. Checks whether startDate is before, the same, or after the endDate based on the values as follows:

  • +1: The startDate is after the endDate.
  • 0: The startDate is the same as the endDate.
  • -1: The startDate is before the endDate.

Usage Notes

If the formats specified in the startDatePattern and endDatePattern parameters are different, IBM webMethods Integration takes the units that are not specified in the startDate and endDate values as 0.

That is, if the startDatePattern is yyyyMMdd HH:mm and the startDate is 20151030 11:11 and if the endDatePattern is yyyyMMdd HH:mm:ss.SSSand the endDate is 20151030 11:11:55:111, then the compareDates service considers start date to be before the end date and will return the result as -1.

To calculate the difference between two dates, use the calculateDateDifference service.

currentNanoTime

Returns the current value of the running Java Virtual Machine’s high-resolution time source, in nanoseconds. This method can only be used to measure elapsed time and is not related to any other notion of system or wall-clock time. The value returned represents nanoseconds since some fixed but arbitrary origin time (perhaps in the future, so values may be negative). Use this service in-conjunction with elapsedNanoTime service.

Input Parameters

None.

Output Parameters

• nanoTime: java.lang.Long - The value returned represents the time elapsed since an arbitrary fixed point in nanoseconds, which is not necessarily related to the actual current date and time.

dateBuild

Builds a date String using the specified pattern and the specified date services.

Input Parameters

• pattern: String - Pattern representing the format in which you want the date returned. If you do not specify pattern, dateBuild returns null. If pattern contains a time zone and timezone is not specified, the default time zone is used.

• year: String Optional - The year expressed in yyyy or yy format (for example, 01 or 2001). If you do not specify year or you specify an invalid value, dateBuild uses the current year.

• month: String Optional - The month expressed as a number (for example, 1 for January, 2 for February). If you do not specify month or you specify an invalid value, dateBuild uses the current month.

• dayofmonth: String Optional - The day of the month expressed as a number (for example, 1 for the first day of the month, 2 for the second day of the month). If you do not specify dayofmonth or you specify an invalid value, dateBuild uses the current day.

• timezone: String Optional - Time zone in which you want the output date and time expressed. Specify a time zone code as shown in the “Time Zones” section, for example, EST for Eastern Standard Time. If you do not specify timezone, the value of the server’s “user timezone” property is used. If this property has not been set, GMT is used.

• locale: String Optional - Locale in which the date is to be expressed. For example, if locale is en (for English), the pattern EEE d MMM yyyy will produce Friday 23 August 2002, and the locale of fr (for French) will produce vendredi 23 août 2002.

Output Parameters

• value: String - The date specified by year, month, and dayofmonth, in the format of pattern.

dateTimeBuild

Builds a date/time string using the specified pattern and the specified date services.

Input Parameters

• pattern: String - Pattern representing the format in which you want the time returned. For pattern-string notation, see the “Pattern String Symbols” section. If you do not specify pattern, dateTimeBuild returns null. If pattern contains a time zone and the timezone parameter is not set, the default time zone is used.

• year: String Optional - The year expressed in yyyy or yy format (for example, 01 or 2001). If you do not specify year or you specify an invalid value, dateTimeBuild uses the current year.

• month: String Optional - The month expressed as a number (for example, 1 for January, 2 for February). If you do not specify month or you specify an invalid value, dateTimeBuild uses the current month.

• dayofmonth: String Optional - The day of the month expressed as a number (for example, 1 for the first day of the month, 2 for the second day of the month). If you do not specify dayofmonth or you specify an invalid value, dateTimeBuild uses the current day.

• hour: String Optional - The hour expressed as a number based on a 24-hour clock. For example, specify 0 for midnight, 2 for 2:00 A.M., and 14 for 2:00 P.M. If you do not specify hour or you specify an invalid value, dateTimeBuild uses 0 as the hour value.

• minute: String Optional - Minutes expressed as a number. If you do not specify minute or you specify an invalid value, dateTimeBuild uses 0 as the minute value.

• second: String Optional - Seconds expressed as a number. If you do not specify second or you specify an invalid value, dateTimeBuild uses 0 as the second value.

• millis: String Optional - Milliseconds expressed as a number. If you do not specify millis or you specify an invalid value, dateTimeBuild uses 0 as the millis value.

• timezone: String Optional - Time zone in which you want the output date and time expressed. Specify a time zone code as shown in the “Time Zones” section, for example, EST for Eastern Standard Time. If you do not specify timezone, the value of the server’s “user timezone” property is used. If this property has not been set, GMT is used.

• locale: String Optional - Locale in which the date is to be expressed. For example, if locale is en (for English), the pattern EEE d MMM yyyy will produce Friday 23 August 2002, and the locale of fr (for French) will produce vendredi 23 août 2002.

Output Parameters

• value: String - Date and time in format of pattern.

dateTimeFormat

Converts date/time (represented as a String) string from one format to another.

Input Parameters

• inString: String - Date/time that you want to convert.
  Important: If inString contains a character in the last position, that character is interpreted as 0. This can result in an inaccurate date. For information about invalid dates, see the “Notes on Invalid Dates” section.

• currentPattern: String - Pattern string that describes the format of inString.

• newPattern: String - Pattern string that describes the format in which you want inString returned.

• locale: String Optional - Locale in which the date is to be expressed. For example, if locale is en (for English), the pattern EEE d MMM yyyy will produce Friday 23 August 2002, and the locale of fr (for French) will produce vendredi 23 août 2002.

• lenient: String Optional - A flag indicating whether an exception will appear if the inString value does not adhere to the format specified in currentPattern parameter. Set to:

  • true to perform a lenient check. This is the default. In a lenient check, if the format of the date specified in the inString parameter does not match the format specified in the currentPattern parameter, the date in the format specified in the currentPattern parameter will be interpreted and returned. If the interpretation is incorrect, the service will return an invalid date.

  • false to perform a strict check. In a strict check, an exception will appear if the format of the date specified in the inString parameter does not match the format specified in the currentPattern parameter.

Output Parameters

• value: String - The date/time given by inString, in the format of newPattern.

Usage Notes

As described in the “Notes on Invalid Dates” section, if the pattern yy is used for the year, dateTimeFormat uses a 50-year moving window to interpret the value of the year.

If currentPattern does not contain a time zone, the value is assumed to be in the default time zone.

If newPattern contains a time zone, the default time zone is used.

elapsedNanoTime

Calculates the time elapsed between the current time and the given time, in nanoseconds.

Input Parameters

• nanoTime: java.lang.Long - Time in nanoseconds. If nanoTime is less than zero, then the service treats it as zero.

Output Parameters

• elapsedNanoTime: java.lang.Long - The difference between the current time in nanoseconds and nanoTime. If nanoTime is greater than the current nano time, the service returns zero.

• elapsedNanoTimeStr: String - The difference between the current time in nanoseconds and nanoTime. The difference is expressed as a String, in this format: [years] [days] [hours] [minutes] [seconds] [millisec] [microsec] . If nanoTime is greater than the current nano time, the service returns zero.

formatDate

Formats a Date object as a string.

Input Parameters

• date: java.util.Date Optional - Date/time that you want to convert.

• pattern: String - Pattern string that describes the format in which you want the date returned.

• timezone: String Optional - Time zone in which you want the output date and time expressed. Specify a time zone code as shown in the Time Zones section, for example, EST for Eastern Standard Time. If you do not specify timezone, the user’s time zone is used, else GMT is used.

• locale: String Optional - Locale in which the date is to be expressed. For example, if locale is en (for English), the pattern EEE d MMM yyyy will produce Friday 23 August 2002, and the locale of fr (for French) will produce vendredi 23 août 2002.

Output Parameters

• value: String - The date/time given by date in the format specified by pattern.

getCurrentDate

Returns the current date as a Date object.

Input Parameters

None.

Output Parameters

• date: java.util.Date - Current date.

getCurrentDateString

Returns the current date as a String in a specified format.

Input Parameters

• pattern: String - Pattern representing the format in which you want the date returned.

• timezone: String Optional - Time zone in which you want the output date and time expressed. Specify a time zone code as shown in the “Time Zones” section, for example, EST for Eastern Standard Time. If you do not specify timezone, the value of the server’s “user timezone” property is used. If this property has not been set, GMT is used.

• locale: String Optional - Locale in which the date is to be expressed. For example, if locale is en (for English), the pattern EEE d MMM yyyy will produce Friday 23 August 2002, and the locale of fr (for French) will produce vendredi 23 août 2002.

Output Parameters

• value: String - Current date in the format specified by pattern.

incrementDate

Increments a date by a specified amount of time.

Input Parameters

• startDate: String - Starting date and time.

• startDatePattern: String - Format in which the startDate parameter is specified (for example, yyyyMMdd HH:mm:ss.SSS).

• endDatePattern: String Optional - Pattern representing the format in which you want the endDate to be returned. If no endDatePattern is specified, the endDate will be returned in the format specified in the startDatePattern parameter.

• addYears: String Optional - Number of years to add to startDate. The value must be an integer between -2147483648 and 2147483647.

• addMonths: String Optional - Number of months to add to startDate. The value must be an integer between -2147483648 and 2147483647.

• addDays: String Optional - Number of days to add to startDate. The value must be an integer between -2147483648 and 2147483647.

• addHours: String Optional - Number of hours to add to startDate. The value must be an integer between -2147483648 and 2147483647.

• addMinutes: String Optional - Number of minutes to add to startDate. The value must be an integer between -2147483648 and 2147483647.

• addSeconds: String Optional - Number of seconds to add to startDate. The value must be an integer between -2147483648 and 2147483647.

• addMilliSeconds: String Optional. Number of milliseconds to add to startDate. The value must be an integer between -2147483648 and 2147483647.

• timezone: String Optional - Time zone in which you want the endDate to be expressed. Specify a time zone code, for example, EST for Eastern Standard Time. If you do not specify timezone, the value of the server’s “user timezone” property is used. If this property has not been set, GMT is used.

• locale: String Optional - Locale in which the endDate is to be expressed. For example, if locale is en (for English), the pattern EEE d MMM yyyy will produce Friday 23 August 2002, and the locale of fr (for French) will produce vendredi 23 août 2002.

Output Parameters

• endDate: String - The end date and time, calculated by incrementing the startDate with the specified years, months, days, hours, minutes, seconds, and/or milliseconds. The endDate will be in the endDatePattern format, if specified. If no endDatePattern is specified or if blank spaces are specified as the value, the endDate will be returned in the format specified in the startDatePattern parameter.

Usage Notes

The addYears, addMonths, addDays, addHours, addMinutes, addSeconds, and addMilliSeconds input parameters can take positive or negative values. For example, If startDate is 10/10/2001, startDatePattern is MM/dd/yyyy, addYears is 1, and addMonths is -1, endDate will be 09/10/2002.

If you specify only the startDate, startDatePattern, and endDatePattern input parameters and do not specify any of the optional input parameters to increment the period, the incrementDate service just converts the format of startDate from startDatePattern to endDatePattern and returns it as endDate.

The format of the date specified in the startDate parameter must match the format specified in the startDatePattern and the format of the date specified in the endDate parameter must match the endDatePattern format.

Datetime Services

Use Datetime services to build or increment a date/time. The services in datetime provide more explicit timezone processing than similar services in the date category.

Providing Time Zones

You can specify timezone input parameters to the datetime services in the following formats:

• As a full name.

  Example: Asia/Tokyo America/Los_Angeles

  You can use java.time.ZoneId.getAvailableZoneIds. () method to obtain a list of the valid full name time zone IDs that your JVM version supports.

• As UTC.

  Example: UTC - 5h

• As a custom time zone ID, in the format GMT[+ | -]hh[ [:]mm].

  Example: GMT+2:00 Time zones 2 hours east of Greenwich GMT-3:00 Time zones 3 hours west of Greenwich (that is, Argentina Standard Time and Brazil Eastern Time)

  GMT+9:30 Time zones 9.5 hours east of Greenwich (that is, Australian Central Time)

• As a three-letter abbreviation.

  Example: PST Pacific Standard Time

  Important: As some three-letter abbreviations can represent multiple time zones (for example, “CST” could represent both U.S. “Central Standard Time” and “China Standard Time”), all abbreviations are deprecated. Use the full name, UTC, or custom time zone ID GMT formats instead.

The following Datetime services are available:

build

Builds a date/time string using the specified pattern and the supplied date/time elements.

Input Parameters

• pattern: String - The pattern with which to format the string. For more information about these pattern letters and symbols, see the Oracle Java API documentation for the DateTimeFormatter class.

• year: String Optional - The year expressed as a 4-digit Integer. If you do not specify year, the year will be from the current date which is determined by the JVM in which IBM webMethods Integration runs. If you specify an invalid value for year, the service will end with an error from the JDK.

• month: String Optional - The month expressed as an Integer where January is 1. If you do not specify month, the month will be from the current date which is determined by the JVM in which IBM webMethods Integration runs. If you specify an invalid value for month, the service will end with an error from the JDK.

• dayOfMonth: String Optional - The day of the month expressed as an Integer, starting with 1 as the first day of the month. If you do not specify dayOfMonth, the day of the month will be from the current date which is determined by the JVM in which IBM webMethods Integration runs. If you specify an invalid value for day, the service will end with an error from the JDK.

• hour: String Optional - The hour of the day expressed as an Integer from 0 through 23. If you do not specify hour, the hour will be from the current time which is determined by the JVM in which IBM webMethods Integration runs. If you specify an invalid value for hour, the service will end with an error from the JDK.

• minute: String Optional - The minute expressed as an Integer from 0 through 59. If you do not specify minute, the minute will be from the current time which is determined by the JVM in which IBM webMethods Integration runs. If you specify an invalid value for minute, the service will end with an error from the JDK.

• second: String Optional - The seconds of the hour expressed as an Integer from 0 through 59. If you do not specify second, the second will be from the current time which is determined by the JVM in which IBM webMethods Integration runs. If you specify an invalid value for second, the service will end with an error from the JDK.

• millis: String Optional - The number of milliseconds expressed as a Long. If you do not specify millis, the millis will be from the current time which is determined by the JVM in which IBM webMethods Integration runs. If you specify an invalid value for millis, the service will end with an error from the JDK.

• timezone: String Optional - The time zone. If you specify a value for timezone, the service ignores the useSystemTimeZone parameter value. It is recommended to supply the full name for timezones, such as Asia/Tokyo, or use UTC. If pattern includes a timezone, you must specify timezone input parameter value or set useSystemTimeZone to true.

• useSystemTimeZone: String Optional - Indicates whether the service uses the time zone of the IBM webMethods Integration JVM if timezone was not specified. Set to:

  • true to use the time zone of IBM webMethods Integration when timezone is not specified.

  • false if you do not want the service to use the timezone of IBM webMethods Integration if timezone was not set. The default is false.

  If pattern includes a timezone, you must specify the timezone input parameter value or set useSystemTimeZone to true.

  To match the behavior of date:dateTimeBuild which produced a date/time that always included a time zone set useSystemTimeZone to true. This ensures that if timezone is not specified, the resulting date/time will include a time zone.

• locale: String Optional - The locale in which to express the date.

Output Parameters

• value: String - The formatted date and time.

Usage Notes

The build service replaces the date:dateBuild and date:dateTimeBuild services which are deprecated.

If you specify a parameter that does not exist in the supplied pattern, the service ignores that parameter.

If you do not specify a timezone, useSystemTimeZone is set to false, and the pattern includes a time zone, the service ends with an exception.

If a time zone is provided as input to the service either in the timezone parameter or by setting useSystemTimeZone to true, the build service calculates the date/time starting with a “zoned” date/time. The resulting values can differ when daylight savings time transitions are in effect. If no time zone is provided as input to the service either by not specifying timezone or by setting useSystemTimeZone to false, then the build service calculates the date/time starting with an “unzoned” date/time.

The build service is similar to date:dateBuild and date:dateTimeBuild, however, the build service allows the building of a date/time that does not include a time zone. Furthermore, the build service assembles a date/time using each of the provided parameters. Consequently the build service can build a date/time with a value that would be invalid in the current time zone, such as a date/time that would fall into the gap of a daylight saving time transition. This is unlike the date:dateBuild and date:dateTimeBuild services which build a local java.util.Date object that uses the timezone of the machine running IBM webMethods Integration. The date:dateBuild and date:dateTimeBuild service then applies the offset between the local timezone and the specified timezone.

increment

Increments or decrements a date and time by a specified amount of time.

Input Parameters

• startDate: String - Starting date and time.

• startDatePattern: String - Pattern in which the startDate value is specified. For more information about these pattern letters and symbols, see the Oracle Java API documentation for the DateTimeFormatter class.

• endDatePattern: String - Pattern in which to format the resulting date/time. For more information about these pattern letters and symbols, see the Oracle Java API documentation for the DateTimeFormatter class. If no endDatePattern is specified, the endDate will be returned in the format specified in the startDatePattern parameter.

• timezone: String Optional - The time zone to use for parsing startDate and formatting endDate. The service uses timezone to parse the startDate String and convert it from the time zone specified in the input, if one was provided. For example, if the timezone input parameter is MST and the startDate is “2019-02-21 11:30:00 EST”, then the service converts the startDate time from EST to MST. The service uses timezone when formatting endDate as a String. That is, the timezone determines the time zone in which the service expresses the endDate.

• locale: String Optional - Locale in which the endDate is to be expressed.

• addYears: String Optional - The number of years to add to startDate. The value must be an integer between -2147483648 and 2147483647.

• addMonths: String Optional - The number of months to add to startDate. The value must be an integer between -2147483648 and 2147483647.

• addDays: String Optional - The number of days to add to startDate. The value must be an integer between -2147483648 and 2147483647.

• addHours: String Optional - The number of hours to add to startDate. The value must be an integer between -2147483648 and 2147483647.

• addMinutes: String Optional - The number of minutes to add to startDate. The value must be an integer between -2147483648 and 2147483647.

• addSeconds: String Optional - The number of seconds to add to startDate. The value must be an integer between -2147483648 and 2147483647.

• addMilliseconds: String Optional - The number of milliseconds to add to startDate. The value must be an integer between -2147483648 and 2147483647.

• useSystemTimeZone: String Optional - Whether to use the system time zone to increment the date/time when the startDate value does not have a time zone. Set to:

  • false if the startDate does not include a time zone, the timezone parameter was not set, and you want to increment the date/time without being affected by a time zone. This is the default.

  • true to use the system time zone when incrementing the startDate.

  When useSystemTimeZone is false and no timezone is provided, the resulting endDate will not include a timezone. To match the behavior of date:incrementDate, which produced a date/time that always included a time zone, set useSystemTimeZone to true.|

• useSameInstant: String Optional - Whether to use the same Instant, where Instant represents a moment on the timeline in UTC, or the same unzoned date/time when applying a different time zone. Using the same Instant will usually result in changes to the unzoned date/time when the time zone and its offset are applied. Not using the same Instant will result in the unzoned date/time being unchanged when the time is applied. If useSameInstant is true, the increment service uses the Instant (the absolute time with no time zones) to determine how the timezone value is used.

  If useSameInstant is false, the increment service uses the unzoned date/time and only changes the time zone. The default is true.

  Note

  For the purpose of this documentation, the term “unzoned date/time” is synonymous with the term “local date/time”.

  For example, if startDate is a date/time of “2019-02-25 08:25:00 CET” (Central European Time, UTC+1:00) and the specified timezone value is America/New_York (EST, UTC-5:00) , the value of useSameInstant has the following impact:

  • If useSameInstant is true, then 2019-02-25 08:25:00 CET becomes 2019-02-25 02:25:00 EST

  • If useSameInstant is false, then 2019-02-25 08:25:00 CET becomes 2019-02-25 08:25:00 EST

Output Parameters

• endDate: String - The incremented date and time.

Usage Notes

The increment service replaces the date:incrementDate service which is deprecated.

The increment service can be used to decrement a date and time by specifying negative numbers. The addYears , addMonths , addDays , addHours , addMinutes , addSeconds , and addMilliSeconds input parameters can take positive or negative values.

The service ends with an exception if the format of the date specified in the startDate parameter does not match the format specified in the startDatePattern.

If endDatePattern includes a time zone, such as “z”, then the input string and startDatePattern must also have time zone fields, or timeZone must be set, or useSystemTimeZone must be true. Otherwise the service ends with an error.

If you specify only the startDate, startDatePattern, and endDatePattern input parameters and do not specify any of the optional input parameters to increment the period, the increment service just converts the format of startDate from startDatePattern to endDatePattern and returns it as endDate.

If you specify a value for timezone, the service ignores the useSystemTimeZone parameter value.

If you specify a value for timezone and the startDate includes a time zone, then the service uses the supplied timezone to convert the startDate time zone.

If you do not specify a value for timezone and the startDate includes a time zone, then the service uses the time zone in the startDate and ignores the useSystemTimeZone parameter.

If you do not specify a value for timezone, the startDate does not include a time zone, and useSystemTimeZone parameter is true, then the service uses the system time zone.

If startDate does not include a time zone, you do not specify a value for timezone, and useSystemTimeZone is false, the resulting endDate will not include a time zone.

The increment service is similar to date:incrementDate, however, the increment service provides more specific handling of time zones. To match the behavior of date:incrementDate, set useSameInstant to true.

Document Services

Use Document services to perform operations on documents.

The following Document services are available:

bytesToDocument

Converts an array of bytes to a document. This service can only be used with byte arrays created by executing the documentToBytes service.

Input Parameters

• documentBytes: Object - An array of bytes (byte[]) to convert to a document.

  • If documentBytes is null, the service does not return a document or an error message.

  • If documentBytes is not a byte array, the service throws an exception.

  • If documentBytes is zero-length, the service produces an empty document.

Output Parameters

• document: Document - A document.

Usage Notes

Use this service with the documentToBytes service, which converts a document into a byte array. You can pass the resulting byte array to the bytesToDocument service to convert it back into the original document.

In order for the document-to-bytes-to-document conversion to work, the entire content of the document must be serializable. Every object in the document must be of a data type known to IBM webMethods Integration, or it must support the java.io.Serializable interface.

If IBM webMethods Integration encounters an unknown object in the document that does not support the java.io.Serializable interface, that object’s value will be lost. It will be replaced with a string containing the object’s class name.

deleteDocuments

Deletes the specified documents from a set of documents.

Input Parameters

• documents: Document List - Set of documents that contain the documents you want to delete.

• indices: String List - Index values of documents to be deleted from the documents parameter document list.

Output Parameters

• documents: Document List - List of documents whose indices do not match the values in indices parameter.

• deletedDocuments: Document List - List of deleted documents.

Usage Notes

The deleteDocuments service returns an error if the indices parameter value is less than zero or more than the number of documents in the documents input parameter.

documentListToDocument

Constructs a document from a document list by generating key/value pairs from the values of two elements that you specify in the document list.

Input Parameters

• documentList: Document List - Set of documents that you want to transform into a single document.

  Note

  If the documentList parameter contains a single document instead of a Document List, the documentListToDocument service does nothing.

• name: String - Name of the element in the documentList parameter whose value provides the name of each key in the resulting document.

  Important

  The data type of the element that you specify in the name parameter must be String.

• value: String - Name of the element in the documentList parameter whose values will be assigned to the keys specified in name. This element can be of any data type.

Output Parameters

• document: - Document Document containing the key/value pairs generated from the documentList parameter.

Usage Notes

The following example illustrates how the documentListToDocument service would convert a document list that contains three documents to a single document containing three key/value pairs. When you use the documentListToDocument service, you specify which two elements from the source list are to be transformed into the keys and values in the output document. In the following example, the values from the pName elements in the source list are transformed into key names, and the values from the pValue elements are transformed into the values for these keys.

A documentList containing these three documents:

Would be converted to a document containing these three keys:

documentToBytes

Converts a document to an array of bytes.

Input Parameters

• document: Document - Document to convert to bytes.

  • If document is null, the service does not return an output or an error message.

  • If document is not a document, the service throws an exception.

  • If document contains no elements, the service produces a zero-length byte array.

Output Parameters

• documentBytes: Object - A serialized representation of the document as an array of bytes (byte[]).

Usage Notes

Use the documentToBytes service with the bytesToDocument service, which converts the byte array created by this service back into the original document.

The documentToBytes service is useful when you want to write a document to a file, an input stream, or a cache.

In order for the document-to-bytes-to-document conversion to work, the entire content of the document must be serializable. Every object in the document must be of a data type known to IBM webMethods Integration, or it must support the java.io.Serializable interface. If IBM webMethods Integration encounters an unknown object in the document that does not support the java.io.Serializable interface, that object’s value will be lost. IBM webMethods Integration will replace it with a string containing the object’s class name.

documentToDocumentList

Expands the contents of a document into a list of documents.

Each key/value pair in the source document is transformed to a single document containing two keys (whose names you specify). These two keys will contain the key name and value of the original pair.

Input Parameters

• document: Document - Document to transform.

• name: String - Name to assign to the key that will receive the key name from the original key/value pair. In the example above, this parameter was set to pName.

• value: String - Name to assign to the key that will receive the value from the original key/value pair. In the example above, this parameter was set to pValue.

Output Parameters

• documentList: Document List - List containing a document for each key/value pair in the document parameter. Each document in the list will contain two keys, whose names were specified by the name and value parameters. The values of these two keys will be the name and value (respectively) of the original pair.

Usage Notes

The following example shows how a document containing three keys would be converted to a document list containing three documents. In this example, the names pName and pValue are specified as names for the two new keys in the document list.

A document containing these three keys:

Would be converted to a document list containing these three documents:

findDocuments

Searches a set of documents for entries matching a set of criteria.

Input Parameters

• documents: Document List - Set of documents from which the documents meeting the retrieve criteria are to be returned.

• matchCriteria: Document - Criteria on which the documents in the documents parameter are to be matched. Parameters for matchCriteria are: path: Name of the element in documentList whose value provides the value for the search text. The value for key can be a path expression. For example, “Family/Chidren[0]/ BirthDate” retrieves the birthday of the first child from the input Family document list.

  • compareValueAs Optional - Allowed values are string, numeric, and datetime. The default value is string.

  • datePattern Optional - Pattern will be considered only if compareValueAs is of type datetime. Default value is MM/dd/yyyy hh:mm:ss a.

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

    • operator - Allowed values are equals, doesNotEqual, greaterThan, greaterThanEqual, lessThan, lessThanEqual, equalsIgnoreCase, contains, doesNotContain, beginsWith, doesNotBeginWith, endsWith, doesNotEndWith.

    • value Optional - Allowed values are string, numeric, and datetime. The default value is string.

    • joinType - Specifies the way two joins can be linked. Values are “and” or “or”. Default value is “and”.

Output Parameters

• result documents: Document List - List of documents that match the retrieve criteria.

groupDocuments

Groups a set of documents based on specified criteria.

Input Parameters

• documents: Document List - Set of documents to be grouped based on the specified criteria.

• groupCriteria: Document List - The criteria on which the input documents are to be grouped. Valid values for the groupCriteria parameter are:

  • key - Key in the pipeline. The value for key can be a path expression. For example, “Family/Chidren[0]/BirthDate” retrieves the birthday of the first child from the input Family document list.

  • compareStringsAs. Optional - Valid values for compareStringsAs are string, numeric, and datetime. The default value is string.

  • pattern. Optional - Pattern will be considered only if the compareStringsAs parameter is of type datetime.

  Note

  If key is not found in all the input documents, the documents that do not match the groupCriteria are grouped together as a single group.

Output Parameters

• documentGroups: Document List - List of documents where each element represents a set of documents grouped based on the criteria specified.

Usage Notes

The following example illustrates how to specify the values for the groupCriteria parameter:

The input documents will be grouped based on name, age, and birth date.

insertDocument

Inserts a new document in a set of documents at a specified position.

Input Parameters

• documents: Document List - Set of documents in which a new document is to be inserted.

• insertDocument: Document. The new document to be inserted to the set of documents specified in the documents parameter.

• index: String. Optional. The position in the seat which the document is to be inserted. The index parameter is zero-based. if the value for the index parameter is not specified, the document will be inserted at the end of the document list specified in the documents parameter.

Output Parameters

• documents: Document List. Document list after inserting the new document.

removeNullFields

Removes null fields from a given document. Optionally, by specifying trimStringFields and removeEmptyStringFields, you can trim leading and trailing spaces in a string field, and after trimming the fields, if the string field length is zero, they can be removed. For array fields, it reduces the size of the array by the number of null fields. After removing all the null fields, if the size is zero, the array field is removed from the given document.

Input Parameters

• document: Documents. A document from where fields having value null are removed.

• trimStringFields: If specified, for fields whose type is String, would remove the leading and trailing space characters. Default value is false.

• removeEmptyStringFields: If specified, if a string field is empty, it is removed from the given document. If both trimStringFields and removeEmptyStringFields are true, then after removing the spaces, if there are no characters in the string, it is removed from the document. Default value is false.

Output Parameters

• document: Document. Returns the document having non-null fields.

searchDocuments

Searches a set of documents for entries matching a set of Criteria.

Input Parameters

• documents: Document List. Set of documents from which the documents meeting the search criteria are to be returned.

• searchCriteria: Document. Criteria on which the documents in the documents parameter are to be searched. Valid values for searchCriteria parameters are:

  • key: Name of the element in documentList whose value provides the value for the search text. The value for key can be a path expression. For example, “Family/Chidren[0]/BirthDate” retrieves the birthday of the first child from the input Family document list.

  • value: Optional. Any search text. If no value is specified, the service searches for null in the document list.

  • compareStringsAs: Optional. Allowed values are string, numeric, and datetime. The default value is string.

  • pattern: Optional. Pattern will be considered only if the compareStringsAs value is of type datetime.

• sorted: String Optional - The value of the sorted parameter is true if the document list is already sorted based on the search criteria and same search key; otherwise false. If the value for the sorted parameter is set to true, the required documents are searched faster.

Output Parameters

• resultdocuments: Document List - List of documents which are matching the search criteria.

• documentListIndices: String List - Positions of search documents in the document list.

• documents: Document List - List of documents that were input.

Usage Notes

For example, if you want to search a set of documents for documents where BirthDate is 10th January 2008, the values for the searchCriteria parameter would be:

sortDocuments

Sorts a set of input documents based on the specified sortCriteria.

Input Parameters

• documents: Document List - Set of documents that are to be sorted.

• sortCriteria: Document List - Criteria based on which the documents in the documents parameter are to be sorted. Valid values for sortCriteria parameters are:

  • key -. Name of the element in documentList whose value provides the value based on which the documents are to be sorted. The value for key can be a path expression. For example, “Family/Chidren[0]/BirthDate” retrieves the birthday of the first child from the input Family document list.

  • order: Optional - Allowed values are ascending and descending. The default value is ascending.

  • compareStringsAs: Optional - Allowed values are string, numeric, and datetime. Default value is string.

  • pattern: Optional - The value for pattern will be considered only if the compareStringsAs value is of type datetime.

  Note

  If key is not found in all the input documents, the sorted list of documents appears at the end or start of the list based on the order specified. If the order is ascending, then all the documents that do not match the sort criteria appears at the top of the list, followed by the sorted list. If the order is descending, the sorted list will appear at the top, followed by the documents that do not match the sort criteria.

Output Parameters

• documents: Document List - The documents sorted based on the sort criteria specified in the sortCriteria parameter.

Usage Notes

For example, if you want to sort a set of documents based on name, age, and then on birth date, the values for sortCriteria parameter would be:

Flat File Services

Use Flat File services to convert data bytes, data stream, and data string to a document and vice versa.

The following Flat File services are available:

delimitedDataBytesToDocument

Converts delimited data bytes (byte array) to a document.

Input Parameters

• delimitedDataBytes: java.lang.Byte[ ] - Delimited data in bytes (Byte array) to convert to a document.

• fieldQualifier: String Optional - The delimiter to use for separating entries in delimitedDataBytes. Default is comma (,).

• textQualifier: String Optional - The character to use for quoted elements. Default is double quote (“).

• useHeaderRowForFieldNames: String Optional - Consider first line as header row and use the delimited data of this line as property names in the output document.

  Set to:

  • true - The delimited data of first line will be used as the property name in the output document. This is the default.

  • false - column1, column2…columnN will be used as the property name in the output document.

• skipBOMBytes: Optional - The default value is False. Set the parameter to True to ensure proper file parsing and avoid integration issues. When the value is set to true, it automatically skips the ByteOrderMark bytes from the input stream which includes an encoded ByteOrderMark as its first bytes.

• encoding: String Optional - The encoding to use while parsing the delimited data.

Output Parameters

• document: Document - Document resulting from the conversion of delimitedDataBytes. This document contains document array rows[ ] corresponding to the delimited data.

delimitedDataStreamToDocument

Converts delimited data stream to a document. The permissible size of the content stream is based on your tenancy.

Input Parameters

• delimitedDataStream: java.io.InputStream - Delimited data in an input stream to convert to a document.

• fieldQualifier: String Optional - The delimiter to use for separating entries in delimitedDataStream. Default is comma (,).

• textQualifier: String Optional - The character to use for quoted elements. Default is double quote (“).

• useHeaderRowForFieldNames: String Optional - Consider first line as header row and use the delimited data of this line as property names in the output document.

  Set to:

  • true - The delimited data of first line will be used as the property name in the output document. This is the default.

  • false - column1, column2…columnN will be used as the property name in the output document.

• skipBOMBytes: Optional - Automatically skips the ByteOrderMark bytes from the input stream which includes an encoded ByteOrderMark as its first bytes.

• encoding: String Optional - The encoding to use while parsing the delimited data.

Output Parameters

• document: Document - Document resulting from the conversion of delimitedDataStream. This document contains document array rows[ ] corresponding to the delimited data.

delimitedDataStringToDocument

Converts delimited data string to a document.

Input Parameters

• delimitedDataString: String - Delimited string to convert to a document.

• fieldQualifier: String Optional - The delimiter to use for separating entries in delimitedDataString. Default is comma (,).

• textQualifier: String Optional - The character to use for quoted elements. Default is double quote (“).

• useHeaderRowForFieldNames: String Optional - Consider first line as header row and use the delimited data of this line as property names in the output document.

  Set to:

  • true - The delimited data of first line will be used as the property name in the output document. This is the default.

  • false - column1, column2…columnN will be used as the property name in the output document.

• encoding: String Optional - The encoding to use while parsing the delimited data.

Output Parameters

• document: Document - Document resulting from the conversion of delimitedDataString. This document contains document array rows[ ] corresponding to the delimited data.

documentToDelimitedDataBytes

Converts a document to delimited data bytes (byte array object).

Input Parameters

• document: Document - Document to be converted to delimited data bytes (byte array object). This document contains document array rows[ ] corresponding to the delimited data.

• fieldQualifier: String Optional - The delimiter to use for separating entries in delimitedDataBytes. Default is comma (,).

• textQualifier: String Optional - The character to use for quoted elements. Default is double quote (“).

• useFieldNamesForHeaderRow: String Optional - The first line in the output delimited data delimitedDataBytes will be constructed using the property names in the input document array document\rows[ ].

  Set to:

  • true - Property names in the input document array document\rows[ ] will be used as the first row in the output delimitedDataBytes.

  • false - column1, column2…columnN will be used as the first row in the output delimitedDataBytes.

• encoding: String Optional - The encoding to use while parsing the delimited data.

Output Parameters

• delimitedDataBytes: Object - Delimited data byte array object resulting from the conversion of a document.

documentToDelimitedDataStream

Converts a document to a delimited data stream.

Input Parameters

• document: Document - Document to be converted to delimited data stream. This document contains document array rows[ ] corresponding to the delimited data.

• fieldQualifier: String Optional - The delimiter to use for separating entries in delimitedDataStream. Default is comma (,).

• textQualifier: String Optional - The character to use for quoted elements. Default is double quote (“).

• useFieldNamesForHeaderRow: String Optional - The first line in the output delimited data delimitedDataStream will be constructed using the property names in the input document array document\rows[ ].

  Set to:

  • true - Property names in the input document array document\rows[ ] will be used as the first row in the output delimitedDataStream.

  • false - column1, column2…columnN will be used as the first row in the output delimitedDataStream.

• encoding: String Optional - The encoding to use while parsing the delimited data.

Output Parameters

• delimitedDataStream: java.io.InputStream - Delimited data stream resulting from the conversion of a document.

documentToDelimitedDataString

Converts a document to a delimited data string.

Input Parameters

• document: Document - Document to be converted to delimited data string. This document contains document array rows[ ] corresponding to the delimited data.

• fieldQualifier: String Optional - The delimiter to use for separating entries in delimitedDataString. Default is comma (,).

• textQualifier: String Optional - The character to use for quoted elements. Default is double quote (“).

• useFieldNamesForHeaderRow: String Optional - The first line in the output delimited data delimitedDataString will be constructed using the property names in the input document array document\rows[ ].

  Set to:

  • true- Property names in the input document array document\rows[ ] will be used as the first row in the output delimitedDataString.

  • false - column1, column2…columnN will be used as the first row in the output delimitedDataString.

• encoding: String Optional - The encoding to use while parsing the delimited data.

Output Parameters

• delimitedDataString: String - Delimited data byte string resulting from the conversion of a document.

Flow Services

Use flow services to perform utility-type tasks.

The following flow services are available:

clearPipeline

Removes all fields from the pipeline. You may optionally specify fields that should not be cleared by this service.

Input Parameters

• preserve: String List Optional - Field names that should not be cleared from the pipeline.

Output Parameters

None.

countProcessedDocuments

Counts the number of documents processed by a flow service. Details about the processed documents can be viewed in the Execution Results screen.

Input Parameters

• status: String Optional - Valid values are success or fail. Set status to success to count the number of successfully processed documents, else set it to fail. Default value is success.

• incrementBy: String Optional - Increment the number of documents processed by a flow service. Every time the service is used, successful or failed documents are incremented by the given value. Default value is 1.

Output Parameters

None.

Usage Notes

To increment the number of documents processed by a list, use the sizeOfList service in the List service category.

getHTTPRequest

Retrieves information about the HTTP request, received by IBM webMethods Integration.

Input Parameters

None.

Output Parameters

• httpRequest: Document - Contains the HTTP request received by IBM webMethods Integration and includes following details:

  • headers: Document - Contains the header fields from the HTTP request.

  • requestURL: String - URL used by the client to invoke the service.

  • method: String - HTTP method used by the client to request the top-level service. Possible values are GET, PUT, POST, PATCH, and DELETE.

  Note

  The getHTTPRequest service does not retrieve the Authorization header.

getLastError

Obtains detailed information about the last error that was trapped within a flow service.

Input Parameters

None.

Output Parameters

• lastError: Document - Information about the last error, which contains details of the time, error, user, block, and call stack information.

  • time: String - Date and time the event occurred, in the format yyyy/MM/dd HH:mm:ss.SSS

  • error: String Optional - Error message of the exception.

  • localizedError: String Optional - Error message in the language that corresponds to the server locale.

  • user: String - User who executed the flow service.

  • block: Document - Contains the following fields:

    • name: String - flow service, Operation, or Service name.

    • type: String - Connector, flow service, or Service.

    • details: String Optional - Account and Application name if the Block Type is Application.

  • callStack: Document List - The call stack information describing where the error occurred including details of the block. Each document represents a block on the call stack. The first document in the list represents the block that threw the error and the last document in the list represents the top level block. It contains the following fields:

    • name: String - flow service, Operation or Service name.

    • type: String - Connector, flow service, or Service.

  • errorDetails: Document Optional - Additional exception information.

Usage Notes

You can use this service in the catch section of the try-catch block. Each execution of a flow service or a service (whether the flow service or the service succeeds or fails) updates the value returned by getLastError. Consequently, getLastError itself resets the value of lastError. Therefore, if the results of getLastError will be used as input to subsequent flow services, map the value of lastError to a variable in the pipeline.

If a map has multiple transformers, then a subsequent call to getLastError will return the error associated with the last failed transformer in the map, even if it is followed by successful transformers.

getLastFailureCaught

Returns information about the last failure that was caught by a CATCH step.

Input Parameters

None.

Output Parameters

• failure: Object - Last failure caught by a CATCH step. The failure parameter is null if no failure has been caught.

• failureMessage: String, Conditional - Message associated with the failure. The service returns a failureMessage output parameter only if a failure has been caught.

• failureName: String, Conditional - Exception class name. The service returns a failureName output parameter only if a failure has been caught.

Usage Notes

If a CATCH step can handle multiple failures, use the getLastFailureCaught service to determine which failure the step caught.

You can rethrow a caught failure by using the getLastFailureCaught service to determine the failure caught by the CATCH step, then use an EXIT step that is configured to signal failure to rethrow the failure. getLastFailureCaught need not be executed within a CATCH step. The service returns the caught failure any time after it has been invoked.

getSessionInfo

Obtains detailed information about the current logged-in user session. Also provides the current flow service execution result reference identifier.

Input Parameters

None.

Output Parameters

• $session: Document - Returns information about the current logged-in user session. Also provides the current flow service name and the execution result reference identifier.

  • tenantId: String - Tenant Identifier.

  • stageId: String - The stage ID where the current flow service resides.

  • user: Document - Returns user details.

    • name: String - Name of the user who is executing the service.

​
​ - CustomContextID: String - Returns the current flow service execution context ID. You can set the context ID in a flow service by using the setCustomContextID service available under the Flow category. ​
​ - integrationName: String - The name of the flow service. If flow service A has a referenced flow service B, and if the getSessionInfo service is called in flow service B, then integrationName will be A but if flow service B is executed independently, then integrationName will be B. ​
​ - executionResultReference: String - Returns the current flow service execution result reference identifier. For example, you can pass the identifier to an on-premises operation and trace the flow service execution.

getRetryCount

Retrieves the retry count and the maximum retry count for a flow service.

The retry count indicates the number of times the IBM webMethods Integration system has re-executed a flow service. For example, a retry count of 1 indicates that the IBM webMethods Integration system tried to execute the flow service twice (the initial attempt and then one retry).

The maximum retry count indicates the maximum number of times the IBM webMethods Integration system can re-execute the flow service if it continues to fail because of a transient error.

Input Parameters

None.

Output Parameters

• retryCount: String - The number of times the IBM webMethods Integration system has re-executed the flow service.

• maxRetryCount: String The maximum number of times the IBM webMethods Integration system can re-execute the flow service.

Usage Notes

Although the getRetryCount service can be invoked at any point in a flow service, the getRetryCount service retrieves retry information for the flow service when invoked by a subscriber. The getRetryCount service does not retrieve retry information for a nested flow service (a flow service that is invoked by another flow service).

The maximum number of times IBM webMethods Integration retries a flow service depends on the retry properties set in the subscriber that invokes the flow service.

logCustomMessage

Logs a message, which can be viewed in the Execution Results screen.

Input Parameters

• message: String - Custom message to be logged, which can be viewed in the Execution Results screen.

Output Parameters

None.

setCustomContextID

Associates a custom value with an auditing context. This custom value can be used to search for flow service executions in the Monitor screen.

Input Parameters

• id: String Optional - The custom value for the current auditing context. Specify a value that you want to associate with the auditing context. The ID length must be less than or equal to 36 characters. In the event that an ID exceeds 36 characters, only the first 36 characters are stored.

Output Parameters

None.

Usage Notes

• Each client request creates a new auditing context. The auditing context is the lifetime of the top-level service. Once the custom context identifier is set, IBM webMethods Integration includes that value in each service audit record it logs in the current context. Calls to this service affect audit logging only for the current request.
• This service is useful when IBM webMethods Integration is configured to log to a database. When the server logs information about a service to the database, it includes the custom context identifier in the service log. On the IBM webMethods Integration Monitor screen, you can use the custom value as search criteria to locate and view all corresponding service audit records.
• If IBM webMethods Integration is configured to log to a file system, IBM webMethods Integration writes the custom context identifier with the service audit records to a file. This file is not accessible on the Monitor screen. You cannot query service records when logging to a file.
• If this service is invoked without a specified value for id, IBM webMethods Integration writes a null value for the custom context identifier field for all subsequent service audit records that it logs in the current context.

setHTTPResponse

Sets the HTTP response information to be returned by IBM webMethods Integration.

Input Parameters

• httpResponse: Document - Contains the HTTP response that will be returned by IBM webMethods Integration and includes following details:

  • headers: Document Optional - Contains the header fields to be returned in the HTTP response.

  • responseCode: String Optional - HTTP status code to be returned to the client. The response codes and phrases are defined in https://tools.ietf.org/html/rfc7231#section-6. If you provide a value for responseCode that is not listed in RFC 7321, Section 6, you must also provide a value for reasonPhrase.

  • responsePhrase: String Optional - HTTP reason phrase to be returned to the client. If no reason is provided, the default reason phrase associated with responseCode will be used. You must provide a reasonPhrase for any responseCode that is not listed in RFC 7321, Section 6.

  • responseString: String Optional - Response to be returned to the client, specified as a string.

  • responseBytes: byte[ ] Optional - Response to be returned to the client, specified as a byte array.

  • responseStream: java.io.InputStream Optional - Response to be returned to the client, specified as an InputStream.

Output Parameters

None.

sleep

Causes the currently executing flow service to pause for the specified number of seconds.

Input Parameters

• seconds: String - The number of seconds to pause the currently executing flow service. The value must be an integer between 1 second and 60 seconds.

Output Parameters

None.

throwExceptionForRetry

Throws an exception and instructs IBM webMethods Integration to re-execute the flow service using the original service input.

Input Parameters

• wrappedException: Object Optional - Any exception that you want to include as part of this exception. This might be the exception that causes the throwExceptionForRetry service to execute. For example, if a Salesforce connector fails to connect to the server due to connection timeout you can use this service inside Catch block to retry the flow service again.

• message: String Optional - A message to be logged as part of this exception.

Output Parameters

None.

Usage Notes

Use the throwExceptionForRetry service to handle transient errors that might occur during flow service execution. A transient error is an error that arises from a condition that might be resolved quickly, such as the unavailability of a resource due to network issues or failure to connect to a database. The flow service might execute successfully if IBM webMethods Integration waits and then retries the flow service. If a transient error occurs, the flow service can catch this error and invoke throwExceptionForRetry to instruct the to retry the service.

The throwExceptionForRetry service must be used for transient errors only.

Only top-level services or subscribers can be retried. That is, a service can be retried only when it is invoked directly by a client request or by a subscriber. The service cannot be retried when it is invoked by another flow service (that is, when it is a nested flow service).

You can invoke the getRetryCount service to retrieve the current retry count and the maximum specified retry attempts.

Hashtable Services

Use Hashtable services to create, update, and obtain information about the hashtable.

The following Hashtable services are available:

containsKey

Checks for the existence of a hashtable element.

Input Parameters

• hashtable: java.util.Hashtable - Hashtable in which to check for the existence of a hashtable element.

• key: String - Hashtable element to be checked for.

Output Parameters

• containsKey: String - Indicates whether the specified hashtable element exists.

  A value of:

  • true - Indicates that the element exists.

  • false - Indicates that the element does not exist.
    

createHashtable

Creates a hashtable object.

Input Parameters

None.

Output Parameters

• hashtable: java.util.Hashtable - The new hashtable object.

get

Gets the value for a specified key in the hashtable.

Input Parameters

• hashtable: java.util.Hashtable - Hashtable from which to retrieve the specified value.

• key: String - Key of the hashtable element whose value is to be retrieved.

Output Parameters

• value: Object - Value of the input hashtable element.

listKeys

Lists all the keys stored in the hashtable.

Input Parameters

• hashtable: java.util.Hashtable - Hashtable from which the keys are to be listed.

Output Parameters

• keys: String[ ] - List of keys stored in the input hashtable.

put

Adds a key/value pair in the hashtable.

Input Parameters

• hashtable: java.util.Hashtable - Hashtable to which the key/value pair is to be added.

• key: String - Key of the element to be added to the hashtable.

• value: Object - Value of the element to be inserted into the hashtable.

Output Parameters

• hashtable: java.util.Hashtable - Hashtable object after the insertion of the key/value pair.

remove

Removes a key/value pair from the hashtable.

Input Parameters

• hashtable: java.util.Hashtable - Hashtable from which to remove the key/value pair.

• key: String - Key of the hashtable element to be removed.

Output Parameters

• hashtable: java.util.Hashtable - Hashtable object after the key/value pair is removed.

• value: Object - Value of the hashtable element that was removed. Returns null if the input key is not found in the hashtable.

size

Gets the number of elements in the hashtable.

Input Parameters

• hashtable: java.util.Hashtable - Hashtable from which the number of elements stored in it is to be retrieved.

Output Parameters

• size: String - Number of elements in the hashtable.

IO Services

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 and 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 run if they are invoked from a client.

The following IO services are available:

bytesToStream

Converts a byte[ ] to java.io.ByteArrayInputStream.

Input Parameters

• bytes: byte[ ] - The byte array to convert.

• length: String Optional - The maximum number of bytes to read and convert. If length is not specified, the default value for this parameter is the length of the input byte array.

• offset: String Optional - The offset into the input byte array from which to start converting. If no value specified, the default value is zero.

Output Parameters

• stream: java.io.ByteArrayInputStream - An open InputStream created from the contents of the input bytes parameter.

Usage Notes

This service constructs stream from the byte array using the constructor ByteArrayInputStream(byte[ ]). This constructor does not make a copy of the byte array, so any changes to bytes will be reflected in the data read from the stream.

close

Closes an InputStream or a reader object and releases the resources.

Input Parameters

• inputStream: java.io.InputStream. Optional - An open InputStream.

• reader: java.io.Reader.Optional - An open reader object.

Output Parameters

None.

Usage Notes

If the InputStream is already closed, invoking this service has no effect. However, leaving an InputStream open may cause errors that may not be recoverable. Use the close service to explicitly close the input stream when a service leaves it open.

createByteArray

Creates a byte array of the specified length.

Input Parameters

• length: String. The length of the byte array to be created.

Output Parameters

• bytes: Object The new byte array.

Usage Notes

The read service reads data from an InputStream into a byte array. You can use this service to create the byte array. Invoking this service is the equivalent of the Java code new byte[length].

mark

Marks the current position in the InputStream or reader object. A subsequent call to reset repositions this stream at the last marked position. Marking and respositioning the input stream allows subsequent service calls to re-read the same bytes.

Input Parameters

• stream: java.io.InputStream. Optional - The InputStream.

• reader: java.io.Reader. Optional - The reader object.

• limit: String - The maximum number of bytes that can be read before the mark position becomes invalid. If more than this number of bytes are read from the stream after the mark service is invoked, the reset service will have no effect.

Output Parameters

• stream: java.io.InputStream. Conditional - The InputStream. Returned only if the input parameter is stream.

• reader: java.io.Reader. Conditional - The reader object. Returned only if the input parameter is reader.

Usage Notes

If the InputStream does not support the mark operation, invoking this service has no effect.

Either of the optional input parameters, stream or reader, is required.

markSupported

Enables you to test whether your InputStream or reader object supports the mark and reset operations.

Input Parameters

• stream: java.io.InputStream. Optional - The InputStream.

  Note

  You can use either stream or reader to specify the input object. If both stream and reader input parameters are provided, then the stream input parameter is ignored.

• reader: java.io.Reader. Optional - The reader object.

Output Parameters

• stream: java.io.InputStream. Conditional - The InputStream. Returned only if the input parameter is stream.

• supported: String - Indicates whether the stream supports the mark and reset operations. A value of:

  • true indicates that the InputStream supports the mark and reset operations.

  • false indicates that the InputStream does not support the mark and reset operations.

• reader: java.io.Reader. Conditional - The reader object. Returned only if the input parameter is reader.

Usage Notes

Either of the input parameters, stream or reader, is required.

read

Reads a specified number of bytes from the InputStream and stores them into a buffer.

Input Parameters

• stream: Object - The InputStream. Object from which the service is to read bytes.

• offset: String. Optional - The offset into the byte array in the buffer to which the data is written. If no value is supplied, this defaults to 0.

• length: String. Optional - The maximum number of bytes to read from the InputStream. If no value is supplied, the default is the length of buffer. If the value supplied for length is greater than the length of buffer, an exception will be thrown.

• buffer: Object - The buffer into which data is written. This is a byte array, which can be created from a flow service by invoking createByteArray.

Output Parameters

• stream: Object - The InputStream. If any bytes were read from the stream, the stream is repositioned after the last byte read.

• buffer: Object - The buffer into which data was written.

• bytesRead: String - The number of bytes read from the InputStream and copied to buffer. If there is no more data because the end of the stream has been reached, bytesRead will be -1.

readAsString

Reads the data from a reader object and returns the contents as a string.

Input Parameters

• reader: java.io.Reader - The reader object.

• length: String - The maximum number of characters to read from the input reader object.

Output Parameters

• reader: java.io.Reader - The reader object.

• lengthRead: String - The number of characters read from the input reader object. If there is no more data because the end of the stream has been reached, lengthRead will be -1.

• value: String - The data read from the reader object, or null if end of stream has been reached.

Usage Notes

The readAsString service does not automatically close the reader object. To close the reader, use the close service.

readerToString

Reads the data from a reader object and converts it to a string.

Input Parameters

• reader: java.io.Reader - The reader object.

Output Parameters

• string: String - Data read from the reader object.

Usage Notes

The readerToString service does not automatically close the reader object. To close the reader, use the close service.

reset

Repositions the InputStream or the reader object to the position at the time the mark service was last invoked on the stream.

Input Parameters

• stream: java.io.InputStream. Optional - The InputStream.

  Note

  You use either stream or reader to specify the input object. If both stream and reader input parameters are provided, then both the objects will be reset.

• reader: java.io.Reader. Optional - The reader object.

Output Parameters

• stream: java.io.InputStream. Conditional - The InputStream. Returned only if the input parameter is stream.

• reader: java.io.Reader. Conditional - The reader object. Returned only if the input parameter is reader.

Usage Notes

If the InputStream does not support the reset operation, invoking this service has no effect.

Either of the input parameters, stream or reader, is required.

skip

Skips over and discards the specified number of bytes or characters from the input stream or a reader object.

Input Parameters

• stream: java.io.InputStream. Optional - The InputStream.

• reader: java.io.Reader. Optional - The reader object.

• length: String - The number of bytes or characters to skip.

Output Parameters

• stream: java.io.InputStream. Conditional - The InputStream. Returned only if the input parameter is stream.

• reader: java.io.Reader. Conditional - The reader object. Returned only if the input parameter is reader.

• bytesSkipped: String. Conditional - The actual number of bytes that were skipped. Returned only if the input parameter is stream.

• charactersSkipped: String. Conditional - The number of characters that were skipped. Returned only if the input parameter is reader.

Usage Notes

The Skip service uses the Java methodskip, which might skip some smaller number of bytes, possibly zero (0). This happens due to conditions such as reaching the end of file before n bytes have been skipped. For more information about the skip method, see the Java documentation on the InputStream class.

Either of the optional input parameters, stream or reader, is required.

If both stream and reader input parameters are specified and if an exception occurs during the stream object usage, then the operations are not performed on the reader object also.

streamToBytes

Creates a byte[ ] from data that is read from an InputStream.

Input Parameters

• stream: java.io.InputStream - The InputStream that you want to convert.

Output Parameters

• bytes: byte[ ] - The bytes read from stream.

Usage Notes

This service reads all of the bytes from stream until the end of file is reached, and then it closes the InputStream.

streamToReader

Converts a java.io.InputStream to a java.io.Reader object.

Input Parameters

• inputStream: java.io.InputStream - The InputStream to convert to a reader object.

• encoding: String. Optional - Name of a registered, IANA character set (for example, ISO-8859-1). If you specify an unsupported encoding, the system throws an exception. If no value is specified or if the encoding is set to autoDetect, the default operating system encoding is used.

Output Parameters

• reader: java.io.Reader - The reader object read from inputStream.

streamToString

Creates a string from data that is read from an InputStream.

Input Parameters

• inputStream: java.io.InputStream - The InputStream to convert to a string.

• encoding: String Optional - Name of a registered, IANA character set (for example, ISO-8859-1). If you specify an unsupported encoding, the system throws an exception. If no value is specified the encoding will be UTF-8.

Output Parameters

• string: String - Data read from inputStream and converted to a string.

stringToReader

Converts a string object to a StringReader object.

Input Parameters

• string: String - The string to convert to a StringReader object.

Output Parameters

• reader: java.io.StringReader - The StringReader object.

stringToStream

Converts a string to a binary stream.

Input Parameters

• string: String - The string object to be converted.

• encoding: String - Optional. Name of a registered, IANA character set, for example, ISO-8859-1. If you specify an unsupported encoding, the system throws an exception. If no value is specified, the encoding will be UTF-8.

Output Parameters

• inputStream: java.io.ByteArrayInputStream - An open InputStream created from the contents of string.

JSON Services

Use JSON services to convert JSON content into a document and to convert a document into JSON content.

The following JSON services are available:

closeArrayIterator

Closes the iteration. The iterator object used in an iteration cannot be reused after this service runs.

Input Parameters

• iterator: Object - The iterator object returned by the getNextBatch service.

Output Parameters

None.

documentToJSONBytes

Converts a document to JSON bytes (byte array).

Input Parameters

• document: Document - The document to be converted to JSON bytes (byte array).

• encodeDateAs: String. Optional. Specifies how java.util.Date instances in the document are encoded in the returned JSON.

  • long to encode java.util.Date instances as timestamps, specifically the number of milliseconds since Jan 1, 1970 00:00:00.

  • ISO8601 to encode java.util.Date instances as strings in a standard ISO format of: YYYY-MM-DD’T’HH:mm:ss.sssZ.

  • ISO_LOCAL_DATE to encode java.util.Date instances as strings in a standard ISO format without an offset.

  • ISO_DATE to encode java.util.Date instances as strings in a standard ISO format with the offset if available.

  • ISO_ZONED_DATE_TIME to encode java.util.Date instances as strings in a standard ISO format with the offset and zone if available.

  • ISO_INSTANT to encode java.util.Date instances as strings in a standard ISO format in UTC.

  • BASIC_ISO_DATE to encode java.util.Date instances as strings in a standard ISO format without an offset.

  • RFC_1123_DATE_TIME to encode java.util.Date instances as strings in a standard ISO format.

  • null to use the dateEncoding setting already in effect for the HTTP client making the request.

• encodeStringAsNumber: String. Optional.

  • true, to convert all the numbers in the string format to numbers by removing the quotes.

  • false, to retain all the numbers without converting.

  The default value is false.

• encodeStringAsBoolean: String. Optional.

  • true, to convert all the boolean values in the string format to Boolean by removing the quotes.

  • false, to retain all the boolean values without converting.

  The default value is false.

Output Parameters

• jsonBytes: Object - JSON bytes (byte array) resulting from the conversion of a document.

documentToJSONStream

Converts a document to a JSON stream.

Input Parameters

• document: Document - The document to be converted to a JSON stream.

• encodeDateAs: String. Optional. Specifies how java.util.Date instances in the document are encoded in the returned JSON.

  • long to encode java.util.Date instances as timestamps, specifically the number of milliseconds since Jan 1, 1970 00:00:00.

  • ISO8601 to encode java.util.Date instances as strings in a standard ISO format of: YYYY-MM-DD’T’HH:mm:ss.sssZ.

  • ISO_LOCAL_DATE to encode java.util.Date instances as strings in a standard ISO format without an offset.

  • ISO_DATE to encode java.util.Date instances as strings in a standard ISO format with the offset if available.

  • ISO_ZONED_DATE_TIME to encode java.util.Date instances as strings in a standard ISO format with the offset and zone if available.

  • ISO_INSTANT to encode java.util.Date instances as strings in a standard ISO format in UTC.

  • BASIC_ISO_DATE to encode java.util.Date instances as strings in a standard ISO format without an offset.

  • RFC_1123_DATE_TIME to encode java.util.Date instances as strings in a standard ISO format.

  • null to use the dateEncoding setting already in effect for the HTTP client making the request.

• encodeStringAsNumber: String. Optional.

  • true, to convert all the numbers in the string format to numbers by removing the quotes.

  • false, to retain all the numbers without converting.

  The default value is false.

• encodeStringAsBoolean: String. Optional.

  • true, to convert all the boolean values in the string format to Boolean by removing the quotes.

  • false, to retain all the boolean values without converting.

  The default value is false.

Output Parameters

• jsonStream: java.io.InputStream - JSON stream resulting from the conversion of a document.

documentToJSONString

Converts a document to a JSON string.

Input Parameters

• document: Document - The document to be converted to a JSON string.

• prettyPrint: String - Formats the jsonString output parameter for human readability by adding carriage returns and indentation to the JSON content.

  Set to:

  • true to format the jsonString output field for human readability.

  • false to leave the jsonString output field in its unformed state.

  The service will not add any additional carriage returns or indentation to the JSON content.

• encodeDateAs: String. Optional. Specifies how java.util.Date instances in the document are encoded in the returned JSON.

  • long to encode java.util.Date instances as timestamps, specifically the number of milliseconds since Jan 1, 1970 00:00:00.

  • ISO8601 to encode java.util.Date instances as strings in a standard ISO format of: YYYY-MM-DD’T’HH:mm:ss.sssZ.

  • ISO_LOCAL_DATE to encode java.util.Date instances as strings in a standard ISO format without an offset.

  • ISO_DATE to encode java.util.Date instances as strings in a standard ISO format with the offset if available.

  • ISO_ZONED_DATE_TIME to encode java.util.Date instances as strings in a standard ISO format with the offset and zone if available.

  • ISO_INSTANT to encode java.util.Date instances as strings in a standard ISO format in UTC.

  • BASIC_ISO_DATE to encode java.util.Date instances as strings in a standard ISO format without an offset.

  • RFC_1123_DATE_TIME to encode java.util.Date instances as strings in a standard ISO format.

  • null to use the dateEncoding setting already in effect for the HTTP client making the request.

• encodeStringAsNumber: String. Optional.

  • true, to convert all the numbers in the string format to numbers by removing the quotes.

  • false, to retain all the numbers without converting.

  The default value is false.

• encodeStringAsBoolean: String. Optional.

  • true, to convert all the boolean values in the string format to Boolean by removing the quotes.

  • false, to retain all the boolean values without converting.

  The default value is false.

Output Parameters

• jsonString: Object - JSON string resulting from the conversion of a document.

getArrayIterator

Returns a batch iterator object.

Input Parameters

• jsonStream: Object - JSON content to be converted to a document (an IData object).

• arrayPaths: String List - The paths of the arrays to be parsed in the JSON input stream. Only the array elements from the paths mentioned in this parameter are considered even though the JSON stream might have more data. For example, to retrieve toppingA1 from the following JSON content, provide the array path as, /topping/0/toppingA/0/toppingA1.

"topping": [{ 
            "toppingA": [{ 
                    "toppingA1": ["None71", "Glazed82"] 
... 
                }]}]
                

• containsKey: String - Indicates whether the specified hashtable element exists. A value of:

  • true - Indicates that the element exists.

  • false - Indicates that the element does not exist.

• decodeRealAsDouble: String. Optional - Converts real numbers from jsonStream to either a Float or Double Java wrapper type. Set to:

  • true to convert real numbers to Double Java wrapper type. This is the default.

  • false to convert real numbers to Float Java wrapper type.

  Note

  The decodeRealAsDouble parameter overrides the value specified by the decodeRealAsDouble server configuration parameter. If no value is supplied for decodeRealAsDouble, IBM webMethods Integration uses the value set for decodeRealAsDouble server configuration parameter.

• decodeIntegerAsLong: String. Optional - Converts integers from jsonStream to either a Long or Integer Java wrapper type. Set to:

  • true to convert integers to Long Java wrapper types. This is the default.

  • false to convert integers to Integer Java wrapper types.

  Note

  The decodeIntegerAsLong parameter overrides the value specified by the decodeIntegerAsLong server configuration parameter. If no value is supplied for decodeIntegerAsLong, IBM webMethods Integration uses the value specified in the decodeIntegerAsLong server configuration parameter.

• decodeRealAsString: String. Optional - Converts real numbers in the jsonStream to String. Set to:

  • true to convert real numbers to String.

  • false to not convert real numbers to String. The real numbers are then converted to either Float or Double Java wrapper type depending on the value specified in decodeRealAsDouble. This is the default value.

  Note

  The decodeRealAsString parameter overrides the value specified by the decodeRealAsString server configuration parameter. If no value is supplied for decodeRealAsString, IBM webMethods Integration uses the value set in decodeRealAsString server configuration parameter.

• unescapeSpecialChars: String. Optional - Controls whether IBM webMethods Integration unescapes the special characters ‘\n’, ‘\r’, ‘\t’, ‘\b’, ‘\f’, ‘\\’, ‘\”’ while parsing JSON documents. Set to:

  • true to unescape these special characters (that is, ‘\n’ will be replaced with new line, similarly other characters will also be replaced) in the output document. This is the default.

  • false to keep these characters as is in the output document.

  Note

  The unescapeSpecialChars parameter overrides the value specified by the unescapeSpecialChars server configuration parameter. If no value is supplied for unescapeSpecialChars, IBM webMethods Integration uses the value specified in the unescapeSpecialChars server configuration parameter.

Output Parameters

• iterator: Object - A batch iterator object that has the list of arrays to be parsed in the JSON input stream. This object is passed as input to the getNextBatch service.

Usage Notes

None.

getNextBatch

Gets the next batch of array elements by parsing the array paths in the iterator object returned by the getArrayIterator service. This service returns the array elements in batches based on the batch size provided in the input. The batch size can vary across invocations of this service. A batch is a set of elements that can be retrieved from an array path at once, based on the batch size. To retrieve the remaining elements in the array path or elements from the next array path in the iterator, invoke the service in a loop until there are no more array paths to iterate.

Input Parameters

• iterator: Object - The iterator object returned by the getArrayIterator service.

• batchSize: Object - Number of array elements that the service should retrieve in one batch.

  Note

  This value must be lesser or equal to the value of the iterator.maxBatchSize server configuration property. Similarly, it must be greater or equal to the value of the iterator.minBatchSize server configuration property. Otherwise, the service throws an error.

Output Parameters

• batch: Document - IData object that contains the following keys.

  • arrayPath: String - The path of the array elements retrieved in a batch. Since the service can iterate over multiple arrays, each batch contains the array path parsed in current iteration to help you identify the array to which the elements in the batch belong.

  • documents [ ]: Document List - If array elements in the batch are JSON objects, they are returned as documents.

  • values [ ]: Object List - If array elements in the batch are not JSON objects, they are returned as values.

• iterationStatus: Document - IData object that contains the following keys.

  • hasNext: String - Indicates whether there are more array elements in the iterator beyond this batch, which the service can retrieve. The value can be true or false.

  • iteration: String - Indicates the current iteration. It starts from 1. If the service runs N times to get all the array elements, then this value is N.

  • numberOfElementsInBatch: String - Indicates the number of elements in the current batch. This value is same as batchSize. However, this value can be less than the batch size for the last batch. For example, if there are 7 elements in an array and the batch size is 5, then the last batch will have only 2 elements.

  • totalElementsParsed: String - Indicates the number of array elements parsed until the current iteration. For example, if the number of elements parsed in the first iteration is 10, second iteration is 20, and third iteration is 7, then in the third iteration, the value of this parameter is 37.

Usage Notes

The getNextBatch service completes the retrieval of elements from one array in the iterator and starts retrieving from the next array that matches in the subsequent iteration. This is explained in the following example:

Suppose you want the service to parse a JSON file with 2 arrays, for example, A and B with 6 and 2 elements each. Set the batchSize input parameter to 5 and invoke the service in a loop until the service returns the hasNext parameter as false. In the first batch of the output, the first 5 elements of the array A are returned and in the next batch, only the last element of the array A is returned, even though the batch size is 5. At this point, the hasNext parameter is true because array B is not parsed yet. In the next batch, the service returns both the elements of array B. Since there are no more elements left either in the array A or B, the hasNext parameter becomes false.

Guidelines

• If two array paths overlap, the path that the service finds first in the input JSON stream is parsed and the other path is ignored. If you provide arrayPath[0] as /a/b and arrayPath[1] as /a/b/0/c to parse the following array, arrayPath[1] is ignored as the paths overlap and the first path retrieves all elements.

  { 
      "a": { 
          "b": [{ 
              "f1": "v1", 
              "c": [1, 2, 3] 
          }] 
      } 
  }

• If an invalid array path is provided in the input, the getNextBatch service does not return any result on parsing the array.

• If the arrayPaths input parameter is not set, then the getNextBatch service parses the input considering that the input stream has a single anonymous array at the root level.

• If the arrayPaths input parameter is set, then it cannot contain null or empty elements.

• If one or more array paths are invalid, then the getArrayIterator service still creates an iterator object containing these paths. However, the getNextBatch service ignores the invalid paths.

  If all the paths are invalid, the getNextBatch service returns the documents and values parameters as null, the hasNext parameter as false, and all other output parameters as 0.

jsonBytesToDocument

Converts JSON content in bytes (byte array) to a document.

Input Parameters

• jsonBytes: java.lang.Byte[ ] - JSON content in bytes (byte array) to convert to a document.

• decodeRealAsDouble - String Optional - Converts real numbers from jsonBytes to either a Float or Double Java wrapper type.

  Set to:

  • true to convert real numbers to Double Java wrapper types.

  • false to convert real numbers to Float Java wrapper types.

  Default value is true.

• decodeIntegerAsLong: String Optional - Converts integers from jsonBytes to either a Long or Integer Java wrapper type.

  Set to:

  • true to convert integers to Long Java wrapper types.

  • false to convert integers to Integer Java wrapper types.

  Default value is true.

• decodeRealAsString: String. Optional. Converts real numbers in the jsonStream to String. Set to:

  • true to convert real numbers to String.

  • false to not convert real numbers to String. The real numbers are then converted to either Float or Double Java wrapper type depending on the values specified in decodeRealAsDouble.

  Default value is false.

• decodeNullRootAsEmpty: String. Optional. Converts a null value that IBM webMethods Integration retrieves from JSON content to either IData or empty IData. Set to:

  • true to convert the null value to empty IData. The subsequent encoding of empty IData creates a JSON text of “{}”. This JSON content is different from the original JSON content (null) as the original null value gets converted to JSON text of “{}”.

  • false to convert the null value to IData.

  Default value is false.

• unescapeSpecialChars: String. Optional. Controls whether IBM webMethods Integration unescapes the special characters ‘\n’, ‘\r’, ‘\t’, ‘\b’, ‘\f’, ‘\’, ‘\“’ while parsing JSON documents. Set to:

  • true to unescape these special characters (that is, ‘\n’ will be replaced with new line, similarly other characters will also be replaced) in the output document.

  • false to keep these characters as is in the output document.

  Default value is true.

Output Parameters

• document: Document - Document resulting from the conversion of jsonBytes.

jsonStreamToDocument

Converts content from the JSON content stream to a document. The permissible size of the content stream is based on your tenancy.

Input Parameters

• jsonStream: java.io.InputStream - JSON content in an input stream to convert to a document.

• decodeRealAsDouble - String Optional - Converts real numbers from jsonStream to either a Float or Double Java wrapper type.

  Set to:

  • true to convert real numbers to Double Java wrapper types.

  • false to convert real numbers to Float Java wrapper types.

  Default value is true.

• decodeIntegerAsLong: String Optional - Converts integers from jsonStream to either a Long or Integer Java wrapper type.

  Set to:

  • true to convert integers to Long Java wrapper types.

  • false to convert integers to Integer Java wrapper types.

  Default value is true.

• decodeRealAsString: String. Optional. Converts real numbers in the jsonStream to String. Set to:

  • true to convert real numbers to String.

  • false to not convert real numbers to String. The real numbers are then converted to either Float or Double Java wrapper type depending on the values specified in decodeRealAsDouble.

  Default value is false.

• decodeNullRootAsEmpty: String. Optional. Converts a null value that IBM webMethods Integration retrieves from JSON content to either IData or empty IData. Set to:

  • true to convert the null value to empty IData. The subsequent encoding of empty IData creates a JSON text of “{}”. This JSON content is different from the original JSON content (null) as the original null value gets converted to JSON text of “{}”.

  • false to convert the null value to IData.

  Default value is false.

• unescapeSpecialChars: String. Optional. Controls whether IBM webMethods Integration unescapes the special characters ‘\n’, ‘\r’, ‘\t’, ‘\b’, ‘\f’, ‘\’, ‘\“’ while parsing JSON documents. Set to:

  • true to unescape these special characters (that is, ‘\n’ will be replaced with new line, similarly other characters will also be replaced) in the output document.

  • false to keep these characters as is in the output document.

  Default value is true.