IBM Support

Integrating IBM Connections Docs 2.0 CR2 with Box.com

Technote (FAQ)


Question

What must be done to integrate IBM Connections Docs 2.0 CR2 with Box.com?

Answer

Note: Before integrating with Box.com, you must download and install IBM Docs 2.0 CR2.
Section I: Creating a Box Application for IBM Docs Integration
1. Log in to the Box developer console at https://developers.box.com/.
2. Create a Box application and choose a name, for example, "Edit in IBM Docs"  (make sure Content API Access Only is selected).


3. Remember the values in the client_id and client_secret fields, as you must import the OAuth credentials to the IBM Docs system.
4. In cases where IBM Docs is integrated with other products, the redirect_uri value in the OAuth2 Parameters section must be the same as that used in docs_call_back_url. For example, the URL might be "https://<docs_server>:<port>/docs/driverscallback".
5. Set the user type to Standard Box users.


6. Go to the Web App Integrations section and click Create a New Web App Integration.
7. Configure the web app integration:
   a. Choose a name for the web application, and fill in the description for the application.
   b. Add the supported extensions for Docs: .docx, .pptx, .xlsx, .doc, .xls, .ppt, .ods, .odt, .odp, .csv, .txt.
   c. Under Permissions requirement, select Full permissions are required.
   d. In the Scoped to field, select The parent folder of the file/folder from which this integration is invoked.
   e. Set the category to Editing.
   f. Set the file type category to Documents.
   g. Set the integration status to Online.


   h. Make the integration open a popup in a new tab.
   i. Use REST method.
   j. Leave the Preliminary Callback URL field empty.
   k. The client callback URL should be the callback URL for the case where IBM Docs is integrated with other products, and must use the https protocol, such as "https://dos_server_domain/docs/driverscallback".



   l. Callback parameters should be configured as follows:

          GET:file_id:#file_id#
          GET:repository:box
          GET:code:#auth_code#

8. For the other fields, accept the default values.

9. Save the web application integration and then save the application.


Section II: Integrating Box with IBM Docs
You can integrate with Box when deploying IBM Docs (Option 1), or when IBM Docs already has an existing installation (Option 2).

Option 1: Integrating with Box when deploying IBM Docs 2.0 CR2
Step 1: Deploy IBM Connections Docs 2.0 CR2
1.1 Deploy IBM Connections Docs with the installer.
To run the installer, see Installing the IBM Docs components using the installer in IBM Knowledge Center.

  • In the Install Packages panel, select Other content management systems and deselect Viewer Application, Editor Extension, Viewer Extension.
    • In the Integration with Other Content Management Systems panel,  set the Box integration configuration as follows:
      • Set the repository type as REST.
      • Set the URL for the file metadata as https://api.box.com/2.0/files/{ID}.
      • Set the URL for getting file content as https://api.box.com/2.0/files/{ID}/content.
      • Set the URL for set file content as https://upload.box.com/api/2.0/files/{ID}/content.
      • Set the call authentication method to oauth2.
      • Set the OAuth endpoint for the repository as https://app.box.com/api/oauth2/token.
      • Set the User profiles endpoint as https://api.box.com/2.0/users/{ID}.
      • Set the Repository home as https://app.box.com.


1.2 Deploy IBM Docs with scripts
See Installing IBM Docs components using scripts in IBM Knowledge Center.
  • You need to deploy only the Document Format Conversion Application, Editor Application, and Editor Proxy Filter.
  • When deploying the Editor Application, set the following fields in DocsApp_2.0.0\installer\cfg.properties for Box integration. For other parameters, see Installing the Editor Application.
                Field Value
                external_s2s_method oauth2
                external_customer_id box.com
                external_oauth_endpoint https://app.box.com/api/oauth2/token
                docs_call_back_url https://<docs_server>:<port>/docs/driverscallback
                external_repository_home https://app.box.com
                external_meta_url https://api.box.com/2.0/files/{ID}
                external_get_content_url https://api.box.com/2.0/files/{ID}/content
                external_set_content_url https://upload.box.com/api/2.0/files/{ID}/content
                external_profiles_url https://api.box.com/2.0/users/{ID}
