Developer's Guide - SAP Help Portals Guide Content 1 Developer's Guides You can develop your own clients or servers for SAP Mobile Documents using the respective developer's guide

PUBLIC

SAP Mobile Documents 1.0 SP06Document Version: 1.6 – 2017-03-02

Developer's Guide

Content

1 Developer's Guides. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.1 Developing Clients. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3CMIS Open Standard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4CMIS Enhancements for . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7REST API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21URLs for App-to-App Integration of SAP Mobile Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

1.2 Connecting Your ABAP Back End as a Content Source. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32ABAP Connector. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Implementing the ABAP Connector. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

1.3 CMIS Extension for Search. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

2 P U B L I CDeveloper's Guide

Content

1 Developer's Guides

You can develop your own clients or servers for SAP Mobile Documents using the respective developer's guide.

● Developing Clients [page 3]● Connecting Your ABAP Back End as a Content Source [page 32]

Related Information

CMIS Extension for Search [page 46]

1.1 Developing Clients

To develop your own clients, you need to be familiar with the architecture of SAP Mobile Documents, the CMIS open standard, and its SAP Mobile Documents extensions.

You can develop your own clients that connect to the SAP Mobile Documents server or you can integrate SAP Mobile Documents functionality into existing platforms.

Related Information

Architecture [page 3]CMIS Open Standard [page 4]CMIS Enhancements for [page 7]REST API [page 21]URLs for App-to-App Integration of SAP Mobile Documents [page 24]

1.1.1 Architecture

The main components of the solution are the clients, the server, and the document repositories.

To ensure interoperability and extensibility, the OASIS standard CMIS (Content Management Interoperability Services) is used for all document-related communication between the clients and the server as well as between the server and the repositories. In the current version of the solution (1.0 SP2), we deliver clients for the desktop (Windows and OS-X), for mobile devices (iPhone, iPad, and Android phones), and a JavaScript-based Web UI.

Developer's GuideDeveloper's Guides P U B L I C 3

All clients connect to and communicate with a single server, the server, using the CMIS protocol. The server is offered . On the server, you can configure settings, users, and connectivity configurations for integrating CMIS-compliant document management systems.

As well as connecting additional (corporate) repositories to the server, offers dedicated repositories to the clients:

● The My Documents repositoryThe repository where every user can store their personal files and then synchronize the repository content with all connected clients. Every user has a folder that is marked as their "home" folder. All folders and files in this home folder are only visible and accessible to the user.

● The Shared Documents repositoryThe repository where users can share files with each other as well as with external users. If Shared Documents is enabled on the server, every user can create shares, invite members to collaborate, and manage the access rights of these members. To share files with external parties, users must create public links to shares with security settings such as expiration date or password. A public link is accessible through a dedicated non-guessable URL, which you can additionally protect with a password. If you enable the write option for a share, anonymous users can also upload or delete documents in this share.

1.1.2 CMIS Open Standard

CMIS (Content Management Interoperability Services) is an open standard that defines a common interface for various operations offered by content management systems. CMIS defines a domain model and operations for different binding types.

CMIS is language-independent, which gives it a significant advantage over other specifications, and many vendors offer (or are going to offer) CMIS interfaces to their systems. In addition, CMIS client libraries already exist in different programming languages. Many of them are available as Open Source implementations under the umbrella project Apache Chemistry. SAP uses the Chemistry components for both app and server implementations.


Developer's Guides

Prerequisites for Developers

To develop an app or to integrate functions, developers need to familiarize themselves with CMIS and Apache Chemistry. If you are a Java developer, OpenCMIS is the tool of choice. Many of the examples in this guide are based on using OpenCMIS to connect to the server.

Related Information

Apache ChemistryOpenCMIS Client API Developer's GuideCMIS 1.1 Specification on OASIS Web page

1.1.2.1 Object Model

uses document and folder objects.

CMIS 1.1 defines the following primary base types:

● Document objects● Folder objects● Relationship objects● Policy objects● Item objects

Currently, supports only document and folder objects.

A document object is an item of content. The document can have a content stream, which is the actual file associated with the document. A content stream exists only as part of its containing document object. A content stream has a mime type associated with it. A document object may contain one or more renditions, which are alternative views of the content. Document objects are the only objects that are versionable. Each version of a document has its own object ID. All the versions of a document make up a version series and share a version series ID. You can create, read, update, and delete documents using OpenCMIS methods.

A folder object is a container used to organize the document objects. A repository has one root folder. All other folder objects have one parent folder. A folder has a folder path representing its place in the repository's folder hierarchy. A folder object can have renditions. For example, a folder can have a thumbnail as a rendition representing the contents of the folder.


http://help.sap.com/disclaimer?site=http://chemistry.apache.org

http://help.sap.com/disclaimer?site=http://chemistry.apache.org/java/developing/guide.html

http://help.sap.com/disclaimer?site=http://docs.oasis-open.org/cmis/CMIS/v1.1/os/CMIS-v1.1-os.html

1.1.2.2 Bindings

supports two of the three binding types defined in CMIS 1.1: the AtomPub and the JSON-based browser binding.

This means that you can connect apps with both bindings. It also means that you can connect repositories to the server that offer one of the two binding types. If you are developing a new app or an extension, opt for the new browser binding if it is technically feasible, since it has better performance.

For more information about the bindings, see the CMIS 1.1 specifications for AtomPub Binding and Browser Binding.

The following service URLs are available for these bindings:

● <protocol>://<server>:<port>/mcm/json● <protocol>://<server>:<port>/mcm/atom

The "/b" after the context root "/mcm" means that the server requests BASIC authentication.

Related Information

AtomPubBinding on OASIS Web pageBrowser Binding on OASIS Web page

1.1.2.3 Repository Information

apps can use the repository information to connect to a repository.

For each repository, the server provides repository information (RepositoryInfo) that describes a repository's general information and its capabilities. When a app calls a binding service URL without parameters, it gets a list of RepositoryInfo objects, one for every repository that is connected to . Apps can then use the repository ID and the provided navigation information to connect to one of the repositories.

For more information, see the OASIS Web page for getRepositoryInfo.

If you send a GET request to the service URL for AtomPub (/mcm/atom), you get the service document XML, which contains service definitions and a list of repositories. If you send a GET request to the service URL of the browser binding (/mcm/json), the server responds with a JSON representation of a list of RepositoryInfo objects.

ExampleGetting the list of RepositoryInfo objects with OpenCMIS

SessionFactory sessionFactory = SessionFactoryImpl.newInstance();Map parameter = new HashMap();parameter.put(SessionParameter.USER, "admin");parameter.put(SessionParameter.PASSWORD, "admin");parameter.put(SessionParameter.BROWSER_URL, server+"/mcm/json/");parameter.put(SessionParameter.BINDING_TYPE, BindingType.BROWSER.value());List<Repository> repositories = sessionFactory.getRepositories(parameters);


Developer's Guides

http://help.sap.com/disclaimer?site=http://docs.oasis-open.org/cmis/CMIS/v1.1/os/CMIS-v1.1-os.html#x1-3750003


For examples of basic operations such as reading, creating, updating, and deleting objects and folder navigation with OpenCMIS, see the OpenCMIS Client API Developer's Guide.

Related Information

getRepositoryInfo on OASIS Web pageOpenCMIS Client API Developer's Guide

1.1.3 CMIS Enhancements for

comes with CMIS enhancements to enable secure and smooth document management.

The following enhancements are available and are described in the following topics:

● Token-based protection mechanism against cross-site request forgery attacks● My Documents repository● Public Documents repository● Exceptions

1.1.3.1 Opening a Session

The following CMIS enhancement is used to connect to the server.

To open a session with exactly one repository in an OpenCMIS client, specify a set of session parameters. Then, connect to the server.

Example SessionFactory sessionFactory = SessionFactoryImpl.newInstance();Map parameter = new HashMap();parameter.put(SessionParameter.USER, "admin");parameter.put(SessionParameter.PASSWORD, "admin");parameter.put(SessionParameter.BROWSER_URL, server+ "/mcm/b/json/");parameter.put(SessionParameter.BINDING_TYPE, BindingType.BROWSER.value());parameter.put(SessionParameter.REPOSITORY_ID, mydocumentsId);parameters.put(SessionParameter.COOKIES, "true");Session session = sessionFactory.createSession(parameter);

For examples of basic operations such as reading, creating, updating, and deleting objects, and folder navigation with OpenCMIS, see the OpenCMIS Client API Developer's Guide.




Custom Authentication Provider

