IBM Docs JavaScript API

In order to integrate IBM Docs with third-party systems, a solution has been implemented to enable browser-side integration by releasing one IBM Docs JavaScript SDK and making some public JavaScript APIs available.

You can develop an external HTML application, create an inline frame, and open an IBM Docs page within the inline frame. You must include the IBM Docs JavaScript SDK in your application. In the beginning, you must call a public API to register the window of external application to IBM Docs, and then two-way communication can be established between the external application and the IBM Docs page in the inline frame. By leveraging these public APIs, you can programmatically access IBM Docs content. The APIs can get IBM Docs content, change IBM Docs content, and change the selection to move to the next or previous object in IBM Docs. Also the APIs can be notified of any selection change in IBM Docs after the listener for the IDOCS.EVENT.selectionChange event has been added.
Note: You can download SDK code for reference.
By default, the external application that has same origin as IBM Docs can work without any configuration. If it is across origins, IBM Docs server admin needs to add this origin into one white list, then external application can communicate with IBM Docs page.
Note: Only the Documents editor and Spreadsheets editor have supported public APIs.


Change the configuration to enable your domain to be a supported domain, for example, There are two ways to update the configuration:
  • Change concord-config.json by adding your domain into WhiteDomainList as follows, and then restart Docs server.
    "WhiteDomainList": ["",""]
    Note: WhiteDomainList is the value in ${WAS_INSTALL_ROOT}/profiles/AppSrv1/config/cells/{cell}/IBMDocs-config/concord-config.json.
  • Get from the IBM Docs installation package and copy it to ${WAS_INSTALL_ROOT}/profiles/AppSrv1/bin.
    Note: Extract the IBM Docs 2.0 CR3 installation package and then you can find in the root folder.
  • Execute the Python command at run time to update the configuration:
    On one of the Docs application servers, go to the folder ${WAS_INSTALL_ROOT}/profiles/AppSrv1/bin and run the following command:
    • Linux: ./ -lang jython -username xx -password xx -f -action add -domain http://*
    • Windows: wsadmin.bat -lang jython -username xx -password xx -f -action add -domain http://*

The following section describes the supported methods in DocumentApp and SpreadsheetApp class.

Class DocumentApp and Class SpreadsheetApp

registerIDocsWindow (window)
window is the window of external application.
Register the window information to IBM Docs, then IBM Docs can establish communication with external application. Calling this API is the first step in order to communicate with IBM Docs.
getDocType (callback)
callback is user defined function that will be called after receiving the response from IBM Docs.
Return string "sheet" or "text" depending on the inline-framed document type.
addListener (eventName, callback)
eventName is the supported event name, which can be IDOCS.EVENT.selectionChange and IDOCS.EVENT.contentReady. Note that the event name is case sensitive. The first event will be sent whenever there is a selection change in IBM Docs. The second event is sent after IBM Docs content is loaded successfully.
callback is user defined function that will be called after receiving the specified event.
Return one event id.
Add one listener to the broadcast list of the specified event, the associated callback will be invoked after receiving the event. The event id can be used later to remove the listener from the broadcast list
removeListener(eventId) - optional
eventId a string id.
Remove the listener from the broadcast list
execCommand(command, cmdArgs, callback)
command is the supported command, for example, getSelectedTextInScope, selectTextInScope, and setTextInScope. Note that the command name is case sensitive. They are used to get either sentences or paragraphs from IBM Docs, change selection to either next or previous sentence or paragraph in IBM Docs, and respectively replace the selected sentence or paragraph with new ones in IBM Docs. If the inline framed document is a spreadsheet, they are used to get cell content from focused cell in IBM Docs, move focus to either previous or next non-empty cells in IBM Docs, and replace current cell content with the new one in IBM Docs.
cmdArgs is the command arguments in array. The arguments for command getSelectedTextInScope, selectTextInScope, and setTextInScope are [scope], [scope, direction], [value, scope] respectively. The supported scope can be either sentence or paragraph in document and cell in spreadsheet. The supported direction isself ornextSibling. Note that they are case sensitive as well.
callback is user defined function that will be called after IBM Docs executes the command and responses. It can be optional.
Ask IBM Docs to execute the command with specified arguments if there is any.

Response format

When the external application calls these APIs, IBM Docs responds to the external application with a JavaScript object like the following one:

{"data": {"status": ["error"|"success"]}, {"detail": [string|boolean|one object]}}

If an error happens, the status is displayed as the error and the detail part as the error message. Typically an error message is a function timeout when the external application fails to get a response from IBM Docs side.

Note: You can download JavaScript sample code for reference.