Using References

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:

1. Create two SmartObjects as shown below. These SmartObjects store customer and regional data.
   
2. Create an association between the two SmartObjects.
3. 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.
4. 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.
5. Add a tab for the Region information on the Customer form, and then add the Region item and list views to this tab.
6. When this form is submitted, it starts the workflow and sends an approval task to the originator's manager.
7. 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.
   
8. Click Help me configure it and select the Use an existing State (Base State) option.
   
9. 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.
   
10. Complete the Start Workflow with Form wizard.
11. Drag a Task step onto the canvas. From the Properties tab, change the name to Manager Task.
    
12. From the Task Detail tab, add a Complete action to the task.
    
13. Select the Forms tab, select the SmartForm option from the menu. Select the Customer Form from the Form menu.
    
14. Configure the Open a Task on a Form wizard with the Customer reference. This loads the SmartObject data from the original form submission.
    
15. Select the Help me configure it option and select the Create a new State option.
    
16. 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.
    
17. Complete the Open a Task on a Form wizard.
18. 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.
    
19. Save and deploy the workflow.
20. 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.
    
21. The workflow starts and creates the worklist item.
22. 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.
    

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:

1. 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.
   
2. Create a new workflow and drag the SmartObject Method step onto the canvas.
   
3. Browse to and select the Sales Order SmartObject. From the Method menu, select the Get List method. Select ID from the Identifier menu.
   
4. Click the Create a Reference option to create a reference to the Sales Order SmartObject, which you then use in the Sum function.
   
5. Drag the Set Folio step onto the canvas. Connect the step to the SmartObject Method step.
   
6. Customize the folio field by typing Total Sales and then drag the Sum function (found in the Mathematical section) from the Context Browser into this field.
   
7. 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.

8. Click X to close the Smartfield Composer. The final configuration on the folio field is as follows:
   
9. Save and deploy the workflow.
10. 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.
    
11. 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.
    

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:

• Get Document Reference step
• Get Library Reference step
• Get List Item Reference step
• Get List Reference step
• Get Subsite Reference step

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:

1. Create the Sales Opportunities list in SharePoint as shown below. This list store all active sales opportunities.
   
2. 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.
   
3. Create a workflow called Sales Cycles.
4. Drag the Get List Item Reference step onto the canvas. Browse to and select the Sales Opportunities list from the Find List Items menu. Click the Add Filter link, select Sales Cycle from the menu and type Medium into the right-hand field - this creates a filter that will find items where Sales Cycle equals Medium. Click the Create link to create a reference to the Sales Opportunities list. Edit the reference name to Sales Opportunities Medium Cycle.
   
5. 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 menu. From the Pick List menu, browse to and select the Sales Medium Cycle list as the destination list.
   
6. 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.
   
7. Drag the End step onto the canvas and connect the step to the Copy List Item step.
   
8. Save and deploy the workflow.
9. Manually start an instance of the workflow using K2 Management.
10. Select the Sales Medium Cycle SharePoint list. Notice all Medium Cycle items were copied to the list.
    

Create references to CRM entities by using the Get CRM Entity Reference step. The references contain all of the properties within the selected CRM Entities, which you can then reuse throughout the workflow.

Example

In the example below, the Create CRM Entity reference is used which created a reference based on the selected CRM Entity (Contact) for you to then use throughout the workflow.

Scenario

The scenario below uses the reference you create using the Get CRM Item Reference step to populate the body of an email. The reference is based on the Contact entity and, as part of the workflow, an email is sent to every contact to confirm the details.

1. Create a new workflow and drag the Get CRM Entity Reference step onto the canvas. Browse to and select the Contact entity from the Find Entity Items menu. Click the Create link to create the reference. Rename the reference to CRM Contact.
   
2. Drag a Send Email step onto the canvas and connect it to the Get CRM Entity Reference step. To view the reference, expand the Context Browser and select the Fields tab. In this example the email is sent to the contact.
   
3. Customize the email by dragging reference items onto the Email Body.
   
4. Add an End step to your workflow and then save and deploy it.
5. Manually start an instance of the workflow using K2 Management.
6. In this example, emails was sent to each of the customer accounts. The email shows as follows:
   

Scenario

Your company stores customer details such as Email, First Name, Last Name, and Status. As part of the sales process, all active customers receive an email to update them on latest deals your company has to offer.

The data source in this scenario is a SQL table called Contacts with a stored procedure called [dbo].[SelectAllContacts] that returns all customers. You created an instance of the SQL server service based on your SQL database and generated a SmartObject. This allows you to use the properties and methods of the stored procedure to specify a condition on the Get Reference step ensuring that only active customers are emailed. To do this, you add a Filter to the reference in the Loop step. This means the workflow only loops through active customers.

The SQL table has four columns namely Email, First Name, Last Name, and Status.

The SQL Stored Procedure ([dbo].[SelectAllContacts] creates a view of all customers in the [dbo].[Contacts] table.

The Loop step requires a Reference that is based on a List method, because a List method returns multiple items. You can create the Reference in the workflow (by using the Create Reference step or any other step where you can create a Reference that uses a SmartObject list method) and select the Reference when configuring the Loop step. SmartObject list methods often have input properties which you can use to filter the results returned by the method. Some list methods, for example list methods based on SQL stored procedures or REST services, may not have input properties that you can use to filter the results. However, when you select a unique SmartObject property as an identifier in a Loop step, you can use return properties to filter the results returned by the list method. In this example, the stored procedure-based SmartObject [dbo].[SelectAllContacts] does not have any input properties, but when you use the Email property as the Identifier, you can apply a filter so that only active customers are contained in the reference.

In this example, the SmartObject ([dbo].[SelectAllContacts]) contains details for active and inactive customers, and you only want to email Active customers.

In the Filters section, configure the filter by adding a condition. Select the Status property and type Active as the value. This filter ensures that only active customers are included in the reference, and will therefore receive the email.

In the Output Mappings section, click the Create link.

This creates the reference for you to use in the Loop step.

Configure the Loop step and select [dbo].[SelectAllContacts] reference from the List menu. This creates the [dbo].[SelectAllContacts] Item item reference that you use in the Send Email step.

Configure the Send Email step and drag the Email and First Name properties (located in the [dbo].[SelectAllContacts] Item reference section) from the Context Browser into the email address and body.

At runtime Anthony, Bob, and Codi receive a monthly specials email.