Triggering Document Actions using Web Applications

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 setProperty 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 setProperty 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 setProperty instead. Unregisters the JavaScript function to get the value for a given property from the browser.	unregisterPropertyProviderFunction('sophora-content:title')
setProperty (since 4.24.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).	setProperty('sophora-content:title', 'New title value')
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')

Triggering Document Actions via sophora://-URLs

These URIs are only working when the page is called within a browser in the DeskClient. Technically the DeskClient's browser implementation intercepts URIs starting with the prefix sophora:// and performs the action defined by the URI's suffix. The following table shows all currently available actions. If an error occurs because invalid parameters were passed, an exception is thrown. If an error occurs while performing the action, an error dialog is displayed.

URI	Parameters	Action	Example
sophora://document/openInEditor	uuid: The UUID of the document to be opened in the editor.	Opens a document in the DeskClient's editor.	sophora://document/openInEditor?uuid=d70df790-17f1-44e2-b052-997235f6f7a5
sophora://document/publish	uuid: The UUID of the document to publish.	Publishes a document.	sophora://document/publish?uuid=d70df790-17f1-44e2-b052-997235f6f7a5
sophora://document/delete	uuid: The UUID of the document to delete.	Deletes a document without showing a confirmation dialog.	sophora://document/delete?uuid=d70df790-17f1-44e2-b052-997235f6f7a5
sophora://document/setProperty	uuid: The UUID of the document the specified property should be set to. property: The name of the property which should be set. value: The value which should be set for the passed property. publishImmediately: Defines whether document should be published immediately after property was set. Allows 'true' or 'false'. Optional, default is 'false'.	Sets value to property of the specified document. Additionally, the document can be re-published if it was published before, has no working version and publishImmediately is set to 'true'. Please note: The property can only be modified when the document is not locked by a user. A dialog may appear asking you to break the lock prior modification of the property.	sophora://document/setProperty?uuid=0c03b298-3e68-47e6-9a0f-c4b84887b3ba&property=sophora:teletextText &value=test&publishImmediately=true
sophora://document/registerForDocumentChanged	uuid: The UUID of the document to register for. remove: Whether to add or remove registration. Allows 'true' or 'false'. Optional, default is 'false'.	Allows to register for "document changed" events. To use, call this URL with remove=false. You must implement the following JavaScript function in your page, which is invoked whenever a document change occurs: function sophora_documentChanged(uuid, stateChange) { // ... do something... }	sophora://document/registerForDocumentChanged?uuid=d70df790-17f1-44e2-b052-997235f6f7a5