Scolvo Virtual Machine built-in functions

This API page describes built-in functions defined on Scolvo Virtual Machine (later referred as SVM) level. As the SVM component integrates an Interpreter, all Interpreter built-in functions are still available.

When the client starts, it starts an SVM and loads the client script received from Backend to the Interpreter.

SVM Built-in function groups

  • Authentication related functions

  • Device information functions

  • External communication functions

  • Document handling functions

  • Native action functions

Authentication functions

This function group implements functionality for managing users security-related representation. Defined functions are:

getCurrentUser() function

This function delivers the user’s token payload in form of Map.

Function syntax

Map<String, Object> getCurrentUser()

Where the returned Map contains following keys (and more according to the payload): - name - the name of the user, - preferred_username - the username of the authenticated user, - email - the email address of the authenticated user, - realm_access - a Map cotaining roles key in which the user roles are listed.

Example getCurrentUser() function call
 1function sessionUserIsAdmin() {
 2  return getCurrentUser().realm_access.roles.contains("administrator") || getCurrentUser().realm_access.roles.contains("superAdministrator");
 3}
 4
 5function sessionUserIsEditor() {
 6  var roles = getCurrentUser().realm_access.roles;
 7  return roles.contains("editor");
 8}
 9
10function sessionUserId() {
11  return getCurrentUser().userId;
12}
13
14function sessionUserName() {
15  return getCurrentUser().name;
16}
17
18function sessionUserUsername() {
19  return getCurrentUser().preferred_username;
20}

Document repository functions

This function group implements functions to access the configured Cloud repository (requires configured Cloud repository to be able to use).

  • documentGetUrl - get public URL of a document in the CloudRepository,

  • documentPut - updaload a file to the configured Cloud repository.

documentGetUrl() SVM function

This built-in function gets a public URL (containing autentication) to the given resource path in the configured Cloud repository. (It requires a configured Cloud repository.)

Function syntax

String documentGetUrl(String documentKey)

Where the documentKey is the path of an existing document in the Cloud repository. It return the URL accessing the document in Http GET reuest.

Example documentGetUrl() function call
 1function getFileContent(cloudRelativePath) {
 2
 3  var downloadUrl = documentGetUrl(cloudRelativePath);
 4  var result = httpCall({ "requestMethod": "GET", "url": downloadUrl });
 5  if (result.status = 200) {
 6      return result.data
 7  }
 8
 9  return null;
10}

documentPut() SVM function

This built-in function uploads asynchronusly a file to the configured Cloud repository. (It requires a configured Cloud repository.)

Function syntax

void documentPut(String uploadId, String targetPath, String sourcePath, String successTrigger, String errorTrigger)

Where the uploadId is a unique String to identify the upload in trigger functions, the targetPath is the desired path in the Cloud repository, the sourcePath is the path of an existing document in the the local filesystem, successTrigger is a function name to be called after successful upload and the errorTrigger is a function name to be called when an error happens.

Example documentPut() function call
 1function uploadFileToCloud(filePath, cloudPath) {
 2  var uploadId = uuid();
 3  documentPut(uploadId, cloudPath, filePath, "UploadFileToCloudSuccess", "UploadFileToCloudError");
 4  return uploadId;
 5}
 6
 7function onUploadFileToCloudSuccess(originId) {
 8  debug("The id Upload is: '" + $IN.data.id);
 9  // Do the  required logic
10}
11
12
13function onUploadFileToCloudError(originId) {
14  error("Upload file to cloud has been failed with id: '" + $IN.data.id + "' The error is: " + $IN.data.errorCode + " - " + $IN.data.errorMessage);
15  // Do the error-case logic
16}

SVM External communication functions

This function group implements functions for external comunication.

httpCall() SVM function

This built-in function is a generic purpose function to send any kind of Http request, where many parameter can be specified.

Function syntax

HttpResponse httpCall(Map<String, Object> requestDescriptor)

Where the requestDescriptor is the Map<String, Object> representation of the HttpRequest object, the result is a HttpResponse object (definitions of these objects are below).

HttpRequest object

  • String requestMethod - default value is GET, other possible values: HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE,

  • String url, contains the targeted URL,

  • Map<String, String> headerParams - all given parameters are put to request headers,

  • boolean baseAuth - defines if base authentication is used (an alternate solution to but the ready made Authorization header value to headerParams),

  • String baseAuthUser - in case of baseAuth is true, then the auth user is used when generating appropriate Base64 String,

  • String baseAuthPw - in case of baseAuth is true, then the auth password is used when generating appropriate Base64 String,

  • String jsonData - if given, then this content is sent as json body of the request,

  • Map<String, Object> formData - if jsonData is not given or null, then this content is sent as form data.

