.. index:: built-in functions, Scolvo Virtual Machine

******************************************
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 :ref:`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


.. index:: SVM Authentication functions

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


.. index::  getCurrentUser() SVM built-in function

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.

.. code-block:: scolvoscript
  :caption: Example getCurrentUser() function call
  :linenos:

  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;
  }

..

.. index:: SVM Device related functions

Device related functions
=========================
This function group implements functionality to get information about the used client device:


.. index::  getEnvType() SVM built-in function

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.

.. code-block:: scolvoscript
  :caption: Example getEnvType() function call
  :linenos:

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

..

.. index:: SVM Document repository functions

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.


.. index::  documentGetUrl() SVM built-in function

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.

.. code-block:: scolvoscript
  :caption: Example documentGetUrl() function call
  :linenos:

  function getFileContent(cloudRelativePath) {

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

    return null;
  }

..

.. index::  documentPut() SVM built-in function

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.

.. code-block:: scolvoscript
  :caption: Example documentPut() function call
  :linenos:

  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
  }

..

.. index::  documentDelete() SVM built-in function

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.

.. code-block:: scolvoscript
  :caption: Example documentDelete() function call
  :linenos:

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

..

File system related functions
===============================
This function group implements functions to access local filesystem.

.. index::  fileDelete() SVM built-in function

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.

.. code-block:: scolvoscript
  :caption: Example fileDelete() function call
  :linenos:


  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.


.. index::  httpCall() SVM built-in function

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,

.. code-block:: scolvoscript
  :caption: Example SVM httpCall() function call
  :linenos:

  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.


.. index::  startCall() SVM built-in function

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.

.. code-block:: scolvoscript
  :caption: Example startCall() function call
  :linenos:


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

..


.. index::  sendEmail() SVM built-in function

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.

.. code-block:: scolvoscript
  :caption: Example sendEmail() function call
  :linenos:


  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.");
  }

..


.. index::  simpleShare() SVM built-in function

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.

.. code-block:: scolvoscript
  :caption: Example simpleShare() function call
  :linenos:


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

..


.. index::  displayAttachments() SVM built-in function

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).

.. code-block:: scolvoscript
  :caption: Example displayAttachments() function call with defined AddAttachment and DeleteAttachment events
  :linenos:


  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
  }

..


.. index::  displayQRCodeReader() SVM built-in function

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.


.. code-block:: scolvoscript
  :caption: Example displayQRCodeReader() function call
  :linenos:


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

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

..



.. index::  hideSoftKeyboard() SVM built-in function

hideSoftKeyboard() SVM function
------------------------------------
This built-in function the hide the soft-keyboard.

*Function syntax*

..
  
  void hideSoftKeyboard()
  


.. code-block:: scolvoscript
  :caption: Example hideSoftKeyboard() function call
  :linenos:


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

..