Administration | Version 4

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 functionParametersActionExample
openDocumentInEditoruuid: The UUID of the document to open as stringOpens 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()
getDocumentByUuiduuid: The UUID of the document as stringReturns the document with the given UUID as JSON string.getDocumentByUuid('d70df790-17f1-44e2-b052-997235f6f7a5')
getDocumentByExternalIdexternalId: The external ID of the document as stringReturns the document with the given external ID as JSON string.getDocumentByExternalId('Fashion-Report-2020')
getDocumentBySophoraIdsophoraId: The Sophora ID of the document as stringReturns the document with the given Sophora ID as JSON string.getDocumentBySophoraId('Fashion-Reports100')
getDocumentStateImageIdentifierByUuiduuid: 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')
getLockOwnerByUuiduuid: 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')
getUserDisplayNameusername: The user name of the user as string (may be null)Returns the display name of the given user.getUserDisplayName('guest')
setDirty-Marks the current editor dirty.setDirty()
registerPropertyProviderFunctionpropertyName: 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'
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')
unregisterPropertyProviderFunctionpropertyName: the property name, e.g. 'sophora-content:title'Unregisters the JavaScript function to get the value for a given property from the browser.unregisterPropertyProviderFunction('sophora-content:title')
registerDocumentChangeListenerFunctionjsFunctionName: The name of a function in windowRegisters 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')
unregisterDocumentChangeListenerFunctionjsFunctionName: The name of a function in windowUnregisters a JavaScript function that is called when a document is changed.unregisterDocumentChangeListenerFunction('sophoraDocumentChanged')
registerLockChangeListenerFunctionjsFunctionName: The name of a function in windowRegisters 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')
unregisterLockChangeListenerFunctionjsFunctionName: The name of a function in windowUnregisters 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()
updateDocumentdocument: The ISophoraDocument to update as JSON stringUpdates the content in the editor (if an editor is available).updateDocument('<Document as JSON>')
saveDocumentdocument: 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')
releaseDocumentuuid: The UUID of the document as stringReleases the document with the given UUID.

Returns false in case the operation was canceled.
releaseDocument('d70df790-17f1-44e2-b052-997235f6f7a5')
publishDocumentuuid: The UUID of the document as stringPublishes the document with the given UUID.

Returns false in case the operation was canceled.
publishDocument('d70df790-17f1-44e2-b052-997235f6f7a5')
setOfflineDocumentuuid: The UUID of the document as stringSets the document with the given UUID offline.

Returns false in case the operation was canceled.
setOfflineDocument('d70df790-17f1-44e2-b052-997235f6f7a5')
deleteDocumentuuid: The UUID of the document as stringDeletes the document with the given UUID.

Returns false in case the operation was canceled.
deleteDocument('d70df790-17f1-44e2-b052-997235f6f7a5')
restoreDocumentuuid: The UUID of the document as stringRestores the document with the given UUID.

Returns false in case the operation was canceled.
restoreDocument('d70df790-17f1-44e2-b052-997235f6f7a5')
cloneDocumentuuid: 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 getDocumentOfJson(getDocument());
}

function getSophoraDocumentByUuid(uuid) {
    return getDocumentOfJson(getDocumentByUUID(uuid));
}

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

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

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.

URIParametersActionExample
sophora://document/openInEditoruuid: 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/publishuuid: The UUID of the document to publish.Publishes a document.sophora://document/publish?uuid=d70df790-17f1-44e2-b052-997235f6f7a5
sophora://document/deleteuuid: 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/setPropertyuuid: 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

Last modified on 12/11/20

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

Icon