Step2: Download and install IBM Connections Docs 2.0 CR2

Step 3: After installing IBM Docs, update the Editor Application configuration file concord-config.json that is located in <WAS install root>/profiles/Dmgr01/config/cells/<cell name>/IBMDocs-config /.
  • Update WhiteDomainList configuration.
      "WhiteDomainList":[
            " https://app.box.com",
      " https://ibm.ent.box.com"
          ]
  • Update class configuration for com.ibm.docs.directory.external.ExternalDirectory. Change "id" to "box" and add new keys "current_user_profiles_url".
        {
          "id": "box",
          "class": "com.ibm.docs.directory.external.ExternalDirectory",
          "config": {
            "profiles_url": " https://api.box.com/2.0/users/{ID}",
            "current_user_profiles_url":" https://api.box.com/2.0/users/me",
            "token_key": "",
            "docs_callback_endpoint": "https://<docs_server name>:<port>/docs/driverscallback",
            "oauth2_endpoint": " https://app.box.com/api/oauth2/token",
            "j2c_alias": "",
            "onbehalf_header": "",
            "customer_id": "box.com",
            "s2s_token": "",
            "s2s_method": "oauth2",
            "keys": {
              org_id_key": "org_id",
              "photo_url_key": "avatar_url",
              "url_query_key": "ID",
              "display_name_key": "name",
              "name_key": "name",
              "id_key": "id",
              "email_key": "login"
              }
           }
        }
  • Update class configuration for com.ibm.docs.repository.external.rest.ExternalRestRepository, and change "id" to "box".
    {
          "id" : "box",
          "class" : "com.ibm.docs.repository.external.rest.ExternalRestRepository",
          "config" :{
            "s2s_method" : "oauth2",
            "customer_id" : "box.com",
            "oauth2_endpoint": " https://app.box.com/api/oauth2/token",
            "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://<docs_server name>:<port>/docs/driverscallback",
            "repository_home" : " https://app.box.com"
              }
          }  
  • Update class configuration for com.ibm.docs.authentication.filters.ExternalAuth. Change "id" to "box" and add "oauth2_authorize_endpoint", "customer_id", "bypass_sso" .
        {
        "id" : "box",
        "class" : "com.ibm.docs.authentication.filters.ExternalAuth",
        "config" :{
        "s2s_method" : "oauth2",
        "oauth2_endpoint": " https://account.box.com/api/oauth2/authorize",
        "custom_id": "box.com",
        "bypass_sso": "true"
        }
        }                  
  • Sync all nodes, and then from the WebSphere console, restart the application servers where the Editor Application is installed.

Option 2: Integrating Box with an existing IBM Docs system
1. Download and install IBM Connections Docs 2.0 CR2.
2. Update the Editor Application configuration file <WAS install root>/profiles/Dmgr01/config/cells/<cell name>/IBMDocs-config/concord-config.json.
  • Update WhiteDomainList configuration.
"WhiteDomainList":[
      " https://app.box.com",
" https://ibm.ent.box.com"     ]       
  • Update class configuration for com.ibm.docs.repository.external.rest.ExternalRestRepository,and add new keys  "current_user_profiles_url".
    {
"id" : "box",
        "class" : "com.ibm.docs.directory.external.ExternalDirectory",
        "profiles_url": https://api.box.com/2.0/users/{ID} ",
        "current_user_profiles_url": " https://api.box.com/2.0/users/me",
        "token_key" : "",
        "docs_callback_endpoint" : " https://<docs_server name>:<port>/docs/driverscallback",
        "oauth2_endpoint" : " https://app.box.com/api/oauth2/token",
        "j2c_alias": "",
        "onbehalf_header": "",
        "customer_id": " box.com",
        "config": {
        "s2s_token": "",
        "s2s_method": " oauth2",
        "keys": {
        "org_id_key": " org_id",
        "photo_url_key": " avatar_url",
        "url_query_key": " ID",
        "display_name_key": " name",
        "name_key": " name",
        "id_key": " id",
        "email_key": " login"
        }
              }

        }              
  • Update class configuration for com.ibm.docs.repository.external.rest.ExternalRestRepository.

