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.

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 drop down menu.
Select Method	Contains a list of methods of the SmartObject.	Select the method from the drop down 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 drop down menu.
Filters	The filter enables you to specify parameters and filters to return data. Use operators such as Equal, Not Equal, Starts With, Ends With, and Contains. Applying filters is optional. Parameters are sometimes required and depend on the SmartObject 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 the Add button 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 the Add button to add additional property fields. Select the property from the drop down 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 drop down 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 State 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 drop down.
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.

In the Filters section, click the Add button to add a property.
In the Input Mappings section click the Add button and from the drop down menu select and configure a value. In the added property field, type a value, use inline functions, or dynamic fields, by clicking on the Add button 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 the Add button.
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 drop down 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 drop down 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 drop down 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 drop down 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 field.
Reset link	Use the link to reset any changes to the title.	Click the Reset link to reset the Title 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 Description field.
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	On step execution and an error occurs, continue to the next step in the workflow.	Check the box to continue if an error occurs. Uncheck the check box to stop workflow execution if an error occurs.

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.

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.