We're updating some of our product names. K2 Five will soon be Automation On-Prem. You may see both product names in our help pages while we make this change.

Create Reference step

Use the Create Reference step to generate dynamic references to a SmartObject item. You can use this for various line of business systems for which you have SmartObjects created. A reference is an XML structure that contains information about loading records from a SmartObject. The Create Reference step binds the SmartObject data to the workflow, making it easier to reuse the SmartObject reference and properties of the SmartObject throughout your workflow.

Use the Create Reference step to:

Eliminate the need to create variables to track SmartObjects used in the workflow
Make a single SmartObject call to create the reference instead of setting up filters and parameters each time you need to use a SmartObject property
Use properties of the reference throughout your workflow activities and events

Drag the Create Reference step from the Basic category, Favorites bar, or the Recent category onto the canvas.

Example of a Create Reference step in a workflow
In this example, you want to create a reference to retrieve a list of customers for a region and a specific city.

See the following resources for more information:

See How To: Filter and Update List Items for an example of using the Create Reference step to create a reference that is used by a Loop step in a workflow.
See How To: Link a SharePoint application's workflow to a secondary list or library for an example of using the Create Reference step to get the SharePoint Integration Setting properties of a primary SharePoint list.
See How To: Modify a Workflow to Link an Application's Start Rule to a Secondary List or Library for an example of removing existing item references and creating new references.
See How To: Use a Loop Step to Loop Through a List for an example of creating a reference to list items so that you can loop through those items in a workflow.
See How To: Use a Loop Step with a Loop Index for an example of creating a reference to list items so that you can loop through those items using a loop index in a workflow.

How to add a Create Reference step

From the Toolbox click the Basic category, then drag the Create Reference step onto the canvas.
Select the added step and click the expand / collapse toggle to expand the Configuration Panel. You can also double click the step to expand the panel.
Select the Create Reference tab. Use this tab to configure the reference to a SmartObject or SmartObject method.

The following table explains the available options:

Option	Explanation	How to Use
SmartObject and Method
Select SmartObject	Contains a list of recently used SmartObjects and a Browse button to locate more.	Select the SmartObject from the menu.
Select Method	Contains a list of methods of the SmartObject.	Select the method from the menu.
Identifier	Once you select a method, the Identifier is populated. The Identifier only displays when the SmartObject does not contain a key property and requires you to select one.	Select the identifier from the menu.
Filters	The filter allows you to specify parameters and filters to return data. Applying filters is optional. Use operators such as Equal, Not Equal, Starts With, Ends With, and Contains. Parameters are sometimes required - it depends on the SmartObject method selected. If the method has parameters, you probably need to provide values for those parameters to execute the method. At runtime, the Get Reference step returns multiple records from the SmartObject. Use the Filter section on the step to configure conditions to return one or more records from the SmartObject. If you don't configure the filter, all records in the SmartObject are returned. For more information see How to configure a condition to filter results for single or multiple records.	Click the Add Filter link to add filters. Select filter values from the drop-down menu. Click the operator button to select the operator. Click Add to add additional filter properties Type values or create dynamic values by dragging Functions, Fields, SmartObjects and Workflow-related items from the Context Browser into the fields. To delete properties, select them and click the Trash bin.
Input Mappings	Specify additional properties for the returned results.	Click Add to add additional property fields. Select the property from the menu. Type values or create dynamic values by dragging Functions, Fields, SmartObjects and Workflow-related items from the Context Browser into the fields. To delete properties, select them and click the Trash bin.
Output Mappings	This option enables you to create a reference to refer to, and use it in any part of your workflow.	To create a reference click Create. Reuse this reference or add it to any other part within your workflow.

Select a SmartObject from the recently picked menu list or browse to one. This is a required field.
Select Browse and find the SmartObject containing the record or records you need to reference.

For more information about the different browse states and errors, see the Browse States topic.

For more information on how to use the breadcrumb bar, see the How to use the Breadcrumb topic.

Select a method of the SmartObject from the menu.
In this example, the Get List method is selected which, when selected, shows the Identifier field.

When determining the key property for the selected SmartObject, the workflow designer shows available methods. It checks for a default load method and, if a method is found, uses the ID property. If a default Load method is not found, it checks for the default list method. If that is found, it uses the key property. If not found, all available properties are returned and you can select one to use.

Click the Add Filter link to specify parameters or filters to return data dynamically. For more information see How to configure a condition to filter results for single or multiple records.
Filtering is dependent on the service object. Some service objects have filter functionality built in as part of the query issued by the broker. For those service objects that don't, the filter is applied after data is returned to the SmartObject. In the latter case, the number of records that are handled by K2 (versus the LOB system) could cause workflow performance issues.

Select a property from the drop down menu. Select an operator to define the filter. Type values or create dynamic values by dragging Functions, Fields, SmartObjects and Workflow-related items from the Context Browser into the fields.

For more information on how to use Smartfields see the Smartfield Composer topic. Added filters can be grouped together to form parameters. To group parameters, click the AND button.

You can add multiple conditions to filter on. In the Filters section, click Add to add a property.
In the Input Mappings section click Add and from the menu select and configure a value. In the added property field, type a value, use inline functions, or dynamic fields, by clicking Add to expand the Context Browser. Within the Context Browser, select inline functions and fields from the Functions, Fields, SmartObjects and Workflow categories. Click and drag the function into the property field.
To add additional properties to filter by, click Add.
To delete properties, select one and click the Trash Bin.
To create a reference click Create. Reuse this reference in the current step or from another step in your workflow.
If you added filter criteria to the Create Reference step, remember to create a reference and use this created reference for the filtered data. If you don't use this reference, all data in the SmartObject returns and not the filtered data.
To edit the auto-generated reference title, click Edit and change it.
To locate the added reference expand the Context Browser, select Fields and expand the Reference section.
Click the List Options down arrow to configure what data is returned and if you want it sorted.

