Integrate IBM Connections Docs 2.0 with BOXA step-by-step Guide

July 2016

Stefano Pogliani, Executive Social Business Consultant, IBMRoberto Boccadoro, Sr. IT Specialist/Architect, ELD Engineering

IntroductionIn this tutorial, we show how to enable the integration between IBM DOCs and BOX starting from an already installed IBM DOCs site.Refer to the article “Integrate IBM Connections Docs 2.0 with BOX” for further details on how to perform the integration during the installation of IBM DOCs.

This tutorial does not replace the article but tries to explain the integration step-by-step, providing some more detailed explanations on each step and providing a final overview of what happens at runtime once you will edit a BOX file inside IBM DOCs.

Note to integrate with Box.com, you must download and install IBM Connections Docs 2.0 iFix 005.

The document is organized in the following way:1. This Introduction2. The Recipe: explaining the steps required for the integration3. Creating a BOX Application to invoke IBM DOCs on an existing document stored

within BOX.4. Configuring IBM DOCs to interact with BOX5. Configuring IBM Websphere Application Server to interact with BOX6. Example of use7. Runtime Flow

The Recipe In this chapter, we will introduce the steps that will be required in order to perform the integration. We thought that this short notice would help practitioners to better follow the step-by-step guide.

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

Creating the BOX ApplicationThe first thing we have to do is to create the BOX application that adds a new contextual menu item for office documents in the BOX interface (this new menu item will invoke IBM DOCs for editing).

Log in to the Box developer console at https://developers.box.com/ using your BOX credentials).On the right side of the page click on “Create a Box Application”; choose a name for the application (for instance “Edit in Docs”) and click the “Create Application” button

When you reach the next page, in the “General Information” section, make sure that Content API Access Only is selected.

In the OAuth2 Parameters section, take note of the “client_id” and “client_secret” values for the Box application: you will need to import the OAuth credentials into the IBM Docs system.

The “redirect_uri” value displayed in the OAuth2 Parameters section must be the same as the one used for the “docs_callback_url” parameter of the IBM Docs configuration that we will see in the next chapter. The format is the following

"https://<docs_server>:<port>/docs/driverscallback".

NOTE: if you installed IBM DOCs together with IBM Connections, the value for “redirect_uri” is going to be

“https://<connections_server>:<port>/docs/driverscallback”

and, most likely, you can omit the <port>.

Set the User type to Standard Box users.

Now, go to the Web App Integrations section and click Create a New Web App Integration.

In the “General Information” sectiono choose a name for the web application, and fill in the description for the

application.Then, add the supported extensions for IBM Docs:

docx, pptx, xlsx, doc, xls, ppt, ods, odt, odp, csv, txt

Note : the extensions need to be entered without the “dot”

o Under Permissions requirement, select Full permissions are required.

o In the Scoped to field, select The parent folder of the file/folder from which this integration is invoked.

o Set the category to Editing.o Set the file type category to Documents.o Set the integration status to Online.

In the “Callback Configuration” sectiono Make the integration open a popup in a new tab.o Use the REST method.o Leave the Preliminary Callback URL field empty.o The client callback URL should have the same value as the one we previously

used for the “redirect_uri” parameter, such as

https://<connections_server>:<port>/docs/driverscallback

In the “Callback Parameters” section click on “add callback parameter”

Add the file_id parameter as shown here :

This tells BOX that, when issuing the callback to IBM DOCs (using the “redirect_uri” parameter specified above), it needs to pass to IBM DOCs the ID of the file to be edited.

Click again on “add callback parameter” and add the repository parameter as shown here:

This tells BOX that, when issuing the callback to IBM DOCs (using the

“redirect_uri” parameter specified above), it needs to pass to IBM DOCs a fixed string (rest in our case). This string is what allows IBM DOCs to refer to the “rest” classes specified in the concord-config.json file we will see in the next chapter.