{
      "id": "box",
      "class": "com.ibm.docs.repository.external.rest.ExternalRestRepository",
      "config": {
      "s2s_method": " oauth2",
      "customer_id": " box.com",
      "oauth2_authorize_endpoint":" https://app.box.com/api/oauth2/token"
      "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://<docs_server name>:<port>/docs/driverscallback",
      "repository_home" : " https://app.box.com"
      }
      }
  • Update class configuration for com.ibm.docs.authentication.filters.ExternalAuth ,and add " oauth2_authorize_endpoint"," customer_id "," bypass_sso".

    {
     "id" : " box",
     "class":"com.ibm.docs.authentication.filters.ExternalAuth",
     "config" : {
     "s2s_method" : " oauth2" ,
"oauth2_authorize_endpoint": " https://account.box.com/api/oauth2/authorize ",
"customer_id": "box.com",
    "bypass_sso":"true"
         }             
}       

  • Update socialConfig configuration:
    "socialConfig":{
    "profile": "null",
    "BIZCard": "null",
    "ST": "null",
    "externalprofile":{
    "url": "https://api.box.com/2.0/users/{ID}",
    "useInitialName": false
    }
  • Sync all nodes, and then from the WebSphere console, restart the application servers where the the Editor Application is installed.

Section III: Additional configuration steps for Box integration on an IBM Docs system
Step 1: Set up OAuth2 credentials for Box
On the IBM Docs server, go to the 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 IBM Docs installation package, ${PATH} is the location of the file, for example, CN30NML.zip\IBMConnectionsDocsrepo\ native\DocsApp_2.0.0.zip\installer\docs\tasks\ (extract the necessary files before using)
  • 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 the IBM Docs application. You can get the value when you create the IBM Docs app on Box.
Note: The customer_id and key limitation is 256 bytes, and the maximum value is 2048 bytes.
For example:
./wsadmin.sh -lang jython -username xx -password xx -f customer_credential_mgr.py -action
add -customer box.com -key oauth2_client_id -value
"l7xxf61984f99f404575a781d47c6bfebdca"
./wsadmin.sh -lang jython -username xx -password xx -f customer_credential_mgr.py -action
add -customer box.com -key oauth2_client_secret -value
"cc692ce34451418e86d9b231ee34af65"

Step2: Add box.com https certificates to the WebSphere local trust store
a. Log in to the WebSphere Application Server Administrative Console.
b. Expand Security and click SSL certificate and key management.
c. Under Configuration settings, click Manage endpoint security configurations.
d. Select the appropriate outbound configuration to get to the (cell) management scope.
e. Under Related Items, click Key stores and certificates.
f. Click CellDefaultTrustStore key store.
g. Under Additional Properties, click Signer certificates > Retrieve From Port.
h. In the Host field, enter api.box.com in the host name field, the port_number value 443 in the Port field, and api.box.com in the Alias field.
i. Click Retrieve Signer Information.
j. Verify that the certificate information is for a certificate that you can trust.
k. Click Apply and Save.
l. Restart Deployment Manager, all nodes and app servers.

Step 3: Update jurisdiction policy files to use unrestricted policy files

Update Java policy files in WebSphere. See Enabling security for the realm in IBM Knowledge Center, WebSphere Application Server.

Section IV: Manage Box Application for Docs Integration

1. Open the Box application for the IBM Docs integration, for example, "Edit in IBM Docs."

2. Go to Information for listing in the Box App Gallery, and get Link to Box App Gallery listing, for example, "https://app.box.com/services/edit_in_ibm_docx". 3. Send the Box App link to the users who want to use IBM Docs. 4. Open the link and click the Add button. The app is added to the user's App list. 5. Click the drop-down arrow to the right of a file’s name. Select More Options at the end of the menu. Select the app. IBM Docs is now ready to use.

Document information

More support for: IBM Connections Docs
Deployment

Software version: 2.0

Operating system(s): Linux, Windows

Reference #: 1981293

Modified date: 10 April 2017


Translate this page: