Files CMIS API
Added by IBM contributorIBM | Edited by Claudia R Elbourn on June 16, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

Use the IBM® Connections Files CMIS API to expose file application data using the Content Management Interoperability Services (CMIS) standard via Open Authorization (OAuth). The Files CMIS API replaces the IBM Connections Cloud™ Filer API.

 

Retrieving the service document

 

If you plan to update resources that are made available through the CMIS APIs, first retrieve the service document of the CMIS repository for the user whose credentials are used to authenticate the request:

Table 1. Retrieve the service document

Request method
URL
GET
/{auth}/cmis/my/servicedoc


The repository contains files and folders that are explicitly owned by the user. authenticated to make the request.

The service document contains the following items:

  • The root folder (Root Children) with a list of files and collections that belong to the user who is currently authenticated.
  • The capabilities that the content provider supports, such as versioning, locking, or search.
  • A list of the following predefined queries (Query Collection):
    • Files shared with me
    • Files shared by me
    • Collections shared with me
  • A list of URI templates for various REST calls, such as objectById and the URI to get the service document for a community.



Conventions

The following documentation conventions are used:

{subscriberId}

A Connections Cloud user ID as a long value (not email address): 123456789. You can use the getUserIdentity API to obtain this value.

{repositoryId}

        The repository ID for the user files and collections. Values include:

  • p!{id} for personal libraries
  • cs!{id} for community shared files
  • co!{id} for community owned files
You can discover these values in the service document.

{communityId}

The repository ID for a community. The current value is cs!{communitUniqueId}.

{fileId}

A file identifier, such as 0804B851323E3DD7ADFDFC020943CB26. You can discover this value in the service document.

{collectionId}

A collection identifier, such as 0804B851323E3DD7ADFDFC020943CB26. You can discover this value in the service document.



CMIS REST binding

The Files CMIS API uses RESTful Atompub binding to allow users to request a service document and interact with file repositories. For more information about RESTful Atompub Binding, see the documentation in the http://docs.oasis-open.org/cmis/CMIS/v1.0/os/cmis-spec-v1.0.html#_Toc243905488" target="external">CMIS standard specification.



Files CMIS API extensions for IBM Connections

The Files CMIS API in IBM Connections uses namespaces and prefixes when referring to XML or XML schema elements in the text or examples. For details see http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Files_CMIS_API_extensions_Namespaces_lc3" target="external">Files CMIS API extensions: Namespaces in the IBM Connections wiki.


Additional Files CMIS API extensions for LotusLive


The following Files CMIS API extensions provide capabilities specifically for Connections Cloud applications. Use the examples of operations provided to see what has changed from the previous Filer API implementation used in previous versions of Connections Cloud.

Sharing a file with everyone in your organization

As a file owner, you can make a file visible to everyone in your organization by setting the file to public.

Sample request:

PUT https://example.com/files/basic/cmis/repository/p!ablanks/object/snx:file!2afd8df9-19fe-46ef-bfc4-aa17854f9ac1

<entry>

<title type="text">testFileUpdateProperties13214517640952.txt</title>

<cmisra:object>

<cmis:properties>

...

<cmis:propertyBoolean propertyDefinitionId="snx:isPublic">

<cmis:value>true</cmis:value>

</cmis:propertyBoolean>

...

</cmis:properties>

</cmisra:object>

</entry>


Sample response:

HTTP 200 OK

<atom:entry>

<atom:author>

...

</atom:author>

<atom:link>

...

</atom:link>

<cmisra:pathSegment>testFileUpdateProperties13214517640952.txt</cmisra:pathSegment>

<cmisra:object>

<cmis:properties>

...

<cmis:propertyBoolean

propertyDefinitionId="snx:isPublic" localName="snx_isPublic"

displayName="Public" queryName="snx:isPublic">

<cmis:value>true</cmis:value>

</cmis:propertyBoolean>

...

</cmis:properties>

</cmisra:object>

</atom:entry>


Sharing files with multiple users and returning ACL error messages

Responses from access control list (ACL) operations include information about actions that fail. According to the Oasis CMIS standard specification, the response is a list of ACLs that exist for a given resource. An error message is returned only if the Atom payload is invalid. Without this extension, callers of this API must manually compare the ACL list returned with what they submitted to understand why certain members in the list failed.

To share a file, first locate the URL identified by the rel="http://docs.oasis-open.org/ns/cmis/link/200908/acl link relation in the file entry. Next, add standard PUT methods, including one or more cmis:permission elements for each user or group with whom with want to share. The response that is returned is a list of one or more current cmis:permission elements for the file after the operation and a list of one or more lcmis:permissionError elements for each action that failed.

