Skip to main content
Version: 10.2.9

Configure input and output contracts in Business Process steps

A contract defines the input and output of a BP element, such as a bot step, connector, Manual Task, Model step, and so on. Contracts allow designing a BP data schema in a no-code manner.

Only Business Processes of the schema-based design require setting up contracts. These are listed on the same Control Tower page as other BPs: navigate to Business Processes > View All.

If a BP is schema-based, you can see an appropriate icon next to it:

The same icon is displayed next to the BP name and schema-based steps on the BP Workflow tab.

Two types of contracts are available in a schema-based BP:

  • An input contract defines a set of fields required as input and their types. Only the fields listed in the input contract appear in the step's input data.
  • An output contract defines a set of fields produced by the step and their types.

If you drag a bot step configuration from the right panel to add to your workflow, the following logic is executed:

  • If a source bot configuration or a Manual Task has a component contract associated with it, a new step contract is created based on the component contract and linked to the new step.

  • If a source bot configuration or a Manual Task doesn’t have a component contract but is used in some BP with the step contract, a new step contract is created based on that step contract and linked to the new step. A step contract is taken from the most recent bot step.

You can also define empty contracts both for input and output:

  • An empty input contract is used for a step that does not require any input business data and is applicable, for example, when a BP is triggered by a timer and the first step does not need any data but instead makes a request and provides data for the downstream steps.
  • An empty output contract refers to a step that does not produce any business data and is used, for example, for clean-up steps or when a step contains some logic but does not produce any data for the BP.

View step contracts​

To view the contracts with mapping for a step, follow the steps below:

  1. Open a schema-based BP instance by clicking it in the Business Processes list.

  2. Navigate to the Workflow tab, find the required bot step in the flow, and double-click it to open the configuration panel.

  3. Go to the Input / Output tab.

    In the example above, the bot input contracts refer to the model_result step variable, and the bot output contract points to the invoice step variable.

  4. To see the contract mapping, move the pointer to the right of the Step variable drop-down list and click Show mapping.

    • For an input contract, Source variables appear next to the related step variables.

    • For an output contract, Destination variables appear next to the related step variables.

    To hide the selected mappings, move the pointer to the right of the variables and click Hide mapping.

    For nested variables, also see Apply data mapping.

Add contract​

tip

Users with advanced engineering skills can also add contracts to Bot Configs and Java Native Workers and import them with an Asset Bundle. For details, refer to Develop and import steps for schema-based Business Process.

To add a contract, follow the steps below:

  1. Open the Input / Output tab for the step where you want to add a contract as described in the View step contracts section.

  2. For a schemaless step, switch on the Enable Input / Output connection toggle.

  3. To add inputs or outputs, click + Input or + Output respectively.

  4. Configure the contract values:

    • In the Type drop-down list, select a variable type. The options are as follows:

      • Basic: boolean, string, number, integer
      • Custom objects
      • List
      • Variable types used in the BP

      To find a specific type, use the Search field.

      Click a type to select it. For custom types, move the pointer to the needed type and click Select.

    • Select a Step variable value. For an input contract, the list contains upstream variables; for an output contract, it includes downstream ones.

    • To map, set up Source values for inputs and Destination values for outputs as described in the Apply data mapping section.

  5. Click Save.

To remove one or more variables from the contract, move the pointer to the variable and click the Remove icon.

Manage custom schema objects​

In your contract, you can create custom schema objects and reuse them in other BPs if needed. To add a new custom object, complete the following steps:

  1. In the Type drop-down list, select Custom > New Object.

  2. In the Object name field, enter a name for the new object.

  3. To add a variable for the custom object, click Field.

    1. In the Variable field, enter the variable name.

    2. In the Type drop-down list, select the variable type.

    3. Click Add.

    To delete a field, move the pointer to the line to be deleted and click the Remove icon.

  4. After adding all required variables, click Save.

  5. On the Input / Output tab, click Save and then save the BP. The new schema object will appear in the list of custom types.

You can perform various actions with custom type definitions created manually. First, select a custom object from the Type drop-down list and click the Edit icon.

In the edit mode, you can:

  • Edit a custom object. Add or remove variables as described above and then click Save.

  • Share a custom object. Sharing a custom data schema object allows reusing it as often as you need across automations.

    info

    The feature is available since Work.AI v10.2.9.2.

    To enable sharing, open the Actions menu in the upper-right corner and switch on the Share toggle.

    Once shared, the object is marked as Shared. Click Save.

    To stop sharing, open the Actions menu, switch off the Share toggle, and click Save.

    note

    When you make changes to a custom object (edit or share), once you click Save, confirm the changes by clicking Save changes in the warning dialog. To discard changes, click Cancel.

  • Delete a custom object. Open the Actions menu and select Delete.

    Confirm the deletion by clicking Delete in the Confirm deletion dialog.

  • To close the custom object menu, click the Actions menu and select Close. You are transferred to the Input / Output tab.