Let's take a closer look at the AUTHENTICATION_PROVIDER_CLASS session parameter as specified in the example above. This parameter tells the session to use your custom authentication provider instead of the default one. In , using a custom authentication provider is mandatory for the following reasons:

● To use , the app must set cookies in the HTTP header. As the OpenCMIS Java client hides specifics to bindings and HTTP calls, you cannot set an HTTP request header directly, but you can use additional headers, which the OpenCMIS Java client provides for the HTTP calls it executes.

● Specify a Java class (in the example below it is called CustomAuthenticationProvider) that implements the org.apache.chemistry.opencmis.commons.spi.AuthenticationProvider interface and overrides the getHTTPHeaders(String url) method. During an HTTP call to the server, getHTTPHeaders() is invoked and arbitrary headers can be added to the HTTP request.

public class CustomAuthenticationProvider extends StandardAuthenticationProvider { @Override public Map<String, List<String>> getHTTPHeaders(String url) { .... .... }}

Related Information

OpenCMIS Client API Developer's Guide

1.1.3.2 Using the CSRF Token

The server offers a token-based mechanism to protect against cross-site request forgery attacks.

NoteThe CSRF protection was simplified with SP02. The differences are as follows:

● The token is no longer repository-specific. It is valid for a session and for any repository that is connected within that session.

● The token can be fetched with HTTP headers. It is no longer necessary to parse RepositoryInfo.● The HTTP header name was changed to harmonize it with other SAP product names.

With the exception of the call to the service URLs, all calls to the server require a valid CSRF token. For the call to the service URLs, the token is provided as an HTTP header (as of version 1.0 SP02). All other requests require the apps to send the token value via the CSRF-token HTTP header. If the app does not supply a token or if the token has expired, the server sends the HTTP response 403: INVALID_TOKEN_PROVIDED.


Developer's Guides


Process Flow

1. When the app creates a session and connects to the server, it first calls getRepositoryInfos. To fetch a CRSF token, the app must send a request header called X-CSRF-Token with the value fetch in this call.

2. The server generates a token, stores it in the user's session table, and sends the value in the X-CSRF-Token HTTP response header.

3. The app reads the value of the X-CSRF-Token HTTP response header and stores it for later use.4. For each call in this CMIS session, the app sends the token value it obtained from the X-CSRF-Token HTTP

header.

ExampleExtracting the token with HTTP and browser binding

1) Get Repository Info and request a tokenRequest: GET /mcm/jsonRequest Header: X-CSRF-Token=fetchResponse: 200 OKResponse Header: X-CSRF-Token=79E85CA37351BBADF02661F64FC21D3C2) Get the home folderRequest: GET /mcm/json/4caf284f-81f4-4b2a-a77a-3fe7112339c2/root?cmisSelector=object&objectId=qn913L3f5e7BReuvIPj3UB3KkX2YYePxvIvcQtICiCoRequest Header: X-CSRF-Token=79E85CA37351BBADF02661F64FC21D3CResponse: 200 OK

ExampleToken handling in Authentication Provider