Sample request:

PUT "http://myserver/files/basic/cmis/repository/p!mshani/acl/snx:file!12345"

Content-Type:application/cmisacl+xml

<cmis:acl>

<cmis:permission>

<cmis:principal>

<cmis:principalId>ablanks</cmis:principalId>

</cmis:principal>

<cmis:permission>cmis:read</cmis:permission>

<cmis:direct>true</cmis:direct>

</cmis:permission>

<cmis:permission>

<cmis:principal>

<cmis:principalId>vhanley</cmis:principalId>

</cmis:principal>

<cmis:permission>cmis:read</cmis:permission>

<cmis:direct>true</cmis:direct>

</cmis:permission>

</cmis:acl>


Sample response:

HTTP Status Code: 200 OK

<cmis:acl>

<cmis:permission>

<cmis:principal>

<cmis:principalId>ablanks</cmis:principalId>

<lcmis:displayName>Amy Blanks</lcmis:displayName>

<lcmis:email>ablanks@renovations.com</lcmis:email>

</cmis:principal>

<cmis:permission>cmis:all</cmis:permission>

<cmis:direct>true</cmis:direct>

</cmis:permission>

<lcmis:permissionError>

<cmis:principal>

<cmis:principalId>vhanley</cmis:principalId>

</cmis:principal>

<cmis:permission>cmis:read</cmis:permission>

<cmis:direct>true</cmis:direct>

<lcmis:errorReason>EJPVJ9067E: Unable to get the user with directory id vhanley.</lcmis:errorReason>

</lcmis:permissionError>

</cmis:acl>


Identifying users by email addresses

During ACL operations, you can optionally identify users by email address instead of cmis:principalId. If the system can resolve the email address to an existing user, the application attempts to apply the specified permissions to that user. However, if the system cannot resolve the email address to an existing user, the application initiates a guest invitation process for that email address.

Sample request:

PUT https://myserver/files/basic/cmis/repository/p!bzechman/acl/snx:file!137cb619-6ba2-4dc9-b298-1313a615fb9d

Content-Type=application/cmisacl+xml

<cmis:acl>

<cmis:permission>

<cmis:principal>

<cmis:principalId></cmis:principalId>

<lcmis:email>csa101910@desaintaignan.com </lcmis:email>

</cmis:principal>

<cmis:permission>cmis:read</cmis:permission>

<cmis:direct>true</cmis:direct>

</cmis:permission>

</cmis:acl>


Deleting a file with more than one version

You can delete all versions of a file by calling a DELETE operation on the URL identified by the version-history link relation. See the http://docs.oasis-open.org/cmis/CMIS/v1.0/os/cmis-spec-v1.0.html#_Toc243905573" target="external">CMIS standard specification for more information.

As the specification explains, if the latest version of a file is deleted, the previous version becomes the latest version. However, the Files component of IBM Connections does not allow users to delete the latest version of a file because previous versions cannot be restored without an explicit request from the user. Users can only delete the latest version of a file if it is the only version available.

Sample request:

DELETE https://example.com/files/basic/cmis/repository/p!ablanks/versions/snx:file!f28737a3-a5b6-4373-9b0d-fdd6b58c6ef4


Sample response:

HTTP Status Code: 204 No Content


Suppressing notifications when updating shared files

To suppress email notifications of changes in files and folders that are shared with others, add the following parameter to the CMIS ACL request: sendNotifications=false.

Sample request:

POST https://example.com/files/basic/cmis/repository/p!ablanks/acl/snx:file!f28737a3-a5b6-4373-9b0d-fdd6b58c6ef4?sendNotification=false


Sample response:

There is no indication of notification suppression in the response.


Including comments when sharing files

To include a comment when sharing files, add the lcmis:shareSummary extension element in the cmis:acl payload that is sent to the ACL resource endpoint. Only one share summary is accepted per request, so the same comment is applied to all shares created within the request. All users involved in the changes caused by the request can see the comment.

Sample request:

POST https://example.com/files/basic/cmis/repository/p!ablanks/acl/snx:file!f28737a3-a5b6-4373-9b0d-fdd6b58c6ef7

<cmis:acl>

<cmis:permission>

<cmis:principal>

<cmis:principalId>vhanley</cmis:principalId>

</cmis:principal>

<cmis:permission>snx:editor</cmis:permission>