tip

You can transfer custom types between environments by exporting them in an Asset Bundle during a variation export and then importing them into the target environment.

Apply data mapping​

You can apply data mapping to transform variable names before and after a bot step processes them. It serves as a wrapper for the bot step logic and renames variables before and after processing.

With the feature, you can reuse a step logic for another step that expects the same data but under different names. For example, an OCR step may require a document URL under the document_link field. If you already have the original_document_url field, you can map original_document_url to document_link and add an OCR step to your BP.

When you add inputs or outputs, Source and Destination variables match step variables and are hidden by default. To modify mapping options, go to the Input / Output tab for a bot step and configure the following:

  • For inputs, specify the Step variable and Source values: the first one refers to the variable name expected by the step, and the second one is the variable name in the BP context. Nested variables (if there are any) are named accordingly.

    In an input object, you can specify values for headers and authorization, query, and path parameters you configure in the connector. Thus, you can set up a constant value, a reference to a secret entry in Secrets Vault, or a reference to an AI Agent configuration. For more details, see Configure no-code Generic Connector.

  • For outputs, specify the Step variable and Destination values: the first one refers to the variable name in the bot step output, and the second one is how it should be named in the BP context. Nested variables (if there are any) are named accordingly.

  • If you do not need mapping, leave values in Step variable and Source for Input or Destination for Output identical.

Define variables carefully to match the step logic. The WorkFusion platform cannot verify if a step contract is correct from the perspective of the correspondent step logic. However, if you remove a value or specify a wrong variable, the mapping is broken, and a broken link between the variables is shown. Make sure to fill in the correct values and do not leave empty fields.

To map complex objects, you can apply nested mapping. To view nested mappings, move the pointer to the nested group and click Show mapping. In the example below, there are two groups of nested variables:

  1. A group of the model_result variables

  2. A subgroup of the model_result.tags variables

To hide selected nested mappings, move the pointer to the right of the group of nested variables and click Hide mapping.

note

  • Mapping cannot cast types. For the same variable, identical types are used for input and output.

  • When you copy or duplicate an existing schema-based step in a BP diagram, mapping is not copied.

Update contract​

To update a contract, select a step where you want to make edits. On the Input / Output tab, change the needed values, or add more variables to the step as required.

If a bot step with a contract is imported as part of an Asset Bundle, you cannot change the Type and Step variable values. Updating is only possible for the Source and Destination values in inputs and outputs, respectively.

Validate contract​

To validate a contract, click Validate or Save on the BP's Workflow page.

Validation uses external contracts, such as input fields before mapping and output fields after mapping, and serves for detecting the following error types:

  • A step requires a variable in its input, but none of the previous BP steps defines the variable in their outputs (see the screenshot above).

  • A step requires a variable in its input. Previous steps provide the variable, but its type is different.

  • A BP has several branches joined at some point. Different branches provide the same variable but with different types.

note

Validation doesn’t prevent BPs from starting. It serves just as a warning for a BP developer.

Remove contract​

To remove a contract, complete the following steps:

  1. Open the Input / Output tab for the step where you want to remove a contract.

  2. Remove all the variables in the contract. To remove a variable, click the Remove icon next to it.

  3. Once you remove all the variables in the contract, switch off the Enable Input / Output connection toggle.

    The step has no contract and is no longer marked with the schema-based icon. As soon as your BP has no schema-based steps, it becomes schemaless and is no longer marked with the schema-based icon on the BP level.

warning

If your BP contains an imported bot step and its contract has immutable variables shown as greyed out, you cannot remove the variables. Thus, you cannot remove the contract from the bot step.

FAQ​

I created a contract for a step in a BP. Can I reuse the step with the contract in another BP?

Yes, if a step has an associated contract imported with an Asset Bundle, you can drag and drop the step to a BP diagram. The contract from the step is applied to the new step.

Also, if a step doesn’t have an imported contract, but you added a contract in the Control Tower user interface, the step can also be reused when you drag and drop it into a BP diagram.

Can I assign a contract to a Manual Task?

Yes, you can assign a contract to a Manual Task like to any bot step. See the example of input and output values for a Manual Task below.

Are contracts supported in event-based sub-process execution?
Yes. If you use a sub-process call step, its input contract is applied to the first sub-process step. Its output contract is applied to the last sub-process step.
How are name conflicts prevented if I use two schemas in a BP with identical type names?
Name conflicts are prevented with the schema namespace: x-package and version. When you drag and drop a bot step to a BP, its types are prefixed with the original schema's x-package and version.
Does the output contract restrict data in step results?

It depends. If you imported a bot step and did not modify anything on the Input / Output tab, the data step results are not restricted. If you made any changes to the contract, the data step results are restricted to the specified output contract.

Is stateless execution supported for a schema-based BP?

Stateless and pipelined execution are not currently supported for a schema-based BP.