Using References

Creating and using references saves you time when building your workflow. You create references to items such as documents, subsites, list items, forms and SmartObject results, and then reuse that information anywhere within the workflow.

In many cases, references are created automatically for you, but you also have the option to create your own. You can create multiple references and reuse them throughout the same workflow. References can contain one or multiple items, and you can use information from references to filter data and build rules. Lastly, you can use references to add content to an email, change the value of the folio, and set or update other properties.

Think of reference fields as placeholders that point to a SmartObject. While you are designing the workflow, the fields do not have any values. When you start an instance of the workflow, the workflow will replace the placeholder values of the reference with the actual data values from the referenced SmartObject record. The data values for the referenced SmartObject are retrieved every time the workflow instance uses the reference. In other words, should the data values for the referenced SmartObject record change, the workflow will always use the latest values for that SmartObject. For example: suppose you reference an Employee SmartObject in the workflow and use the Employee’s department name in the workflow. Whenever an instance of the workflow needs to read the Employee’s department, the workflow will retrieve the latest value of the Department from the Employee record referenced by the workflow. Should the Employee’s department change, the workflow will always use the latest value for the department whenever it needs to read the Employee’s department.

If you change the structure of the referenced SmartObject (for example if you add a new property to the SmartObject), the changes will only reflect once you update the reference in the workflow designer and redeploy the workflow, and only new instances of the workflow will be aware of the new property. Existing instances of the workflow will not be aware of the new property, because you must update the reference in the workflow designer and redeploy the workflow. This creates a new version of the workflow, and new instances of the workflow will use this new version. Any existing instances of the workflow will continue to use the older version of the workflow definition and therefore will not be aware of the new property added to the SmartObject reference.

For information on how to delete references, see Delete References.

References appear in the Context Browser on the Fields tab. From the Reference section, drag and drop the referenced information onto your workflow steps.

Let's look a few scenarios for creating and using references in your workflow.

Scenario 1: Using References with a Form

References are automatically created when you integrate with a form. When you start a workflow with a form, one or more references are available to use in your workflow. This also happens when you select to use a form on the Task step.

Examples

In the example below, there are four references created based on the SmartObject data used in the form, which you can use throughout the workflow.

The same references are automatically created for you if you use a form to action a task in the workflow, as shown here:

Scenario

The scenario below uses multiple views on a form containing different tabs. You can navigate between tabs to capture information and populate other views by using references. The scenario outlined here creates a reference when a form is submitted. This reference is subsequently used in a task step to fill views with SmartObject data. Follow the steps to set up the scenario:

Create two SmartObjects as shown below. These SmartObjects store customer and regional data.
Create an association between the two SmartObjects.
Create an item view and list view using the Customer SmartObject, and an item view and list view using the Region SmartObject. These views capture the customer details and the region information.
Create a form and name it Customer Form. Add the Customer list and item views to the form. Change the item view label to Customer Details and list view label to Customer Details List.
Add a tab for the Region information on the Customer form, and then add the Region item and list views to this tab.
When this form is submitted, it starts the workflow and sends an approval task to the originator's manager.
Create a new workflow. On the Start step, select the Start with a Form option and browse to the Customer form. Run through the wizard to complete configuration. Make sure to select the Customer reference, which is automatically created for you using the Customer SmartObject. Since there is more than one view on the form, you see more than one reference. Deselect all but the Customer reference.
Click Help me configure it and select the Use an existing State (Base State) option.
Make sure that the On Customer Item View, when Create Button is Clicked option is selected for Form Rules. This starts the workflow when you click the Create button on the Customer Item View.
Complete the Start Workflow with Form wizard.
Drag a Task step onto the canvas. From the Properties tab, change the name to Manager Task.
From the Task Detail tab, add a Complete action to the task.
Select the Forms tab, select the SmartForm option from the drop down menu. Select the Customer Form from the Form drop down
Configure the Open a Task on a Form wizard with the Customer reference. This loads the SmartObject data from the original form submission.
Select the Help me configure it option and select the Create a new State option.
Make sure the When the Form is Initializing option is selected for Form Rules. Move the then open the Task worklist item down as shown below, which makes sure the data returns before the form is shown.
Complete the Open a Task on a Form wizard.
Drag a Decision step onto the canvas and connect it to the Manager Task. Drag a Placeholder step onto the canvas and connect the Completed path to the Placeholder step.
Save and deploy the workflow.
Run the Customer form. Navigate to the Region tab and add a region name. Click the Customer tab and complete the information as shown below. Click Create.
The workflow starts and creates the worklist item.
Open the worklist item. Both the customer and region details show when the manager opens the task. The details were captured when the form was submitted. Note how the details are loaded on the form automatically and you didn't have to create any custom rules.

Scenario 2: Creating and Using a Reference without a Form

