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.

 K2 uses two Service Types for integrating with SharePoint Online/2013 and later:

• K2 SharePoint 2013
• K2 SharePoint 2013 Integration (this service is reserved for internal use and 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 2013 Service Type.

Service Authentication

OAuth is the only supported Authentication Mode for the SharePoint 2013 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 K2 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 2013 broker are based on the site collection.

As part of the Service Registration , you can see the resources that K2 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		(Required) When set to True this will force the user to specify a complete URL during execution as opposed to relative URLs based on the instance. Default value is False.
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.

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

K2 generates SmartObjects for these Service Objects when you create Data for a K2 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 2013 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 K2 Support
• Any instances of the SharePoint 2013 service broker must be created by using the K2 for SharePoint App Registration Wizard.
• The SharePoint 2013 Integration broker is not meant to be used directly and is reserved for internal use by K2
• 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 K2 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