XML Schemas for SharePoint Workflow Integration Processes
K2 uses internal XML structures from time to time, for example specific schemas that are added to workflows when integrating with SharePoint. This topic contains reference information on these internal XML schemas.
The following sections outline the XML schemas related to the XmlFields that are created when using the K2 Workflow Integrated Process Wizards to integrate with SharePoint 2010 or InfoPath 2010.
K2 InfoPath Integration
The following XML field is created once the InfoPath integration process wizard completes:
{Form Name} – this is the name of the form which was integrated during the execution of the wizard.
The field is used to hold InfoPath field data supplied by the user on their form, and also has a _K2 node that holds data related to K2 instance. For examples of these schemas, download and extract the following file: K2Documentation.Samples.Reference.InfoPathIntegration.zip.
K2 SharePoint Workflow Integration
When you use the SharePoint Workflow Integration wizard to expose a K2 workflow as a SharePoint workflow, K2 will create four XML datafields in the process automatically. For examples of these schemas, download and extract the following file: K2Documentation.Samples.Reference.SPWorkflowIntegration.zip.
SPComments (hidden field)
This (hidden) datafield is very useful to know about, since the comments entered by users during Client Events are saved into the XML field. If you wanted to include comments from the manager as to why the request was rejected, for example, you can find the manager’s comments in this XML structure. The table below describes the values saved in this XML datafield.
| Field | Value Stored | Sample Value |
|---|---|---|
| Comments | A repeating node containing all the comments entered by various users during the workflow Client Events | |
| EventName | The name of the Client Event for the user task | Manager Approval |
| Comment | A repeating node, since a task may have had more than one user’s input | |
| UserName | The user name of the user that completed the task | DENALLIX\administrator |
| DisplayName | Display Name of the user that completed the task | Administrator |
| DateTime | The date that the task was completed | 1/26/2012 2:40 PM |
| Body | The comment body entered by the approver | Not _x0020_enough _x0020_leave _x0020_days
Note that the special characters like “Space” are encoded. You could use a custom inline function to convert the HTML encoding to plain text |
| Action | The action selected by the user when completing the item | Rejected |
SPIntegrationData (hidden field)
The SPIntegration XML datafield is used by K2 to store the details relating to the K2/SharePoint Workflow integration. The screenshot below shows the structure of this field, and the table following describes the fields in this XML structure
The sample values are based on a list item created in a list located at http://portal.denallix.com/K2Test/Lists/SharePointWorkflowList
| Field | Value Stored | Sample Value |
|---|---|---|
| HistoryListId | Internal SharePoint ID of the List used to save the Workflow History (GUID) | 38ac23da-22cf-4628-b56d-708a5c887f65 |
| HistoryListURL | The relative URL of the workflow history list The URL is relative form the root site of the site collection | /K2Test/Lists/Workflow History |
| HistoryListName | The Display Name of the workflow history list | Workflow History |
| ItemName | The Name of the item submitted to workflow | Test Item |
| ItemTitle | The Title of the item submitted to workflow | Test Item |
| ItemId | The SharePoint ID of the item submitted to worfklow | 2 |
| ItemUniqueId | The internal SharePoint ID of the item submitted to workflow (GUID) | 28fe05a3-6563-4d9d-906d-bc59c4bbe70e |
| ItemURL | The relative location of the item submitted to workflow. The URL is relative to the URL of the Site where the list is defined. | Lists/SharePointWorkflowList/2_.000 |
| ListTitle | The title of the list where the item resides | SharePointWorkflowList |
| ListId | The internal SharePoint ID of the list where the item resides (GUID) | 675684a7-8090-461c-8076-e18c83ed83c7 |
| ListURL | The relative URL of the list where the item resides. The URL is relative from the root site of the site collection | /K2Test/Lists/SharePointWorkflowList |
| OriginatorName | The name of the user that submitted the workflow | DENALLIX\administrator |
| OriginatorLoginName | The login name of the user that submitted the item to workflow | DENALLIX\administrator |
| OriginatorId | The internal SharePoint ID if the user that submitted the item to workflow | 10 |
| OriginatorEmail | Email of the person who submitted the item to workflow | administrator@denallix.com |
| SiteTitle | The title of the root site of the site collection | PortalRootSite |
| SiteId | The internal SharePoint ID for the root site of the site collection | 54707d5b-9e8d-410e-aec7-84ebca121dbb |
| SiteURL | The URL of the root site of the site collection | http://portal.denallix.com |
| TaskListTitle | The title of the task lists where user tasks will be displayed | Tasks |
| TaskListId | The internal SharePoint ID of the task list where user tasks are displayed | /K2Test/Lists/Tasks |
| TaskListURL | The relative URL of the task list where user tasks are displayed. The URL is relative to the URL of the root site on the site collection | /K2Test/Lists/Tasks |
| WebId | The internal SharePoint ID of the site where the list resides | 4217499d-9fa3-4715-9c32-f02cb9086d05 |
| WebURL | The full URL of the site where the list resides | http://portal.denallix.com/K2Test |
| WorkflowId | The unique SharePoint ID for the SharePoint workflow | 5840d436-8b67-4808-ac2c-03e9921c1871 |
| TemplateName | The name of the SharePoint workflow | K2Test\SharePointWorkflowIntegrationProcess |
| InternalState | A list of valid sates for the SharePoint workflow | Locked, Running, NotStarted |
| AuthorUserLoginName | Login name of the author of the item | DENALLIX\administrator |
| InstantiationData | A collection of instantiation data when the workflow was started | (depends on the item being submitted) |
| CustomData | (not used) |
WFIProcessField
K2 Content field that holds data related to the item in SharePoint for which the workflow instance is executing. The WFIProcessField XML datafield added by the wizard is a standard Content Field/Item Reference Field. The screenshot below shows the structure of this XML field, and the table following describes the fields in this structure.
The sample values are based on a list item created in a list located at http://portal.denallix.com/K2Test/Lists/SharePointWorkflowList
| Field | Value Stored | Sample Value |
|---|---|---|
| Type | The Content Type of the item | ListItems |
| Item (repeating node) | This is a repeating XML node. Multiple Items can be listed under this repeating node. | |
| ID | The index of the current item in the Item repeating node | 1 |
| SiteURL | The URL of the site where the item list is located | http://portal.denallix.com/TestK2 |
| ListURL | The relative URL of the list where the item is located. The URL is relative to the Site where the list exists. | Lists/SharePointWorkflowList |
| FolderURL | The name of the folder where the item exists. If no folder, the Item ID is used. | TestFolder or 2_.000 |
| Item | The ID of the item that started the process | 2 |
| URL | The full URL to the item. Can be used as a hyperlink to open the Display Page of the item | http://portal.denallix.com/TestK2/Lists/ SharePointWorkflowList/DispForm.aspx?ID=2 |
| Source | (Not relevant for the SharePoint workflow integration wizard) | (not applicable) |
K2 SharePoint Events Integration
The following process-level XML data fields are created once the SharePoint Events Integration wizard completes. The SharePoint Events Process wizard is used to start a K2 process automatically based on events that occur in lists and libraries in SharePoint
For examples of the EventDetails and SPEventsField XML fields schemas, download and extract the following file: K2Documentation.Samples.Reference.SPEventsIntegration.zip.
EventDetails
Holds data related to the event that was fired for the SharePoint Item or List. The EventDetails XML datafield added by the wizard represents details about the event that caused the workflow to start. The structure of this XML field is shown in the screenshot below and the table following describes the fields.
The sample values are based on a list item created in a list located at http://portal.denallix.com/K2Test/Lists/SharePointEventsList
| Field | Value Stored | Sample Value |
|---|---|---|
| Scope | The scope at which the event occurred (e.g. ListItem or List) | ListItem |
| EventType | The event that caused the workflow to fire | ItemAdded |
| SiteURL | The full URL to the site where the list is defined | http://portal.denallix.com/K2Test |
| SiteRelativeURL | The relative URL of the site where the list is located, relative to the Root Site URL of the Site Collection | /K2Test |
| List | The Name of the list where the list item was created | SharePointEventsList |
| ListRelativeURL | The relative URL of the List where the item is located. The URL is relative to the Site where the list is defined | Lists/SharePointEventsList |
| ListFullURL | The full URL of the List where the item is located. | http://portal.denallix.com/K2Test/Lists/SharePointEventsList |
| ListItem | The ID if the list item that started the process | 2 |
| ListItemTitle | The title of the list item that started the process | Test Item |
| ListItemRelativeURL | The relative URL of the list item that started the workflow. The URL is relative to the Site where the list item is defined. | Lists/SharePointEventsList/2_.000 |
| ListItemFullURL | The full URL to the list item that started the workflow. This link can be used as a hyperlink to open the List Item display form. | http://portal.denallix.com/K2Test/Lists/ SharePointEventsList/DispForm.aspx?ID=2 |
| Folder | The folder where the list item is saved. (If no folder, the list item ID is used, as shown here) | TestFolder or 2_.000 |
| Fields | Stores the BEFORE and AFTER metadata values of the Item in two separate fields in CDATA format | (Depends on the Item’s Metadata) |
SPEventsField
K2 Content field that holds data related to the item in SharePoint for which the workflow instance is executing. The SPEventsField XML datafield added by the wizard is a standard Content Field/Item Reference Field.
The screenshot below shows the structure of this XML field, and the table following describes the fields in this structure.
The sample values are based on a list item created in a list located at http://portal.denallix.com/K2Test/Lists/SharePointEventsList
| Field | Value Stored | Sample Value |
|---|---|---|
| Type | The Content Type of the item | ListItems |
| Item (repeating node) | This is a repeating XML node. Multiple Items can be listed under this repeating node. | |
| ID | The index of the current item in the Item repeating node | 1 |
| SiteURL | The URL of the site where the item list is located | http://portal.denallix.com/K2Test |
| ListURL | The relative URL of the list where the item is located. The URL is relative to the Site where the list exists. | Lists/SharePointEventsList |
| FolderURL | The name of the folder where the item exists. If no folder the Item ID is used. | TestFolder or 2_.000 |
| Item | The ID of the item that started the process | 2 |
| URL | The full URL to the item. Can be used as a hyperlink to open the Display Page of the item. | http://portal.denallix.com/K2Test/Lists/ SharePointEventsList/DispForm.aspx?ID=2 |
| Source | (Not relevant for the SharePoint Events process wizard) | (not applicable) |
Item XML Metadata Field
As part of the Events Integration and SharePoint Workflow Integration process wizards, you can also elect to save metadata from the list item to the workflow. You can select individual data values and save them to discrete data fields in the workflow, or instruct K2 to generate a XML datafield that will automatically store all the metadata for the list item. The structure of this data field will depend on the definition of the list or library where the item is created, so we cannot provide a definitive screenshot or explanation of the structure. However, the screenshot and table below describe an example of this XML datafield for a sample list
Saving the list item metadata into the workflow effectively creates a copy of the data captured in the SharePoint item, so bear in mind that if the SharePoint item is changed after the workflow has started, the data in the workflow may no longer be in sync. If you need to retrieve the latest values from the SharePoint item during the workflow, you can use the SharePoint List Items event to read the metadata from the item, or expose the SharePoint list as a SmartObject and then use the Read or List method to retrieve the data from the SharePoint list item.
If you need to retrieve metadata from the List Item several times in the workflow, it is easier to use the SmartObject approach, especially if you create a SmartObject reference in the process.
If you only need to retrieve the latest metadata once or twice in the workflow, the SharePoint List Items wizard approach is easier.
| Field/Field Data Type | Notes | Sample Value |
|---|---|---|
| Choice | Saves the Name of the item selected in the choice drop-down | Option 1 |
| DateTime (e.g. Created, Modified or custom date field) | Timestamp for the SharePoint server where the item was created | 2012-01-26T11:54:10 |
| Lookup | The ID and Value of the selected lookup item | 2;#Finance |
| User (e.g. Author or custom user field) | Stores values in domain\username for AD users | DENALLIX\administrator |
| ID | The SharePoint List Item ID | 2 |
| Title | Stores the title | Test Item |
| YesNo | True or False value | True |