HttpResponse object

  • statusCode int, containing the HTTP status code as integer, can be accessed by getStatusCode() call,

  • data Object, containing the response data, can be accessed using getData() call,

Example SVM httpCall() function call
 1function sendPostRequestWithAuthorizationHeader(originId) {
 2  debug("Sending post request ... ");
 3
 4  var jsonObject = {"key": "value"};
 5  var request = {
 6    "requestMethod": "POST",
 7    "url": "https://mydream.net",
 8    "baseAuth": true,
 9    "baseAuthUser": "MyUser",
10    "baseAuthPw": "MyPassword",
11    "headerParams": {
12      "Content-Type": "application/json"
13    },
14    "jsonData": jsonObject.toString()
15  };
16  var response = httpCall(request);
17  debug("The result code is: " + response.getStatusCode());
18  debug("The result data is: " + response.getData());
19
20  return response;
21}

SVM Native action functions

This function group implements native action calls.

startCall() SVM function

This built-in function supports starting a call on the device (if there is such feature is implementedn on the given device type).

Function syntax

void startCall(String phoneNumber)

Where the phoneNumber represents the phone number to be called. The implementation details may vary on client type.

Example startCall() function call
1function callContact(userDao) {
2  debug("Calling user '" + userDao.name + "' using number " + userDao.phoneNumber);
3  startCall(userDao.phoneNumber);
4}

sendEmail() SVM function

This built-in function supports email sending by the device.

Function syntax

void sendEmail(Map<String, Object> emailParams)

Where the emailParams map represents the email sendig parameters as:

  • addresses - List<String> parameter, shows where the email is sent,

  • ccAddresses - List<String> parameter, represents the cc addresses,

  • subject - String, the subject of the email,

  • body - String, the body of the email to be sent,

  • attachments - List<String> parameter, represents file pathes to be attached.

Example sendEmail() function call
 1function sendEmailToContact(userDao, subject, content, filePath) {
 2  debug("Sending email to user '" + userDao.email + "' and to user's manager '" + userDao.manager.email + "' ...");
 3  sendEmail({
 4    "addresses": [userDao.email],
 5    "ccAddresses": [userDao.manager.email],
 6    "subject": subject,
 7    "body": content,
 8    "attachments": [filePath]
 9  });
10  debug("Email has been sent.");
11}

simpleShare() SVM function

This built-in function supports sharing different type of media.

Function syntax

void simpleShare(String mediaType, Object media)

Where the mediaType can be one of valid types (TEXT, IMAGE,AUDIO, VIDEO, FILE, OTHER) and the media represents the content to be shared. The implementation may vary based on the client type.

Example simpleShare() function call
1function shareMessage(message) {
2  debug("Sharing message ...");
3  simpleShare("TEXT", message);
4}

displayAttachments() SVM function

This built-in function shows the Attachments page with the given parameters.

Function syntax

void displayAttachments(String componentName, List<Map<String, String>> attachments, String headerText)

Where the componentName is the name of the calling component and used in event names, the attachments is a List of file representation as name-path pairs, and the headerText is the text to be displayed as header. When the user adds a new attachment of deletes an existing one the appropriate event is triggered:

  • on<componentName>AddAttachment(originId) for adding a new attachment, where the data of the attachment is available in the context ($IN.data),

  • or on<componentName>DeleteAttachment(originId) for deleting an attachment, where the attachment data is available in the context ($IN.data).

Example displayAttachments() function call with defined AddAttachment and DeleteAttachment events
 1function showUserAttachments(files) {
 2  debug("Show attachment page ...");
 3  displayAttachments("UserAttachments", files, "User Attachments");
 4}
 5
 6function onUserAttachmentsAddAttachment(originId) {
 7  var attachmentDao = $IN.data;
 8  // Do the required logic
 9}
10
11function onCallLogDetailDeleteAttachment(originId) {
12  var idToBeDeleted = $IN.data.id;
13  // Do the desired logic
14}

displayQRCodeReader() SVM function

This built-in function displays the QR Code reader.

Function syntax

void displayQRCodeReader(String componentName)

Where the componentName is the name of the calling component and basis of the callback event name:

  • on<componentName>ReadSuccess(originId) event is invoked after successful QR code reading, where the read code is available in the context with key $IN.data.code.

Example displayQRCodeReader() function call
1function readTheCode(originId) {
2  displayQRCodeReader("ItemCodeReader");
3}
4
5function onItemCodeReaderReadSuccess(originId) {
6  var qrCode = $IN.data.code;
7  // Implement desired logic here
8}

hideSoftKeyboard() SVM function

This built-in function the hide the soft-keyboard.

Function syntax

void hideSoftKeyboard()

Example hideSoftKeyboard() function call
1function checkName(name) {
2  if (name != null && !name.isEmpty()) {
3    hideSoftKeyboard();
4  }
5  // Other logic to be executed ...
6}