<cmis:direct>true</cmis:direct>

</cmis:permission>

<lcmis:shareSummary>testEditFileACLWithShareMessage - shareSummary test</lcmis:shareSummary>

</cmis:acl>


Sample response:

The comment is not included in the ACL operation response.


To view comments for shared files, retrieve the MyShares feed. If the comment exists, it is returned in the summary element of each feed entry.

Sample request:

GET https://example.com/files/basic/api/myshares/feed


Sample response:

<feed>

<generator version="3.5.0.0" uri="http://www.ibm.com/xmlns/prod/sn">IBM Connections - Files</generator>

<id>urn:lsid:ibm.com:td:myshares</id>

<title type="text">All Shares for Vivian Hanley</title>

<link href="https://example.com/files/basic/api/myshares/feed" rel="self">

</link>

<author>

<name>Vivian Hanley</name>

...

</author>

<updated>2011-11-15T19:16:40.967Z</updated>

<opensearch:totalResults>2</opensearch:totalResults>

<app:collection href="https://example.com/files/basic/api/myshares/feed">

<title type="text">myshares</title>

</app:collection>

<entry>

<id>urn:lsid:ibm.com:td:bae2f83d-b326-41a3-8f36-6e21c05fdf5a</id>

<td:uuid xmlns:td="urn:ibm.com/td">bae2f83d-b326-41a3-8f36-6e21c05fdf5a</td:uuid>

<link href="https://example.com/files/basic/api/share/bae2f83d-b326-41a3-8f36-6e21c05fdf5a/entry" rel="self">

</link>

<link href="https://example.com/files/basic/api/share/bae2f83d-b326-41a3-8f36-6e21c05fdf5a/entry" rel="edit">

</link>

<category term="share" scheme="tag:ibm.com,2006:td/type" label="share">

</category>

<author>

...

</author>

<title type="text">testEditFileACLWithShareMessage1321384600413.txt shared by Amy Blanks</title>

<published>2011-11-15T19:16:40.794Z</published>

<updated>2011-11-15T19:16:40.794Z</updated>

<summary type="text">testEditFileACLWithShareMessage - shareSummary test</summary>

...

</entry>

...

</feed>


Including a comment when uploading a new version of a file

Users can include a comment when uploading a new version of a file. This operation is supported on multi-part POST operations to the URL identified by the rel="http://www.ibm.com/xmlns/prod/sn/cmis/multipart-form/object" link relation in a file entry. Next, add a string part to the form with the cmis:checkinComment name and set the value as the comment string. The default value is an empty string. You can view comments by performing a GET operation on the URL identified by rel="version-history" in the file entry.

Encrypting a file

When creating files, you can mark them for encryption by specifying a query parameter on the POST operation. After you mark a file for encryption, you cannot change the setting. The default value is false. Status is returned for entries of type snx:file.

Sample request:

POST https://example.com/files/basic/cmis/repository/p!ablanks/folderc/snx:files?encrypt=true


Sample response:

<atom:entry>

<atom:author>

...

</atom:author>

<atom:link href="https://example.com/files/app/file/4fe4b43c-c471-4789-b8df-5e294ff621f5" rel="alternate" type="text/html">

</atom:link>

...

<cmisra:pathSegment>testCreateEncryptDocumentByPostFileInRequestBody_cb46ae51-547f-4ef9-9a88-e5ff8159c029.pdf</cmisra:pathSegment>

<cmisra:object xmlns:cmisra="http://docs.oasis-open.org/ns/cmis/restatom/200908/">

<cmis:properties xmlns:cmis="http://docs.oasis-open.org/ns/cmis/core/200908/">

...

<cmis:propertyBoolean propertyDefinitionId="snx:encrypt" localName="encrypt" displayName="Encryption Status" queryName="snx:encrypt">

<cmis:value>true</cmis:value>

</cmis:propertyBoolean>

...

</cmis:properties>

</cmisra:object>

</atom:entry>




Differences between Connections Cloud Filer API and IBM Connections Files CMIS API


Connections Cloud now supports the Files CMIS API from IBM Connections. The Files CMIS API replaces the Connections Cloud Filer API used in earlier versions of Connections Cloud.

File names must be unique

When uploading files, file names must be unique. If you need two files to have the same name, consider appending a timestamp to the name of the file, for example filename_12012011_745pm.

URL differences

This section provides comparisons of URLs that have changed.

Note: URLs that are not listed are the same for both APIs.

Table 2. Retrieve files owned by a user

