Input and Output Fields Declaration

The Defined I/O feature specifies the input and output fields for a flow service. You can define the input and output fields from the Defined input and output fields screen. You can access the screen by clicking the I/O icon from the Flow Editortoolbar.

The Defined input and output fields page has two tabs:

  • Input Fields - Defines the fields that the flow service requires as input.
  • Output Fields - Defines 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 page. The field names are case-sensitive. For more information about the data types that are supported for the input and output fields, see Default Pipeline Mapping Rules and Behavior.

Guidelines for Defining Input and Output Fields

Declaring input and output fields for a flow service is optional. However, declaring the fields for every flow service that is created is a best practice for the following reasons:

  • Declaring fields makes the flow service’s input and output fields available in the pipeline.
  • Declaring fields enables 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 that is known to that 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 starts two other flow services, one that takes a field that is 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 starts 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 that are 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 that are 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 that are used by the constituent flow services, you must manually link them to one another.

  • Avoid that uses 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 start this flow service.

  • Make sure 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 that is 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.
  • Make sure that the names of output fields match the names that are used by the flow services that produce them. Like input fields, if the specified names do not match those produced by the flow service’s constituent services, you must manually link them. Avoid that uses 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 start this flow service.
  • Make sure 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 that is called AuthorizationCode, make sure 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 that is entered in a text field.
  • Large Editor if you want the input that is 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 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, suchas minimum value of a field or maximum length of a string. For example,
  • Password if you want the input that is enteredthat is as a password.
  • Large Editor if you want the input that is 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 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, suchas minimum value of a field or maximum length of a string.
  • Avoid that uses characters like / and & in field names, as they 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 page.

  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 by 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 composing of document references, and also define the signature of flow services composing of document references.|

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

  2. Select Document Reference in the Input Fields tab. The Choose Document Reference drop-down list appears to list 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 at run time. 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. At run time, 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 page.

Value Set

When running a service that uses IBM webMethods Integration, you frequently need to submit input values. A value set allows you to save these input values. If you need to run 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 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 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 icon and define the input fields channel and message.
  3. Click the mapping icon () and define the pipeline mapping.
  4. Click the Run. The Input values dialog box appears.
    Note: If you do not define any input fields in a flow service, then the Input values dialog box does not appear and the flow service executes directly.
  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.

    Note: If you do not define any input fields in a flow service, then the Input values dialog box does not appear and the flow service runs directly.
  6. 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 runtime 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.

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

Include Empty Values for String Types

The Include empty values for string types option in flow services ensures that string variables with empty values ("") are explicitly included in the output or passed downstream in the pipeline. By default, empty strings are omitted, resulting in the absence of those variables in the pipeline.

The Include empty values for string types option is enabled by default, and its setting is not persisted when toggled on or off. Enable or disable this option based on the wanted outcome. Enabling the option saves the string variable with empty values, while disabling it saves the string variable with null values.

Key points to consider when using the Include empty values for string types option in flow services:

  • With the Option Enabled (Default behavior):
    • If you do not provide a value for a string field in the input pipeline, its value defaults to an empty string ("") at run time.
  • With the Option Disabled:
    • If you do not provide a value for a string field in the input pipeline, its value defaults to null during runtime.
Note: The Include empty values for string types setting also applies to map set steps in flow services, ensuring that string fields without provided values are treated as empty strings ( "") instead of null.

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, a warning appears if a value with the same name is already set.

  • 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.
Note: The JSON file can be a maximum of 2 MB. Exceeding this limit may impact the performance of the user interface.

Download Input Values

The Download input values feature allows you to download the input values that are 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.