Triggering Document Actions using Web Applications

This section explains how external web applications can trigger document actions within the DeskClient.

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.	`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.	`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 5.2.1)	`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).	`setString('sophora-content:title', 'New title value')` `setDate('sophora-content:date', Date.now())`
`setBooleans setDoubles setLongs setDates setStrings setUuidReferences setExternalIdReferences` (since 5.2.1)	`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).	`setStrings('sophora-content:titles', ["title1", "title2", "title3"])`
`removeProperty` (since 5.2.1)	`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. 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`

The content of this page is licensed under the CC BY 4.0 License. Code samples are licensed under the MIT License.