Create Reference step

1. From the Toolbox click the Basic category, then drag the Create Reference step onto the canvas.
   
2. 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.
   
3. 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.

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

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.

6. Select a method of the SmartObject from the menu.
   
7. 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.
8. 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.
   
Applying filters is optional. Parameters depend on the SmartObject method and are sometimes required. The filter may have a positive impact on performance by limiting the number of records returned. When you create a filter, only records that match the filter criteria are returned.

9. 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.

10. You can add multiple conditions to filter on. In the Filters section, click Add to add a property.
    
11. 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.
    
12. To add additional properties to filter by, click Add.
    
13. To delete properties, select one and click the Trash Bin.
    
14. 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.

15. To edit the auto-generated reference title, click Edit and change it.
    
16. To locate the added reference expand the Context Browser, select Fields and expand the Reference section.
    
17. 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.

18. 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 New field.
Notes	Allows you to add additional notes for the step.	Enter a value into the Notes field.

19. Click the Errors tab.
    

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. 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.
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.	Check the box to force the error. Uncheck the box to not force the error.

20. Your changes are automatically saved.

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 Florida customers. This filter ensures that only customers from Region A and from Florida 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.

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 A and Florida customer details.

When working with the Create Reference step keep in mind the following considerations:

• The filter feature positively affects reporting query performance as all records are not returned. If a filter has been applied, records are filtered according to the filter criteria and only those records that match the filter are returned, as long as the service object (and LOB) supports server-side filtering.
• When using the filter feature, using input mappings is critical if a large number of records exist on the LOB system. The more records you can filter-out before the results are returned to K2, the better the performance is. If items are filtered out of the result set that is expected by using parameters, the filters applied may not work properly. As a troubleshooting tip, supply parameters only, look at the result set to confirm the records, and then go back and apply one or more filters.