Connections Cloud Filer API
IBM Connections Files CMIS API
GET /files/{auth}/cmis/repository/{repositoryId}/folderc/snx:files!{subscriberId}
GET /files/{auth}/cmis/repository/{repositoryId}/folderc/snx:files
GET /files/{auth}/cmis/repository/{repositoryId}/folderc/snx:virtual!filesownedby!.
GET /files/{auth}/cmis/repository/{repositoryId}/folderc/snx:virtual!.!filesownedby

 


Table 3. Files shared with me

Connections Cloud Filer API
IBM Connections Files CMIS API
GET /files/{auth}/cmis/repository/{repositoryId}/folderc/snx:virtual!filessharedwith!.
GET /files/{auth}/cmis/repository/{repositoryId}/folderc/snx:virtual!.!filessharedwith

 


Table 4. My collections

Connections Cloud Filer API
IBM Connections Files CMIS API
GET /files/{auth}/cmis/repository/{repositoryId}/folderc/snx:collections!{subscriberId}
GET /files/{auth}/cmis/repository/{repositoryId}/folderc/snx:collections

 


Table 5. Collections shared with me

Connections Cloud Filer API
IBM Connections Files CMIS API
GET /files/{auth}/cmis/repository/{repositoryId}/folderc/snx:virtual!collectionssharedwith
GET /files/{auth}/cmis/repository/{repositoryId}/folderc/snx:virtual!.!collectionssharedwith

 


Table 6. Upload a file (binary)

Connections Cloud Filer API
IBM Connections Files CMIS API
POST /files/{auth}/cmis/repository/{repositoryId}/folderc/snx:files!{subscriberId}
POST /files/{auth}/cmis/repository/{repositoryId}/folderc/snx:files

 


Table 7. Upload a file (Atom)

Connections Cloud API
IBM Connections Files CMIS API
POST /files/{auth}/cmis/repository/{repositoryId}/folderc/snx:files!{subscriberId}
POST /files/{auth}/cmis/repository/{repositoryId}/folderc/snx:files

 


Table 8. Unshare file (payload)

Connections Cloud Filer API
IBM Connections Files CMIS API
POST /files/{auth}/cmis/repository/{repositoryId}/acl-remove/snx:file!{fileId}
POST /files/{auth}/cmis/repository/{repositoryId}/acl-remover/snx:file!{fileId}

 


Table 9. List of files in a collection

Connections Cloud Filer API
IBM Connections Files CMIS API
GET /files/{auth}/cmis/repository/p!{subscriberId}/folderc/snx:collection!{collectionId}
GET files/{auth}/cmis/repository/{repositoryId}/folderc/snx:collections

 


Table 10. Get collections and folders shared with me

Connections Cloud Filer API
IBM Connections Files CMIS API
GET /files/{auth}/cmis/repository/{repositoryId}/folderc/snx:virtual!collectionssharedwith
GET /files/{auth}/cmis/repository/{repositoryId}/folderc/snx:virtual!.!collectionssharedwith

 




Example: How to retrieve public files in your organization

Use a query collection URL to see all public files in your organization. Query collection URLs are specific for each user.

Note: An equivalent method for on-premises configurations is to use the Public documents feed. In the cloud version, the Public feed is called My Organization.

 

You can perform the following steps to determine the query collection URL for a particular user. In this example, the user is vhanley.

  1. Get the service document for the user, for example https://server:9443/files/{auth}/cmis/my/servicedoc/.
  2. Retrieve the URL for the query collection:
  3. Use cmisra:id="snx:virtual!.!filespublic" to retrieve the link to the public files folder:
  4. Get the feed so you can retrieve public files:

 

<app:collection href="https://server:9443/files/basic/cmis/repository/p%21vhanley/query">

<cmisra:collectionType>query</cmisra:collectionType>

<atom:title type="text">Query Collection</atom:title>

<app:accept>application/cmisquery+xml</app:accept>

</app:collection>
<atom:link href="https://server:9443/files/basic/cmis/repository/p%21vhanley/object/snx%3Avirtual%21.%21filespublic"

rel="self" type="application/atom+xml;type=entry"

cmisra:id="snx:virtual!.!filespublic"

xmlns:cmisra="http://docs.oasis-open.org/ns/cmis/restatom/200908/"></atom:link>
<atom:link href="https://server:9443/files/basic/cmis/repository/p%21vhanley/folderc/snx%3Avirtual%21.%21filespublic"

rel="down" type="application/atom+xml;type=feed"/>