Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Include PageDD:Client Plugin APIDD:Client Plugin APIThis article describes the API used to develop client plugins, as well as client-side form scripts.

For more information, refer to the client API documentation.


Table of Contents

scope.api

The API is available by using scope.api.<moren>

scope.api.router

It contains only the function get(), which returns the Angular router.

scope.api.clipboard

The clipboard consists of an array of DMS objects and the type of clipboard action.

There are two action types available using the const "ClipboardAction":

TypeDescription
ClipboardAction.COPY
copies DMS objects
ClipboardAction.CUT
cuts DMS objects


scope.api.clipboard.set()

Use this function to set DMS objects and action type.

ParameterTypeDescription
elements
DmsObject[]
DMS objects you want to copy or cut
action
ClipboardAction

type of action

scope.api.clipboard.get()

This function returns a clipboard object with elements and action.

scope.api.clipboard.clear()

This function clears the clipboard.


scope.api.events

Events can be triggered by a component. Listening components can then react.

Type of events

There are several client-specific events. The most common ones are bundled in the const "EnaioEvent".

Type

Description

Data

LOGOUT
on logout
CLIENT_LOCALE_CHANGED
the client locale has changedISO locale string
SCHEMA_LOCALE_CHANGED
the schema locale has changedISO locale string
DMS_OBJECT_DELETED
a DMS object was deletedthe deleted DMS object
DMS_OBJECT_VERSION_RESTORED
an older version of a DMS object was restoredthe ID of the restored DMS object
DMS_OBJECT_FAVORITE_ON
a DMS object was added to the favoritesthe ID of the DMS object
DMS_OBJECT_FAVORITE_OFF
a DMS object was removed from the favoritesthe ID of the DMS object
DMS_OBJECT_UPDATED
a DMS object was updated (index data, content, subscription, ...)the updated DMS object
DMS_OBJECT_PASTED
a DMS object was pasted into a new context folderthe pasted DMS objects
EO_DIALOG_STACK_CHANGED
the dialog stack has changedan object with ID and active status of the dialog


scope.api.events.trigger()

With this function, you can trigger an event of a type mentioned above.

ParameterTypeDescription
typestringtype of the event
dataany

(optional) data associated with the event


Code Block
languagejs
titleExample
linenumberstrue
scope.api.events.trigger(EnaioEvent.DMS_OBJECT_UPDATED, dmsObject);


scope.api.events.on()

With this function, you can listen to events of a type mentioned above.

ParameterTypeDescription
typestringtype of the event


Returns an Observable containing type and data.

Code Block
languagejs
titleExample
linenumberstrue
scope.api.events.on(EnaioEvent.DMS_OBJECT_UPDATED).subscribe(event => {
	let dmsObject = event.data;
	let eventType = event.type;
});

scope.api.session

Currently, only the following session function is available.

scope.api.session.getUser() (user information)

The function scope.api.session.getUser() returns the user object, in which the following properties about the currently logged-in user are available. They are read-only.

NameDescription
idSystem ID (32 characters)
nameLogin name
firstnameFirst name
lastnameLast name
titleDisplayed name in the format of lastname, firstname
emailE-Mail address
rolesString array with the roles for which the user is authorized
localeApplication language in ISO code (de,en,..) as configured in the client settings
schemaLocaleObject definition language in ISO code (de,en,..) as configured in the client settings
deputiesString array with configured deputies for this user
prevelegesString array with the function rights of the user
presentFALSE if the user is not present as configured in the client settings or in enaio management-studio
userImageREST call for retrieval of the user image

Functions

NameDescription
hasRole(rolename)Checks whether 'rolename' is given in the array 'scope.api.session.getUser().roles'. Note: case-sensitive!

Sample script:

Code Block
languagejs
titleAktueller Benutzer
linenumberstrue
// Write information for the current user in a model value
// The model value must be a STRING type.
var u=scope.api.session.getUser(); 
scope.model.text.value=
'- Login name				\n'+u.name+'\n'+
'- Roles					\n'+u.roles.join()+'\n'+
'- Hasrole FULL_ACCESS?		\n'+u.hasRole('FULL_ACCESS');

