Developer Guide SAP Document Center Document Version: PUBLIC. Developer's Guide

Transcription

1 Developer Guide SAP Document Center Document Version: PUBLIC

2 Content Developing Clients....3 Architecture....3 CMIS Open Standard CMIS Enhancements for SAP Document Center REST API URLs for App-to-App Integration of SAP Document Center Configuring the Server URL with a URL Scheme Connecting Your ABAP Back End as a Content Source SAP Document Center ABAP Connector Implementing the SAP Document Center ABAP Connector Integrating the Fiori Component into a UI5 Application CMIS Extension for Search Supported CMIS 1.1 Features (Cloud) P U B L I C Content

3 1 You can develop your own clients or servers for SAP Document Center using the respective developer's guide. Related Information Developing Clients [page 3] Connecting Your ABAP Back End as a Content Source [page 31] Integrating the Fiori Component into a UI5 Application [page 45] CMIS Extension for Search [page 49] Supported CMIS 1.1 Features (Cloud) [page 51] 1.1 Developing Clients To develop your own clients, you need to be familiar with the architecture of SAP Document Center, the CMIS open standard, and its SAP Document Center extensions. You can develop your own clients that connect to the SAP Document Center server or you can integrate SAP Document Center functionality into existing platforms. Related Information Architecture [page 3] CMIS Open Standard [page 4] CMIS Enhancements for SAP Document Center [page 7] REST API [page 20] URLs for App-to-App Integration of SAP Document Center [page 22] Configuring the Server URL with a URL Scheme [page 30] Architecture The main components of the SAP Document Center 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 P U BL IC 3

4 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. All clients connect to and communicate with a single server, the SAP Document Center server, using the CMIS protocol. The SAP Document Center server is offered as a cloud-based solution (subscription model). 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, SAP Document Center offers dedicated repositories to the clients: The My Documents repository The repository where every SAP Document Center 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 repository The repository where SAP Document Center 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 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 4 P U B L I C

5 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. Prerequisites for Developers To develop an app or to integrate SAP Document Center 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 SAP Document Center server. Related Information Apache Chemistry OpenCMIS Client API CMIS 1.1 Specification on OASIS Web page Object Model SAP Document Center 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, SAP Document Center 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. P U BL IC 5

6 Bindings SAP Document Center supports two of the three binding types defined in CMIS 1.1: the AtomPub and the JSONbased 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 following additional endpoints exist for SAP Document Center: <protocol>://<server>:<port>/mcm/b/json <protocol>://<server>:<port>/mcm/b/atom The "/b" after the context root "/mcm" means that the server requests BASIC authentication. Related Information AtomPubBinding on OASIS Web page Browser Binding on OASIS Web page Repository Information SAP Document Center 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 SAP Document Center. 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. Example Getting the list of RepositoryInfo objects with OpenCMIS SessionFactory sessionfactory = SessionFactoryImpl.newInstance(); 6 P U B L I C

7 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); For examples of basic operations such as reading, creating, updating, and deleting objects and folder navigation with OpenCMIS, see the OpenCMIS Client API. Related Information getrepositoryinfo on OASIS Web page OpenCMIS Client API CMIS Enhancements for SAP Document Center SAP Document Center 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 Opening a Session The following CMIS enhancement is used to connect to the SAP Document Center server. To open a session with exactly one repository in an OpenCMIS client, specify a set of session parameters. Then, connect to the SAP Document Center 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. P U BL IC 7

