This chapter supplements the OASIS CMIS specification, and provides details on the specific implementation of the Content Management REST Service.
The OASIS CMIS (Content Management Interoperability Services) Technical Committee works to standardize a Web services interface specification that will enable greater interoperability of Enterprise Content Management (ECM) systems. For more information, see the OASIS CMIS site:
http://www.oasis-open.org/committees/cmis/
Before continuing, all users should review the OASIS CMIS specification. This chapter references the Content Management Interoperability Services (CMIS) Version 1.0, which can be viewed at the following URL:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cmis-spec-v1.0.html.
The Content Management REST Service provides a server that uses the CMIS RESTful AtomPub server binding to provide access to Oracle Content Server repositories configured in your application.
The specification includes the domain model and two server bindings. As mentioned above, only the RESTful AtomPub binding is currently implemented by the Content Management REST Service. Users should be familiar with Atom and AtomPub, which are the default formats for responses.
Note:
CMIS provides a lowest common denominator for a wide range of different content systems; it is not aligned directly with Oracle WebCenter Content functionality. Refer to the Content Management REST Service service document to identify available functionality.This chapter includes the following sections:
Section 2: Domain Model in the CMIS specification defines a domain model that can be used by applications to work with one or more Content Management repositories.
The Content Management REST Service service document consists of AtomPub workspaces. Each workspace maps to a content connection (only Oracle WebCenter Content repositories are supported by the Content Management REST Service). For details on the service document, see the next section, Section 31.2, "CMIS Part II: RESTful AtomPub Binding".
For this release, some of the optional capabilities listed in section 2.1.1 have not been implemented. Versioning, ACL, Policies, Relationships, Change Log, Folder Descendants/Tree, and Renditions will be considered for future releases.
Specifically, the Content Management REST Service implementation has the following optional capabilities:
capabilityGetDescendants = true capabilityGetFolderTree = false capabilityContentStreamUpdatability = anytime capabilityChanges = none capabilityRenditions = none capabilityMultifiling = false capabilityUnfiling = false capabilityVersionSpecificFiling = false capabilityPWCUpdateable = false capabilityPWCSearchable = false capabilityAllVersionsSearchable = false capabilityJoin = none capabilityACL = none capabilityQuery = none, metadataonly, or both combined
The Content Management REST Service supports document and folder objects. In CMIS the cmis:baseTypeId for a Node will be cmis:folder or cmis:document. Also, the cmis:baseId for a Type will be cmis:folder or cmis:document.
A CMIS Object-Type contains fields mapped from the Oracle WebCenter Content: WebCenter Content metadata field definitions and Oracle WebCenter Content's Site Studio region definitions.
The mapping from Oracle WebCenter Content metadata fields to CMIS property definitions is as follows:
Table 31-1 WebCenter Content Metadata Mappings
| Oracle WebCenter Content Metadata | CMIS Property Definition |
|---|---|
|
TEXT metadata field with option list configured with select list validated and YesNoView or TrueFalseView view |
cmis:propertyBoolean |
|
All other TEXT metadata fields |
cmis:propertyString |
|
LONG TEXT metadata field |
cmis:propertyString |
|
MEMO metadata field |
cmis:propertyString |
|
INTEGER metadata field |
cmis:propertyInteger |
|
DATE metadata field |
cmis:propertyDateTime |
|
DECIMAL metadata field |
cmis:propertyDecimal |
The mapping from Site Studio region definition fields to CMIS property definitions is as follows:
Table 31-2 Site Studio Region Definition Mappings
| Site Studio Region Definition | CMIS Property Definition |
|---|---|
|
Image Element Definition fields |
cmis:propertyString |
|
WYSIWYG Element Definition fields |
cmis:propertyString |
|
Plain Text Element Definition fields |
cmis:propertyString |
|
Static List Element Definition fields |
cmis:propertyString |
Document Objects are the elementary information entities managed by the repository. As defined by the CMIS specification, Document Objects may be version-able, file-able, query-able, control-able and ACLControl-able. As stated earlier, the Content Management REST Service does not support versioning, multi-filing, Policies or ACL for this release.
If a Node is determined to be a Document (not a Folder) then any children it has will not be exposed through CMIS. In CMIS, each Document Object is associated with a single content stream, and for WebCenter CMIS REST, this stream is the Oracle WebCenter Content: WebCenter Content binary associated with the document.
The CMIS specification states that Folder Objects do not have a content-stream and are not version-able. If a Node is determined to be a Folder, then the Content Management REST Service exposes it in this manner. (In Oracle WebCenter Content, folders do not have a content stream and are not versionable).
Section 2.1.6: Relationship Object in the CMIS specification is not applicable; the Content Management REST Service does not support Relationships for this release.
Section 2.1.7: Policy Object in the CMIS specification is not applicable; the Content Management REST Service does not support Policies for this release.
Most of Section 2.1.8: Access Control in the CMIS specification is not applicable; the Content Management REST Service does not support ACL for this release. See the next section for details on allowable actions.
This section lists allowable actions defined for Objects. Because of how this release is implemented, some of these are hard-coded for all objects. Other allowable actions will be set based on the repository configuration.
canGetObjectRelationships = false
canCreateRelationship = false
canGetDescendants = false
canGetFolderTree = false
canCheckOut = false (versioning)
canCancelCheckOut = false (versioning)
canCheckIn = false (versioning)
canAddObjectToFolder = false (multi-filing)
canRemoveObjectFromFolder = false (unfiling/multi-filing)
canApplyPolicy = false
canGetAppliedPolicies = false
canRemovePolicy = false
canCreatePolicy = false
canApplyACL = false
canGetACL = false
canGetRenditions = false
canDeleteTree = true
canGetAllVersions = false (versioning)
Section 2.1.9: Versioning in the CMIS specification is not applicable; the Content Management REST Service does not support versioning for this release.
CMIS queries return a Result Set where each Entry object will contain only the properties that were specified in the query. The Content Management REST Service does not support JOINs in queries, so each result entry will represent properties from a single node. Common searches use a query like "SELECT * FROM …".
The FROM clause specifies a content-type to be searched.
FROM cmis:document ==> any Oracle WebCenter Content document (for example, IDC:GlobalProfile)
FROM cmis:folder ==> any Oracle WebCenter Content folder (for example, IDC:Folder)
FROM typeQueryName ==> type's cmis queryName, as long as the type is queryable (for example, ora:t:IDC!;GlobalProfile)
The cmis:document and cmis:folder types are always queryable. Other types will be queryable if they are searchable in the repository.
The IN_FOLDER predicate is implemented as the folder ID specified, being the parent of the results.
The IN_TREE predicate is implemented as the folder ID specified, being a parent in the folder structure of the results.
The CONTAINS() predicate is a full-text query expression operator.
Properties of cmis:document and cmis:folder will be queryable and orderable if their corresponding Oracle WebCenter Content system property is searchable and sortable. The system property mappings are:
cmis:createdBy ==> dDocAuthor
cmis:lastModifiedBy ==> dDocCreator
cmis:creationDate ==> dCreateDate
cmis:lastModificationDate ==> dLastModifiedDate (for 10g, folders map to dLastModifiedDate and documents map to dCreateDate)
cmis:name ==> dOriginalName (for a document) or dCollectionName (for a folder)
cmis:contentStreamFileName ==> dOriginalName
cmis:contentStreamLength ==> VaultFileSize
cmis:contentStreamMimeType ==> dFormat
cmis:objectId ==> dDocName
cmis:objectTypeId ==> Oracle WebCenter Content profile name or SiteStudio Region Definition name
Note:
cmis:objectTypeId is never orderable.cmis:path ==> use IN_FOLDER or IN_TREE predicate
Note:
Some repositories may have capabilities that are not representable in a CMIS query, and some repositories may have restrictions which will limit the CMIS-query predicates (or combinations of predicates) that can be used in a query. Use the mappings above to translate repository capabilities and restrictions into corresponding considerations for CMIS queries.Nested properties are not queryable or orderable.
The Content Management REST Service implementation reports as orderable any properties which Oracle WebCenter Content specifies as sortable. This list can include properties which Oracle WebCenter Content cannot actually sort on. To allow ordering on a field for which Oracle WebCenter Content reports a sort error, follow the steps below to make the specified Oracle WebCenter Content field sortable:
Go to Administration and open Admin Applets.
Open the Configuration Manager applet and click Advanced Search Design.
Edit the field you wish to make orderable and select Is sortable.
Save your changes and exit Administration.
The table that follows lists specific search considerations and recommendations. For example queries, see Section 31.3, "Content Management REST Service Best Practices and Examples."
Table 31-3 Search Considerations and Recommendations
| Consideration | Recommendation |
|---|---|
|
Oracle WebCenter Content provides limited support for querying on null or non-null values. |
Be aware of the differences in search behavior and do not write search expressions that depend on unsupported criteria. |
|
Recursive search for folders is not supported by Oracle WebCenter Content, but is supported for documents if configured on the Oracle WebCenter Content server as described to the right. |
Scope the search to only include documents (add a select clause like Set the search path on the Search object (add a where clause like " Configure the |
|
Multivalued property operators perform substring matches. This is true for |
Be aware of the differences in search behavior and consider changing the Oracle WebCenter Content option list delimiter character in the Configuration Manager applet to reduce the potential for finding extra matches. |
|
When searching folders ( |
Do not use |
|
Not all properties are searchable, and if the search encounters a property that is not searchable, it will return a ParseException (400 error). |
Understand which properties are searchable for a given content type by examining the Oracle WebCenter Content Configuration Manager information fields section, or by reviewing the ContentType definition. Examine the URL for the Example URLS:
Or, examine the specific type through CMIS. |
|
Not all ContentTypes are searchable. An attempt to search for a non-searchable ContentTypes will throw an exception. For example, the |
Be aware that not all ContentTypes are searchable. |
|
Only String multi-valued properties can be searched. |
Do not specify search for multi-valued property types other than String. |
|
The |
Try to restructure the query using supported syntax. |
|
Only one sort criteria is supported. |
Do not write search expressions that use more than a single sort criteria. |
|
Sorting on non-indexed fields results in an exception. Searching on a non-indexed field throws an exception, with the embedded exception code of, for example, "DRG-10837: section dStatus does not exist". |
Understand which fields have been indexed before using them as sort criteria. Examine the URL for the Example URL: |
|
Empty values are not allowed in a search query. |
Do not use a criteria such as |
|
The |
Be aware of the differences in search behavior and do not write search expressions that depend on unsupported criteria. |
|
Multiple search paths on the same Oracle WebCenter Content repository are not supported. |
Be aware of the differences in search behavior and do not write search expressions that depend on unsupported criteria. |
|
When searching for documents, recursive search (folder tree search) is supported if Oracle WebCenter Content is configured properly. If the search path is not set, then all documents in the repository will be searched (both filed and unfiled). |
Configure the content server |
|
When searching for documents and using the |
Be aware of the differences in search behavior and do not write search expressions that depend upon unsupported criteria. |
|
When searching documents (select * from cmis:document), it is not possible to limit the search to more than just a single content type; for example, this is not supported: |
If you need to limit the search to more than just a single content type, issue multiple queries to achieve the same behavior. If you want to search across all types, use cmis:document in the select statement. |
|
Oracle WebCenter Content search does not support |
If this functionality is necessary, issue multiple queries to achieve the same behavior. |
|
The |
Be aware of the valid operators when using |
|
Queries may be case-sensitive depending on the selected Oracle WebCenter Content search engine. |
Be aware that the Oracle WebCenter Content search engine selection can affect case-sensitivity. Metadata searches using OracleTextSearch as the search engine are generally case-insensitive. Metadata searches using |
The methods described in Section 2.2 Services of the CMIS specification are implemented by the Content Management REST Service; specific implementation details are covered in Section 31.2, "CMIS Part II: RESTful AtomPub Binding."
Section 3: RESTful AtomPub Binding in the CMIS specification defines a specification based on AtomPub that can be used by applications to work with one or more Content Management Repositories. REST services are available through a portal instance.
All navigation of a repository begins with the AtomPub Service Document. From this document, all accessible content in a repository can be discovered through the collections, links, and templates. The URI to the service document, relative to the CMIS web application's context-root, is /rest/cmis/repository.
Therefore, if an application is deployed with a library-context-root-override as in the example above, the service document would be accessed through the following URL: http://hostname:port/rest/cmis/repository
Note:
The REST application is only available with portals and not with Portal Framework applications. However, you can make HTTP requests from your Framework application to access the REST and CMIS resources that are available in a portal. You must make sure that the portal instance is configured with the relevant content connections that you wish to access.By default, this document will contain a workspace for each configured Oracle WebCenter Content repository (only Oracle WebCenter Content repositories are supported by CMIS REST in Oracle WebCenter Portal). A service document for a single repository can be obtained by using the repositoryId query parameter, as described in section 3.6.2.1 of the CMIS AtomPub binding specification.
As noted in the previous section, the service document consists of AtomPub workspaces. Each workspace maps to a Oracle WebCenter Portal WebCenter Content connection.
Specific URIs beyond the service document are not published; it is assumed that users will start at the service document and navigate the collections and links down expected paths. The relationships of the links and the titles and types of the collections are all defined in the CMIS specification, and thus can be commonly navigated by a client implementation. There are also templates defined for each repository, for easier access of objects by path, object by ID, type by ID, and queries. The format of the variables for the path and ID templates can be discovered by viewing the Entries of Folders and Documents.
Section 3.1.3: Response Formats in the CMIS specification indicates that Atom/AtomPub style formats will be returned by default unless overridden by a supported media type expressed in the Accept header.
A generic AtomPub feed reader can walk through any of the feeds returned by the CMIS REST server. It will not see all the CMIS specifics, but will be able to navigate through links. In general, to set up a feed reader, you need to know the URI of a particular feed, which can be discovered by navigating through the service document, for example, the workspace link for "typesdescendants".
For details on query syntax, see the CMIS specification. For Content Management REST Service best practices and examples, see Section 31.3, "Content Management REST Service Best Practices and Examples."
The Content Management REST Service provides the following additional functionality beyond the CMIS specification.
The specification defines the following CMIS services:
GET: getChildren
POST: createDocument
or createFolder
or createPolicy
or moveObject
or addObjectToFolder
The Content Management REST Service provides the following additional services:
POST: create
This service has five query parameters: uid, fileName, contentId, comments, simpleResponse, and one header parameter: Slug. This service is meant to be used as a simple binary request upload. A new document is created with this service. Slug and fileName are used to name the binary that is attached to the request (using both parameters is optional; only one needs to be defined and fileName is checked first). The comments parameter is optional and contentId is optional if Oracle WebCenter Content is set up to auto-generate the dDocName.
POST: create Content-Type: multipart/form-data
This service has a single query parameter: uid, which is the uid of the folder in which the document is to be created. The boolean query parameter simpleResponse will return a response of media type: application/atom+xml;type=entry, if set to false. If set to true, a response of media type: text/html will be returned with a URI pointing to the newly created document. The comments and simpleResponse parameters are both optional, contentId is optional if Oracle WebCenter Content is set up to auto-generate the dDocName, and the name "fileUpload" is required.
<html>
<head>
<title>simple post</title>
</head>
<body>
<form action="http://<host>:<port>/rest/api/cmis/children/StellentRepository?uid=IDC:Folder/2"
method="POST"
enctype="multipart/form-data">
Select a document to upload: <input type="file" name="fileUpload"/><br>
<input type="hidden" name="comments" value="this is just a comment"/>
<input type="hidden" name="contentId" value="uniqueID1"/>
<input type="hidden" name="simpleResponse" value="true"/>
<input type="submit" value="Submit"/>
</form>
</body>
</html>
The specification defines the following CMIS services:
GET: getObject, getObjectOfLatestVersion (getObject)
PUT: updateProperties
DELETE: deleteObject
The Content Management REST Service provides the following additional services:
POST: postToDelete
This service has two query parameters: uid and _method, and allows a document to be deleted through POST.
http://<host>:<port>/rest/api/cmis/document/repoName?uid=ABC&_method="delete"
The specification defines the following CMIS services:
GET: getContentStream
PUT: setContentStream
DELETE: deleteContentStream
The Content Management REST Service provides the following additional services:
POST: postTunnelContentStream
This service has five query parameters: uid, overwriteFlag, fileName, comments, _method, and one header parameter: Slug. This service is meant to be used as a simple binary request upload or delete through POST. A document must already exist for this service. Slug and fileName are used to name the binary that is attached to the request (using both parameters is optional; only one needs to be defined and fileName is checked first). The overwriteFlag parameter defaults to true, the comments parameter is optional and valid values for _method are "delete" or "put" (not case sensitive).
http://<host>:<port>/rest/api/cmis/stream/repoName?uid=ABC&_method="delete"
POST: postTunnelContentStream
Content-Type: multipart/form-data
This service has a single query parameter: uid and is meant to be used as a simple html multipart/form-data upload or delete through POST. A document must already exist for this service. The attribute name="fileUpload" is required, "comments" is optional, and valid values for "_method" are "delete" or "put" (not case sensitive).
<form action="http://<host>:<port>/rest/api/cmis/stream/repoName?uid=WDOC019113"
method="POST"
enctype="multipart/form-data">
Select a document to upload: <input type="file" name="fileUpload"/><br>
<input type="hidden" name="comments" value="this is just a comment"/>
<input type="hidden" name="_method" value="PUT"/>
<input type="submit" value="Submit"/>
</form>
This section provides best practices and examples using the Content Management REST Service. For details on query syntax, see the CMIS specification.
This section includes the following subsections:
The following list provides suggested best practices for repositories that use the Content Management REST Service.
To determine the types that can be used in the "FROM" portion of a query, see the types collection from the AtomPub service document. The type must be queryable and the query name of that type must be used.
For example, IDC:GlobalProfile might have type information similar to the following:
<cmis:localName>IDC:GlobalProfile</cmis:localName> <cmis:displayName>IDC:GlobalProfile</cmis:displayName> <cmis:queryName>ora:t:IDC!;GlobalProfile</cmis:queryName> <cmis:queryable>true</cmis:queryable>
An example query for the type information above could be: "SELECT * FROM ora:t:IDC!;GlobalProfile".
To determine the properties that can be used in the "SELECT" and "WHERE" portions of a query, see the entry for the associated type. Each property definition of that type will be listed and will have a setting for queryable and orderable. The cmis:queryname will be the value to be used in the query.
For example, IDC:GlobalProfile might have property definition information similar to the following:
<cmis:propertyStringDefinition>
<cmis:id>/stanl18-ucm11g/IDC:GlobalProfile.ora:p:dDocName</cmis:id>
<cmis:localName>dDocName</cmis:localName>
<cmis:displayName>dDocName</cmis:displayName>
<cmis:queryName>ora:p:dDocName</cmis:queryName>
<cmis:description>Content ID</cmis:description>
<cmis:propertyType>string</cmis:propertyType>
<cmis:cardinality>single</cmis:cardinality>
<cmis:updatability>readwrite</cmis:updatability>
<cmis:inherited>false</cmis:inherited>
<cmis:required>false</cmis:required>
<cmis:queryable>true</cmis:queryable>
<cmis:orderable>true</cmis:orderable>
</cmis:propertyStringDefinition>
An example query for the property definition information above could be: "SELECT ora:p:dDocName FROM ora:t:IDC!;GlobalProfile"
To keep queries more readable, avoid non-alphanumeric characters in ContentType and PropertyDefinition names.
This section provides some example queries. For details on query syntax, see the CMIS specification. (To get the full URI for a query, see the query URI template in the service document.)
SELECT * from cmis:folder
SELECT cmis:name, cmis:contentStreamFileName, cmis:contentStreamMimeType, cmis:contentStreamLength FROM cmis:document WHERE cmis:contentStreamFileName = 'BinaryName' AND cmis:contentStreamMimeType = 'text/html' AND cmis:contentStreamLength > 1
SELECT cmis:name, cmis:creationDate, cmis:lastModificationDate FROM cmis:folder WHERE cmis:name = 'Trash' AND cmis:lastModificationDate > TIMESTAMP '2008-05-18T10:32:44.703-06:00'
SELECT * FROM cmis:document WHERE cmis:name LIKE 'baker%'
SELECT * FROM cmis:document WHERE cmis:name NOT IN ('nodeBoolean', 'nodeLong')
SELECT cmis:name from cmis:document where IN_TREE('/StellentRepository')
SELECT * FROM ora:t:IDC:GlobalProfile WHERE ora:p:xBooleanTestField = FALSE ORDER BY ora:p:dDocTitle ASC
SELECT ora:p:xMultiValuedDelimiterTest FROM ora:t:IDC:GlobalProfile WHERE ANY ora:p:xMultiValuedDelimiterTest NOT IN ('four')
SELECT cmis:name FROM ora:t:IDC:GlobalProfile WHERE CONTAINS('test') ORDER BY ora:p:dInDate DESC
SELECT * FROM cmis:document where IN_TREE('/StellentRepository/IDC:Folder/2')