scope.api.util

Following are some helper functions.

sopce.api.util.translate

Returns the translated value for a specific translation key.

Code Block
languagejs
titleExample: Messages
linenumberstrue
var myText = scope.api.util.translate('my.translation.key'); // myText = 'Example Text'

sopce.api.util.notifier (display messages)

This helper can be used to display messages in the form of a toaster. 

Functions

NameDescriptionColorsince version
success(message[,title])Display a success messageGreen3.3
error(message[,title])Display an error messageRed3.3
info(message[,title])Display an informational messageGray3.3
warning(message[,title])Display an informational messageOrange4.1

Example

Code Block
languagejs
titleExample: Messages
linenumberstrue
var scope.api.util.notifierm=scope.model;
m.unlimited.onchange=function() {
	if( m.unlimited.value ) {	
		scope.api.util.notifier.success( 
			 m.firstname.value +' ' +m.familiyname.value+' is now employed without time limit.',		// Message
			'Personal information changed'   // optional: use a short title
		);
	}
}



The success message is displayed in green.

Image Added

scope.api.util.encodeFileName

Encodes a filename save for sending characters beyond ASCII-7bit using quoted printable encoding.

More information to come.

scope.api.http

You can use HTTP requests to get data from any service of the system, including custom microservices, which are part of the enaio(r) microservice infrastructure.

The following standard funtions are supported: get, post, put and delete.

scope.api.http.get

Code Block
languagejs
titleExample for get
linenumberstrue
// 1st example: show some user´s inbox workitems in the message box:
scope.api.http.get('/get?size=10','/inboxservice').then(
	function(result) {
	    var inbox='';
		result.data.content.forEach(function(row) {
			inbox+=row.title+'</br>';
		});
		scope.api.util.notifier.success(inbox,'Some inbox workitems');
	},
	function(error) {
		scope.api.util.notifier.error('Failed to load inbox', 'Error');
	}
);


// 2nd example: show all user´s favorites
scope.api.http.get('/service/user/favorites','/rest-ws').then(
	function(result) {
	    var favs='';
		result.data.forEach(function(row) {
			favs+=row.title+'</br>';
		});
		scope.api.util.notifier.success(favs,'Your favorites');
	},
	function(error) {
		scope.api.util.notifier.error('Failed to load favorites', 'Error');
	}
);

// For more information, see the REST function descriptions.

scope.api.http.put

Code Block
languagejs
titleExample for put
linenumberstrue
// how to change object data
var objectId = '7B683C8E19BD492198F6A262D14EF43F';
var changeBody = {'status': 'active'};
scope.api.http.put('/service/dms/'+objectId, changeBody, '/rest-ws').then(
	function(result){
		scope.api.util.notifier.info('Status changed to "active"', 'Success');
	},
	function(error){
		scope.api.util.notifier.error('Failed to change object data for ' + objectId, 'Error');
	}
);

// For more information, see the REST function descriptions.

scope.api.http.del

Code Block
languagejs
titleExample for del
linenumberstrue
// how to delete an object
var objectId = '7B683C8E19BD492198F6A262D14EF43F';

scope.api.http.del('/service/dms/' + objectId, '/rest-ws').then(
	function(result) {
	    scope.api.util.notifier.info('Deleted object ' + objectId, 'Success');
	},
	function(error) {
		scope.api.util.notifier.error('Failed to delete object ' + objectId, 'Error');
	}
);

// For more information, see the REST function descriptions.

scope.api.http.post

Code Block
languagejs
titleExample for post
linenumberstrue
// how to create a subscription
var objectId = '7B683C8E19BD492198F6A262D14EF43F';
var body = {subject: 'My subscription', type: 'document'};


scope.api.http.post('/service/dms/subscription/' + objectId, body, '/rest-ws').then(
	function(result){
		scope.api.util.notifier.info('Created subscription for ' + objectId, 'Success');
	},
	function(error){
		scope.api.util.notifier.error('Failed to create subscription for ' + objectId, 'Error');
	}
);

// For more information, see the REST function descriptions.

scope.api.dms

This section describes the read access to object information.

scope.api.dms.getObject()