8 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 SAP Document Center, using a custom authentication provider is mandatory for the following reasons: To use SAP Document Center, 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 public Map<String, List<String>> gethttpheaders(string url) { Related Information OpenCMIS Client API Using the CSRF Token The SAP Document Center server offers a token-based mechanism to protect against cross-site request forgery attacks. Note The 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 SAP Document Center 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. 8 P U B L I C

9 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. Example Extracting the token with HTTP and browser binding 1) Get Repository Info and request a token Request: GET /mcm/json Request Header: X-CSRF-Token=fetch Response: 200 OK Response Header: X-CSRF-Token=79E85CA37351BBADF02661F64FC21D3C 2) Get the home folder Request: GET /mcm/json/4caf284f-81f4-4b2a-a77a-3fe c2/root? cmisselector=object&objectid=qn913l3f5e7breuvipj3ub3kkx2yyepxvivcqticico Request Header: X-CSRF-Token=79E85CA37351BBADF02661F64FC21D3C Response: 200 OK Example Token handling in Authentication Provider public class CustomAuthenticationProvider extends StandardAuthenticationProvider { private String token = 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 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 P U BL IC 9

10 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 requests jquery.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 public Map<String, List<String>> gethttpheaders(string url) { Map<String, List<String>> httpheaders = super.gethttpheaders(url); if (httpheaders == null) { 10 P U B L I C

11 httpheaders = new HashMap<String, List<String>>(); Map<String, List<String>> cookies = cookiemanager.get(url, httpheaders); if (!cookies.isempty()) { httpheaders.putall(cookies); return public void putresponseheaders(string url, int statuscode, Map<String, List<String>> headers) { super.putresponseheaders(url, statuscode, headers); cookiemanager.put(url, protected boolean gethandlecookies() { // deactivate standard opencmis session handling // cmis session parameter "COOKIES" will be ignored return false; My Documents Every SAP Document Center 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: 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. Example Getting the My Documents repository Repository mydocumentsrepository = getrepository(repositories, "mydocuments"); // use the repositories list of chapter Repository Information public static Repository getrepository(list<repository> repositories, String extension) { for (Repository rep : repositories) { if(getextensionvalue(rep.getextensions(), extension)!=null) { return rep; return null; Example Getting 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())) { P U BL IC 11

12 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); Example Getting the user's home folder with browser binding and jquery // read repositoryinfos jquery.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-4b2aa77a-3fe c2"].token); ); // read the home folder and alert its displayname var homefolderid = data[id].mydocuments; jquery.getjson("/mcm/json/4caf284f-81f4-4b2a-a77a-3fe c2/root? cmisselector=object&objectid="+homefolderid).done(function(data) { alert(data.properties["cmis:name"].value); ); ); Shared Documents SAP Document Center provides a repository called Shared Documents for collaborating on documents with other users. The following table clarifies the terms used to implement Shared Documents. Table 1: Terms Relevant for Shared Documents Term share owner public link member Definition 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). The user who creates the share automatically becomes its owner. The share's size is billed to the owner's quota. 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. 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. 12 P U B L I C

13 Table 2: Share Roles Role Description CMIS Permission owner Permission to create a share. cmis:all administrator contributor Permission to delete a share, to manage user rights, and to allow public links. Permission to create, to update, and to delete files and folders. This permission also enables the user to create and to delete public links. cmis:all 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 3: CMIS Extensions (on RepositoryInfo Level, Valid for All Public Links) Name Description Type sharing sharing.uploadallo wed sharing.baseurl sharing.downloadur L sharing.maxepirati ondays sharing.minpasswor dlength Similar to the mydocuments extension, this extension contains the ID of the user's Shared Documents home folder. Indicates whether the administrator allows uploads by anonymous users or not. 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. Contains the base URL of a document download link. 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. 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. String Boolean String String int int P U BL IC 13

14 Table 4: CMIS Extensions (on Folder Level, Valid for All Shares) Name Description Type 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 App Operations for Sharing You can use app operations for shared files in SAP Document Center. 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. 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 address, but not the user ID. To help apps to search for users and to assemble an ACL with the correct IDs, SAP Document Center 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 14 P U B L I C

15 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 displayname logonid id Example Example response of an ACL with a single contributor. { "acl": { "aces": [ { "principal": { "principalid": "USER.PRIVATE_DATASOURCE.un:testuser", "principal": { "firstname": "Manfred", "lastname": "Mustermann", " ": "Manfred.Mustermann@sap.com", "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. P U BL IC 15

16 These are the properties: Table 5: 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 DATE TIME 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 DATE TIME Share Password Can be used to protect the access to the shared file with a password. Administrators can enforce the setting of a password. mcm:sharepassword mcm:publiclink String Note The 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. Public write access Controls whether anonymous users have write access to shared files. If set to, 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 Destruction Date Defines the date after which the share is automatically and permanently deleted and cannot be recovered. mcm:destructiondate mcm:destruction DATE TIME Note If no destruction date has been specified, the share will not be deleted automatically. Example Code Samples: OpenCMIS // Getting the sharing home folder String sharinghomefolderid = null; for (CmisExtensionElement extension : sharingrepositoryinfo.getextensions()) { if ("sharing".equals(extension.getname())) { sharinghomefolderid = extension.getvalue(); Folder sharinghomefolder = session.getobject(sharinghomefolderid); 16 P U B L I C

17 // Getting all shares for a user 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 link Folder 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 week properties.put("mcm:validtodate", cal); share.updateproperties(properties); Example Code 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]" "propertyvalue[2]" : "A description" : "cmis:description", ).done(function(data){ shareid = data.properties[ "cmis:objectid"].value; ); P U BL IC 17

18 // 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. Creating a Direct Download Link A direct download link is a link to a file that resides in a share, which has not expired and is not passwordprotected. This link can be used to download the file directly without the sharing Web UI. In the following cases, the user is redirected to the sharing Web UI: The download link is invalid. The share does not exist. The file does not exist. The share has expired or is password-protected. 18 P U B L I C

19 The HTTP URL syntax of a direct download link is: http(s)://<server>:<port>/mcm/public/dl?shr=<share ID>&obj=<doc ID> The syntax contains the following URL parameters: shr string (URL-encoded), required Provides the ID of the share the file resides in. obj string (URL-encoded), required Provides the ID of the file to download 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. Related Information My Documents [page 11] Exceptions To notify users that they have made incorrect user entries, SAP Document Center uses specific messages in exception texts. In general, SAP Document Center adheres to the exception behavior described in the CMIS specification. If the exception is used to express incorrect user entries, SAP Document Center uses specific messages in the exception text. Table 6: Specific Messages in Exception Text Exception Name Message Description CmisPermissionDeni edexception INVALID_TOKEN_PR OVIDED The app must provide a token in every operation except getrepositoryinfos. If no token or the wrong token is provided, this exception is thrown. P U BL IC 19

20 Exception Name Message Description CmisInvalidArgumen texception CmisInvalidArgumen texception CmisInvalidArgumen texception CmisInvalidArgumen texception CmisInvalidArgumen texception CmisInvalidArgumen texception CmisConstraintExce ption CmisConstraintExce ption PASSWORD_NOT_SET PASSWORD_TOO_SHO RT PASSWORD_INVALID PASSWORD_REQUIRE D SHARE_LOCKED<unl ock_date_in_ms> EXPIRATION_DATE_ IN_PAST QUOTA_EXCEEDED Virus VIRUS virus Thrown when creating a public link without a password if the administrative settings require a password. Thrown when creating a public link if the provided password does not meet the requirements specified in the administrative settings. Thrown when a password-protected public link is anonymously accessed with a wrong password. Thrown when a password-protected public link is anonymously accessed without a password. 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). Thrown when creating a share. The expiration date for the share is a link with a validtodate in the past. The quota for the currently logged-on user is used up. No write operations are allowed until the user frees up some space. 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 REST API In some cases the apps need server calls that cannot be mapped to CMIS services. For these calls, the SAP Document Center 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 SAP Document Center, 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 For SAP Cloud Platform, principal search currently only supports the logon ID attribute. 20 P U B L I C

21 Table 7: Title URL Method URL Params Validate Users /mcm/rest/v1/users/validate GET 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=i Success Response Code: 200 Content sample for single entry response: { "foundprincipals": { "displayname": "Horst Sapbox", " ": "admin@mobidocs.de", "firstname": "Horst", "id": "admin", "lastname": "Sapbox", "type": "USER", "nothingfoundfor": "d736367" Content sample for multiple entry response: { "foundprincipals": [ { "displayname": "Horst Sapbox", " ": "admin@mobidocs.de", "firstname": "Horst", "id": "admin", "lastname": "Sapbox", "type": "USER", { "displayname": "Heinz Ketchup", " ": "user1@mobidocs.de", "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. P U BL IC 21

22 Title Sample Call Validate Users 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 ); URLs for App-to-App Integration of SAP Document Center You can build URLs that perform actions in the SAP Document Center app and that can be used for app-to-app integration or as links in s. These URLs are either custom URLs (doccenter://) 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 8: 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 22 P U B L I C

23 Table 9: 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 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). opened and the object itself is selected in the documents list. doccent er://: //v1/ select? rep= &obj= https: // myhost: 8080/mc m/ browser /v1/ select? rep= &obj= P U BL IC 23

24 Action Comment Web App ios App Android App Windows Desktop App Mac Desktop App Windows Native App open If the pa Supported as Supported as Supported as Supported as rameter of Web app of ios SP2 of Android of Windows obj is SP3 (1.3.x). (1.2.x). SP3 (1.3.x). desktop app the ID of SP4 (1.4.x). 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. doccent er://: //v1/ open? rep= &obj= https: // myhost: 8080/mc m/ browser /v1/ open? rep= &obj= P U B L I C

25 Action Comment Web App ios App Android App Windows Desktop App Mac Desktop App Windows Native App present Only for PDF files. Opens a PDF file in presentation mode. Supported as of ios SP2 (1.2.x). doccent er://: //v1/ present? rep= &obj= configure Server configuration URL, together with the server.url =http(s): // <host>(:<p ort>) parameter Supported as of ios SP4 (1.4.x). doccent er://: //v1/ configu re? server. url=htt ps:// myhost: 8080 P U BL IC 25

26 Action Comment Web App ios App Android App Windows Desktop App Mac Desktop App Windows Native App create Link to create share page: Only in combination with rep=share Supported as of Web app SP5 (1.5.x). https: // myhost: 8080/mc m/ browser /v1/ create? rep=sha re edit Opens the edit dialog for a given object. Only in combination with rep=share and obj=object ID Currently, only available for existing shares in the Web UI with this URL: Supported as of Web app SP5 (1.5.x). [server ]: [port]/ mcm/ browser / [versio n]/ edit? rep=sha re&obj= P U B L I C

27 Available URL Parameters rep [page 27] has the following values: <repository ID> mydocuments share corporate obj [page 28] has the following values: <object ID> path [page 28] has the following case-sensitive values: </folder1/folder2> <server.url> has the following values: http(s)://<host>(:<port>) page [page 28], ios-only chapter [page 28], ios-only Note You cannot use the obj and the path parameters in the same URL. Custom URL Syntax The custom URL syntax is: doccenter://://<version>/<action>?parameters Example doccenter://://v1/open?obj=1234&rep=abcdef This URL opens the document with the CMIS object ID 1234 from the SAP Document Center repository with ID abcdef, using version v1 of the SAP Document Center URL scheme and the open action. The syntax contains the following elements: version string, required Denotes the scheme version of SAP Document Center; 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), required SAP Document Center repository 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. P U BL IC 27

28 obj string (URL-encoded), optional CMIS object ID of a file or folder. If provided, the path is ignored. path string (URL-encoded), optional The absolute path inside the specified repository. The start URI is not considered here. The path is URL encoded before it is passed to SAP Document Center. 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, optional If 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: doccenter://://v1/open?rep=abcdef&obj=1234&page=27 chapter string, optional If 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: doccenter://://v1/open?rep=abcdef&obj=1234&chapter=examplechaptername (for ToC entry "ExampleChapterName") doccenter://://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 Example This URL starts the Web app and triggers navigation to the repository The URL then opens all possible subfolders until object 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 SAP Document Center. The syntax contains the following elements: version string, required Denotes the scheme version of SAP Document Center; 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. 28 P U B L I C

29 The syntax contains the following URL parameters: rep string (URL-encoded), required SAP Document Center repository 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), optional CMIS object ID of a file or folder. If provided, the path is ignored. path string (URL-encoded), optional The absolute path inside the specified repository. The start URI is not considered here. The path is URL encoded before it is passed to SAP Document Center. 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 Example version string, required Denotes the scheme version of SAP Document Center; 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: shr string (URL-encoded), required Provides the ID of the share to display. obj string (URL-encoded), optional Specifies 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. P U BL IC 29

30 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, 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. Example The apps receive the following URL: The apps use the following URL to send the getobjectbypath() request: folder2 Related Information Configuring the Server URL with a URL Scheme [page 30] 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 SAP Document Center app using a URL scheme and provide this URL scheme to your users. The URL scheme syntax for configuring the server URL is: doccenter://v1/configure?server.url=<http(s)>://<host>(:<port>) Example doccenter://v1/configure?server.url= This URL configures the server URL of the SAP Document Center app. The syntax contains the following elements: version string, required Denotes the scheme version of SAP Document Center; the current version is v1. 30 P U B L I C

31 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 SAP Document Center 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 Document Center. 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 SAP Document Center ABAP Connector [page 31] Implementing the SAP Document Center ABAP Connector [page 32] SAP Document Center ABAP Connector The SAP Document Center ABAP connector enables ABAP applications to expose a CMIS interface to SAP Document Center. Content stored and/or managed in an ABAP system can be retrieved using the SAP Document Center 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 SAP Document Center 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 SAP Document Center server. The other part resides in the SAP Document Center 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. P U BL IC 31

32 The SAP Document Center ABAP connector connects the SAP Document Center 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 SAP Document Center 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 SAP Document Center ABAP connector and how to attach it to SAP Document Center Implementing the SAP Document Center ABAP Connector To provide documents, content, folder hierarchies, and metadata to SAP Document Center, you must implement the SAP Document Center 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. 32 P U B L I C

33 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 SAP Document Center 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. Tip We 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 33] Constants and Enum Values [page 37] Exceptions [page 37] Content Handling [page 38] Query [page 39] Building a CMIS Server for SAP Document Center [page 40] Building a CMIS Repository in an ABAP System [page 43] 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 33] Properties [page 34] Repository Info [page 36] 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 P U BL IC 33

34 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 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 10: Property Type boolean string id integer datetime decimal html uri Value Field BOOLEAN_VALUE STRING_VALUE STRING_VALUE INT_VALUE DATE_TIME_VALUE DECIMAL_VALUE STRING_VALUE 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. 34 P U B L I C

35 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. propertydefinitions position: 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" ] Example The 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 P U BL IC 35

36 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'. 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 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. 36 P U B L I C

37 DEFAULT_CONTENT_DELIVERY Table 11: Value full chunked document_specific Comment Content is always delivered as a complete xstring. Content is delivered in chunks. 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 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. Example Using Constants ls_property = cl_cmis_object_factory=>create_string_prop_single ( iv_property_id = cl_cmis_property_ids=>created_by iv_value = 'Joe' ) Exceptions The CMIS exceptions defined in the standard are assigned to specific ABAP exceptions. These exceptions are passed on to the respective app. Table 12: CMIS Exception invalidargument notsupported ABAP Exception CX_CMIS_INVALID_ARGUMENT CX_CMIS_NOT_SUPPORTED P U BL IC 37

38 CMIS Exception objectnotfound permissiondenied runtime constraint contentalreadyexists filternotvalid nameconstraintviolation storage streamnotsupported updateconflict versioning ABAP Exception CX_CMIS_OBJECT_NOT_FOUND CX_CMIS_PERMISSION_DENIED CX_CMIS_RUNTIME CX_CMIS_CONSTRAINT CX_CMIS_CONTENT_ALREADY_EXISTS CX_CMIS_FILTER_NOT_VALID CX_CMIS_NAME_CONSTRAINT_VIOLATION CX_CMIS_STORAGE CX_CMIS_STREAM_NOT_SUPPORTED CX_CMIS_UPDATE_CONFLICT 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.' 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 Document Center 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 Document Center server forwards the content sent in the STREAM export parameter. If the parameter contains the full content, set the HAS_MORE export parameter to 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 Document Center 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. Note The size of a chunk should not exceed 1 MB and must not exceed 15 MB. 38 P U B L I C

39 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 36]). The flow differs depending on the chosen method: full In 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). chunked In 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_specific In 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 Query The SAP Document Center 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. P U BL IC 39

40 Example Using 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 Building a CMIS Server for SAP Document Center The SAP Document Center end-user clients require the following set of methods to work properly. Other CMIS clients may require more. Table 13: Methods Service CMIS Method ABAP Method Convenience Implementation in Abstract Class Required (ro = readonly, rw = read-write) Repository Service getrepositorie s X ro / rw getrepositoryi nfo gettypechildre n REP_INFO - ro / rw GET_TYPE_CHILDREN - ro / rw gettypedecenda nts GET_TYPE_DESCENDAN TS X ro / rw gettypedefinit ion GET_ TYPE_DEFINITION - ro / rw createtype - - updatetype - - deletetype - - Navigation Service getchildren GET_CHILDREN - ro / rw getdecendants X - getfoldertree X - 40 P U B L I C

41 Service CMIS Method ABAP Method Convenience Implementation in Abstract Class Required (ro = readonly, rw = read-write) getfolderparen t getobjectparen ts getcheckedoutd ocs - ro / rw GET_OBJECT_PARENTS - ro / rw - - Object Service createdocument - rw createdocument FromSource - rw createfolder - rw createrelation ship - - createpolicy - - createitem - - getobject GET_OBJECT - ro / rw getallowableac tions X ro / rw getproperties X ro / rw getobjectbypat h getcontentstre am - ro / rw GET_CONTENT - ro / rw getrenditions X - updateproperti es bulkupdateprop erties - rw X - moveobject - ro / rw deleteobject - ro / rw deletetree - ro / rw setcontentstre am appendcontents tream deletecontents tream - ro / rw ro / rw Versioning Service P U BL IC 41

42 Service CMIS Method ABAP Method Convenience Implementation in Abstract Class Required (ro = readonly, rw = read-write) checkout - rw cancelcheckout - rw checkin - rw getobjectoflat estversion getpropertieso flatestversion - ro / rw X - getallversions - rw Discovery Service query QUERY - ro / rw (metadata query is required, fulltext query is optional) getcontentchan ges - - (used if available) ACL Service getacl - - applyacl - - Relationship Service getobjectrelat ionships - - Policy Service - - Multifiling Service applypolicy - - removepolicy - - getappliedpoli cies addobjecttofol der removeobjectfr omfolder Queries The following queries must be supported: 42 P U B L I C

43 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 (%@) 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. Note Avoid 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. Note The 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. Example Using 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' P U BL IC 43

44 iv_id = 'MY_REPOSITORY_ID' iv_vendor = 'Example Inc' iv_product_name = 'Document Store' iv_product_version = '1.0' iv_root_folder_id = ' ' 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. Note GET_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. Note The 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 (singlevalue or multivalue) has no value, use the CREATE_XXX_PROP_NOTSET method. Example Using 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 SAP Document Center 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 SAP Document Center 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 SAP Document Center clients provide you with more options. 44 P U B L I C

45 8. Implement the GET_CONTENT method. Note It 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 SAP Document Center 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 SAP Document Center clients, only add support for the queries mentioned above. The simple query parser that is included in the SAP Document Center 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 SAP Document Center requires. 1.3 Integrating the Fiori Component into a UI5 Application With SAP Document Center you can develop your own HTML5 application to display a list of files stored in a repository. Prerequisites To use the SAP Document Center Fiori component, the following prerequisites apply: Your SAP Cloud Platform subaccount is subscribed to SAP Document Center. The repository where the relevant files are stored is connected to SAP Document Center. This setting is configured on the administrator user interface (UI). Context Your UI5 app displays the content of the folder you have chosen as a simple list of documents. In addition, the app provides a set of actions, for example, Delete, Create Folder, Download, and Preview. P U BL IC 45

46 Procedure 1. Create a new destination in SAP Document Center cockpit as described in Creating HTTP Destinations. Use the following data: Table 14: Destination Data Field Name Type URL Value Enter a name, for example, DOCUMENT_CENTER. HTTP You can use the URL for accessing the Web app of your SAP Document Center instance. You can determine the URL in the cockpit. Choose Services SAP Document Center Go to Service. In the browser that opens, copy the first part of this URL (without the /mcm/browser/ part). Paste the URL into the URL field of the new destination. Authentication For easy authentication, choose AppToAppSSO as authentication type. 2. Update the neo-app.json file of your Fiori HTML5 app with the following entries: Sample Code { "welcomefile": "/index.html", "routes": [ { "path": "/webapp/mcm", "target": { "type": "destination", "name": "DEMO_DESTINATION", "entrypath": "/mcm", "description": "Destination to SAP Document Center", { "path": "/mcm", "target": { "type": "destination", "name": "DEMO_DESTINATION", "entrypath": "/mcm", "description": "Destination to SAP Document Center", { "path": "/demodestination", "target": { "type": "destination", "name": "DEMO_DESTINATION", "description": "Destination to SAP Document Center",... ], P U B L I C

47 Sample Code The name property must match the name of the newly created destination in cockpit. 3. Adjust the manifest.json of your HTML5 app as follows: Sample Code "sap.ui5": {... "resourceroots": { "mcm": "mcm/resources/com/sap/mcm" 4. Find the repository ID and object ID of the folder the component should display. a. In the standard SAP Document Center Web app, navigate to the parent folder of the folder you want to use. b. Click (Properties) to the right of the folder name. On the Properties screen of the folder, the Web Link field displays a URL similar to browser/v1/open?rep= &obj= a. Later, when implementing the call to the SAP Document Center component factory, indicate the repository and the object IDs. The value following rep= is the repository ID. The value following obj= is the object ID. 5. In your HTML5 app, add a container with a specific ID. This is where the component will be displayed. The following example displays a default UI5 XML view that contains a <VBox> with the ID documentcenterbox: Sample Code <mvc:view controllername="your.controller.app" xmlns:html=" xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m"> <App id="appview" backgroundcolor="#fcfcfc"> <pages> <Page title=""> <content> <VBox id="documentcenterbox" width="100%"/> </content> <footer> <Bar/> </footer> </Page> </pages> </App> </mvc:view> P U BL IC 47

48 6. Configure DocumentList component. Use the following data: Table 15: Required parameters Name Type Description Type String One of the following, depending on the use case: 1. "DocumentList" (Document List) 2. "Library" (Library Component with optional header, filtering,...) 3. "DocumentListSelector"(Document list that enables only selection of documents. All other actions are disabled and hence the list acts as a document selector) destinationpath String The destination for SAP Document Center [Refer step 1] repositoryid String Repository ID [Refer step 4] objectid String Specifies the home folder of the document list component. It is the top of the folder hierarchy displayed in the component. It is the first entry in the breadcrumbs. [Refer step 4] 7. To retrieve the Fiori component and add it to the page, call the SAP Document Center component factory from the controller of your app: You can use up to four optional parameters that are displayed in the Fiori component. Sample Code sap.ui.define([ "sap/ui/core/mvc/controller", "mcm/components/factory" ], function(controller, Factory) { "use strict"; return Controller.extend("your.controller.App", { oninit: function () { this.setcontrol();, setcontrol: function () { var factory, doccentercomponent, box; factory = new Factory(); doccentercomponent = factory.create({ // required parameters type: "DocumentList, destinationpath: "/[NAME_OF_DESTINATION]", repositoryid: "[REPOSITORY_ID]", objectid: "[OBJECT_ID]", // optional parameters metadata1: cmis:lastmodificationdate, metadata2: cmis:lastmodifiedby, metadata3: cmis:contentstreamlength, metadata4: mcm:classification ); box = this.getview().byid("documentcenterbox"); box.additem(doccentercomponent); ); ); 48 P U B L I C

49 8. Save and deploy your changes. 1.4 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 () Usage This 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. Inputs No inputs must be provided for this predicate function. Return Value The 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 repositoryspecific. Extension Definition (CMIS 1.1) The repository MUST provide the following feature extension in the repository info. Table 16: Feature Extension Attribute ID URL Value n.a. P U BL IC 49

50 Feature Extension Attribute Common Name Value 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. 50 P U B L I C

51 2 Supported CMIS 1.1 Features (Cloud) SAP Document Center supports the following CMIS methods in browser and AtomPub bindings. Note For performance reasons, we recommend using the browser binding. Table 17: CMIS 1.0 Features Service Method Supported Repository Service getrepositories getrepositoryinfo gettypechildren gettypedecendants gettypedefinition Navigation Service getchildren getdecendants getfoldertree getfolderparent getobjectparents getcheckedoutdocs Object Service createdocument createdocumentfromsource createfolder createrelationship createpolicy getallowableactions getobject getproperties getobjectbypath getcontentstream getrenditions updateproperties No No No Supported CMIS 1.1 Features (Cloud) P U BL IC 51

52 Service Method Supported moveobject deleteobject deletetree setcontentstream deletecontentstream Versioning Service checkout cancelcheckout checkin getobjectoflatestversion getpropertiesoflatestversion getallversions Discovery Service query getcontentchanges No ACL Service getacl applyacl Relationship Service getobjectrelationships No Policy Service applypolicy removepolicy getappliedpolicies No No No Multifiling Service addobjecttofolder removeobjectfromfolder No No 52 P U B L I C Supported CMIS 1.1 Features (Cloud)

53 Important Disclaimers and Legal Information Coding Samples Any 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. Gender-Neutral Language As 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 Hyperlinks The 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: Important Disclaimers and Legal Information P U BL IC 53

54 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 for additional trademark information and notices.