Item Reference Event
When the Item Reference Event wizard is configured, an item reference is created that points to one or more SharePoint list items, SharePoint documents, or CRM entities. References can be used later in the workflow.
Note: It is not necessary to create item references for SharePoint 2013 or SharePoint Online items as they are created automatically for you when you integrate K2 with a document library or list in SharePoint.
What is a Reference Field?
A Reference Field is a reusable process object that contains data referring to SharePoint or CRM objects. It is an XML field where the reusable reference to the objects are stored.
When Would a Reference Field be Used?
Once configured, the reference field is available from the context browser and can be used in later process events.
This means that, at design time, you have a pointer -- a reference -- to properties of the referenced items in SharePoint or CRM, without having to browse for the objects each time. You can use these references in subsequent activities in the workflow to get the data and perform actions on the referenced items.
Using the Item Reference Event Wizard
The Item Reference Event wizard is available from the K2 Toolbox. To load the Item Reference Event onto the canvas, click and drag the item onto the design canvas.
Welcome
The Welcome page is the entry point to the wizard and is used to configure the item reference.
Event Name and Action Selection
The Event Name and Action page allows you to select the type of reference you're creating.
| Field | Description | Sample Value |
|---|---|---|
| SharePoint List Item Reference | Creates a process reference to a SharePoint list | Select this action to create a reference to a SharePoint list item property |
| SharePoint Document Reference | Creates a process reference to a SharePoint library | Select this action to create a reference to a SharePoint document property |
| CRM Entity Reference | Creates a process reference to a CRM entity | Select this action to create a reference to a CRM entity |
SharePoint List Settings
The SharePoint list item reference action allows you to create a reference to a SharePoint list item. The List Settings page configures the SharePoint Site URL and the SharePoint list containing one or more items that you want to reference in your workflow.
| Field | Description | Sample Value |
|---|---|---|
| SharePoint Site URL | The SharePoint connection URL |
Enter the SharePoint Site URL or click on the ellipsis button to open the context browser and drag the variable containing the SharePoint Site URL onto the field Click on the Test button to test the connection to the SharePoint site |
| List | The SharePoint list to be referenced | Enter the SharePoint List, or use the ellipsis button to open the Context Browser and drag the variable containing the SharePoint LIst onto the field. Alternatively, use the Browse button to open the K2 SharePoint Browser to locate or create the SharePoint list |
Mappings
The Mappings page provides you with the configuration details of the specific reference and reference filter to be created. If you want to reference a single item, use the Title field. If you want to reference multiple items, use a different field such as Status or Created By.
| Field | Description | Sample Value |
|---|---|---|
| Reference Field | The name of the reference field to be configured by the event | Enter the name of the process data or XML field to be used as the reference field or click on Create button to create a new process field |
| Create | Opens the create new reference field dialog. See the Creating a New Reference Field section below | Click on the Create button to add a new reference field to the process |
| Content Type | The SharePoint Content Type indicator | Click on the drop down to select the SharePoint Content Type |
| Assign | Opens the assign value dialog. See the Assign a Value section below | Once you have selected a data field from the table, click on the Assign button to assign a filter value |
| Clear | Clears the value of the selected data item | Once you have selected a data field to clear, click on the Clear button to remove its assigned value |
| Clear All | Clears all the assigned values from the data table | Click on the Clear All button to clear all the assigned values |
| First | Sets the filter type to the first returned value | Select this option by clicking on the associated radio button |
| All | Sets the filter type to return all values | Select this option by clicking on the associated radio button |
Creating A New Reference Field
To create a new reference field, click on the Create button and specify a name in the Reference Field text box.
Assign a Value
To assign a value to a data item, click on the Assign button and enter the required value in the field, or use the ellipsis button to open the context browser and drag the variable containing the value onto the field.
SharePoint Document Settings
The SharePoint Document Reference action allows you to create a reference to a SharePoint document property. The Document Library Settings page configures the SharePoint Site URL and the SharePoint library to be referenced.
| Field | Description | Sample Value |
|---|---|---|
| SharePoint Site URL | The SharePoint connection URL |
Enter the SharePoint Site URL or click on the ellipsis button to open the Context Browser and drag the variable containing the SharePoint Site URL onto the field Click on the Test button to test the connection to the SharePoint Site |
| Document Library | The SharePoint library to be referenced | Enter the SharePoint Document Library, or use the ellipsis button to open the context browser and drag the variable containing the SharePoint Document Library onto the field. Alternatively, use the Browse button to open the K2 SharePoint Browser to locate or create the SharePoint library |
Mappings
The Mappings page provides you with the configuration details of the specific reference and reference filter to be created. If you want to reference a single item, use the Title field. If you want to reference multiple items, use a different field such as Status or Created By.
| Field | Description | Sample Value |
|---|---|---|
| Reference Field | The name of the reference field to be configured by the event | Enter the name of the process data or XML field to be used as the reference field or click on Create button to create a new process field |
| Create | Opens the create new reference field dialog. See the Creating a New Reference Field section below | Click on the Create button to add a new reference field to the process |
| Content Type | The SharePoint Content Type indicator | Click on the drop down to select the SharePoint Content Type |
| Assign | Opens the assign value dialog. See the Assign a Value section below | Once you have selected a data field from the table, click on the Assign button to assign a filter value |
| Clear | Clears the value of the selected data item | Once you have selected a data field to clear, click on the Clear button to remove it's assigned value |
| Clear All | Clears all the assigned values from the data table | Click on the Clear All button to clear all the assigned values |
| First | Sets the filter type to the first returned value | Select this option by clicking on the associated radio button |
| All | Sets the filter type to return all values | Select this option by clicking on the associated radio button |
Creating A New Reference Field
To create a new reference field, click on the Create button and specify a name in the Reference Field text box.
Assign a Value
To assign a value to a data item, click on the Assign button and specify the value in the field, or use the ellipsis button to open the context browser and drag the variable containing the value onto the field.
Finished
The Finish page shows that the Item Reference Event Wizard has been completed successfully.
Example Scenario
As a simple example, consider the following scenario:
- You have a custom list in SharePoint with Created By and Comments columns
- You want to update the Comments column in all the list items that were created by a particular user - Henry
Implementation:
- Configure an Item Reference Event:
- Configure the wizard to point to the relevant SharePoint list
- Set up the mappings so that Created By equals Henry
- You also need to create an Item Reference Field
- Configure an Update List Item Event:
- Select the Update from Content Field action from the Update List Item event
- Select the Item Reference created in the previous step as your content field
- Assign a value to the Comment column
Execution
When the process is executed, all the items created by Henry are updated with the value supplied in the Comment column.
Note that the Item Reference is only populated at runtime, so each time a new process is started, it resolves all items that were created by Henry at that time, so the list varies over time and the reference is not the same across different instances of the same process.