Loads a DMS object from the backend

ParameterTypeDescription
idstringThe id of the DMS-Object to be fetched.
typestringoptional: The object type of the selected DMS-Object. Will improve performance if set.
versionstringoptional: retrieve a specific version of the dms object.


Code Block
languagejs
linenumberstrue
// example: get object of a given ID
var objectId = '7B683C8E19BD492198F6A262D14EF43F';
scope.api.dms.getObject(objectId).then(
	function(result) {
		scope.api.util.notifier.info(result.title, 'Title of Object');
		// index-values can be found in result.data
		// example: result.data.companyname
	},
	function(error) {
		scope.api.util.notifier.error(''+error, 'An error occured');
	}
);


scope.api.dms.getResult()

Fetch DMS objects from the server by search parameters

This functions uses the DMS-Service search 

ParameterTypeDescription
fieldsobjectthe fields to matched. example: {name: 'max', plz: '47111}
typestringthe target object type


This function returns a promise which is resolved by an array of DmsObjects matching the given parameters.

(Code sample to come.)


scope.api.dms.downloadContent()

This function starts a download of the content file of a dms object.

ParameterTypeDescription
dmsObjectDmsObjectthe dms object with the content to download
renditionstring(optional) the type of the content file ('PDF', 'TIFF', 'TEXT', 'JPEG') if you don't want to have the original file

scope.api.config

Gets information about configurations.

scope.api.config.get()

This function returns information about the location of special resources.

config entrydescription
serviceBaserelative URL to the enaio rest services
pluginsBaserelative path to the plugins project folder
pluginStatesBaserelative path to the plugin states project folder
themeBaserelative path to the themes folder

scope.api.agent (version 4.0)

These functions help to handle custom actions with enaio agent.

scope.api.agent.getAvailability()

This function gets the agent availability and returns a promise which is resolved with the agent availability.

PromiseDescription
agentAvailability.CONNECTEDThe user has an agent connected and the current browser session is connected.
agentAvailability.AVAILABLEThe user has an agent connected to the system, but there is no pairing between the current browser session and an agent.
agentAvailability.UNAVAILABLEThe user is not connected with any agent.


For examples, see the 
Custom Action Scripting (Client-side) documentation.

scope.api.agent.executeAction()

This function executes an action on a connected and paired client computer. For the format of the args parameter, see below.

ActionParametersDescription
scope.api.agent.action.OPEN { document: { id: <string>, title: <string>, type: <string> }, lock: <bool> }Open a document for local editing. Only a single DmsObject at a time can be opened.
The current user can lock the document by passing true.
scope.api.agent.action.MAIL[ { id: <string>, title: <string>, type: <string> }, .. ]Creates a new e-mail with documents as attachment.
scope.api.agent.action.MAIL_AS_PDF[ { id: <string>, title: <string>, type: <string> }, .. ]Creates a new e-mail with as PDF rendition documents as attachment.
scope.api.agent.action.CLIPBOARD[ { id: <string>, title: <string>, type: <string> }, .. ]Downloads the documents to the local computer and puts them into the system clipboard.
scope.api.agent.action.CLIPBOARD_AS_PDF[ { id: <string>, title: <string>, type: <string> }, .. ]Downloads the documents as PDF rendition to the local computer and puts them into the system clipboard.
scope.api.agent.action.EXTERNAL{ executable: <string>, args: [ <string, .. ] }Calls a local executable. Restricted to executables in the 'agent externals' folder next to the agent installation directory: <AGENT_INSTALLATION_DIRECTORY>\..\agent externals


Examples

Code Block
languagejs
linenumberstrue
scope.api.agent.executeAction(scope.api.agent.action.OPEN, { document: { id: myObject.id, title: myObject.title, type: myObject.type }, lock: false });

scope.api.agent.executeAction(scope.api.agent.action.MAIL, objectList.map(o => { return { id: o.id, title: o.title, type: o.type } }));

scope.api.agent.executeAction(scope.api.agent.action.EXTERNAL, { executable: 'jump2sap.exe', args: [ '/ID', myObject.id ] });
For additional examples, see the Custom Action Scripting (Client-side) documentation.