The following table explains the available options:

Option	Explanation	How to Use
List Options	Specify what data to return from the list. You can select one of the following: All - Returns all records First - Returns the first record Last - Returns the last record Index - Specify index	Select the option from the menu.
Ordered By	Use this to specify a field on which the returned data is sorted. You can select the display order as ascending or descending.	Check the Ordered By check box to enable this option. Select the field to order on, from the menu. Select either the Ascending or Descending radio button.

Option

Explanation

How to Use

List Options

Specify what data to return from the list. You can select one of the following:

All - Returns all records
First - Returns the first record
Last - Returns the last record
Index - Specify index

Select the option from the menu.

Ordered By

Use this to specify a field on which the returned data is sorted. You can select the display order as ascending or descending.

Check the Ordered By check box to enable this option.

Select the field to order on, from the menu.

Select either the Ascending or Descending radio button.

With the step selected, select the Properties tab.

The following table explains the options available on this tab:

Option	Explanation	How to Use
Title / Name	By default, each step on the canvas has a step title. You can change this title to suit your workflow logic and show it on the canvas by checking the Show Label box.	Enter a value into the Title/Name field.
Reset link	Use the link to reset any changes to the title.	Click the Reset link to reset the Title/Name field to default value.
Show Label	Allows you to see the step label on the canvas. The label shows the value of the title.	Check the check box to display step label on the canvas.
Description	Allows you to add a detailed description for the step.	Enter a value into the Create Newfield.
Notes	Allows you to add additional notes for the step.	Enter a value into the Notes field.

Click the Errors tab.

Different types of exceptions can occur on a step, such as:

Type	Description
Known exceptions	Any SmartWizard or standard wizard that has Boolean options for handling known exceptions have these options displayed as check boxes in the Known exceptions section of the Exceptions tab.
Unhandled exceptions	Any unknown runtime exceptions.

The tab contains the following known exceptions:

Exception	Explanation	How to Use
Continue on error	If an error occurs when the step executes at runtime, this configuration specifies whether to continue to the next step in the workflow, or not.	Check the check box to continue the workflow even if an error occurs in the step. Uncheck the check box to stop workflow execution if an error occurs. In this case, the workflow will go into an Error state and an administrator will need to Retry the error before the workflow will resume.

In K2 Five (5.3) Fix Pack 38 and later an additional exception configuration is available: a check box stating Force error when required SmartObject inputs are missing. When executing a SmartObject step in a workflow, if the SmartObject's required input fields don't have values, this option specifies whether to continue on to the next step in the workflow, or not.

If the error is forced, the workflow instance stops and the following error shows in K2 Management > Workflow Server > Workflows > {workflow name} > Errors tab: "One or more required inputs are missing for the {SmartObject Method} method in the {StepName} step."

Checking this check box overwrites the Continue on error functionality.

By default, this check box is checked for all new workflows. For existing workflows, this check box is unchecked.

The tab contains the following unhandled exception:

Exception	Explanation	How to Use
Log Exception	Logs the exception to the error log.	Check the box to log the exception.

Your changes are automatically saved.

How to configure a condition to filter results for single or multiple records

At runtime, the Get Reference step returns multiple records from the SmartObject. Use the Filter section on the step to configure conditions to return one or more records from the SmartObject. If you don't configure the filter, all records in the SmartObject are returned.

Scenario

Your company stores customer details such as Customer Name, Contact Person, City, and Region. As part of the sales process, the sales representative receives and email with a detailed list of their customers. In this scenario, you need to specify a condition on the Get Reference step to make sure the correct customer list is sent to the representative. To do this, add a condition in the Filter section.

The Customer SmartObject contains details for all customers. The list you need to email only needs to contain Region C customers.

In the Filter section, configure the filter by adding a condition. Select the region property (DenallixRegion) and type Region C as the value. This filter ensures that only customers from Region C are added to the customer list email.

In the Output Mappings section, click the Create link.

This creates the Customers reference for you to use in the Send Email step.

Configure the Send email step and drag the CustomerName, BillingAdressCity and DenallixRegion properties (located in the Customers reference section) from the Context Browser into the email body.

At runtime the sales rep receives an email with Region C customer details.

To filter for a specific record, use a unique identifier in your condition. In this example, you only want to include the details for Summer Newman from Tremblay Inc in the email.

In the Filter section, configure the filter by adding a condition. Select the unique property (CustomerID) and type 5 as the value. This filter ensures that only this customer is added to the email.

In the Output Mappings section, click the Create link.

This creates the Customers reference for you to use in the Send Email step.

Configure the Send Email step and drag the CustomerName, BillingAdressCity and DenallixRegion properties (located in the Customers reference section) from the Context Browser into the email body.

At runtime the representative receives an email with Tremblay Inc customer details.

You can add multiple conditions in the filter section. In this example, you only want to include details for Region A and customers from Miami.

In the Filter section, configure the filter by adding two conditions. One for Region A customers and one for the Miami customers. This filter ensures that only customers from Region C and from Miami gets added to the customer list email.

In the Output Mappings section, click the Create link.

This creates the Customers reference for you to use in the Send Email step.

At runtime the sales rep receives an email with Region A and Miami customer details.

If you add customer records to a referenced SmartObject, they are not included in the reference until you start a new instance of the workflow.