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. For the use of attachments and files please see the below sections.

Configuration

Field name	Description	Format	Example
Domain	The domain of the Sharepoint site to be accessed.	<sharepointDomain>/<siteName>	https://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.

Java

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.

Java

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.

File handling

If list items (class SharepointListItem) contain attachments and includeAttachments=="true" was provided in the query, they will be listed in the attribute attachments, which is a map which maps the file name to the Base64 string of the file.

Regular files (class SharepointFile) were handled as Base64 strings in the attribute downloadableFile of the SharepointFile object before version 3.0, but gets handled differently since 3.0:

The SharepointFile object's attribute downloadableFile was changed from a String to a File, so that the JSON of a SharepointFile object now only contains the attribute downloadableFileURL. The SDKs handle this transparently for you and you can simply call mySharepointFile.loadDownloadableFile() or a similar method (depending on the SDK you use) to download the file. In Native Module code similar methods are available. For manual HTTP calls see the section below.

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 assumedJSON

{
  "@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",
  "attachments": {
    "myFile.png": "�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 "attachments" contains a map that maps file names to Base64 strings of the files.

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

JSON

body

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

Load a SharepointFile

When loading a SharepointFile object you will get a JSON that contains a downloadableFileURL, which looks like this:

https://apiomat.yourcompany.com/yambas/rest/apps/YourApp/data/files/Sharepoint/SharepointFile/47-_100-_101-_109-_111-_47-_70-_114-_101-_101...120-_116/downloadableFile/47-_100-_101-_109-_111-_47-_70-_114-_101-_101...120-_116

You have to suffix this URL with ".img" and send a GET request to it, with the usual ApiOmat specific headers and "Accept: application/octet-stream".

This will lead to a response that consists of the file.

CRUD Functionality - (Create Read Update Delete)

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.