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.
Prerequisites
Change the configuration to enable your domain to be a supported domain, for example,
https://xyz.com. 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": ["https://app.box.com","https://xyz.com"]
Note: WhiteDomainList is the value in ${WAS_INSTALL_ROOT}/profiles/AppSrv1/config/cells/{cell}/IBMDocs-config/concord-config.json. - Get domain_list_mgr.py 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 domain_list_mgr.py 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: ./wsadmin.sh -lang jython -username xx -password xx -f domain_list_mgr.py -action add -domain http://*.ibm.com
- Windows: wsadmin.bat -lang jython -username xx -password xx -f domain_list_mgr.py -action add -domain http://*.ibm.com
The following section describes the supported methods in DocumentApp and SpreadsheetApp class.
Class DocumentApp and Class SpreadsheetApp
Methods:
- registerIDocsWindow (window)
- window is the window of external application.
- getDocType (callback)
- callback is user defined function that will be called after receiving the response from IBM Docs.
- 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.
- removeListener(eventId) - optional
- eventId a string id.
- 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.
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.