DeskClient JavaScript API

If an external web application is integrated in the DeskClient via 'Tools' or browser tab, it can trigger (document) actions via JavaScript functions or hyperlinks. The following actions also work within the preview view of a document inside the DeskClient.

Triggering Document Actions via JavaScript

JavaScript function	Parameters	Action	Example
openDocumentInEditor	uuid: The UUID of the document to open as string	Opens and/or focuses the document with the given UUID in an editor.	openDocumentInEditor('d70df790-17f1-44e2-b052-997235f6f7a5')
getDocument	-	Returns the document of the current editor as JSON string or null if the browser is not associated with any document editor.	getDocument()
getDocumentByUuid	uuid: The UUID of the document as string	Returns the document with the given UUID as JSON string.	getDocumentByUuid('d70df790-17f1-44e2-b052-997235f6f7a5')
getDocumentByExternalId	externalId: The external ID of the document as string	Returns the document with the given external ID as JSON string.	getDocumentByExternalId('Fashion-Report-2020')
getDocumentBySophoraId	sophoraId: The Sophora ID of the document as string	Returns the document with the given Sophora ID as JSON string.	getDocumentBySophoraId('Fashion-Reports100')
getDocumentStateImageIdentifierByUuid	uuid: The UUID of the document as string (may be null for new documents)	Returns the identifier for the state image of the document with the given UUID.	getDocumentStateImageIdentifierByUuid('d70df790-17f1-44e2-b052-997235f6f7a5')
getLockOwnerByUuid	uuid: The UUID of the document as string (may be null for new documents)	Returns the user who has the lock of the document with the given UUID. Returns null if the document is not locked or the current user has the lock.	getLockOwnerByUuid('d70df790-17f1-44e2-b052-997235f6f7a5')
getSelectValuesByExternalId	externalId: The ExternalID of the select values document to convert to JSON string	Returns the select values document as JSON string. (since 4.7.0)	getSelectValuesByExternalId('751c382b-bed1-475e-8ec8-29e70d4c77f7')
getSelectValueListByExternalIdForStructurePath	externalId: The ExternalID of the select values document to convert to JSON string structure path: The path of the structure node to search for select values in	Returns a list of select values documents as JSON string. (since 4.7.0)	getSelectValueListByExternalIdForStructurePath('751c382b-bed1-475e-8ec8-29e70d4c77f7', '/system')
getUserDisplayName	username: The user name of the user as string (may be null)	Returns the display name of the given user.	getUserDisplayName('guest')
setDirty	-	Deprecated: Use property setters (e.g. setBoolean, setDouble etc.) instead. Marks the current editor dirty.	setDirty()
registerPropertyProviderFunction	propertyName: the property name, e.g. 'sophora-content:title' jsFunctionName: the name of a JavaScript function that returns the string value for the property, e.g. 'getTitle'	Deprecated: Use property setters (e.g. setBoolean, setDouble etc.) instead. Registers a JavaScript function to get the value for a given property from the browser. When the editor is saved this property will be set in the document. Do not forget to unregister your function again. E.g. you can register an event handler for the 'beforeunload' event to unregister your function when the page changes (via navigation or reload).	registerPropertyProviderFunction('sophora-content:title', 'getTitle')
unregisterPropertyProviderFunction	propertyName: the property name, e.g. 'sophora-content:title'	Deprecated: Use property setters (e.g. setBoolean, setDouble etc.) instead. Unregisters the JavaScript function to get the value for a given property from the browser.	unregisterPropertyProviderFunction('sophora-content:title')
setBoolean setDouble setLong setDate setString setUuidReference setExternalIdReference (since 4.25.0)	propertyName: The name of the property that is to be set. value: The value to be set in the document of the editor	Sets a property of the current document and makes the editor dirty if anything changes. If the editor is opened read-only, no values will be updated. Returns true if setDirty() was called on the editor or false if nothing changed (for example because the editor is read-only). Properties that are modified using these functions should not be configured on other tabs. Changes made outside the browser tab are not guaranteed to be visible to the JavaScript code within the browser tab, and vice versa.	setString('sophora-content:title', 'New title value') setDate('sophora-content:date', Date.now())
setBooleans setDoubles setLongs setDates setStrings setUuidReferences setExternalIdReferences (since 4.25.0)	propertyName: The name of the property that is to be set. values: An array of values to be set in the document of the editor	Sets a property of the current document and makes the editor dirty if anything changes. If the editor is opened read-only, no values will be updated. Returns true if setDirty() was called on the editor or false if nothing changed (for example because the editor is read-only). Properties that are modified using these functions should not be configured on other tabs. Changes made outside the browser tab are not guaranteed to be visible to the JavaScript code within the browser tab, and vice versa.	setStrings('sophora-content:titles', ["title1", "title2", "title3"])
removeProperty (since 4.25.0)	propertyName: The name of the property that is to be removed.	Removes a property of the current document and makes the editor dirty if anything changes. If the editor is opened read-only, no values will be updated. Returns true if setDirty() was called on the editor or false if nothing changed (for example because the editor is read-only).	removeProperty('sophora-content:title')
registerDocumentChangeListenerFunction	jsFunctionName: The name of a function in window	Registers a JavaScript function that is called when a document is changed. The function will receive the event object as parameter. Do not forget to unregister your function again. E.g. you can register an event handler for the 'beforeunload' event to unregister your function when the page changes (via navigation or reload). Example of a parameter object: { "uuid":"78390270-cd40-430b-8f14-e17f5966f5ee", "sophoraId":"test100", "externalId":"test-external-ID", "primaryType":"test-nt:document", "oldState":{ "state":"IN_PROCESS", "deleted":false, "enabled":true, "liveVersionAvailable":false, "offline":false }, "newState":{ "state":"PUBLISHED", "deleted":false, "enabled":true, "liveVersionAvailable":true, "offline":false }, "stateChange":"PUBLISH", "nodeChanges":{ "propertyNames":[ "test:changed" ] }, "cause":"SUBSTANTIAL_CHANGE" }	registerDocumentChangeListenerFunction('sophoraDocumentChanged')
unregisterDocumentChangeListenerFunction	jsFunctionName: The name of a function in window	Unregisters a JavaScript function that is called when a document is changed.	unregisterDocumentChangeListenerFunction('sophoraDocumentChanged')
registerLockChangeListenerFunction	jsFunctionName: The name of a function in window	Registers a JavaScript function that is called when a document is locked or unlocked. The function will receive two parameters: A uuid as string and a boolean to indicate if the document is locked or not. Do not forget to unregister your function again. E.g. you can register an event handler for the 'beforeunload' event to unregister your function when the page changes (via navigation or reload).	registerLockChangeListenerFunction('sophoraOnLockChangedEvent')
unregisterLockChangeListenerFunction	jsFunctionName: The name of a function in window	Unregisters a JavaScript function that is called when a document is locked or unlocked.	unregisterLockChangeListenerFunction('sophoraOnLockChangedEvent')
isUpdatable	-	Returns whether the document of the current editor is editable and can therefore be updated. Returns false if the browser is not associated with any document editor.	isUpdatable()
updateDocument	document: The ISophoraDocument to update as JSON string	Updates the content in the editor (if an editor is available).	updateDocument('<Document as JSON>')
saveDocument	document: The ISophoraDocument to save as JSON string idStem: The ID stem the document shall achieve or null to keep the existing one	Saves the given document. If the document has not been saved yet, the idStem must not be null. In other cases, the idStem can be null to keep the existing ID stem. Returns the saved document as JSON string or null if the document has not been saved.	saveDocument('<Document as JSON>', 'fashion-report')
releaseDocument	uuid: The UUID of the document as string	Releases the document with the given UUID. Returns false in case the operation was canceled.	releaseDocument('d70df790-17f1-44e2-b052-997235f6f7a5')
publishDocument	uuid: The UUID of the document as string	Publishes the document with the given UUID. Returns false in case the operation was canceled.	publishDocument('d70df790-17f1-44e2-b052-997235f6f7a5')
setOfflineDocument	uuid: The UUID of the document as string	Sets the document with the given UUID offline. Returns false in case the operation was canceled.	setOfflineDocument('d70df790-17f1-44e2-b052-997235f6f7a5')
deleteDocument	uuid: The UUID of the document as string	Deletes the document with the given UUID. Returns false in case the operation was canceled.	deleteDocument('d70df790-17f1-44e2-b052-997235f6f7a5')
restoreDocument	uuid: The UUID of the document as string	Restores the document with the given UUID. Returns false in case the operation was canceled.	restoreDocument('d70df790-17f1-44e2-b052-997235f6f7a5')
cloneDocument	uuid: The UUID of the document to clone as string structureNodeUUID: UUID of the target structure node as string	Clones the document with the given UUID. Returns the UUID of the clone as string or null if the document could not be cloned (e.g. the editor was dirty and the user declined the save).	cloneDocument('d70df790-17f1-44e2-b052-997235f6f7a5', '0c03b298-3e68-47e6-9a0f-c4b84887b3ba')

