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.

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.

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.

<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.

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.

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.

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.