public class CustomAuthenticationProvider extends StandardAuthenticationProvider { private String token = "fetch"; @Override public Map<String, List<String>> getHTTPHeaders(String url) { Map<String, List<String>> httpHeaders = super.getHTTPHeaders(url); if(httpHeaders==null) { httpHeaders = new HashMap<String, List<String>>(); } httpHeaders.put("X-CSRF-Token", Collections.singletonList(token)); return httpHeaders; } @Override public void putResponseHeaders(String url, int statusCode, Map<String, List<String>> headers) { super.putResponseHeaders(url, statusCode, headers); if(headers!=null) { for(String headerName:headers.keySet()) { // loop for a ignore case check -> header names are case-insensitive (RFC 2616) if(headerName!=null && headerName.equalsIgnoreCase("X-CSRF-Token") && !headers.get(headerName).isEmpty()) { this.token = headers.get(headerName).get(0); } } } }}

Because OpenCMIS executes a call to get the RepositoryInfos when a session is created, this AuthenticationProvider adds the X-CSRF-Token=fetch HTTP request header. Then the server sends the


response to the AuthenticationProvider. The AuthenticationProvider stores the value returned by the server for further requests.

Browser Binding Example

In JavaScript-based applications, you first read the repository info by sending a GET request to /mcm/json. Every other repository contains a token for the communication with this /mcm/json repository. In the following example, jQuery is used to read the token and set it for all subsequent AJAX requests.

// read repositoryInfos extract token and set it to following requestsjQuery.ajax("/mcm/json",{ type: "GET", contentType: 'application/json', dataType: 'json', beforeSend: function(xhr){ xhr.setRequestHeader('X-CSRF-Token', 'fetch'); }, complete : function(response) { jQuery.ajaxSetup({ beforeSend: function(xhr) { xhr.setRequestHeader("X-CSRF-Token",response.getResponseHeader('X-CSRF-Token')); } }); }});

Static Cookie Manager

Because the repository ID is a parameter when creating a session with an OpenCMIS client, a app would open a session on the server for each repository. To avoid multiple server sessions for the same app, we highly recommend using the same server session for multiple CMIS sessions by re-using the cookies that are used for the state management between the apps and the server.

To do this, use a static CookieManager instead of one cookie per instance. If a app application opens several sessions for the same user, it must use the same authentication provider with the static CookieManager. Additionally, it has to override the putResponseHeaders() and getHandleCookies() methods as described in the following example.

Overriding the getHandleCookies() method has the effect that the COOKIES session parameter is ignored.

Example public class CustomAuthenticationProvider extends StandardAuthenticationProvider {// The use of a singleton cookie manager ensures that all created cmis sessions// use the same session cookies and therefore avoids multiple server session for each app private static final CmisCookieManager cookieManager = new CmisCookieManager(); @Override public Map<String, List<String>> getHTTPHeaders(String url) { Map<String, List<String>> httpHeaders = super.getHTTPHeaders(url); if (httpHeaders == null) {


Developer's Guides

httpHeaders = new HashMap<String, List<String>>(); } Map<String, List<String>> cookies = cookieManager.get(url, httpHeaders); if (!cookies.isEmpty()) { httpHeaders.putAll(cookies); } return httpHeaders; } @Override public void putResponseHeaders(String url, int statusCode, Map<String, List<String>> headers) { super.putResponseHeaders(url, statusCode, headers); cookieManager.put(url, headers); } @Override protected boolean getHandleCookies() { // deactivate standard opencmis session handling // cmis session parameter "COOKIES" will be ignored return false; }}

1.1.3.3 My Documents

Every user has their own home folder in the My Documents repository.

To enable clients to easily get the home folder, the repository used to store the My Documents repository contains a CMIS extension called myDocuments (namespace: http://www.sap.com/mcm; name: myDocuments). The value of this extension contains the ID of the home folder of the currently logged-on user. A repository with this extension is easily identifiable as the My Documents repository.

ExampleGetting the My Documents repository

Repository myDocumentsRepository = getRepository(repositories, "myDocuments"); // use the repositories list of chapter Repository Informationpublic static Repository getRepository(List<Repository> repositories, String extension) { for (Repository rep : repositories) { if(getExtensionValue(rep.getExtensions(), extension)!=null) { return rep; } } return null;}

ExampleGetting the user's home folder

String homeFolderId = null;List<CmisExtensionElement> extensions = myDocumentsRepositoryInfo.getExtensions();if (extensions != null) { for (CmisExtensionElement extension : extensions) { if ("myDocuments".equals(extension.getName())) {


homeFolderId = extension.getValue(); } }} if (homeFolderId != null) { // Obtain a session see chapter Working with the CSRF token Session session = sessionFactory.createSession(parameter); Folder userHomeFolder = (Folder) session.getObject(homeFolderId);}

ExampleGetting the user's home folder with browser binding and jQuery

// read repositoryInfosjQuery.getJSON("/mcm/json").done(function(data){ for(id in data) { // loop repositories and find myDocuments if(data[id].myDocuments) { $.ajaxSetup({ // set token for following calls beforeSend: function(xhr) { xhr.setRequestHeader("x-token",data["4caf284f-81f4-4b2a-a77a-3fe7112339c2"].token); } }); // read the home folder and alert its displayname var homeFolderId = data[id].myDocuments; jQuery.getJSON("/mcm/json/4caf284f-81f4-4b2a-a77a-3fe7112339c2/root?cmisSelector=object&objectId="+homeFolderId).done(function(data){ alert(data.properties["cmis:name"].value); }); } }});

1.1.3.3.1 Creating and Integrating a Custom View with an Existing Plug-In

SAP Mobile Documents allows you to create a custom view and integrate it with an existing plug-in, and also allows you to return back to the plug-in after having displayed the custom view.

To implement a custom view, for example, in My Document plug-ins, follow the procedures below:

Adding a Custom View

1. Under resources\com\sap\mcm\browser\views, create a new folder with the name of the custom view. For example, search.

2. The newly created location (resources\com\sap\mcm\browser\views\search) is the location for creating your custom view and controller. For example, search.controller.js and search.view.js.


Developer's Guides

Integrating a Custom View into a Plug-In

Once you have created your custom view, you can integrate it into any of the provided plug-ins (My Documents, Corporate, Shared) based on the triggering of an event. Here is an example of how the search results view is integrated into the My Documents plug-in.

1. In order to be able to display the custom view from the plug-in, based on the triggering of some event, there should be a mapping of the type {pluginId, event ,view}. This mapping defines that for the plug-in with the ID pluginid, the view view will be displayed when the event event is triggered. As a result the search results view should be displayed when mcm.util.constants.EVENTS.searchTriggered.event is triggered.

2. To create this mapping, use the addPluginViewItem (pluginId, id, event, getViewToOpen, onViewOpen, viewContext) function defined in mcm.plugin.api, where:

Table 1: addPluginViewItem

pluginId The ID of the plug-in in which the custom view is integrated.

id Uniquely identifies the custom view.

event The event that will trigger the display of the custom view.

getViewToOpen The function that returns the custom view.

onViewOpen The optional function executed as soon as the initial view provided with function getViewToOpen() is to be displayed.

viewContext The optional parameter storing additional information that should be passed to the custom view from the plug-in, for example, callback functions, etc.

NoteThe mapping {pluginId, event ,view} is unique, which means that for each plug-in, there cannot be two different views that are mapped to the same event.

Example1. In myDocumentsPlugin.js, define the mapping between plug-in, event, and view that is done in

onFrameworkLoaded:

pluginInterface.addPluginViewItem(constants.PLUGIN_ID, constants.SEARCH_ID, mcm.util.constants.EVENTS.searchTriggered.event,getSearchView, jQuery.noop, { /* * Reference to allownotification of plugin inherited custom actions when table selection is changedin the plugin view */ notifyCustomActionsCallback: myDocuments.services.myDocumentsService.notifyCallbacks }); functiongetSearchView() { if(!searchView) { searchView = newsap.ui.core.mvc.JSView({viewName: mcm.util.appUtil.createMcmNamespace('searchView')}); } returnsearchView;}

In the My Documents plug-in, the viewContext optional parameter holds the reference to the myDocuments.services.myDocumentsService.notifyCallbacks function. This way, when a selection in the search view is changed, the search view will be aware which function it should call in order to check whether the SHARE action should be displayed or not.


2. In search.controller.js define the onViewOpened function as follows:

functiononViewOpened(oEventData) { …}

This function is the entry point to your custom view controller. In this function, you could place all the initializations needed in order to display your custom view.

Returning to the Initial Plug-in from the Custom View

To return from your custom view back to the initial plug-in, trigger the navigationFromView event from your custom view controller:

events = mcm.util.constants.EVENTS;sap.ui.getCore().getEventBus().publish(events.navigationFromView.publisher, events.navigationFromView.event, callbackData);

In the callbackData parameter you can store all the information that the plug-in needs in order to initialize its content.

ExampleTo return from the search results view to the My Documents plug-in:

1. In myDocumentsPlugin.js, register the function that will be called once you return from the custom view:

pluginInterface.addPluginViewCallback(constants.PLUGIN_ID, pluginViewCallback);functionpluginViewCallback(pluginViewData) { if(pluginViewData.params.obj) { pluginStartedWithHistory = true; getMyDocumentsView(); myDocumentsView.getController().initTableFromHistory(pluginViewData); }}

The call to addPluginViewCallback is made in onFrameworkLoaded.2. In your custom view, trigger the navigationFromView event defined in mcm.util.constants.EVENTS:

events = mcm.util.constants.EVENTS;sap.ui.getCore().getEventBus().publish(events.navigationFromView.publisher, events.navigationFromView.event, callbackData);

callbackData will be passed on as a parameter to pluginViewCallback, previously defined in myDocumentsPlugin.js.

1.1.3.4 Shared Documents

provides a repository called Shared Documents for collaborating on documents with other users.

The following table clarifies the terms used to implement Shared Documents.


Developer's Guides

Table 2: Terms Relevant for Shared Documents

Term Definition

share The root folder that is used for collaboration with other users. It can contain folders and files. Users can create any number of shares (until their quota is used up).

owner The user who creates the share automatically becomes its owner. The share's size is billed to the owner's quota.

public link A link that can be applied to a share, to folders, or to files residing in the share. The link makes the share, the folder, or the file available to anonymous users.

member Any user that has one of the defined roles for the share and can access it.

For each share, the following roles are available. The table below maps these roles to the respective CMIS permissions.

Table 3: Share Roles

Role Description CMIS Permission

owner Permission to create a share. cmis:all

administrator Permission to delete a share, to manage user rights, and to allow public links.

cmis:all

contributor Permission to create, to update, and to delete files and folders. This permission also enables the user to create and to delete public links.

sap:delete

reader Permission to read documents. cmis:read

Similar to the My Documents repository, every user has their own personal sharing home folder. Beneath this home folder are the shares of the user. The ID of the sharing home folder is specified in the RepositoryInfo with the sharing extension.

If public links are enabled, there are some general settings with which every public link must comply. These general settings are transported as CMIS extensions in the RepositoryInfo of the sharing repository. In addition to the general settings, every public link has its own set of properties, where a user can define validity and security for this public link. In any case, a user is only allowed to define values that are stricter than the general ones defined by an administrator. If, for example, an administrator defines a minimum password length of four characters, the user can only choose to use a password with more characters. The user cannot choose to use less than four characters or even no password at all.

Table 4: CMIS Extensions (on RepositoryInfo Level, Valid for All Public Links)

Name Description Type

sharing Similar to the mydocuments extension, this extension contains the ID of the user's Shared Documents home folder.

String

sharing.uploadAllowed

Indicates whether the administrator allows uploads by anonymous users or not.

Boolean

sharing.baseURL Contains the base URL of the public sharing Web link. The app can use this information to create a public link by appending the object ID of the public link to this base URL.

String



sharing.maxEpirationDays

The administrator can define the maximum period in days for which anonymous users can access a shared folder. This extension contains the number of days.

When a public link is created, the expiration date must not be later than the current date plus the number of days specified. If the value is 0, no expiration date is predefined.

int

sharing.minPasswordLength

For values greater than 0, the user must set a password for the public links of this share. This password must be longer than or of the same length as the value of this extension.

int

Table 5: CMIS Extensions (on Folder Level, Valid for All Shares)


owner.isOutOfSpace Indicates whether the share owner has enough quota left to upload files to the share.

● True: No content upload allowed.● False: Content upload allowed, as far as the quota is concerned.

Boolean

1.1.3.4.1 App Operations for Sharing

You can use app operations for shared files in .

Getting All Shares of a User

To list all shares that a user can access (with any of the roles specified for share access), the app sends a query to the server. Since shares have the specific mcm:share CMIS type the query is simply: select * from mcm:share. The result is a list of all shares where the calling user has an entry in the share's access control list (ACL).

Creating a Share

Shares must be created under a user's sharing home folder. They have the specific mcm:share type with the cmis:folder base type.


Developer's Guides

Managing Share Members

Members are entries in a share's access control list (ACL). An ACL is a list of ACEs (access control entries) that consist of a principal ID and a list of permissions. The permissions are listed in the roles table in Shared Documents.

For on-premise installations, the principal ID is a user's unique ID, for SAP Cloud Platform it is the user's logon ID. You can pass the ACL as an input parameter while creating a share or modify the ACL by calling the applyAcl CMIS service on an existing share.

When adding a new member to a share, the share administrator wants to use known user attributes, for example, the name or the e-mail address, but not the user ID. To help apps to search for users and to assemble an ACL with the correct IDs, offers a REST API (see REST API).

In the members overview for a share, apps should display user names rather than IDs. To prevent extra server roundtrips or extra non-CMIS APIs, OpenCMIS offers the possibility to add generic extensions to various objects. When a app reads the members of a share, technically this is a getObject operation (with ACLs included) on the folder representing the share. The ACL is a list of ACEs and each ACE contains a principal object. OpenCMIS only defines an ID for a principal; additional attributes can be added as extensions. The server extends the principal object with an extension called principal that has the following children as extensions:

● _firstName● lastName● email● displayName● logonId● id

ExampleExample response of an ACL with a single contributor.

{ "acl": { "aces": [ { "principal": { "principalId": "USER.PRIVATE_DATASOURCE.un:testuser", "principal": { "firstName": "Manfred", "lastName": "Mustermann", "email": "[email protected]", "logonId": "testuser", "id": "USER.PRIVATE_DATASOURCE.un:testuser", "displayName": "Manfred Mustermann" } }, "permissions": [ "sap:delete" ], "isDirect": true } ] }, "exactACL": true}


Managing Public Links

To make a share accessible to external users using a public link, it must be given a CMIS secondary type called mcm:publicLink. CMIS defines the standard multi-value cmis:secondaryObjectTypeIds property that can contain 0..n secondary type IDs. To make a share public, the mcm:publicLink ID must be added to the cmis:secondaryObjectTypeIds.

Secondary types contain a set of properties that can be attached or detached from an object. Public links have properties, for example, a password or an expiration date.

These are the properties:

Table 6:

Name Description ID Secondary Typ Data Type

From to Date

Defines the date on which the shared files in this folder become accessible for anonymous users.

mcm:validFromDate mcm:publicLink DATETIME

Valid to Date

Defines the date after which the shared files in this folder are no longer accessible for anonymous users. The creator of the share can still access it.

mcm:validToDate mcm:publicLink DATETIME

Share Password

Can be used to protect the access to the shared file with a password. Administrators can enforce the setting of a password.

NoteThe server never exposes the hashed password to the apps. Therefore, the server returns "null" as a value if no password has been set for an existing folder. If a password has been set the value is an empty string.

mcm:sharePassword mcm:publicLink String

Public write access

Controls whether anonymous users have write access to shared files. If set to Yes, anonymous users are allowed to create, update, or delete files within the share.

mcm:enableUpload mcm:publicLink Boolean

Share Owner

Indicates the owner of the share. If quota is enabled, everything within this share is counted in the owner's quota.

mcm:shareOwner mcm:publicLink String

ExampleCode Samples: OpenCMIS

// Getting the sharing home folderString sharingHomeFolderId = null;for (CmisExtensionElement extension : sharingRepositoryInfo.getExtensions()) {if ("sharing".equals(extension.getName())){ sharingHomeFolderId = extension.getValue(); }}Folder sharingHomeFolder = session.getObject(sharingHomeFolderId);// Getting all shares for a user


Developer's Guides

ItemIterable<QueryResult> result = session.query("select * from mcm:share",true);for(QueryResult result:results) {String shareName = result.getPropertyValueById("cmis:name");}// Create share "Share 1" with administrator "User01"Map<String, Object> properties = new HashMap<String, Object>();properties.put("cmis:name", "Share 1");properties.put("cmis:description", "A description");properties.put("cmis:objectTypeId", "mcm:share");List<Ace> aces = new ArrayList<Ace>();aces.add(session.getObjectFactory().createAce("User01", Collections.singletonList("cmis:all")));ObjectId shareId = session.createFolder(properties, sharingHomeFolder, null, aces, null);// adding contributor "User02"List<Ace> addAces = new ArrayList<Ace>();addAces.add(session.getObjectFactory().createAce("User02", Collections.singletonList("sap:delete")));session.applyAcl(shareId, addAces, null, AclPropagation.PROPAGATE);// Creating a public linkFolder share = session.getObject(shareId);properties = new HashMap<String, Object>();properties.put("cmis:secondaryObjectTypeIds", Collections.singletonList("mcm:publicLink"));properties.put("mcm:sharePassword", "secret");properties.put("mcm:enableUpload",true);GregorianCalendar cal = new GregorianCalendar();cal.setTime(new Date());cal.add(Calendar.DAY_OF_MONTH, 7); // one weekproperties.put("mcm:validToDate", cal);share.updateProperties(properties);

ExampleCode Samples: JavaScript / jQuery

// Getting all shares for a user var repositoryId = sharingRepositoryInfo.id; var queryUrl = "/mcm/json/"+repositoryId+ "?cmisSelector=query&q=select+*+from+mcm%3Ashare&maxItems=1000&skipCount=0";jQuery.getJSON(queryUrl).done(function(data){ for( var i=0;i<data.results.length;i++) { // loop results var shareName = data.results[i].properties[ "cmis:name"].value; // do something }}); // Create share "Share 1" var sharingHomeFolderId = sharingRepositoryInfo.sharing;jQuery.ajax( "/mcm/json/"+repositoryId+ "/root", { type : 'POST', async : false, data : { objectId : sharingHomeFolderId, cmisaction : "createFolder", "propertyId[0]" : "cmis:name", "propertyValue[0]" : "Share 1", "propertyId[1]" : "cmis:objectTypeId", "propertyValue[1]" : "mcm:share", "propertyId[2]" : "cmis:description", "propertyValue[2]" : "A description" }}).done(function(data){ shareId = data.properties[ "cmis:objectId"].value;}); //


adding contributor "User02"jQuery.ajax( "/mcm/json/"+repositoryId+ "/root", { type : 'POST', async : false, data : { objectId : shareId, cmisaction : "applyACL", ACLPropagation : "propagate", "addACEPrincipal[0]" : "User02", "addACEPermission[0][0]" : "sap:delete" }}); // Creating a public link var currentTime = new Date(); var expirationDate = currentTime.setDate(currentTime.getDate()+7);jQuery.ajax( "/mcm/json/"+repositoryId+ "/root", { type : 'POST', async : false, data : { objectId : shareId, cmisaction : "update", "propertyId[0]" : "cmis:secondaryObjectTypeIds", "propertyValue[0]" : "mcm:publicLink", "propertyId[1]" : "mcm:sharePassword", "propertyValue[1]" : "secret", "propertyId[2]" : "mcm:enableUpload", "propertyValue[2]" : "true ", "propertyId[3]" : "mcm:validToDate", "propertyValue[3]" : expirationDate }});

Determine Whether Upload to a Share Possible (Quota Handling)

Apps can only determine the quota and the used disc space of their own logged-on user. However, in the context of sharing, apps typically also upload files to shares of other users. In this situation, the user who wants to upload files is not the share owner. It is not possible to get the quota information of another user. But it is possible to determine if the share owner has enough quota left to upload more files. Apps can and should use this information to inform the user that no more uploads are allowed and to avoid triggering uploads to this share. For all shares that are folders of type mcm:share the server provides a CMIS extension named owner.isOutOfSpace.

1.1.3.5 Corporate Repositories

Corporate repositories can have a configured root URI that clients use as a start folder in a repository.

For more information on the root URI, see Configuring Corporate Documents Repositories.

To set the root URI, you configure a path, for example, /folder1/folder2; clients should initially display the folder structure beneath this path instead of displaying the contents of the root folder. If you configure a root URI, it is transported to the clients similarly to the user's home folder of My Documents as an extension containing the ID of the configured path. The extension's name is corporate, so you can apply the same example code as in the My Documents example. You only need to replace the extension name myDocuments with the extension name corporate.


Developer's Guides

1.1.3.6 Exceptions

To notify users that they have made incorrect user entries, uses specific messages in exception texts.

In general, adheres to the exception behavior described in the CMIS specification. If the exception is used to express incorrect user entries, uses specific messages in the exception text.

Table 7: Specific Messages in Exception Text

Exception Name Message Description

CmisPermissionDeniedException

INVALID_TOKEN_PROVIDED

The app must provide a token in every operation except getRepositoryInfos. If no token or the wrong token is provided, this exception is thrown.

CmisInvalidArgumentException

PASSWORD_NOT_SET Thrown when creating a public link without a password if the administrative settings require a password.


PASSWORD_TOO_SHORT

Thrown when creating a public link if the provided password does not meet the requirements specified in the administrative settings.


PASSWORD_INVALID Thrown when a password-protected public link is anonymously accessed with a wrong password.


PASSWORD_REQUIRED

Thrown when a password-protected public link is anonymously accessed without a password.


SHARE_LOCKED<unlock_date_in_ms>

Thrown when a password-protected public link is currently locked because it was accessed with a wrong password. The exception key is followed by the date when the public link is accessible again (in milliseconds from 1970/1/1).


EXPIRATION_DATE_IN_PAST

Thrown when creating a share. The expiration date for the share is a link with a validToDate in the past.

CmisConstraintException

QUOTA_EXCEEDED The quota for the currently logged-on user is used up. No write operations are allowed until the user frees up some space.

CmisConstraintException

● Virus● VIRUS● virus

When uploading a document, the repository can reject the document if a virus is detected. If the app tries again to upload this document to the server, the same exception is thrown. Therefore, the app should not retry uploading the document.

1.1.4 REST API

In some cases the apps need server calls that cannot be mapped to CMIS services. For these calls, the server offers a proprietary REST API that apps can use.

User Validation

With this API, apps can validate the existence of principals using attributes. A principal is a user management object, for example, a user, a group, or a role. The response contains JSON representations of the found principal objects as well as a list of terms for which no principals can be found. In , this API is used in the context of the


Shared Documents repository when adding members to a share. Wildcards are not supported, because this API is meant for validating, not for searching.

Note

Table 8:

Title Validate Users

URL /mcm/rest/v1/users/validate

Method GET

URL Params term=[URL Encoded]

1...n term parameters are possible. Note that a URL including parameters must not exceed 2000 characters.

Example to validate 3 users at a time: .../mcm/rest/v1/users/validate?term=d123456&term=c654321&term=i123456


Developer's Guides


Success Response Code: 200

Content sample for single entry response:

{ "foundPrincipals": { "displayName": "Horst Sapbox", "email": "[email protected]", "firstName": "Horst", "id": "admin", "lastName": "Sapbox", "type": "USER" }, "nothingFoundFor": "d736367"}

Content sample for multiple entry response:

{ "foundPrincipals": [ { "displayName": "Horst Sapbox", "email": "[email protected]", "firstName": "Horst", "id": "admin", "lastName": "Sapbox", "type": "USER" }, { "displayName": "Heinz Ketchup", "email": "[email protected]", "firstName": "Heinz", "id": "user1", "lastName": "Ketchup", "type": "USER" } ], "nothingFoundFor": [ "d736367", "admin1" ]}

Error Response ● Code 400 for bad requests, for example, parameters contain invalid characters.● Code 403 for unauthorized requests, for example, user has no permission to call this

URL.



Sample Call Validate users within a JavaScript-based app using jQuery

var restURLStart = "/mcm/rest/v1/users/validate?";var restURL = restURLStart + 'term=d012345&term=i012345';$.ajax(encodeURI(url), { type: 'GET', async: false }). done(function (data) { // Handle successful call // data = JSON response from server as described above }). fail(function (cause) { // Handle Server Exception });

1.1.5 URLs for App-to-App Integration of SAP Mobile Documents

You can build URLs that perform actions in the SAP Mobile Documents app and that can be used for app-to-app integration or as links in e-mails.

These URLs are either custom URLs () or HTTP URLs. Not all apps support both types. In addition, there is a distinction between URLs for links for share members and URLs for public links, which can be accessed by anyone who receives the link (and the password, if any).

App Support

Table 9: URL Types

URL Type Web App iOS App Android App Windows Desktop App

Mac Desktop App

Windows Native App

Custom URL x x x

HTTP URL x x


Developer's Guides

Table 10: Available Actions

Action Comment Web App iOS App Android App Windows Desktop App

Mac Desktop App

Windows Native App

select The folder containing the object identified with the parameter obj is opened and the object itself is selected in the documents list.

://v1/select?rep=1234567890&obj=0987654321

https://myhost:8080/mcm/browser/v1/select?rep=1234567890&obj=0987654321

Supported as of Web app SP3 (1.3.x).

Supported as of iOS SP2 (1.2.x).

Supported as of Android SP3 (1.3.x).

Supported as of Windows desktop app SP4 (1.4.x).



Mac Desktop App

Windows Native App

open ● If the parameter obj is the ID of a folder, the folder is opened and its content is displayed.

● If the parameter obj is the ID of a file, the folder is opened and the file is downloaded.

://v1/open?rep=1234567890&obj=0987654321

https://myhost:8080/mcm/browser/v1/open?rep=1234567890&obj=0987654321



Supported as of Android SP3 (1.3.x).

Supported as of Windows desktop app SP4 (1.4.x).


Developer's Guides


Mac Desktop App

Windows Native App

present Only for PDF files. Opens a PDF file in presentation mode.

://v1/present?rep=1234567890&obj=0987654321


configure Server configuration URL, together with the server.url=http(s)://<host>(:<port>) parameter

://v1/configure?server.url=https://myhost:8080


create Link to create share page: Only in combination with rep=share

https://myhost:8080/mcm/browser/v1/create?rep=share



Available URL Parameters

● rep [page 28] has the following values:○ <repository ID>○ mydocuments○ share○ corporate

● obj [page 29] has the following values:○ <object ID>

● path [page 29] has the following case-sensitive values:○ </folder1/folder2>

● <server.url> has the following values:○ http(s)://<host>(:<port>)

● page [page 29], iOS-only● chapter [page 29], iOS-only

NoteYou cannot use the obj and the path parameters in the same URL.

Custom URL Syntax

The custom URL syntax is:

://<version>/<action>?parameters

Example://v1/open?obj=1234&rep=abcdef

This URL opens the document with the CMIS object ID 1234 from the repository with ID abcdef, using version v1 of the URL scheme and the open action.

The syntax contains the following elements:

● version string, requiredDenotes the scheme version of ; the current version is v1.

● action string, required: Is an action that the app performs on the provided parameters. Available actions are listed in the table above.

The syntax contains the following URL parameters:

● rep string (URL-encoded), requiredrepository ID. mydocuments, share, and corporate are reserved keywords. mydocuments and share can be used instead of the corresponding repository ID. If no path or object ID is provided or found, the repository root is selected. rep=corporate can be used to address the list of all corporate repositories. For rep=corporate, the parameters obj and path are ignored.


Developer's Guides

● obj string (URL-encoded), optionalCMIS object ID of a file or folder. If provided, the path is ignored.

● path string (URL-encoded), optionalThe absolute path inside the specified repository. The start URI is not considered here. The path is URL encoded before it is passed to . If the repository is share, the path parameter is not considered, as a link to a document or folder within a share would have the logon ID as part of the URL. Supported as of iOS SP3 (1.3.x), Android SP3 (1.3.x), Web app SP3 (1.3.x), and Windows desktop app SP4 (1.4.x).

● page string, optionalIf the object is a PDF document, this parameter can display a given page on opening the document. If the object is not a PDF document or the given page is outside the range of the document, this parameter is ignored.Example: ://v1/open?rep=abcdef&obj=1234&page=27

● chapter string, optionalIf the object is a PDF document that has a table of contents (ToC), this parameter can display the given chapter on opening the document. The chapter must be specified using the URL-encoding (percent representation) of the exact chapter name in the table of contents of the PDF document. If the object is not a PDF document or the given chapter is not part of its table of contents in that sense, this parameter is ignored.Examples:○ ://v1/open?rep=abcdef&obj=1234&chapter=ExampleChapterName (for ToC entry

"ExampleChapterName")○ ://v1/open?rep=abcdef&obj=1234&chapter=Example%20Chapter%20Name (for ToC entry

"Example Chapter Name")

HTTP URL Syntax for All Non-Public Links

The HTTP URL syntax is:

http(s)://<server>:<port>/mcm/browser/<version>/<action>?parameters

Examplehttps://myhost:8080/mcm/browser/v1/select?rep=1234567890&obj=0987654321

This URL starts the Web app and triggers navigation to the repository 1234567890. The URL then opens all possible subfolders until object 0987654321 is found. The URL selects this object. The select action does not differentiate between folders or documents. The respective object is selected in the documents list of .





● rep string (URL-encoded), requiredrepository ID. mydocuments, share, and corporate are reserved keywords. mydocuments and share can be used instead of the corresponding repository ID. If no path or object ID is provided or found, the repository


root is selected. rep=corporate can be used to address the list of all corporate repositories. For rep=corporate, the parameters obj and path are ignored.

● obj string (URL-encoded), optionalCMIS object ID of a file or folder. If provided, the path is ignored.

● path string (URL-encoded), optionalThe absolute path inside the specified repository. The start URI is not considered here. The path is URL encoded before it is passed to . If the repository is share, the path parameter is not considered, as a link to a document or folder within a share would have the logon ID as part of the URL. Supported as of iOS SP3 (1.3.x), Android SP3 (1.3.x), Web app SP3 (1.3.x), and Windows desktop app SP4 (1.4.x).

HTTP URL Syntax for Public Links

The public HTTP URL syntax is:

http(s)://<server>:<port>/mcm/public/<version>/<action>?parameters

Examplehttps://myhost:8080/mcm/browser/v1/select?rep=1234567890&obj=0987654321




● shr string (URL-encoded), requiredProvides the ID of the share to display.

● obj string (URL-encoded), optionalSpecifies the object on which the provided action should be executed. If the obj parameter is not present, the share is opened in the sharing UI and the action is ignored.

For shares with a public link, the share properties only show the URL for share members because the public link is already available using the link icon ( ).

For an object (folder or file) in a share with a public link, the object properties show the Public URL of the Folder or Public URL of the Document, as this link is currently not available elsewhere.

Path Handling for HTTP URLs

Path handling for shares is explicitly switched off, as the user ID would have to be a visible part of the URL, which is not wanted. In addition, the caller (who is creating the URL and calling it) cannot determine the ID of the user who owns the share that is addressed.

For objects under My Documents, the user ID must also be part of the URL as stated in the CMIS specification. However, apps parsing the URL know which ID must be used in the path: the ID of the logged-on user. Therefore,


Developer's Guides

the path does not need to contain the user ID. When the apps parse the URL, they add the user ID to the beginning of the path. With this adjusted path, getObjectByPath() works.

ExampleThe apps receive the following URL:

http://myhost:8080/mcm/browser/v1/select?rep=mydocuments&path=/folder1/folder2

The apps use the following URL to send the getObjectByPath() request:

http://myhost:8080/mcm/browser/v1/select?rep=mydocuments&path=/UserID/folder1/folder2

Related Information

Configuring the Server URL with a URL Scheme [page 31]

1.1.5.1 Configuring the Server URL with a URL Scheme

If your company does not use the automatic server URL configuration available with a Mobile Device Management (MDM) solution, you can supply the server URL for the app using a URL scheme and provide this URL scheme to your users.

The URL scheme syntax for configuring the server URL is:

ExampleThis URL configures the server URL of the app.



● configure action that the app performs. Supported as of iOS SP4 (1.4.x) and Android SP4 (1.4.x).● server.url string, required. Server URL parameter to connect to the server. Supported as of iOS SP4 (1.4.x)

and Android SP4 (1.4.x).


1.2 Connecting Your ABAP Back End as a Content Source

You can use your ABAP system as a content source for SAP Mobile Documents.

With an ABAP system as a content source, you can easily access documents stored, for example, in SAP ERP system repositories. These documents are then available like any other repository file and can be downloaded to a mobile device for offline access.

Related Information

ABAP Connector [page 32]Implementing the ABAP Connector [page 33]

1.2.1 ABAP Connector

The ABAP connector enables ABAP applications to expose a CMIS interface to .

Content stored and/or managed in an ABAP system can be retrieved using the runtime by any CMIS client. The ABAP CMIS server can provide any kind of folder hierarchy and any kind of metadata. Both can be mapped to an existing back end or can be virtual and assembled at runtime. The current connector version only allows reading of data.

The ABAP connector consists of two parts. The connector provides an ABAP interface and helper classes to build a CMIS 1.1-compliant server. The data is provided by RFC to the server. The other part resides in the server. It accepts calls from a CMIS client, converts the data, calls the appropriate RFC, converts the response, and sends it back to the client.


Developer's Guides

The ABAP connector connects the runtime to the SAP ERP system.

Whenever possible, document content is not routed through SAP NetWeaver AS for ABAP. If content is stored in an external document store and if that store provides an HTTP interface, the content can be directly pulled from that store. In this case, the ABAP connector implementation must provide a URL to the document instead of sending the content. This allows content streaming and handling of large documents.

This document explains how to implement the ABAP connector and how to attach it to .

1.2.2 Implementing the ABAP Connector

To provide documents, content, folder hierarchies, and metadata to , you must implement the ABAP connector.

This interface adheres closely to the CMIS 1.1 specification, that is, there is a method for each CMIS operation. Each method takes the same parameters and returns data structures similar to those described in the CMIS specification. There are only a few instances where the input and output deviate from the specification, either to avoid technical restrictions or to enable optimizations.

The connector allows you to use the full fidelity of the CMIS standard. This freedom increases complexity in some areas, specifically to the data structures. To mitigate the complexity, the ABAP connector also provides an abstract class that implements the interface. It provides convenience code for several methods. That is, for most


scenarios you only have to implement a small set of methods; the abstract class covers everything else, but can be overridden where necessary.

TipWe strongly recommend that you extend this abstract class instead of implementing the interface directly.

Additionally, helper and factory classes are provided. These help fill the data structures. Among other things, the factory provides CMIS-compliant type definitions for documents and folders and provides repository info data structures for the most common use cases. There is also a simple query parser for the CMIS query language.

Related Information

Enhancements to the CMIS Specification [page 34]Constants and Enum Values [page 38]Exceptions [page 38]Content Handling [page 39]Query [page 40]Building a CMIS Server for [page 41]Building a CMIS Repository in an ABAP System [page 44]

1.2.2.1 Enhancements to the CMIS Specification

To provide a full-featured CMIS interface, some enhancements to the CMIS specification were necessary.

Related Information

Tree Handling [page 34]Properties [page 35]Repository Info [page 37]

1.2.2.1.1 Tree Handling

CMIS specifies some recursive structures that cannot be directly mapped to ABAP.

If you are dealing with treelike structures, for example, the extensions, then the corresponding structure contains two additional fields named TRANSPORT_ID and TRANSPORT_PARENT_ID. With these two fields, you can create the tree as a flat structure. The transport ID can be any string-like value. You must not set a transport parent ID for the root element. If you set a transport parent ID it must exist, otherwise the element is discarded as it cannot be mapped to a parent.


Developer's Guides

1.2.2.1.2 Properties

The property structure in CMIS defines only a table of value objects, which can be of any type.

The property structure in CMIS defines only a table of value objects, which can be of any type. The ABAP implementation of the property structure is different; there is a table containing not single values but value structures.

Each value structure contains fields for the following data types:

● string value● boolean value● int value● decimal value● date time value

Depending on the property type, the corresponding value must be supplied:

Table 11:

Property Type Value Field

boolean BOOLEAN_VALUE

string STRING_VALUE

id STRING_VALUE

integer INT_VALUE

datetime DATE_TIME_VALUE

decimal DECIMAL_VALUE

html STRING_VALUE

uri STRING_VALUE

Custom Groups

If your back-end repository provides custom properties, you can group them and define a display text for each group. In addition, you can configure whether a property group is initially displayed expanded or collapsed, or is completely hidden. The order of the groups and the order of the properties inside each group are also configurable.

To achieve these changes, you modify the typeDefinition of the respective repository using the following elements:

● propertyGroups○ displayname: This property defines the name of the group displayed on the user interface. If you do not

provide a display name, then the technical name (the prefix) of the group is displayed.


○ position: This property defines the position of this group in relation to other groups defined in this type definition. If you do not define it, the different properties of the group are rendered in alphabetical order.

○ expanded: This property defines whether the group is initially expanded or collapsed. Possible values are true and false, default value is false.

○ hidden: This property defines whether the group is displayed on the user interface at all or whether it is hidden. Possible values are true and false, default is false.

● propertyDefinitionsposition: This defines the order of the property in relation to the other properties of the group.

TypeDefinition Syntax

Code Syntax typedefinition : { "name": "...", "displayname": "...", "propertyGroups" : { "ppm" : { "displayname": "My nice Name for this Property Group", "position": "1", "expanded": "true", "hidden": "true" }, "ppm2": { "displayname": "My nice Name for this second Property Group", "position": "2", "expanded": "false", "hidden": "false" } }, "propertyDefinitions: [ { "id" : "ppm:CustomPropertyOne", "displayname" : "Nice Name for Property One", "position" : "1" }, { "id" : "ppm:CustomPropertyTwo", "displayname" : "Nice Name for Property Two", "position" : "2" } ] }

ExampleThe following example demonstrates how to configure the custom properties group in SAP NetWeaver Application Server for ABAP.

Sample Code "Extend the property definition by the position DATA: prop1 TYPE cmis_s_property_definition, prop_position type cmis_s_extension. "The Id will be used in the later example to map it to the group prop1-id = 'grp1:prop1'. prop1-display_name = 'Property 1'. "Add the position extension to the property definition prop_position-name = 'position'. prop_position-value = '1'.


Developer's Guides

APPEND prop_position to prop1-extensions. "Add the groupmapping to your type definition DATA: ls_type type cmis_s_type_definition,DATA: property_group TYPE cmis_s_extension, group TYPE cmis_s_extension, displayname TYPE cmis_s_extension, position TYPE cmis_s_extension, expanded TYPE cmis_s_extension, hidden TYPE cmis_s_extension. "Define the property group extension that contains all group extensions property_group-name = 'propertyGroups'. property_group-transport_id = 'propertyGroup'. "Define the group for properties starting with 'grp1' and create the mapping to the property group extension group-name = 'grp1'. group-transport_id = 'grp1'. group-transport_parent_id = property_group-transport_id. "Define the other extensions and add map them to the group extension displayname-name = 'displayname'. displayname-value = 'Property Group 1'. displayname-transport_id = 'disp_grp1'. displayname-transport_parent_id = group-transport_id. position-name = 'position'. position-value = '3'. position-transport_id = 'pos_grp1'. position-transport_parent_id = group-transport_id. expanded-name = 'expanded'. expanded-value = 'true'. expanded-transport_id = 'exp_grp1'. expanded-transport_parent_id = group-transport_id. hidden-name = 'hidden'. hidden-value = 'false'. hidden-transport_id = 'hidden_grp1'. hidden-transport_parent_id = group-transport_id. APPEND property_group TO es_type-extensions. APPEND group TO es_type-extensions. APPEND displayname TO es_type-extensions. APPEND position TO es_type-extensions. APPEND expanded TO es_type-extensions. APPEND hidden TO es_type-extensions.

1.2.2.1.3 Repository Info

The repository info has an additional field that contains information about the implementation capabilities.

Currently, the structure that is used in this field contains two values. These contain information about the content delivery abilities of the repository. The content delivery behavior is determined by what the repository returns for these values. See the table below for more information.


DEFAULT_CONTENT_DELIVERY

Table 12:

Value Comment

full Content is always delivered as a complete xstring.

chunked Content is delivered in chunks.

document_specific Content is delivered as stated in the export parameter of the create_document method. To deliver the content using a URL, use this option.

DEFAULT_CHUNK_SIZE

If the content is delivered in chunks, set the default chunk size for this parameter. The chuck size should not exceed 1 MB. Chuck sizes over 16 MB are not supported.

1.2.2.2 Constants and Enum Values

The CL_CMIS_PROPERTY_IDS class contains constants for all property IDs that are defined in the CMIS 1.1 specification.

All other constants and enum values used in the specification can be found in the CL_CMIS_CONSTANTS class.

ExampleUsing Constants

ls_property = cl_cmis_object_factory=>create_string_prop_single ( iv_property_id = cl_cmis_property_ids=>created_by iv_value = 'Joe' ).

1.2.2.3 Exceptions

The CMIS exceptions defined in the standard are assigned to specific ABAP exceptions. These exceptions are passed on to the respective app.

Table 13:

CMIS Exception ABAP Exception

invalidArgument CX_CMIS_INVALID_ARGUMENT

notSupported CX_CMIS_NOT_SUPPORTED


Developer's Guides

CMIS Exception ABAP Exception

objectNotFound CX_CMIS_OBJECT_NOT_FOUND

permissionDenied CX_CMIS_PERMISSION_DENIED

runtime CX_CMIS_RUNTIME

constraint CX_CMIS_CONSTRAINT

contentAlreadyExists CX_CMIS_CONTENT_ALREADY_EXISTS

filterNotValid CX_CMIS_FILTER_NOT_VALID

nameConstraintViolation CX_CMIS_NAME_CONSTRAINT_VIOLATION

storage CX_CMIS_STORAGE

streamNotSupported CX_CMIS_STREAM_NOT_SUPPORTED

updateConflict CX_CMIS_UPDATE_CONFLICT

versioning CX_CMIS_VERSIONING

To throw a CMIS exception, use the following code snippet:

RAISE EXCEPTION TYPE cx_cmis_invalid_argument EXPORTING message_text = 'Invalid object ID.'.

1.2.2.4 Content Handling

Read

The GET_CONTENT method can deliver document content in different ways. It can either provide an HTTP URL to the content or provide the content itself as one or more xstrings.

If a URL is provided, the SAP Mobile Documents server tries to retrieve the content directly from that URL. Keep in mind that the server must be able to reach the URL and must be authorized to retrieve the content.

If no URL is provided, the SAP Mobile Documents server forwards the content sent in the STREAM export parameter. If the parameter contains the full content, set the HAS_MORE export parameter false.

We recommend that you only transfer content of up to 1 MB in this way. The maximum size is 15 MB. Transfer larger content in chunks. In this way, the GET_CONTENT method only returns the first few bytes in the STREAM parameter and sets the HAS_MORE parameter to true. The SAP Mobile Documents server then calls the GET_CONTENT method again with an offset pointing to the next byte after this chunk. The server repeats the call until the entire content is transferred and HAS_MORE is set to false. To the clients, this looks like one continuous stream.

NoteThe size of a chunk should not exceed 1 MB and must not exceed 15 MB.


The GET_CONTENT method must supply a MIME type for the content. If no MIME type is provided and the content is pulled from an external store using HTTP, the MIME type provided by the external store is used (HTTP header Content-Type). If the content source does not provide a MIME type, application/octet-stream is used.

Write

Similarly to the GET_CONTENT method, there are also different ways to create content. The content can be delivered as one xstring, it can be directly pushed to an HTTP URL, or it can be delivered in chunks. The method that the repository supports can be expressed with the repository info (see Repository Info [page 37]). The flow differs depending on the chosen method:

● fullIn this case, CREATE_CONTENT receives the full content as an xstring within the IS_CONTENT structure and the HAS_MORE parameter is set to false. The implementation only needs to return the new object ID using the EV_OBJECT_ID parameter. Use this method if you expect small content (<1 MB, max 15 MB).

● chunkedIn this case the content is delivered in chunks, the CREATE_DOCUMENT method is called, and the first chunk is transported using the IS_CONTENT structure. If there is only one chunk, the HAS_MORE parameter is set to false. If the HAS_MORE parameter is set to true, the CREATE_CONTENT method is then called. The same logic as for the CREATE_DOCUMENT method applies to the CREATE_CONTENT method: If the HAS_MORE parameter is set to true, it is called again until the complete content is transferred, as indicated by the HAS_MORE parameter. In this case it is sufficient for the CREATE_DOCUMENT method to return the object ID using the EV_OBJECT_ID parameter. Use this method if you expect medium-size content (<100 MB).

● document_specificIn this case the CREATE_DOCUMENT method is called with only the document metadata and without content. The repository must also ensure that the properties are saved and an empty document is created. In addition,the repository has to send back the ES_CONTENT_DELIVERY_INFO structure that contains the information on how to deliver the content. If you choose to deliver the content using a URL, then the repository must provide an HTTP URL and the method (POST/PUT) to use. The content is then directly pushed to that URL. After the content upload and regardless of whether the upload succeeded or failed, the ON_CONTENT_UPLOADED method is called. The parameter IV_UPLOAD_RESULT is set to "OK" if the upload was successful. Any other value indicates an upload failure. If you choose a chunked or a full delivery, the CREATE_CONTENT method is called either with the complete content or the first chunk of it.

1.2.2.5 Query

The ABAP connector contains a simple query parser. It splits CMIS queries into the four main parts of a query: SELECT, FROM, WHERE, and ORDER BY.

It also parses the SELECT, FROM, and ORDER BY parts and provides the results in appropriate data structures. The WHERE clause is not parsed, but is provided as a single string.


Developer's Guides

ExampleUsing the Query Parser

DATA: iv_query_statement TYPE cmis_string,rs_simple_parse_result TYPE cl_cmis_simple_query_parser=>parse_result,select TYPE STANDARD TABLE OF cl_cmis_simple_query_parser=>name_alias WITH DEFAULT KEY,from TYPE cl_cmis_simple_query_parser=>name_alias,where TYPE cmis_string,orderBy TYPE cl_cmis_simple_query_parser=>sort_order_tab.iv_query_statement = 'SELECT cmis:name AS name, cmis:contentStreamLength FROM cmis:document WHERE cmis:contentStreamLength < 1024 ORDER BY cmis:name'.rs_simple_parse_result = cl_cmis_simple_query_parser=>parse( iv_query_statement ).select = rs_simple_parse_result-property-query_names.from = rs_simple_parse_result-property-type_query_name.where = rs_simple_parse_result-property-where_clause.orderBy = rs_simple_parse_result-property-sort_order.

1.2.2.6 Building a CMIS Server for

The end-user clients require the following set of methods to work properly. Other CMIS clients may require more.

Table 14: Methods

Service CMIS Method ABAP Method Convenience Implementation in Abstract Class

Required (ro = read-only, rw = read-write)

Repository Service

getRepositories

X ro / rw

getRepositoryInfo

REP_INFO - ro / rw

getTypeChildren

GET_TYPE_CHILDREN - ro / rw

getTypeDecendants

GET_TYPE_DESCENDANTS

X ro / rw

getTypeDefinition

GET_ TYPE_DEFINITION

- ro / rw

createType - -

updateType - -

deleteType - -

Navigation Service

getChildren GET_CHILDREN - ro / rw

getDecendants X -

getFolderTree X -




getFolderParent

- ro / rw

getObjectParents

GET_OBJECT_PARENTS - ro / rw

getCheckedOutDocs

- -

Object Service

createDocument - rw

createDocumentFromSource

- rw

createFolder - rw

createRelationship

- -

createPolicy - -

createItem - -

getObject GET_OBJECT - ro / rw

getAllowableActions

X ro / rw

getProperties X ro / rw

getObjectByPath

- ro / rw

getContentStream

GET_CONTENT - ro / rw

getRenditions X -

updateProperties

- rw

bulkUpdateProperties

X -

moveObject - ro / rw

deleteObject - ro / rw

deleteTree - ro / rw

setContentStream

- ro / rw

appendContentStream

- -

deleteContentStream

- ro / rw

Versioning Service


Developer's Guides



checkOut - rw

cancelCheckOut - rw

checkIn - rw

getObjectOfLatestVersion

- ro / rw

getPropertiesOfLatestVersion

X -

getAllVersions - rw

Discovery Service

query QUERY - ro / rw

(metadata query is required, fulltext query is optional)

getContentChanges

- -

(used if available)

ACL Service

getACL - -

applyACL - -

Relationship Service

getObjectRelationships

- -

Policy Service - -

applyPolicy - -

removePolicy - -

getAppliedPolicies

Multifiling Service

addObjectToFolder

- -

removeObjectFromFolder

- -

Queries

The following queries must be supported:


● SELECT * from cmis:folder WHERE cmis:name LIKE '%@'● SELECT * from cmis:document WHERE cmis:name LIKE '%@'● SELECT * FROM cmis:folder WHERE cmis:name LIKE '%@' AND LIKE '%@' ... AND

IN_TREE('%@')● SELECT * FROM cmis:document WHERE cmis:name LIKE '%@' AND LIKE '%@' ... AND

IN_TREE('%@')● SELECT * FROM cmis:folder WHERE cmis:objectId = '%@'● SELECT * FROM cmis:document WHERE cmis:objectId = '%@'● SELECT * FROM cmis:folder WHERE cmis:objectId IN (%@)● SELECT * FROM cmis:document WHERE cmis:objectId IN (%@)

1.2.2.7 Building a CMIS Repository in an ABAP System

These first steps allow you to create a read-only implementation of the ABAP repository.

Procedure

1. Create a class that extends the CL_CMIS_ABSTRACT_SERVICE class.

2. Define a repository ID for your new repository implementation.

A repository ID must be unique within the system and can be any case-insensitive string up to 100 characters.

NoteAvoid special characters. The ID will be part of URLs and debugging is easier if the ID does not need to be encoded or decoded.

3. Add the repository ID and the name of your class to the CMISD_SERVICE table.

4. Implement the GET_REPOSITORY_INFO method in your class.

Make sure that you use the same repository ID that you entered in the CMISD_SERVICE table.

NoteThe CL_CMIS_OBJECT_FACTORY class provides a CREATE_REPOSITORY_INFO_READ method that creates a stub of a repository info structure. The returned structure is sufficient for most read-only repositories. Repositories that support create and update operations have to modify this structure depending on their capabilities.

ExampleUsing the Object Factory to Create a Repository Info Object

es_repository_info = cl_cmis_object_factory=>create_repository_info_read( iv_name = 'My Repository' iv_description = 'This is my first repository'


Developer's Guides

iv_id = 'MY_REPOSITORY_ID' iv_vendor = 'Example Inc' iv_product_name = 'Document Store' iv_product_version = '1.0' iv_root_folder_id = '783245-837234-23490823' iv_acl_supported = abap_false).

5. Implement the GET_OBJECT, the GET_OBJECT_BY_PATH, and the GET_OBJECT_LATEST_VERSION methods.

These methods are all quite similar. Focus on the properties. Everything else can be added later.

NoteGET_OBJECT returns a structure of type CMIS_S_OBJECT. This structure is used in many places. Consider using a central method that can be reused by other methods and that fills a CMIS_S_OBJECT structure.

NoteThe CL_CMIS_OBJECT_FACTORY class provides methods to fill CMIS_S_PROPERTY structures. These structures hold property values and you need one for every property value that you have to return.

There are three methods for each data type:○ CREATE_<XXX>_PROP_SINGLE○ CREATE_<XXX>_PROP_MULTI○ CREATE_<XXX>_PROP_NOTSET

<XXX> is a placeholder for one of the CMIS data types: ID, String, Integer, Decimal, Boolean, DateTime, URI, and HTML.

The CREATE_XXX_PROP_SINGLE methods return a structure for a single-value property. The CREATE_XXX_PROP_MULTI methods return a structure for a multivalue property. If the property (single-value or multivalue) has no value, use the CREATE_XXX_PROP_NOTSET method.

ExampleUsing the Object Factory to Create a Property Value

ls_name_property = cl_cmis_object_factory=>create_string_prop_single( iv_property_id = cl_cmis_property_ids=>name iv_value = 'test.txt').

6. Implement the GET_CHILDREN, the GET_FOLDER_PARENT, and the GET_OBJECT_PARENTS methods.

You can reuse a lot of the code from the GET_OBJECT method.

At this point, you can browse through your repository, but the clients do not allow you to do anything else.7. Go back to the GET_OBJECT method and add support for Allowable Actions. If your repository supports ACLs,

also add ACL support.

The clients use the Allowable Actions to determine which buttons are active and which buttons are deactivated. Once you have added support for Allowable Actions, the clients provide you with more options.

8. Implement the GET_CONTENT method.


NoteIt is preferable to send a URL to the content rather than sending the content as an xstring. The performance is better and the content size is not limited.

You should now be able to use most features of the clients, except syncing and querying. These depend on the QUERY method.

9. Implement the QUERY method.

This is the most complex task. If you just want to support clients, only add support for the queries mentioned above.

The simple query parser that is included in the ABAP connector helps you identify the queries and return the correct result set.

Once the query is implemented, this server supports all read-only operations that requires.

1.3 CMIS Extension for Search

This specification defines a new predicate function PREVIEW() in the CMIS Query Language that returns a content snippet with the found match in the searched CMIS objects.

When displaying search results, CMIS clients can display a content snippet with the matched content.

Specification

BNF grammar structure: PREVIEW ()

● UsageThis is a predicate function that encapsulates the full-text search capability that may be provided by a repository. It offers a string content snippet for the matched content in a CMIS object.

● InputsNo inputs must be provided for this predicate function.

● Return ValueThe PREVIEW () predicate function returns a string with HTML formatting such as …<b>matched term</b>….

● Constraints○ The PREVIEW () function must only be used in queries that also include a CONTAINS() predicate

function.○ The PREVIEW () function must only be used in the SELECT clause of a query. It must not be used in the

WHERE clause or in the ORDER BY clause.○ If PREVIEW() is included in the SELECT clause and an alias column name is not provided, then a query

name of SEARCH_PREVIEW is used for the query output, and the property definition id is repository-specific.


Developer's Guides

Extension Definition (CMIS 1.1)

The repository MUST provide the following feature extension in the repository info.

Table 15:

Feature Extension Attribute Value

ID http://sap.com/cmis/extension/fulltextsearchpreview

URL n.a.

Common Name Full Text Search Content Preview

Version Label 1.0

Description Allows the CMIS query language to support the PREVIEW() function which returns a content snippet of the matching text in the selected resources.


Important Disclaimers and Legal Information

Coding SamplesAny software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP intentionally or by SAP's gross negligence.

AccessibilityThe information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a binding guideline on how to ensure accessibility of software products. SAP in particular disclaims any liability in relation to this document. This disclaimer, however, does not apply in cases of willful misconduct or gross negligence of SAP. Furthermore, this document does not result in any direct or indirect contractual obligations of SAP.

Gender-Neutral LanguageAs far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as "sales person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun does not exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible.

Internet HyperlinksThe SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any damages caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. All links are categorized for transparency (see: http://help.sap.com/disclaimer).


Important Disclaimers and Legal Information

http://help.sap.com/disclaimer/

Developer's GuideImportant Disclaimers and Legal Information P U B L I C 49

go.sap.com/registration/contact.html

© 2017 SAP SE or an SAP affiliate company. All rights reserved.No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice.Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary.These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. All other product and service names mentioned are the trademarks of their respective companies.Please see http://www.sap.com/corporate-en/legal/copyright/index.epx for additional trademark information and notices.

https://go.sap.com/registration/contact.html

https://go.sap.com/registration/contact.html

http://www.sap.com/corporate-en/legal/copyright/index.epx

http://www.sap.com/corporate-en/legal/copyright/index.epx