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

function sessionUserIsAdmin() {
  return getCurrentUser().realm_access.roles.contains("administrator") || getCurrentUser().realm_access.roles.contains("superAdministrator");
}

function sessionUserIsEditor() {
  var roles = getCurrentUser().realm_access.roles;
  return roles.contains("editor");
}

function sessionUserId() {
  return getCurrentUser().userId;
}

function sessionUserName() {
  return getCurrentUser().name;
}

function sessionUserUsername() {
  return getCurrentUser().preferred_username;
}

Device related functions

This function group implements functionality to get information about the used client device:

getEnvType() function

This function returns the type of the client device.

Function syntax

String getEnvType()

Where the returned String is one of the following valid device types: MOBILE, TABLET, MHUB, WEBAPP, DESKTOP.

Example getEnvType() function call

function sendEmailRequestToBackend(originId) {
  var requestData = {
    "type": "SendEmailToUser",
    "userId": sessionUserId(),
    "deviceType": getEnvType()
  };
  sendDataChange("request", [requestData]);
}

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

function getFileContent(cloudRelativePath) {

  var downloadUrl = documentGetUrl(cloudRelativePath);
  var result = httpCall({ "requestMethod": "GET", "url": downloadUrl });
  if (result.status = 200) {
      return result.data
  }

  return null;
}

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

function uploadFileToCloud(filePath, cloudPath) {
  var uploadId = uuid();
  documentPut(uploadId, cloudPath, filePath, "UploadFileToCloudSuccess", "UploadFileToCloudError");
  return uploadId;
}

function onUploadFileToCloudSuccess(originId) {
  debug("The id Upload is: '" + $IN.data.id);
  // Do the  required logic
}


function onUploadFileToCloudError(originId) {
  error("Upload file to cloud has been failed with id: '" + $IN.data.id + "' The error is: " + $IN.data.errorCode + " - " + $IN.data.errorMessage);
  // Do the error-case logic
}

documentDelete() SVM function

This built-in function deletes a file given by path in the configured Cloud repository. (It requires a configured Cloud repository.)

Function syntax

void documentDelete(String pathToFile)

Where the pathToFile is the path in the Cloud repository.

Example documentDelete() function call

function onDeleteButtonClicked(originId) {
  documentDelete(mapPictureFilePath);
}

File system related functions

This function group implements functions to access local filesystem.

fileDelete() SVM function

This built-in function deletes the given file from local filesystem.

Function syntax

boolean fileDelete(String pathToFile)

Where the pathToFile is the path of the local filestem entry to be deleted. It returns if the delete is successful or not. The implementation details may vary on client type.

Example fileDelete() function call

function onUploadFileToCloudSuccess(originId) {
  debug("The id Upload is: '" + $IN.data.id);
  var filePath = $IN.data.soruceFilePath;
  fileDelete(filePath);
}

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

function sendPostRequestWithAuthorizationHeader(originId) {
  debug("Sending post request ... ");

  var jsonObject = {"key": "value"};
  var request = {
    "requestMethod": "POST",
    "url": "https://mydream.net",
    "baseAuth": true,
    "baseAuthUser": "MyUser",
    "baseAuthPw": "MyPassword",
    "headerParams": {
      "Content-Type": "application/json"
    },
    "jsonData": jsonObject.toString()
  };
  var response = httpCall(request);
  debug("The result code is: " + response.getStatusCode());
  debug("The result data is: " + response.getData());

  return response;
}

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

function callContact(userDao) {
  debug("Calling user '" + userDao.name + "' using number " + userDao.phoneNumber);
  startCall(userDao.phoneNumber);
}

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

function sendEmailToContact(userDao, subject, content, filePath) {
  debug("Sending email to user '" + userDao.email + "' and to user's manager '" + userDao.manager.email + "' ...");
  sendEmail({
    "addresses": [userDao.email],
    "ccAddresses": [userDao.manager.email],
    "subject": subject,
    "body": content,
    "attachments": [filePath]
  });
  debug("Email has been sent.");
}

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

function shareMessage(message) {
  debug("Sharing message ...");
  simpleShare("TEXT", message);
}

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

function showUserAttachments(files) {
  debug("Show attachment page ...");
  displayAttachments("UserAttachments", files, "User Attachments");
}

function onUserAttachmentsAddAttachment(originId) {
  var attachmentDao = $IN.data;
  // Do the required logic
}

function onCallLogDetailDeleteAttachment(originId) {
  var idToBeDeleted = $IN.data.id;
  // Do the desired logic
}

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

function readTheCode(originId) {
  displayQRCodeReader("ItemCodeReader");
}

function onItemCodeReaderReadSuccess(originId) {
  var qrCode = $IN.data.code;
  // Implement desired logic here
}

hideSoftKeyboard() SVM function

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

Function syntax

void hideSoftKeyboard()

Example hideSoftKeyboard() function call

function checkName(name) {
  if (name != null && !name.isEmpty()) {
    hideSoftKeyboard();
  }
  // Other logic to be executed ...
}