Content

Introduction

The Sharepoint module enables app developers to access information about lists, folders, folder contents and files stored within a Microsoft Sharepoint instance. It covers basic information about found list items and will provide any additional information in a dynamic Map called additionalAttributes. If items contain attachments, they will be listed as an Array of Byte64-Strings in the attribute attachmentBytes if includeAttachments=="true" was provided in the query.

Configuration

Field name	Description	Format	Example
Domain	The domain of the Sharepoint site to be accessed.	<sharepointDomain>/<siteName>	mycompany.sharepoint.com/site

Authentication

direct Authentication

Apiomat users that will have to access Sharepoint must use an e-mail address and password that correspond to a Sharepoint user. In order to access the api, the api-key of the backend needs to be provided. Api-docs provides a convenient way to test the functionality of the Sharepoint connector.

Authentication with a system user

The Sharepoint Module can be set up with a system user, which has access to the corresponding sharepoint. If sharepoint-credentials are provided in the Module-Configuration, the provided credentials will be used to authenticate against sharepoint, while regular Users (ApiOmat-Users) can be used to access sharepoint data.

Use

Getting information about lists is done using the SharepointList meta model. Simply call the usual methods to get either one object or all.

Example for lists

        List<SharepointList> listOfLists = SharepointList.getSharepointLists( query );
        for ( SharepointList sharepointList : listOfLists )
        {
            System.out.println( sharepointList.getTitle( ) );
        }
   

The meta models called SharepointFile and SharepointFolder provide information about files and folders located in a particular folder. Therefore, you need to specify which folder to use by passing the folder path in the query.

Example for folders and files

    private static void printFolders( String parentFolderPath ) throws ApiomatRequestException
	{
		List<SharepointFolder> folderList = SharepointFolder.getSharepointFolders( "path==\"" + parentFolderPath + "\"" );
		for ( SharepointFolder sharepointFolder : folderList )
		{
			String subFolderPath = parentFolderPath + "/" + sharepointFolder.getName( );
			System.out.println( subFolderPath );
			printFiles( subFolderPath );
			printFolders( subFolderPath );
		}
	}
 
    private static void printFiles( String parentFolderPath ) throws ApiomatRequestException
	{
		List<SharepointFile> files = SharepointFile.getSharepointFiles( "path==\"" + parentFolderPath + "\"" );
		for ( SharepointFile sharepointFile : files )
		{
			System.out.println( parentFolderPath + "/" + sharepointFile.getName( ) );
		}
	}

The meta model SharepointFolderContent can be used additionally to get both sub-folders and files that are located inside a certain folder by specifying the folder path in the query. This will return an object which holds lists of references to objects of SharepointFile and SharepointFolder.

REST-Interface

Load a complete List

GET <baseURL>/yambas/rest/apps/<AppName>/models/Sharepoint/SharepointList

Query: key=="value" example: title=="Todos"

possible keys: title / foreignId / description / entityTypeName / imageURL / parentWebUrl / templateFeatureId

Load a list item

GET <baseURL>/yambas/rest/apps/<AppName>/models/Sharepoint/SharepointListItem/

dataModelId <foreignId-of-parent>__<itemId> example: 410c6c68-25a1-42a0-b542-dc6cd83784b9__2

explanation for the example:

410c... is the foreignId of Todos

__ is a double _underline that separates the ids

2 is the second item on Todos (caution: list items always start at 1)

(default) if no list item id is provided (..84b9 ) __1 is assumed

Update a list item

PUT <baseURL>/yambas/rest/apps/<AppName>/models/Sharepoint/SharepointListItem/

dataModelId: <foreignId>

Behavior: If an item is saved the server will respond with Status 200 and the item will have been updated.

Important: @type and foreignId need to be provided

body

{
    "@type": "Sharepoint$SharepointList",
    "foreignId": "506e9fc8-8669-42a5-a69b-1723783f9882"
	...
} 
 

Reading ListItems

{
  "@type": "Sharepoint$SharepointListItem",
  "createdAt": 1474964472340,
  "lastModifiedAt": 1474964472340,
  "id": null,
  "applicationName": "TestSharepoint",
  "moduleName": "Sharepoint",
  "allowedRolesRead": [],
  "allowedRolesWrite": [],
  "allowedRolesGrant": [],
  "restrictResourceAccess": false,
  "foreignId": "506e9fc8-8669-42a5-a69b-1723783f9882__1",
  "referencedHrefs": {},
  "additionalAttributes": {
    "ParentID": "",
    ...
  },
  "assignedTo": "Mr. Mister",
  "attachmentBytes": [
    "�PNG\r\n\u001a...
],
  "dueDate": "07.10.2016",
  "guid": "e47d9d03-14bd-433c-9152-7bdfb1d92868",
  "listId": "506e9fc8-8669-42a5-a69b-1723783f9882",
  "order": 1,
  "percentComplete": "20 %",
  "title": "Testen der Aufgaben",
  "href": "<baseURL>/yambas/rest/apps/<AppName>/models/Sharepoint/SharepointListItem/506e9fc8-8669-42a5-a69b-1723783f9882__1"
}

"foreignId" consists of two ids where the part on the left before "__" is the foreignId of the parent List and the number on the right resembles the index of the Sharepoint item. The attributes from "@type" to "additionalAttributes" will be provided by ApiOmat, while "assignedTo" to "title" will be provided by Sharepoint and will only be mapped by ApiOmat. Additional information that was provided by Sharepoint will be found in "additionalAttributes". The attribute "attachmentBytes" contains an Array of Byte64-Strings resembling the attached binary files.

CRUD Functionality - ( C reate R ead U pdate D elete)

is provided for:

SharepointList
SharepointListItem
SharepointFile
SharepointFolder

partially provided

SharepointListField (R)
SharepointFolderContents (RD)

Query

Supported expressions in queries:

name	format	example
equals expressions	`<key>=="<value>"`	`title=="Todos"`
order by	`order by <fieldName> (asc\|desc)`	`order by createdAt`
limit	`limit <limitValue>`	`limit 10`
offset	`offset <offsetValue>`	`offset 500`

Support of multiple sites

It is possible to read data from different Sharepoint sites by providing the site name in the query like: site=="<siteName>".

If the site key is present in a query, the site name configured in the domain will be overriden.

DeltaSync

The Sharepoint connector supports object based DeltaSync for the models SharepointList, SharepointListItem and SharepointListField (limited, see section "Limitations").

To use it just enable DeltaSync via the Datastore or set the DetaSyncStrategy to OBJECT_BASED (depending on your SDK). For further information have a look at the DeltaSync page.

Limitations - work in progress

query passing to sharepoint only works partially
implementation of sharepoint SearchAPI
DeltaSync for SharepointListField returns deleted as well as objects removed from a query result in the x-apiomat-delta-removed header. The x-apiomat-delta-deleted will always be empty.