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.

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 AD 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> <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 be excluded on your SmartObjects.
Excluded Lists	XML	<lists> <property name='BaseTemplate' operator='equals' value='100' /> <property name='BaseTemplate' operator='equals' value='101' /> </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> <Fields> <list name="TypeAsString" value="BusinessData" /> <list name="TypeAsString" value="ContactInfo" /> </Fields>	The property allows you to specify an override for which Fields must surface in the SmartObjects.
Included Lists	XML	<lists> <property name='BaseTemplate' operator='equals' value='100' /> <property name='BaseTemplate' operator='equals' value='101' /> </lists> <Lists> <list name="BaseType" value="102" /> <list name="BaseType" value="108" /> </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

The tables below describe some of the commonly-used Service Object Methods for this service.

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.