Note that the getDocument functions provide a JSON string. To use it as a JavaScript object you need to parse it. Conversely the saveDocument function requires a JSON string that has to be created from a JavaScript object. For simple usage you can create an according function in your website.

function getSophoraDocument() {
    return getSophoraDocumentOfJson(getDocument());
}

function getSophoraDocumentByUuid(uuid) {
    return getSophoraDocumentOfJson(getDocumentByUuid(uuid));
}

function getSophoraDocumentOfJson(documentJson) {
    return JSON.parse(documentJson);
}

function saveSophoraDocument(documentObject, idStem) {
    var documentJson = JSON.stringify(documentObject);
    var savedDocumentJson = saveDocument(documentJson, idStem);
    return getSophoraDocumentOfJson(savedDocumentJson);
}

Check User Role and Pemissions via JavaScript

If an external web application is integrated in the DeskClient via 'Tools' or browser tab, it can execute checks on the users role and permissions via JavaScript functions or hyperlinks (since 4.11.1). The following checks also work within the preview view of a document inside the DeskClient.

JavaScript function	Parameters	Action	Example
userHasRole	roleId: The role ID (which is the external ID) as string	Returns true if the user has the role with the given role id, else false.	userHasRole('057336b7-e41a-378d-971c-37dfe8b19af0')
userHasStructureNodePermission	structureNodeUuid: The UUID of the structure node as string structureNodePermission: The structure node permission as string	Returns true if the user has the given structure node permission on the specified structure node, else false.	userHasStructureNodePermission('e40a400a-38d9-4b3b-95b6-2de2a1228892', 'editStructure')
userHasDocumentPermissionByNodeType	nodeTypeName: The node type name as string documentPermission: The document permission as string structureNodeUuid: The UUID of the structure node or null to specify any structure node as string	Returns true if the user has the given document permission for the specified node type and structure node, else false.	userHasDocumentPermissionByNodeType('sophora-nt:message', 'read', 'e40a400a-38d9-4b3b-95b6-2de2a1228892')
userHasDocumentPermissionByNode	document: The ISophoraDocument as JSON string documentPermission: The document permission as string	Returns true if the user has the given document permission on the specified document, else false.	userHasDocumentPermissionByNode('<Document as JSON>', 'read')
userHasProposalSectionPermission	proposalPermission: The proposal permission as string proposalSectionUuid: The uuid of the proposal section as string	Returns true if the user has the given proposal permission for the given proposal section, else false.	userHasProposalSectionPermission('readProposals', '6985297e-feaf-49e2-a225-f3b7a5113c32')
userHasTabPermission	tabName: The tab name as string tabPermission: The wanted tab permission as string	Returns true if the user has the given tab permission for the given tab, else false.	userHasTabPermission('base', 'readTab')
userHasSystemPermission	systemPermission: The system permission as string	Returns true if the user has the given system permission, else false.	userHasSystemPermission('administrator')