SharePoint 2013
The SharePoint 2013 Service Type is used to integrate with SharePoint via the client side object model (CSOM) and REST services to query and update SharePoint lists and libraries. This service type forms the foundation of integration between K2 and SharePoint Online/2013 and later.
The product uses two Service Types for integrating with SharePoint Online/2013 and later:
- K2 SharePoint
- K2 SharePoint Integration (this service is reserved for internal use and new instances cannot be registered or modified, but it may be visible in your environment)
For the purposes of this topic, we will focus only on the K2 SharePoint Service Type.
You cannot manually register, refresh, modify or delete service instances for the SharePoint service types (unless directed by Nintex Customer Central to do so). You must use the K2 for SharePoint App registration wizard to create and manage Service Instances.
The product integrates with SharePoint Lists and Libraries by appifying them. SmartObjects of the structure of the List or Library are created in SmartBox, making the data of the List or Library available for use in SmartForms and workflows. You can appify each List or Library, or for Lists and Libraries that have identical data structures, you can create an application of the primary List or Library and use those SmartObject methods to access the data in the secondary Lists or Libraries, such as an Employee List that exists in multiple region sub-sites (all with the same columns). See Using SharePoint Data.
Service Authentication
OAuth is the only supported Authentication Mode for the SharePoint Service Brokers. The necessary configuration to enable OAuth is performed when you register the App in a SharePoint site, which is one of the main reasons a service instance cannot be manually created. The authentication uses either a high-trust, server to server (S2S) token for on-premises SharePoint servers, or a standard token along with an Azure Active Directory token for SharePoint Online servers.
To allow the server to integrate with SharePoint outside of the context of a user (for example when a workflow executes a SmartObject that points to a list in SharePoint), an administrative OAuth token is generated at the time of registration, which happens on the app catalog. The site collections served by that app catalog all use the same Administrative OAuth token, however the instances of the SharePoint broker are based on the site collection.
As part of the Service Registration , you can see the resources that the product creates to enable the authentication and integration.
Service Keys (Service Instance Configuration Settings)
Key | Data Type | Sample Value | Notes |
---|---|---|---|
Admin Site URL | Uri for the administration site. | http://dlx:44544/default.aspx | (Only applies to on-premises) this will expose the administration site as a SmartObject for things like site templates. |
Default Locale ID | Number | 1033 for English | The Locale ID is set to identify the culture and language used by windows to display information. |
Describe sub sites | True or False | When set to True, sub sites will be shown in the service instance if False they will not be displayed. The default is False. | |
Dynamic | True or False | False |
(Required) Reserved for future functionality. This service key is internal to the product and does not configure the reuse of K2 for SharePoint artifacts or any Dynamic URL features. |
Excluded Fields | XML |
<fields> |
The property allows you to specify an override for which Fields must be excluded on your SmartObjects. |
Excluded Lists | XML |
<lists> |
The property allows you to specify an override for which Lists must be excluded on your SmartObjects. |
Include Hidden Libraries | True or False | When set to True, all Service Objects based on the hidden libraries in the SharePoint site will be exposed, provided the user has sufficient permissions in SharePoint. The default value is False. | |
Include Hidden Lists | True or False | Taxonomy Hidden List User Information List | When set to True, all Service Objects based on the hidden lists in the SharePoint site will be exposed, provided the user has sufficient permissions in SharePoint. The default value is False. |
Included Fields | XML |
<fields>
<property name='TypeAsString' operator='equals' value='MediaFieldType' />
<property name='TypeAsString' operator='equals' value='Overbook' />
</fields>
|
The property allows you to specify an override for which Fields must surface in the SmartObjects. |
Included Lists | XML |
<lists> |
The property allows you to specify an override for which lists you want to surface in your SmartObject layer. This includes custom lists. |
Office 365 | True or False | If connecting to SharePoint On-premises, this field must be set to False. If the value is set to True, it will indicate the URL is a SharePoint Online site. | |
Site Url | Http or Https link | https://portal.denallix.com | (Required) The local or cloud SharePoint site URL against which the instance is registered and from where the Service Objects are to be exposed. The default value is HTTP:// |
Parse Lookup Field Values | True or False | When set to True, this will parse the Lookup Field values in SharePoint. The default value here is True. In SharePoint, the number of Lookup Field values is limited to 8 (Refer to http://support.microsoft.com/kb/2489707 for more information). | |
Throttle Documents | Number | (Required) The number of results that can be returned in a user query. The default value is 50. (changing the number of returned results will have an impact on performance). | |
Throttle List Items | Number | (Required) The number of results that can be returned in a user query. The default value is 2000. (changing the number of returned results will have an impact on performance). | |
Use Internal Field Names | True or False | When set to False, the Service Object schema properties display names will be 'Display' names. When set to True, the property names displayed will be System names. The default value is False (Display names). | |
Service Time Out | Time intervals in milliseconds | (Required) Service registration time out. The default value is 120000ms (If increased this will allow for service to wait longer before it times out, this will be helpful if the connection to SharePoint is slow). |
Service Objects
When SmartObjects are created for the Service Instance, they are organized within the following categories:
- Management
- Sites
- Taxonomy (You may not see the Taxonomy node if your SharePoint site does not include a Managed Metadata term store)
- Lists
- Libraries
If the K2 for SharePoint App is added to a subsite of the site collection, it is added to the service instance that already exists for the site collection. The structure of the artifacts generated, such as SmartObjects, View, Forms, Workflows and Reports, follows the structure of the site collection. For example, if you have a subsite called Subsite1 that is a child of your root site, and created a subsite under Subsite1 called Subsite1-1, when you add the K2 for SharePoint app to Subsite1-1 and generate at least a data app for the Documents library on Subsite1-1, the following structure is created automatically
Sorting and paging may only be used on the following SmartObject methods:
- Get List Items
- Get List Items with Method Options
- Get Documents Metadata With Options
- Get Documents Metadata
- Get Document Sets
The tables below describe some of the commonly-used Service Object Methods for this service.
Method | Description | CSOM/REST |
---|---|---|
Add User Or Group Permissions To List Item By ID | Add permissions to a List Item. | CSOM |
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. | CSOM |
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. | CSOM |
Create List Item | Creates an item in the current List. | CSOM |
Delete List Item | Delete a single item which is specified by the item’s ID. | CSOM |
Delete Unique Permissions From List Item By ID | Delete the unique permission on the specified List Item | CSOM |
Get List Item By ID | Retrieves a single item which is specified by the item’s ID. | CSOM |
Get List Item By ID without Lookup Values | Retrieves a single item which is specified by the item’s ID. | REST |
Get List Item By Name | Retrieves a single item which is specified by the item’s Name. | CSOM |
Get List Item By Name without Lookup Values | Retrieves a single item which is specified by the item’s Name. | REST |
Get List Item By Title | Retrieves a single item which is specified by the item’s Title. | CSOM |
Get List Item By Title without Lookup Values | Retrieves a single item which is specified by the item’s Title. | REST |
Get List Items | Retrieves all the items in the current List. | CSOM |
Get List Item By View | Retrieves a single item which is specified by the item’s View. | CSOM |
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. | CSOM |
Get Permissions On List Item By ID | Retrieve all the permissions on the list item specified by the item’s ID. If you have an existing SmartObject, you must regenerate the SmartObject to use this method. From the Application page, click New > Generate SmartObjects, or edit the SmartObject to manually add the method. | CSOM |
Get SharePoint Time Zone | Retrieves the Time Zone of the current SharePoint site. Mostly for internal use. | CSOM |
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. | CSOM |
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. | CSOM |
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. | CSOM |
Remove User of Group Permissions From List By ID | Remove permissions from a List Item. | CSOM |
Restore List Item | Restore a item from the recycle bin. The item to restore is specified by the item’s Recycle Bin Guid. | CSOM |
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 | CSOM |
Update List Item | Updates a single item which is specified by the item’s ID. | CSOM |
Method | Description | CSOM/REST |
---|---|---|
Add User Or Group Permissions To Library By ID | Add permissions to a document. | CSOM |
Check In Document | Check In a single document. The document to check in is specified by its Name. | CSOM |
Check In Document By ID | Check In a single document. The document to check in is specified by its ID. | CSOM |
Check Out Document | Check Out a single document. The document to check out is specified by its Name. | CSOM |
Check Out Document By ID | Check Out a single document. The document to check out is specified by its ID. | CSOM |
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. | CSOM |
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. | CSOM |
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. | CSOM |
Delete Document | Delete a single document. The document to delete is specified by Name. | CSOM |
Delete Document By ID | Delete a single document. The document to delete is specified by ID. | CSOM |
Delete Unique Permissions From Library By ID | Delete the unique permission on the specified document. | CSOM |
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. | CSOM |
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. | CSOM |
Get Document | Get a single document with the document’s file content. The document to retrieve is specified by its Name. | CSOM |
Get Document By ID | Get a single document with the document’s file content. The document to retrieve is specified by its ID. | CSOM |
Get Document Metadata | Get a single document without the document’s file content. The document to retrieve is specified by its Name. Use this method for a List View with paging. | CSOM |
Get Document Metadata without Lookup Values | Get a single document without the document’s file content. The document to retrieve is specified by its Name. | REST |
Get Document Metadata By ID | Get a single document without the document’s file content. The document to retrieve is specified by its ID. | CSOM |
Get Document Metadata by ID without Lookup Values | Get a single document without the document’s file content. The document to retrieve is specified by its ID. | REST |
Get Documents | Retrieves all the Documents in the current Library. | CSOM |
Get Documents Metadata | Retrieves all the Documents in the current Library without the Document’s File content (Faster call). | CSOM |
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. | REST |
Get Documents Metadata by View | Retrieves all the Documents in the current Library. The documents to retrieve are specified by the View. | CSOM |
Get Documents Metadata without Lookup Values | Retrieves all the Documents in the current Library without the Document’s File content (Faster call). No Paging/Sorting. Some limitations on filtering. | REST |
Get Documents Metadata with Options | Retrieves all the Documents in the current Library. The documents to retrieve are specified by the options. | CSOM |
Get Permissions On Document By ID | Retrieve all the permissions on the document specified by the document’s ID. If you have an existing SmartObject, you must regenerate the SmartObject to use this method. From the Application page, click New > Generate SmartObjects, or edit the SmartObject to manually add the method. | CSOM |
Get SharePoint Time Zone | Retrieves the Time Zone of the current SharePoint site. Mostly for internal use. | CSOM |
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. | CSOM |
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. | CSOM |
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. | CSOM |
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. | CSOM |
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. | CSOM |
Remove User or Group Permissions Library By ID | Remove permissions from a document. | CSOM |
Rename Document | Rename a single document. The document to rename is specified by its Name. | CSOM |
Rename Document By ID | Rename a single document. The document to rename is specified by its ID. | CSOM |
Restore Document | Restore a document from the recycle bin. The document to restore is specified by the document’s Recycle Bin Guid. | CSOM |
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. | CSOM |
Update Document Metadata | Update a single document’s properties. The document to update is specified by Name. | CSOM |
Update Document Metadata by ID | Update a single document’s properties. The document to update is specified by ID. | CSOM |
Upload Document | Upload local file to current Library. REST is used for the upload part to overcome the size limit of CSOM. CSOM is used to update the file metadata. | CSOM and REST |
If Folders are enabled these methods are added on the List/Library SmartObject
Method | Description | CSOM/REST |
---|---|---|
Add User Or Group Permissions To Folder | Add permissions to a folder. If you have an existing SmartObject, you must regenerate the SmartObject to use this method. From the Application page, click New > Generate SmartObjects, or edit the SmartObject to manually add the method. | CSOM |
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. | CSOM |
Create Folder | Create a folder in the current List/Library. | CSOM |
Delete Folder | Delete a single folder. The folder to delete is specified by its Name. | CSOM |
Delete Unique Permission From Folder | Delete the unique permission on the specified folder. If you have an existing SmartObject, you must regenerate the SmartObject to use this method. From the Application page, click New > Generate SmartObjects, or edit the SmartObject to manually add the method. | CSOM |
Get Folders | Retrieves all the folders in the current List/Library. | CSOM |
Get Permissions On Folder | Retrieve all the permission on the specified folder. If you have an existing SmartObject, you must regenerate the SmartObject to use this method. From the Application page, click New > Generate SmartObjects, or edit the SmartObject to manually add the method. | CSOM |
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. | CSOM |
Recycle Folder | Place a single folder in the Recycle Bin. The folder to place in the Recycle Bin is specified by its Name. | CSOM |
Remove User Or Group Permissions From Folder | Remove permissions from a folder. If you have an existing SmartObject, you must regenerate the SmartObject to use this method. From the Application page, click New > Generate SmartObjects, or edit the SmartObject to manually add the method. | CSOM |
Rename Folder | Rename a single folder. The folder to rename is specified by its Name. | CSOM |
Restore Folder | Restore a single folder from the Recycle Bin. The folder to restore is specified by its Recycle Bin Guid. | CSOM |
Stop Inheriting Permissions on Folder | Stop inheriting permissions from the base document library. The folder specified will now have different permissions than all other folders. If you have an existing SmartObject, you must regenerate the SmartObject to use this method. From the Application page, click New > Generate SmartObjects, or edit the SmartObject to manually add the method. | CSOM |
If Attachments are enabled for a List, an Attachment SmartObject with the following methods is generated.
Method | Description | CSOM/REST |
---|---|---|
Add Attachment | Add attachment to single List Item. The item to add an attachment to is specified by ID. | CSOM |
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. | CSOM |
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. | CSOM |
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. | CSOM |
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. | CSOM |
Remove All Attachments | Remove all the attachments from a single List Item. The List Item to remove attachments from is specified by ID. | CSOM |
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.
Method | Description | CSOM/REST |
---|---|---|
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. | CSOM |
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. | CSOM |
Create Document Set | Create a document set in the current Library. | CSOM |
Delete Document Set | Delete a single document set. The document set to delete is specified by Name. | CSOM |
Delete Document Set By ID | Delete a single document set. The document set to delete is specified by Name. | CSOM |
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. | CSOM |
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. | CSOM |
Get Document Set | Get a single document. The document to retrieve is specified by Name. | CSOM |
Get Document Set By ID | Get a single document. The document to retrieve is specified by ID. | CSOM |
Get Document Sets | Retrieve all document sets in the current Library. | CSOM |
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. | CSOM |
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. | CSOM |
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. | CSOM |
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. | CSOM |
Rename Document Set | Rename a single document set. The document set to rename is specified by Name. | CSOM |
Rename Document Set By ID | Rename a single document set. The document set to rename is specified by Name. | CSOM |
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. | CSOM |
Update Document Set | Update a single document set’s properties. The document set to update is specified by Name. | CSOM |
Update Document Set By ID | Update a single document set’s properties. The document set to update is specified by Name. | CSOM |
If a choice field is added to the List/Library a Choice SmartObject with the following methods is generated
Method | Description | CSOM/REST |
---|---|---|
GetFieldMetaData | Retrieves the different choices that can be selected for the field. Mostly internal use. | CSOM |
SmartObjects
The product generates SmartObjects for these Service Objects when you create Data for an application in SharePoint. To generate SmartObjects for a specific List or Library, browse to the library, click the K2 Application button, and then makes sure Data is selected. This refreshes the service instance and generates the SmartObject in the corresponding category that mimics the structure of your site collection.
If you do not need these SmartObjects to show up in the browser-based workflow design tools, select None in the Allow this SmartObject to be used in Workflow for this setting. Selecting This site and all of its subsites allows the SmartObject to appear in the browser-based workflow designer when designing workflows on sites that are direct descendants of the site.
If you do not need these SmartObjects to show up in the designer (for use in workflows) you can select None. Note that selecting This site and all of its subsites allows the SmartObject to appear in the designer when designing workflows on sites that are direct descendants of the site.
You can also use the SmartObjects link from the K2 for SharePoint Settings page to generate multiple SmartObjects at a time for selected Lists or Libraries in the Site. This is especially helpful if you need to use data from other lists and libraries on your site but do not need to create additional artifacts, such as Views, Forms, Workflows and Reports, for those lists and libraries
Finally, designers can also use the SmartObject design tools to build advanced SmartObjects that leverage the Service Objects in this service.
Considerations
- An authentication error will occur if the timestamp between two systems is more than 5 minutes apart. You will receive an error and not be able to authenticate through to an Office 365 environment using the K2 SharePoint broker if the systems have a timestamp more than 5 minutes apart.
- Refreshing, modifying or deleting an existing service instance of this Service Type should only be done if instructed to do so by Nintex Customer Central.
-
Use the Edit button to modify the service keys of the SharePoint Service Type. Do not change any other settings on the edit page.
- Any instances of the SharePoint broker must be created by using the K2 for SharePoint App Registration Wizard.
- The SharePoint Integration broker is not meant to be used directly and is reserved for internal use by the product
- This service type uses a combination of REST and CSOM calls, depending on the task being performed. Some tasks can only be performed in one of the available APIs, while other tasks may perform better in one of the APIs. This means that some methods are constrained by the limitations of REST.
- When using REST, as is the case for ‘without Lookups’ methods, we lose capabilities in SmartObjects. Namely, we cannot guarantee that all columns are filterable, and paging doesn’t work. However, it does allow for more than twelve lookups because the broker is not joining to get the Value column. When using the GetListItemsByView method in SmartForms, the SharePoint broker successfully builds up a return table that corresponds to the View Fields, but the K2 Host Server is restricted to the Return Properties for the method. This means that you have to give the method the same amount of return properties that you would expect for the normal GetListItems as the K2 Host Server will only populate the fields that have been described. This is important if you are using the ‘All Items’ view since ‘Title’ is then not part of the view, but instead ‘LinkTitle' (linked to item with edit menu) and 'Id' is. You are limited to only selecting the fields in the view that have described
- No sorting or paging is implemented by the broker, so data is returned in the same order that it was entered into SharePoint from a Choice Column when displayed in a SmartForm.
-
SharePoint Lookup Column Limits: SharePoint limits the number of join operations that can happen per query. This limit surfaces when SharePoint SmartObject methods are used to access data in a list or library with more than the maximum number of lookup, person/group, or workflow status columns. SharePoint Online, SharePoint 2016 and SharePoint 2013 (with CU June 2013) all have a default limit of 12 lookups per query. SharePoint Online cannot be changed. SharePoint 2016/2013 can be changed per this article https://blogs.msdn.microsoft.com/spses/2013/12/02/sharepoint-20102013-list-view-lookup-threshold-uncovered. Microsoft has implemented these limits for good reason and both Microsoft and we highly recommend you honor these limits and build solutions that don’t exceed them for optimal SharePoint and product performance. We do understand that rare situations exist that may require a solution to exceed the limits. In these cases, the solution must be manually configured to primarily use methods that no longer return lookup values for both SmartForms and Workflow Item References. This will require that an additional call be made with the Lookup column ID to return the Lookup Column Value when necessary in the solution. The methods ending with “Without Lookup Values” should be used for these solutions.
When the look-up threshold limit of a SharePoint list or library is reached, a SharePoint error stating "This view cannot be displayed because the number of look-up and workflow status columns it contains exceeds the threshold enforced by the administrator" is displayed. Similarly, trying to integrate the list or library with K2 app will result in the error "GUID should contain 32 digits with 4 dashes."
- The SharePoint broker uses the SharePoint CSOM API which limits name values to a maximum of 128 characters. So you cannot use SharePoint SmartObjects to create document sets or folders with names longer than the 128 character limit.