Administration

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')
getSelectValuesByExternalIdexternalId: The ExternalID of the select values document to convert to JSON stringReturns the select values document as JSON string.getSelectValuesByExternalId('751c382b-bed1-475e-8ec8-29e70d4c77f7')
getSelectValueListByExternalIdForStructurePathexternalId: 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')
getUserDisplayNameusername: 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()
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'
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')
unregisterPropertyProviderFunctionpropertyName: 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')
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 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 functionParametersActionExample
userHasRoleroleId: The role ID (which is the external ID) as stringReturns true if the user has the role with the given role id, else false.userHasRole('057336b7-e41a-378d-971c-37dfe8b19af0')
userHasStructureNodePermissionstructureNodeUuid: 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')
userHasDocumentPermissionByNodeTypenodeTypeName: 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')
userHasDocumentPermissionByNodedocument: 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')
userHasProposalSectionPermissionproposalPermission: 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')
userHasTabPermissiontabName: 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')
userHasSystemPermissionsystemPermission: The system permission as stringReturns 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.

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/registerForDocumentChangeduuid: 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 1/13/21

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

Icon