Expose SharePoint Lists and Document Libraries as Data
To expose SharePoint Lists and Document Libraries as data, you need to generate a SmartObject based on a SharePoint List or Library. You will also need to enable the use of this SmartObject in Workflows. This can be done at the time of creating your K2 Application, when you generate a new SmartObject for your K2 Application or from the K2 for SharePoint App Settings page.
Generate SmartObjects at K2 Application Creation
When you create an Application from a SharePoint List or Library, K2 automatically creates a SmartObject for the list/library and other SmartObjects as needed, such as SmartObjects for attachments on custom Lists. This is why the Data check-box is selected and grayed out by default.
You can then select whether or not the SmartObjects should be made available for use in workflows by selecting the check-box to Allow this SmartObjects to be used in Workflows for this and selecting the availability scope for the SmartObject. The following options are available when defining the availability scope:
- List/Library: Select this option to allow the SmartObject to be used only in Workflows for this specific List/Library.
- Site and all of its subsites: Select this option to allow the SmartObjects to be used by Workflows in any List or Library for this site or all of the subsites under this Site.
Enable SmartObjects for use in Workflows at K2 Application Creation
When you create a K2 Application from a SharePoint List or Document Library, K2 automatically creates a SmartObject for the List/Library. To enable the use of this SmartObject in Workflows, select the Allow this SmartObject to be used in Workflows for this check-box at the time of the K2 Application creation. Click the drop-down and select one of the following options:
- List/Library: Select this option if you want the SmartObject to be visible for Workflows created only on this specific SharePoint List or Document Library.
- Site and all of its subsites: Select this option if you want the SmartObject to be visible in Workflows created on any List or Library in this SharePoint Site and subsites.
The same steps can be followed when generating new SmartObjects from the K2 Application page as illustrated in the image below
When exposing the SmartObject to workflows. the SmartObject properties and methods will be visible in the context browser under the SmartObject node and in the ribbon bar of the workflow design tool. The SmartObject's properties and methods can be dragged and dropped onto the design canvas/wizard or input fields as required. The image below illustrates SmartObjects in the context browser, using the E-mail Event as an example.
Generate SmartObjects from the K2 for SharePoint App Settings page
Follow these steps to generate single or multiple SharePoint List or Library SmartObjects for a Site:
- click on New from either the Libraries or Lists section.
- A list of SharePoint Lists or Libraries will display depending on which section you are working from. Select the items for which the SmartObjects will be created by clicking the check-box in front of each item. Select the Scope of these items. The Scope can be changed per item at a later stage. The Scope options are:
- This Site and all of its subsites - This option enables the use of the SmartObjects in a K2 workflow designed in the K2 for SharePoint application from any List or Library in the Site Collection including all of the sites subsites.
- List/Library - This option enables the use of the SmartObjects in a K2 workflow designed in the K2 for SharePoint application only for the specific List or Library.
- None - Selecting this option will prevent the use of the SmartObjects in a K2 workflow designed in the K2 for SharePoint application.
- Click OK to generate the selected items as SmartObjects.
- The items selected will now be listed under the relevant sections indicating the scope per item.
- If you click on New again, only the items for which SmartObjects do not exist will now be displayed. These can be selected to generate SmartObjects.
When generating SmartObjects based on SharePoint Lists, the associated Attachments SmartObject will also be generated and displayed in the list of SmartObjects as per the image above.
Clicking OK or Cancel on the Manage SmartObjects Landing page after generating SmartObjects, will not influence the SmartObjects generated. It will only save or cancel changes made to the Scope of these SmartObjects.
Enable SmartObjects for use in Workflows from the K2 for SharePoint App Settings page
Follow these steps to enable SmartObjects for use in Workflows:
- Open the K2 for SharePoint App Settings page from the SharePoint Site Contents and select the SmartObject item under Artifacts as shown in the image below
- This takes you to the Manage SmartObjects page.
- Select a SmartObject from either the Libraries or Lists section by highlighting the SmartObject
- Click on Edit. This enables the Scope drop-down which allows you to select the scope of visibility for the SmartObject in workflows. The Scope options are:
- This Site and all of its subsites - This option enables the use of SmartObjects in workflows designed any SharePoint List, Document Library or related subsites in the Site Collection.
- List/Library - This option enables the use of the SmartObjects in a workflow only for the specific SharePoint List or Document Library.
- None - Selecting this option will prevent the use of the SmartObject in a workflow designed in the K2 Application.
- Select an option and click OK to save the changes.
Unsupported SharePoint Fields (columns)
The Create K2 Application page will display a warning message in the Data section if K2 detects unsupported fields in the list/library.
Similarly, a warning displays in the Form Section if K2 supports a SharePoint Field at the SmartObject level but not at the Form level (Managed Metadata Fields, for example). You can still generate and use the Form, but K2 will not generate controls for the unsupported Fields on the generated Form. .
For unsupported lists and libraries (for example a Data Connection Library), K2 does not create a SmartObject nor the associated Forms and Views. For these unsupported lists and libraries, the Create K2 Application page will display an error message and prevent you from creating any artifacts, as shown below.
Exposed SmartObject Methods
When a SharePoint Library or List is exposed by the K2 for SharePoint App, specific smartobjects methods are created automatically. The methods can be used when creating rules in the K2 Designer for forms, smartobjects and views. The tables below provides a list of these methods and their definitions.
| List Item Methods | |
|---|---|
| Get List Items | Retrieves all the items in the current List. |
| Get List Items For Lookups | Retrieves all the items in the current List. Only retrieves a single field which is specified by the field’s internal name. Used by other Lists to retrieve items as fast as possible. |
| Get List Item By ID | Retrieves a single item which is specified by the item’s ID. |
| Get List Item By Title | Retrieves a single item which is specified by the item’s Title. |
| Get List Item By Name | Retrieves a single item which is specified by the item’s Name. |
| Get SharePoint Time Zone | Retrieves the Time Zone of the current SharePoint site. Mostly for internal use. |
| Create List Item | Creates an item in the current List. |
| Add User Or Group Permissions To List Item By ID | Add permissions to a List Item |
| Remove User of Group Permissions From List By ID | Remove permissions from a List Item |
| Stop Inheriting Permissions On List Item By ID | Stop inheriting permissions from the base List Item. The List Item specified will now have different permissions than all other List Items |
| Delete Unique Permissions From List Item By ID | Delete the unique permission on the specified List Item |
| Update List Item | Updates a single item which is specified by the item’s ID. |
| Delete List Item | Delete a single item which is specified by the item’s ID. |
| Recycle List Item | Place a single item in the Recycle Bin. The item that will be placed in the Recycle Bin is specified by the item’s ID. |
| Restore List Item | Restore a item from the recycle bin. The item to restore is specified by the item’s Recycle Bin Guid. |
| Copy List Item | Copy an item from the current List to a target List. The item to copy is specified by ID. The target List is specified by the List’s Relative Url |
| Move List Item | Move an item from the current List to a target List. The item to copy is specified by ID. The target List is specified by the List’s Relative Url |
| Copy List Item From | Copy an item from a target List to the current List. The item to copy is specified by ID. The target List is specified by the List’s Relative Url |
| Move List Item From | Move an item from a target List to the current List. The item to copy is specified by ID. The target List is specified by the List’s Relative Url |
| Document Methods | |
|---|---|
| Get Documents | Retrieves all the Documents in the current Library. |
| Get Documents Metadata | Retrieves all the Documents in the current Library without the Document’s File content (Faster call) |
| Get Documents Metadata for Lookups | Retrieves all the documents in the current Library. Only retrieves a single field which is specified by the field’s internal name. Used by other Libraries to retrieve documents as fast as possible. |
| Get Document | Get a single document with the document’s file content. The document to retrieve is specified by its Name |
| Get Document Metadata | Get a single document without the document’s file content. The document to retrieve is specified by its Name |
| Get Document By ID | Get Document By ID |
| Get Document Metadata By ID | Get a single document without the document’s file content. The document to retrieve is specified by its ID |
| Get SharePoint Time Zone | Retrieves the Time Zone of the current SharePoint site. Mostly for internal use. |
| Save Document to File Location | Save a single document to a local file location. The document to save is specified by Name |
| Upload Document | Upload local file to current Library |
| Add User Or Group Permissions To Library By ID | Add User Or Group Permissions To Library By ID |
| Remove User of Group Permissions Library By ID | Remove permissions from a document |
| Stop Inheriting Permissions On Library By ID | Stop inheriting permissions from the base document. The document specified will now have different permissions than all other documents |
| Delete Unique Permissions From Library By ID | Delete the unique permission on the specified document |
| Update Document Metadata | Update a single document’s properties. The document to update is specified by Name |
| Update Document Metadata by ID | Update a single document’s properties. The document to update is specified by ID |
| Delete Document | Delete a single document. The document to delete is specified by Name |
| Delete Document By ID | Delete a single document. The document to delete is specified by ID |
| Recycle Document | Place a single document in the Recycle Bin. The document that will be placed in the Recycle Bin is specified by its Name. |
| Recycle Document By ID | Place a single document in the Recycle Bin. The document that will be placed in the Recycle Bin is specified by its ID. |
| Restore Document | Restore a document from the recycle bin. The document to restore is specified by the document’s Recycle Bin Guid. |
| Rename Document | Rename a single document. The document to rename is specified by its Name |
| Rename Document By ID | Rename a single document. The document to rename is specified by its ID |
| Check In Document | Check In a single document. The document to check in is specified by its Name |
| Check In Document By ID | Check In a single document. The document to check in is specified by its ID |
| Check Out Document | Check Out a single document. The document to check out is specified by its Name |
| Check Out Document By ID | Check Out a single document. The document to check out is specified by its ID |
| Discard Document Check Out | Discard a single document’s Check Out. Discard the changes made to a Checked Out document. The document is specified by Name |
| Discard Document Checkout By ID | Discard a single document’s Check Out. Discard the changes made to a Checked Out document. The document is specified by ID |
| Copy Document | Copy a document from the current Library to a target Library. The document to copy is specified by Name. The target Library is specified by the Library’s Relative Url |
| Copy Document By ID | Copy a document from the current Library to a target Library. The document to copy is specified by ID. The target Library is specified by the Library’s Relative Url |
| Move Document | Move a document from the current Library to a target Library. The document to copy is specified by Name. The target Library is specified by the Library’s Relative Url |
| Move Document By ID | Copy a document from the current Library to a target Library. The document to copy is specified by ID. The target Library is specified by the Library’s Relative Url |
| Copy Document From | Copy a document from a target Library to the current Library. The document to copy is specified by Name. The target Library is specified by the Library’s Relative Url |
| Move Document From | Copy a document from a target Library to the current Library. The document to copy is specified by Name. The target Library is specified by the Library’s Relative Url |
Additional Methods depending on List/Library settings
| Folder Methods (If Folders are enabled these methods are added on the List/Library SmartObject) | |
|---|---|
| Get Folders | Retrieves all the folders in the current List/Library |
| Create Folder | Create a folder in the current List/Library |
| Rename Folder | Rename a single folder. The folder to rename is specified by its Name |
| Delete Folder | Delete a single folder. The folder to delete is specified by its Name |
| Recycle Folder | Place a single folder in the Recycle Bin. The folder to place in the Recycle Bin is specified by its Name |
| Restore Folder | Restore a single folder from the Recycle Bin. The folder to restore is specified by its Recycle Bin Guid |
| Copy Folder | Copy a single folder and all its contents from the current List/Library to a target List/Library. The folder to copy is specified by its Name. The target List/Library is specified by its Relative Url |
| Move Folder | Move a single folder and all its contents from the current List/Library to a target List/Library. The folder to copy is specified by its Name. The target List/Library is specified by its Relative Url |
| Attachment Methods (Can only be enabled on a List. If enabled an Attachment SmartObject with these methods is generated) | |
|---|---|
| Add Attachment | Add attachment to single List Item. The item to add an attachment to is specified by ID |
| Get Attachment | Get a single attachment from a specific List Item. The attachment to retrieve is specified by Name. The List Item to retrieve the attachment from is specified by its ID |
| Get Attachments List | Retrieves all the attachments from a single List Item without the attachment’s file content. The List Item to retrieve attachments from is specified by its ID |
| Get Attachments | Retrieves all the attachments from a single List Item with the attachment’s file content. The List Item to retrieve attachments from is specified by its ID |
| Remove Attachment | Remove a single attachment from a specific List Item. The attachment to remove is specified by Name. The List Item to remove the attachment from is specified by ID |
| Remove All Attachments | Remove all the attachments from a single List Item. The List Item to remove attachments from is specified by ID |
| Document Set Methods (Can only be created on Libraries. If a Library has a Document Set Content Type and a Document Set is created in the Library an additional SmartObject is created with the following methods) | |
|---|---|
| Get Document Sets | Retrieve all document sets in the current Library |
| Create Document Set | Create a document set in the current Library |
| Get Document Set | Get a single document. The document to retrieve is specified by Name |
| Get Document Set By ID | Get a single document. The document to retrieve is specified by ID |
| Get Document in Document Set | Retrieve all the documents in a single document set. The document set to retrieve documents from is specified by Name |
| Get Document in Document Set By ID | Retrieve all the documents in a single document set. The document set to retrieve documents from is specified by ID |
| Update Document Set | Update a single document set’s properties. The document set to update is specified by Name |
| Update Document Set By ID | Update a single document set’s properties. The document set to update is specified by ID |
| Rename Document Set | Rename a single document set. The document set to rename is specified by Name |
| Rename Document Set By ID | Rename a single document set. The document set to rename is specified by ID |
| Delete Document Set | Delete a single document set. The document set to delete is specified by Name |
| Delete Document Set By ID | Delete a single document set. The document set to delete is specified by ID |
| Recycle Document Set | Place a single document and all its content in the Recycle Bin. The document set to place in the Recycle Bin is specified by Name |
| Recycle Document Set By ID | Place a single document set and all its content in the Recycle Bin. The document set to place in the Recycle Bin is specified by ID |
| Restore Document Set | Restore a single document set and all its content from the Recycle Bin. The document set to restore is specified by its Recycle Bin Guid |
| Copy Document Set | Copy a single document set and all its content from the current Library to the target Library. The document set to copy is specified by Name. The target Library is specified by its Library Relative Url |
| Copy Document Set By ID | Copy a single document set and all its content from the current Library to the target Library. The document set to copy is specified by ID. The target Library is specified by its Library Relative Url |
| Move Document Set | Move a single document set and all its content from the current Library to the target Library. The document set to move is specified by Name. The target Library is specified by its Library Relative Url |
| Move Document Set By ID | Move a single document set and all its content from the current Library to the target Library. The document set to move is specified by ID. The target Library is specified by its Library Relative Url |
| Choice Methods (If a choice field is added to the List/Library a Choice SmartObject with the following methods is generated) | |
|---|---|
| GetFieldMetaData | Retrieves the different choices that can be selected for the field. Mostly internal use. |