Requirements for integrating with other repositories

This page describes API requirements.

APIs for integrating Docs with other repositories

Other repositories must support one of the following two standards:
  • CMIS AtomPub binding APIs

    HCL Connections Docs uses Apache Chemistry as the CMIS client to communicate with a CMIS repository via AtomPub binding.

    For more details about Apache Chemistry, see https://chemistry.apache.org/.

    For more details about CMIS and AtomPub, see http://docs.oasis-open.org/cmis/CMIS/v1.0/cmis-spec-v1.0.html.

  • REST APIs
    Table 1. REST APIs

    This table provides information on the REST APIs.

    Method URI Description Note
    GET /context/{ID}/meta Get the metadata of the document represented by the {ID} where {ID} should be a document id The URI can be different from that listed but should contain the {ID} part
    GET /context/{ID}/content Get the content of the document represented by the {ID} where {ID} is a document ID. The result will download the document. The URI can be different from that listed but should contain the {ID} part
    POST /context/{ID}/content Set the content of the document represented by the {ID} where {ID} is a document ID. This API must support the multipart post method (http://hc.apache.org/httpclient-3.x/methods/multipartpost.html) to complete all upload tasks. The URI can be different from that listed but should contain the {ID} part. The name of the part sent by the multipart POST method is the file name of the current document. If it is different from the file name in the repository, rename the document in the repository to be the same. The repository server should respond with the updated meta json for the document.
    PUT /context/{ID}/meta It is used to update individual or multiple fields of the document represented by the {ID} where {ID} is a document id, including renaming the document and changing its description. The new fields data will be put into an json string, for example, {"name":"new name.docx"}, and then are sent to the repository with the PUT request. The repository server should respond with the updated meta json for the document.
    Sample output of /context/{ID}/content
    {
      "total_count": 1,
      "entries": [
        {
        "id":"test.odt",
        "version": "1.0",
        "name":"test.odt",
        "description":"This is a test document",
        "size":9223,
        "created_at":"2015-04-08T04:21:56-07:00",
        "modified_at":"2015-04-08T04:21:56-07:00",
        "created_by":
        {
            "id":"12345678",
            "name":"fake user",
            "email":"fakeuser@gmail.com"
        },
        "modified_by":
        {
            "id":"12345678",
            "name":"fake user",
            "email":"fakeuser@gmail.com"
        },
        "permissions":
        {
            "read": "true",
            "write": "true"
        }
       }
              
      ]
    }
    Note: A timestamp in the return such as "created_at" should follow RFC 3339 (https://www.ietf.org/rfc/rfc3339.txt) timestamps as in the above sample.
    Sample output of /context/{ID}/meta
    {
        "id":"test.odt",
        "version": "1.0",
        "name":"test.odt",
        "description":"This is a test document",
        "size":9223,
        "created_at":"2015-04-08T04:21:56-07:00",
        "modified_at":"2015-04-08T04:21:56-07:00",
        "created_by":
        {
            "id":"12345678",
            "name":"fake user",
            "email":"fakeuser@gmail.com"
        },
        "modified_by":
        {
            "id":"12345678",
            "name":"fake user",
            "email":"fakeuser@gmail.com"
        },
        "permissions":
        {
            "read": "true",
            "write": "true"
        }
    }
    Note: A timestamp in the return such as "created_at" should follow RFC 3339 (https://www.ietf.org/rfc/rfc3339.txt) timestamps as in the above sample.

Document status notification API(Only available in HCL Docs 2.0.1)

Through the REST API, a notification about whether the document is being edited or closed will be posted to the 3rd party repository. To enable this API, add a notification url in repository section of concord-config.json:
{
"id" : "rest",
"class" : "com.ibm.docs.repository.external.rest.ExternalRestRepository",
"config" :
{
"notification_url" : "http://127.0.0.1:81/notify",
"s2s_method" : "oauth2",
"customer_id" : "box.com",
"bypass_sso" : "true",
"oauth2_endpoint" : "https://app.box.com/api/oauth2/token",
"oauth2_authorize_endpoint": "https://account.box.com/api/oauth2/authorize",
"j2c_alias" : "",
"s2s_token" : "",
"token_key" : "",
"onbehalf_header" : "",                               
"media_meta_url" : "https://api.box.com/2.0/files/{ID}",
"media_get_url" : "https://api.box.com/2.0/files/{ID}/content",
"media_set_url" : "https://upload.box.com/api/2.0/files/{ID}/content",
"docs_callback_endpoint" : "https://box.cn.ibm.com:9443/docs/driverscallback",
"repository_home" : "https://www.ibm.com",
"repository_name" :"Box",
"repo_type": "external.rest"
}
The notification message will be posted to the notification url when the editing session is opened or closed. And the message will be in the following json format:
{"docId":"54529403181","type":"edit.session.close","repoId":"rest"}
{"docId":"54529403181","type":"edit.session.open","repoId":"rest"}

Profiles APIs (optional)

If the repository provides Profiles APIs, HCL Docs can read the users profiles from the API and display the information in the HCL Docs UI, such as the user name, user email, user photo, language setting and so on. The Profiles API should follow format as below:

Table 2. APIs

This table shows the format that the Profiles APIs should follow

Method URI Description Note
GET /context/profiles?userid={ID} Get the users profile identified by {ID}. If no userid is defined, current users profile will be returned. The URI can be different as listed but should support "userid" parameter.
Table 3. Query parameter

This table lists the query parameters

Name Type Description Note
userid string Pass the userid to be queried. N/A
self string Identify to query self, the value could be true or false. N/A
Sample output:
{
	"id": "5c11a0c0-7f6f-1033-982d-eba7a40afa7a",
	"name": "docs_tester",
	"display_name": "docs_tester",
	"email": "docs_tester@gmail.com",
	"photo_url": "https://domain/profiles/id/photo.png",
	"org_id": "default_org",
	"org_name": "myOrg",
	"job_title": "myJob",
	"locale": "de-de"
} 
Note:
  • The locale specified in the user profile will be applied to set the UI language of HCL Docs. If the locale field is missing from the profile output, the UI language of HCL Docs will be the same as the browser.
  • You can download the sample files for REST APIs and Profiles APIs at: http://public.dhe.ibm.com/software/dw/cloud/3rd-party-repository-rest-sample.zip. The samples only demonstrate the APIs implementation, and do not take it as a fully implemented service.

Creating a configuration .xml file for server-to-server communication

  1. Check the file ${DMGR_PROFILE_PATH}/config/cells/${CELL_NAME}/LotusConnections-config/LotusConnections-config.xml. If you cannot find this file, create a new one with following content:
    <?xml version="1.0" encoding="UTF-8"?>
    <config id="LotusConnections" xmlns="http://www.ibm.com/LotusConnections-config" 
    xmlns:sloc="http://www.ibm.com/service-location" xmlns:tns="http://www.ibm.com/LotusConnections-config" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ibm.com/LotusConnections-config LotusConnections-config.xsd">
    <customAuthenticator name="DefaultAuthenticator"/>
    </config>
  2. If the file ${DMGR_PROFILE_PATH}/config/cells/${CELL_NAME}/LotusConnections-config/LotusConnections-config.xml already exists, make sure it contains customAuthenticator element.
  3. Synchronize HCL Docs nodes and restart HCL Docs.

Setting up OAuth2 credentials (optional)

When the server-to-server call from HCL Docs to the repository uses OAuth authentication, you must set up the credentials first.
  1. Import OAuth client_id and client_secret
    On Docs server go to folder ${WAS_INSTALL_ROOT}/profiles/AppSrv1/bin and run the following command:
    • Linux: ./wsadmin.sh -lang jython -username xx -password xx -f ${PATH}/customer_credential_mgr.py -action add -customer customer_id -key key -value value"
    • Windows: wsadmin.bat -lang jython -username xx -password xx -f ${PATH}/customer_credential_mgr.py -action add -customer customer_id -key key -value value"
    where:
    • customer_credential_mgr.py is located in the HCL Docs installation package, ${PATH} is the location of the file, for example, CN30NML.zip\IBMConnectionsDocsrepo\ native\DocsApp_1.3.10.zip\installer\docs\tasks\ (extract the necessary files before using it)
    • customer_id is the value specified in external_customer_id in ${WAS_INSTALL_ROOT}/profiles/AppSrv1/config/cells/{cell}/IBMDocs-config/concord-config.json.
    • key could be oauth2_client_id or oauth2_client_secret and value should be the one that the repository server assigned to HCL Docs application.
      Note: The customer_id and key limitation is 256 bytes, and maximum value is 2048 bytes.
    For example:
    ./wsadmin.sh -lang jython -user xx -password xx -f customer_credential_mgr.py -action
    add -customer abc.com -key oauth2_client_id -value
    "l7xxf61984f99f404575a781d47c6bfebdca"
    ./wsadmin.sh -lang jython -user xx -password xx -f customer_credential_mgr.py -action
    add -customer abc.com -key oauth2_client_secret -value
    "cc692ce34451418e86d9b231ee34af65"
  2. This step is necessary only when integrating with Docs Viewer and repository server via OAuth server to server call.

    Open Websphere concolse of Docs Viewer deployment manager and go to Global security > JAAS > J2C anthentication data and create alias for Docs Viewer. Alias is ViewerOauth, and UserId and Password should be oauth2 client id and client secret that repository server assigned to Docs Viewer.

  3. Import SSL signer

    This step is necessary only when integrating with Docs and repository server via OAuth server to server call. Import the signer of repository server to Docs WebSphere cell following http://www-01.ibm.com/support/docview.wss?uid=swg21650234.