Click again on “add callback parameter” and add the code parameter as shown here:

This tells BOX that, when issuing the callback to IBM DOCs (using the “redirect_uri” parameter specified above), it needs to pass to IBM DOCs the #auth_code# information. As #auth_code# is computed by BOX, this is what will allow the IBM DOCs server to connect to BOX without engaging in the first leg of the OAUTH2 dance (more information about this step in the last chapter)

Leave the other fields to their default, then click Save Web App Integration

This will save the web app integration, but you will remain on the same page. To go back editing the Box application you created, you must click on “Cancel” after you saved the web app integration.

Scroll down to the bottom of the page and save the Box application

Now, you have added a new menu item that will show on the BOX files that have the extensions you entered above.

Configuring IBM DOCs to work with BOXNow it is time to tell IBM DOCs something about BOX !In order to do this, you need to edit the file “concord-config.json” that is found in the following directory on your IBM DOCs installation:

<WAS install root>/profiles/Dmgr01/config/cells/<cell name>/IBMDocs-config/concord-config.json

Open the file in your preferred editor and follow these steps:

At the beginning of the concord-config.json file (after the first curly bracket), just add the following fragment:

"x-frame-options": {      "allow_option":"ALLOW-FROM",      "allow_uri": “https://app.box.com”},

as shown here :

This code tells IBM DOCs to allow the IBM DOCs editor to be opened in an iFrame (so, IBM DOCs will be opened as an iFrame managed by the BOX application).

NOTE: when, later, you will be editing a BOX document with IBM DOCs, you will notice that the URL of the IBM DOCs window refers to “app.box.com” and not to the

URL corresponding to your IBM DOCs installation.

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

NOTE: the “class” and “id” may appear at the end of the JSON block to which it refers. Be careful to make the changes to the relevant JSON fragment and not to a different one!

Then provide the following changes:

"repository_home" : “https://app.box.com” "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”

This will make the JSON fragment look like the one here below:

In this step, you told IBM DOCs few information:o Which are the BOX APIs to call to obtain the metadata about the file to be

edited (media_meta_url), the content of the file to be edited (media_get_url) and the endpoint to which to send the file once modified by IBM DOCs (media_set_url)

o Which is the IBM DOCs endpoint that is invoked by BOX when BOX wants to start the editing process (docs_callback_endpoint).NOTE : this value MUST be the same as the “redirect_uri” entered when creating the BOX application in the previous chapter.

o Which authentication method to use (s2s_method, in our case “oauth2”)o Which is the WebSphere Application Server identifier that holds the security

information (customer_id, in our case “box.com”)NOTE : the value for customer_id MUST be the same as the value you will provide later when you will setup the OAUTH2 Credentials for the IBM WebSphere Application Server. It will be used by IBM DOCs to ask the IBM Websphere Application Server to retrieve the correct OAUTH2 credentials to be used to integrate with BOX.

Search the JSON code related to the class "com.ibm.docs.authentication.filters.ExternalAuth" for the id “external.rest” as shown here:

NOTE: the “class” and “id” may appear at the end of the JSON block to which it refers. Be careful to make the changes to the relevant JSON fragment and not to a different one!

Then provide the following changes:

s2s_method : “oauth2”

to obtain the following result:

In this step you told IBM DOCs which is the External Authorization method to use.

Now, let’s change the “com.ibm.docs.directory.external.ExternalDirectory” class for the “external.rest” id

NOTE: the “class” and “id” may appear at the end of the JSON block to which it refers. Be careful to make the changes to the relevant JSON fragment and not to a different one!

You will provide the following values :

“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""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""docs_callback_endpoint": “https://<docs_server name>:<port>/docs/driverscallback”

in order to obtain the following result :

In this step you told IBM DOCs few additional information:

o Bypass_sso, when set to TRUE, allows IBM DOCs to use the current BOX user as the editor of the document.In this way, IBM DOCs will NOT force you to login with any of the users of the relevant IBM Connections installation but will perform the editing under the “authority” of the current BOX user.NOTE: you are likely to add the line for “bypass_sso”. In case it did not exist previously, do not forget to add a comma at the end of the line.

o Which are the BOX APIs to use to retrieve the BOX user information (current_user_profiles_url and profiles_url)

o Which is the OAUTH2 endpoint at BOX (oauth2_endpoint) that provides the runtime OAUTH2 Token that will be used by IBM DOCs to exchange information with BOX on behalf of the current BOX user.

o Which is the identifier that holds the security information (customer_id, in our case “box.com”)NOTE : the value for customer_id MUST be the same as the value you will provide later when you will setup the OAUTH2 Credentials for the IBM WebSphere Application Server. It will be used by IBM DOCs to ask the IBM Websphere Application Server to retrieve the correct OAUTH2 credentials to be used to integrate with BOX.

o Which is the IBM DOCs endpoint that is invoked by BOX when BOX wants to start the editing process (docs_callback_endpoint).NOTE : this value MUST be the same as the “redirect_uri” entered when creating the BOX application in the previous chapter.

o The different “Keys” parameters are used by IBM DOCs to map the information coming from the BOX APIs to the parameters IBM DOCs expects.

Finally let’s change the “socialConfig” item

by modifying the “url” parameter as follows :

"url": https://api.box.com/2.0/users/{ID}”

In this step you told IBM DOCs how to retrieve the information about the BOX user.

You can now save the concord-config.json file.

Now we are ready to Sync all nodes in order to propagate the modifications that have been done on the configuration file.You open the WebSphere Console and you synchronize the nodes:

Finally, from the WebSphere Console, restart the application servers where the Editor Application is installed.

At this point we configured IBM DOCs with all the information that are required for it to interact with BOX

Configuring the IBM WebSphere Application ServerNow we need two more steps to finish the configuration.

Set up the OAuth2 credentials 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 yy -f ${PATH}/customer_credential_mgr.py -action add -customer customer_id -key key -value value

where: The “customer_credential_mgr.py” file is located in the IBM Docs

installation package; thus ${PATH} is the location of this file, for example, CN30NML.zip\IBMConnectionsDocsrepo\ native\DocsApp_2.0.0.zip\installer\docs\tasks\ NOTE: extract the necessary files before using it

“customer_id” is the value specified for the “customer_id” parameter in the concord-config.json file (in our case, the value was “box.com”) NOTE : this step is important as it allows IBM DOCs at runtime to fetch the proper OAUTH2 keysto interact with BOX.

the “key” and “value” pair is used to enter the OAUTH2 Keys that were created by BOX when the BOX Application was created (refer to this first chapter when we created the BOX Application). These keys are assigned to be used by IBM DOCS.Since there are TWO OAUTH2 keys (the “oauth2_client_id” and the “oauth2_client_secret”), you will have to issue the wsadmin command twice, one for each key, as shown here below:

./wsadmin.sh -lang jython -user xx -password xx -f ${PATH}/customer_credential_mgr.py -action add -customer box.com -key oauth2_client_id -value "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

./wsadmin.sh -lang jython -user xx -password xx -f ${PATH}/customer_credential_mgr.py -action add -customer box.com -key oauth2_client_secret -value "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

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.

On the left, choose Key stores and certificates

Select the proper KeyStore (depending on your environment (single server or not) it would be either NodeDefaultTrustStore or CellDefaultTrustStore)

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 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, then, Save. Restart Deployment Manager, all nodes and app servers.

Example of use

At this point, we are able to edit a BOX file using IBM DOCs as shown in this sequence;

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

This final chapter describes the runtime flow of information between IBM DOCs and BOX.This flow underlies the “sample use” described in the previous chapter.

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 generated when the “Edit in IBM DOCs” BOX application was 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” described here.

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