Use the Create Reference step to create a reference to a SmartObject without binding it to a form. The created references contains all of the properties within the SmartObject which you can then reuse throughout the same workflow. You can also use the SmartObject Method step to create a reference to a SmartObject.

Example

In the example below, two separate Create Reference steps are used which created two references based on the selected SmartObject data (Regions and Products) for you to then use throughout the workflow.

The example below shows how to use the SmartObject Method step to create a reference to the SmartObject (Sales Order).

Scenario

The scenario uses data from a SmartObject called Sales Orders. In the workflow scenario, you create a Get List method reference and sum the values of each Sub Total SmartObject property. Then you append the sum value to the workflow folio using the Set Folio step. Follow the steps to set up the scenario:

Create a SmartObject as shown below. This Sales Order SmartObject stores sales order data. Once you create the SmartObject, populate it with some data by generating an editable list view.
Create a new workflow and drag the SmartObject Method step onto the canvas.
Browse to and select the Sales Order SmartObject. From the Method drop down menu, select the Get List method. Select ID from the Identifier drop down.
Click the Create a Reference option to create a reference to the Sales Order SmartObject, which you then use in the Sum function.
Drag the Set Folio step onto the canvas. Connect the step to the SmartObject Method step.
Customize the folio field by entering 'Total Sales ' and then dragging the Sum function (found in the Mathematical section) from the Context Browser into this field.
The Smartfield Composer shows. From the Fields section, expand the Sales Order reference and drag the Sub Total property into the Values field. Change the name of the Sum function to Sales Sub Total. In this example, the Sum function totals all Sub Total values.
For more information on how to use the Smartfield Composer, see the Smartfield Composer topic.
Click X to close the Smartfield Composer. The final configuration on the folio field is as follows:
Save and deploy the workflow.
From K2 Management, manually start an instance of the workflow. At runtime, the workflow calls the SmartObject, collects and calculates data, and the sets the workflow folio field with the total value of the Sub Total values. In this example the final sum is 600.
After the workflow completes, click the Reports tab (in K2 Management) to view the All Instances report. The folio's value is Total Sales 600.

Scenario 3: Creating and Using SharePoint References

Create references to your SharePoint list, list items, libraries and subsites to reuse throughout the workflow. In most cases, references are automatically created for you when you integrate your lists and libraries with K2 for SharePoint, but you also have the option to create your own. You can create multiple SharePoint references within a workflow. Use any of the SharePoint Get Reference steps listed below to create references. Click these links to see detailed information on each of the reference steps:

Example

In the example below, references are automatically created when the SharePoint list (Induction Program 2018) is integrated with K2 for SharePoint. The same happens when you select a SharePoint list to start the workflow with. For more information on how to start a workflow with a SharePoint event, see Start a Workflow with a SharePoint Event.

In the example below, you use the Get Document Reference to create a reference to the a SharePoint library (Employee Contracts) for you to then use throughout the workflow.

In the example below, you use three separate Get Reference steps to create three references to the SharePoint library, list and subsite for you to then use throughout the workflow.

Scenario

The scenario below uses two SharePoint lists, one called Sales Opportunities and the other Sales Medium Cycle. The Sales Opportunities list contains a list item for each active sales opportunity. A column called Sales Cycle tracks the cycle type for each of the sales opportunities. There are three different cycles, namely Short, Medium and Long. The scenario outlined here creates a reference with a filter to only show Medium sales. This reference is called Sales Opportunities Medium Cycle. The reference is then used to copy the list items from the Sales Opportunities list to the Sales Medium Cycle list. Follow the steps to set up the scenario:

Create the Sales Opportunities list in SharePoint as shown below. This list store all active sales opportunities.
Create the Sales Medium Cycle list in SharePoint as shown below. This list contains no list items and is used in the workflow to hold the copied list items from the Sales Opportunities list.
Create a workflow called Sales Cycles.
Drag the Get List Item Reference step onto the canvas. Browse to and select the Sales Opportunities list from the Find List Items drop down menu. Click the Add Filter link, select Sales Cycle from the drop down menu and add the Medium Cycle option by typing it into the fields. Click the Create link to create a reference to the Sales Opportunities list. Edit the reference name to Sales Opportunities Medium Cycle.
Drag the Copy List Item step onto the canvas and connect the step to the Get List Item Reference step. Select the Sales Opportunities Medium Cycle from the Pick List Item drop down menu. From the Pick List drop down menu, browse to and select the Sales Medium Cycle list as the destination list.
In the Properties section add the properties you want to copy to the new SharePoint list. These properties are auto-mapped so there is no need to map them.
Drag the End step onto the canvas and connect the step to the Copy List Item step.
Save and deploy the workflow.
Manually start an instance of the workflow using K2 Management.
Select the Sales Medium Cycle SharePoint list. Notice all Medium Cycle items were copied to the list.