Integrating IBM Connections Docs 2.0 with Box

Vienna, October 16-17 2017
Integrating IBM Connections Docs 2.0
with Box
Roberto Boccadoro
@robboc59
blog http://robertoboccadoro.com/
roberto.boccadoro@eldeng.it

PLATINUM SPONSORS
GOLD SPONSORS
SILVER SPONSORS
BRONZE SPONSORS

The recipe
• What we want to configure, at very high level, is the following:
• Create an UI extension on BOX to allow the user to invoke IBM DOCs via the BOX User Interface
• The extension should clearly define the IBM DOCs endpoint that needs to be reached
• We do not want to exchange username/passwords. So we need to have BOX generate the OAuth keys
that will be used by IBM DOCs when it will need to talk with BOX.
At the same time, we need to tell BOX which instance of IBM DOCs it will need to work with
• After the user will use the BOX UI extension, we expect that IBM DOCs would need to invoke BOX to get
the document to be edited, to get information about the user editing it, to send the modified document
back to BOX.
Thus we need to tell IBM DOCs which are the BOX APIs to call and how to authenticate at BOX. This
authentication needs to be the most transparent as possible as we do not want to perform multiple
logins
• As IBM DOCs is a WebSphere Application Server application, we also need to define the security
artefacts that would allow the J2EE engine to interact with BOX

How is it done ?
There are a few steps needed
1. Create an app in Box
2. Edit the Docs configuration file
3. Set up Oauth credential for Box
4. Add box.com certificates in WAS trust store

1) Create a Box application
• Log in to the Box developer console at https://developers.box.com/
• On the right side of the page click on “Create a Box Application”
• Choose a name for the application and click “Create Application”

• In the next page in the section General Information make sure Content
API Access Only is selected

• In the section OAuth2 Parameters take note of client_id and
client_secret for the Box application. You need to import the OAuth
credentials to the IBM Docs system.
• The redirect_uri in the OAuth2 Parameters section should be the
same used in docs_call_back_url of the IBM Docs non-IBM product
integration, such as
"https://<docs_server>:<port>/docs/driverscallback".
• Set the user type to Standard Box users.

• Go to the Web App Integrations section and click Create a
New Web App Integration.

In the General Information section:
• Choose a name for the web application, and fill in the description
for the application.
• Add supported extensions for Docs: .docx, .pptx, .xlsx, .doc, .xls,
.ppt, .ods, .odt, .odp, .csv, .txt.
• Under Permissions requirement, select Full permissions are
required.
• In the Scoped to field, select The parent folder of the file/folder
from which this integration is invoked.
• Set the category to Editing.
• Set the file type category to Documents.
• Set the integration status to Online.

In the Callback Configuration section:
• Make the integration open a popup in a new tab.
• Use REST method.
• Leave the Preliminary Callback URL field empty.
• The client callback URL should be the callback URL of the IBM Docs
non-IBM product integration and must use the https protocol, such as
"https://docs_server/docs/driverscallback".

In the Callback Parameters section click on “add callback parameter”
Add the file_id parameter
Add the repository parameter
Add code parameter

• Leave the other fields as default.
• Save the Web App Integration
• Save the Box Application

2) Edit Docs configuration file
Go in <WAS install root>/profiles/Dmgr01/config/cells/<cell
name>/IBMDocs-config/ and edit concord.config.json
Tip : use Notepad++ or another «smart» editor, this will help you a lot with the correct syntax
At the beginning of the file add the following code
"x-frame-options": {
"allow_option":"ALLOW-FROM",
"allow_uri":https://app.box.com
}
Don’t get mad trying to copy the text from the slides. Grab the document we wrote and you’ll find all the needed code in there
https://www.ibm.com/developerworks/community/files/form/anonymous/api/library/98a7ab0c-9742-463d-bf96-
1c4ff2a65138/document/8f2d3c09-7874-4566-b6d4-
cb410bbba54d/media/Integrate%20IBM%20Connections%20Docs%202.0%20with%20BOX.docx

• Search the JSON code related to the class
"com.ibm.docs.repository.external.rest.ExternalRestRepository" for the id
“external.rest” as shown here:

• Add the following code
"s2s_method" : "oauth2"
"customer_id" : "box.com"
"oauth2_endpoint" : https://app.box.com/api/oauth2/token
"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_servername>:<port>/docs/driverscallback
"repository_home" : https://app.box.com
This will make the JSON fragment look like the one here below:

"com.ibm.docs.authentication.filters.ExternalAuth" for the id
s2s_method : “oauth2”
This will make the JSON fragment look like the one here below:

"com.ibm.docs.directory.external.ExternalDirectory" for the id

“s2s_method” : “oauth2”
"profiles_url": https://api.box.com/2.0/users/{ID}
"current_user_profiles_url":https://api.box.com/2.0/users/me
"bypass_sso":"true"
"docs_callback_endpoint": https://<docs_server name>:<port>/docs/driverscallback
"oauth2_endpoint": https://app.box.com/api/oauth2/token
"customer_id": "box.com"
"keys": "org_id_key": "org_id"
"keys": "photo_url_key": "avatar_url"
"keys": "url_query_key": "ID"
"keys": "display_name_key": "name"
"keys": "name_key": "name"
"keys": "id_key": "id"
"keys": "email_key": "login"
This will make the JSON fragment look like the one here:

• Search the " socialConfig " item
• Modify the following parameter as
follows :
"url":
https://api.box.com/2.0/users/{ID}”

• Sync the nodes
• and then from the WebSphere console, restart the application servers
where the Editor Application is installed.

3) Set up Oauth credential for Box
• On the IBM Docs server, go to the folder ${WAS_INSTALL_ROOT}/profiles/AppSrv1/bin and run the following command:
• 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.zipIBMConnectionsDocsrepo nativeDocsApp_2.0.0.zipinstallerdocstasks (extract the necessary files before using)
• customer_id is the value specified in 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

For example:
wsadmin.bat -lang jython -user xx -password xx -f customer_credential_mgr.py -action
add -customer abc.com -key oauth2_client_id -value
"l7xxf61984f99f404575a781d47c6bfebdca"
wsadmin.bat -lang jython -user xx -password xx -f customer_credential_mgr.py -action
add -customer abc.com -key oauth2_client_secret -value
"cc692ce34451418e86d9b231ee34af65"

4) Add box.com https certificates into the WebSphere local trust store
• Log into the WebSphere Application Server Administrative Console.
• Expand Security and click SSL certificate and key management.
• Under Configuration settings, click Manage endpoint security configurations.

• Select the appropriate outbound
configuration to get to the (cell)
management scope.

• Under Related Items, click Key stores and certificates.
• Click the CellDefaultTrustStore key store

• Under Additional Properties, click Signer certificates > Retrieve From Port
• In the Host field, enter api.box.com, the port_number value 443 in the Port
field, and the api.box.com in the Alias field.
• Click Retrieve Signer Information.

• Verify that the certificate information is for a certificate that you can trust
• Click Apply and Save
• Restart Deployment Manager, all nodes and app servers.

Test the integration

•Log into your BOX account

•Select the document you want to edit and navigate to the “Edit with IBM DOCs” extension that was previously created

•Click on the “Edit with IBM DOCs” and then click “Okay”

•You do not need to be logged in IBM DOCs / IBM Connections.
IBM DOCs will open the document to be edited under the name of the BOX user :
NOTE : IBM
DOCs was also
able to get the
user’s picture
from BOX.

•Comments are also included under the name of the BOX user as shown below:

Once finished, you can force the “Save to Repository” which actually creates a new version of the document inside BOX:

Nothing changes to the behavior described above if am logged into
IBM Connections or IBM DOCs.

Runtime flow of information between IBM DOCs and BOX.
1. A BOX user asks BOX to give IBM DOCs permission to access one of her files.
This step maps the action of the BOX user clicking on the new menu item “Edit in IBM DOCs” from the
BOX’s file contextual menu
2. BOX retrieves the id of the currently logged-in BOX user and the BOX Application’s id (the API Key)
One of the information that BOX generates when the “Edit in IBM DOCs” BOX application is created is
the API Key (you find it just at the bottom of the Application page as shown here):

3.BOX generates the “auth_code”.
This auth_code will be generated based on some schema to ensure its uniqueness; then it will be internally managed
by BOX together with the “Box user id” and the “API Key”.
4. The Browser will be redirected to the IBM DOCs “redirect_uri” with the auth_code, the file_id and the string
“rest” in the query string
5. IBM DOCs exchanges the “auth_code” and the OAUTH2 keys (stored in WebSphere) against the BOX OAUTH2
Token by invoking the BOX API specified by the “oauth2_endpoint” parameter in the concord-config.json
parameter.
In this way, BOX will be able to retrieve the information about the BOX user and the Application that is invoked
(via the auth_code), thus replacing the need for the first leg of the OAUTH2 dance (which cannot happen because
this conversation happens from the IBM DOCs server to the BOX runtime)

6.Now, IBM DOCs has the OAUTH2 token to perform all the other calls to BOX (the media_meta_url, media_get_url
and media_set_url parameters previously specified in concord-config.json)
7.IBM DOCs invokes the media_meta_url to get, from BOX, the metadata about the file to be edited.
Metadata include the “mime type”, the “user” and the “timestamp for the last version”.
8.If IBM DOCs did not cache an older version of the document on respect to the one specified by the timestamp, it
invokes the media_get_url to ask BOX to retrieve the content of the file.
In case IBM DOCs cached the last version, the media_get_url api is not invoked but the cached content is used.
9.Once the user on IBM DOCs decides to save a modified version of the file, the media_set_url of BOX is invoked to
push the content of the modified version

Thank you

Integrating IBM Connections Docs 2.0 with Box

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Integrating IBM Connections Docs 2.0 with Box

Similar to Integrating IBM Connections Docs 2.0 with Box (20)

More from Roberto Boccadoro

More from Roberto Boccadoro (6)

Recently uploaded

Recently uploaded (20)

Integrating IBM Connections Docs 2.0 with Box