Backend built-in functions

This API page describes built-in functions defined on Backend level. As the Backend component integrates an Interpreter, all Interpreter built-in functions are still available.

When the Backend component starts, it builds-up the Backend Scolvo script using the backend.scolvo as entry point. The built-up script is loaded to the Interpreter and holds the Backend business logic.

Backend built-in function groups

• Scheduling functions

• Authentication related functions

• Internal communication functions

• External communication functions

• Document handling functions

• Reporting functions

• Misc functions

Scheduling functions

This function group implements functionality for scripting-space automation, it supports addJob, addImmediateJob and deleteJob functions.

addJob() function

This function defines a repeated job for the Backend.

Function syntax

void addJob(cronExpression, jobName, groupName, triggerExpression)

Where the given cronExpression is a mandatory String describing the repetition, the jobName mandatory String defines the name of the repeated job, the groupName mandatory String defines the job group and the triggerExpression defines the repeating expression (usually event name without ‘on’, e.g.: ‘CalculateUserFees’).

The CRON expression is validated by Quartz scheduler during appropriate object creation, next invoke time is logged as debug information for validation purposes. Job is created with the unique name of groupName - jobName pair, which can be used when deleting the job.

Example addJob() function call

function initScheduledJobs() {
  addJob("0 0 8 ? * * *", "morningDataImportJob", "DataImport", "MorningDataImport");
  addJob("0 0 12 ? * * *", "noonDataImportJob", "DataImport", "NoonDataImport");
}

initScheduledJobs();

function onMorningDataImport(originId) {
  importUsers();
  importData();
}

function onNoonDataImport(originId) {
  importData();
}

addImmediateJob() function

This function defines a start-time executed job for the Backend Scheduler.

Function syntax

void addImmediateJob(jobName, groupName, triggerExpression)

Where the given jobName mandatory String defines the name of the repeated job, the groupName mandatory String defines the job group and the triggerExpression defines the repeating expression (usually event name without ‘on’, e.g.: ‘CalculateStartTimeFees’).

Example addImmediateJob() function call

function initScheduledJobs() {
  addImmediateJob("startTimeFeeCalculationJob", "Statistics", "CalculateFeesAtStart");
}

initScheduledJobs();

function onCalculateFeesAtStart(originId) {
  calculateFees();
}

deleteJob() function

This function deletes a job defined with jobGroup and jobName. It returns if the action is successful.

Function syntax

boolean deleteJob(jobName, groupName)

Where the given jobName mandatory String and the groupName mandatory String defines the job.

Example deleteJob() function call

function cleanUpUnnecessaryJobs() {
  if (deleteJob("morningDataImportJob", "DataImport")) {
    info("Job has been deleted successfully.");
  } else {
    info("Scheduled job DataImport - morningDataImportJob delete has been failed");
  }
}

Authentication functions

This function group implements functionality for managing users security-related representation in the Authentication Service (actually a Keycloak Server). Defined functions are:

• createKeycloakUser

• updateKeycloakUser

• deleteKeycloakUser

• getAuthToken

These function keep in-sync the Backend’s User database and the Keycloak data.

createKeycloakUser() function

This function creates a user with given attributes, it returns the Keycloak id of the created user.

Function syntax

String createKeycloakUser(userConfig)

Where the given userConfig contains the user attributes (see the example for details). Usual usage is when a new User created on administration UI or by self registration.

createKeycloakUser() function call in self registration events

function onSelfRegistering(originId) {
  var userDao = $IN.data.map;

  var userConfig = {
      "id": userDao.id,
      "enabled": true,
      "name": userDao.name,
      "email": userDao.email,
      "username": userDao.username,
      "password": userDao.password,
      "realmRoles": ["authenticated", "otherRelevantRole"]
  };

  var keycloakUserId = createKeycloakUser(userConfig);
  debug("Created keycloak user is: " + keycloakUserId);
  userDao.put("keycloakId", keycloakUserId);
  userDao.put("role", "otherRelevantRole");
  return userDao;
}

function onSelfRegistered(originId) {
}

createKeycloakUser() function call in TypeDefinitionLifeCycle.scolvo where the User creation events are defined

function onUserInserting(originId) {
  var userDao = $IN.data.map;

  var userConfig = {
    "id": userDao.id,
    "enabled": true,
    "name": userDao.name,
    "email": userDao.email,
    "password": userDao.password,
    "username": userDao.username,
    "realmRoles": ["authenticated", userDao.role]
  };
  return createKeycloakUser(userConfig);
}

function onUserInserted(originId) {
  var userDaoFromRequest = $IN.data.map;
  info("Updating created user with KeycloakId: " + $IN.data.preScriptResult + " ...");
  var userDao = {
    "id": userDaoFromRequest.id,
    "keycloakId": $IN.data.preScriptResult,
    "changeType": "UPDATE"
  };
  updateTypeDefinition("user", userDaoFromRequest.id, userDao);
  info("User has been updated with KeycloakId.");
}

updateKeycloakUser() function

This function updates a user definition with given attributes.

Function syntax

void updateKeycloakUser(userConfig)

Where the given userConfig contains the user attributes (see the example for details). Usual usage is when a User update is done on administration UI or in the profile.

updateKeycloakUser() function call in TypeDefinitionLifeCycle.scolvo where the User modification events are defined

function onUserUpdating(originId) {
}

function onUserUpdated(originId) {
  var userDao = $IN.data.map;
  var userConfig = {
    "id": userDao.id
  };
  if (userDao.containsKey("name")) {
    userConfig.put("name", userDao.name);
  }
  if (userDao.containsKey("email")) {
    userConfig.put("email", userDao.email);
  }
  if (userDao.containsKey("username")) {
    userConfig.put("username", userDao.username);
  }
  if (userDao.containsKey("role")) {
    userConfig.put("realmRoles", ["authenticated", userDao.role]);
  }
  if (userDao.containsKey("password")) {
    userConfig.put("password", userDao.password);
  }
  if (userDao.containsKey("status")) {
    userConfig.put("enabled", userDao.get("status") == "active");
  }
  updateKeycloakUser(userConfig);
}

deleteKeycloakUser() function

This function deletes a user definition identified by email address.

Function syntax

boolean deleteKeycloakUser(emailAddress)

Where the given emailAddress is a String identifying a user. The result value reflects if the deletion is successful or not. Usual usage is when a User is deleted on the administration UI.

deleteKeycloakUser() function call in TypeDefinitionLifeCycle.scolvo where the User deletion events are defined

function onUserDeleting(originId) {
  var userInfo = $IN.data.map;
  var userDao = getUserById(userInfo.id);
  debug("Deleting user: " + userDao.email);
  if (deleteKeycloakUser(userDao.email)) {
    info("The user with email '" + userDao.email + "' has been successfully deleted.");
  } else {
    error("User delete in Keycloak has been failed.");
  }
}

function onUserDeleted(originId) {
}

getAuthToken() function

This function gets a valid auth token for given email. Backend events usually contain the client authentication token (accessible form script space). For the cases where the authentication token is not yet defined, or it is not available, but the user’s email and password are available, this function call gets a valid authentication token for further internal requests. For example at self-registration time there is no authentication token (as before the successful Keycloak registration it is not possible to get one), but we know the username and password - a valid token can be received and used for other internal service calls.

Function syntax

String getAuthToken(emailAddress, password)

Where the given emailAddress and the password are Strings and the result access token is given in form of String.

getAuthToken() function call in self-registration

function onSelfRegistering(originId) {
  var userDao = $IN.data.map;

  var userConfig = {
      "id": userDao.id,
      "enabled": true,
      "name": userDao.name,
      "email": userDao.email,
      "username": userDao.username,
      "password": userDao.password,
      "realmRoles": ["authenticated", "someRoleName"]
  };

  var keycloakId = createKeycloakUser(userConfig);
  debug("Created keycloak user is: " + keycloakId);
  var userToken = getAuthToken(userDao.email, userDao.password);

  // Do your logic, use the userToken as needed for internal calls
  // e.g. store it to be able to use in further requests
  putTheTokenToTheStore(userDao.id, userToken);

  userDao.put("keycloakId", keycloakId);
  userDao.put("role", roleEditor);

  return userDao;
}

function onSelfRegistered(originId) {
  var userDaoFromRequest = $IN.data.map;
  var token = getTheTokenFromTheStore(userDaoFromRequest.id);
  if (token != null) {
      var response = doTheSpecialInternalRequest(token);
      if (response.getStatusCode() == 200) {
          var someResult = response.getData();
          sendWelcomeEmail(userDaoFromRequest.id, someResult);
      } else {
          error("Error when requesting some result: " + response.getData());
      }
  } else {
      error("No token found for the given user.");
  }
}

Internal Communication functions

This function group implements functionality for internal communication between clients. It supports broadcastDatagram function sending internal message to all or to a dedicated client and function createDataSyncElement helping in the creation of data synchronization message elements.

broadcastDatagram() function

It has the dataChangeDg - a Map<String, Object> (mandatory parameter) - and the clientId parameter - an optional String parameter.

Function syntax

void broadcastDatagram(dataChangeDg, clientId)

Where the valid keys of the dataChangeDg Map<String, Object> parameter are:

• originId - String (mandatory key), represents the origin Id,

• typeDefinition - String (mandatory key), defined the name of the type definition,

• typeDefinitionVersion - long (mandatory key), represents the version number of the type definition,

• changeSet - List<Map<String, Object>> parameter (mandatory key, the list must be non-empty), it holds the row definitions.

And the clientId can be the clientId of an existing client or null to send the message to all clients).

Example broadcastDatagram() function call in client-backend-client communication case

function onDoSometingRequest(originId) {
  var requestData = $IN.data;
  var clientId = $IN.data.clientId;
  debug("Received request with parameters: " + requestData.toString());

  var response = calculateSomeResoinse();
  // Send the Backend-side calculated response to the requesting client:
  publishBroadcastToClient("doSometingResponse",  [{"someKeyForTheresponse": response}], clientId);
}

function publishBroadcastToAllClients(typeDefinitionName, changeSetList) {
  publishBroadcastToClient(typeDefinitionName, changeSetList, null);
}

function publishBroadcastToClient(typeDefinitionName, changeSetList, clientId) {
  if(!changeSetList.isEmpty()) {
    var broadcastData = {
      "originId": uuid(),
      "typeDefinitionVersion": nowInMillis(),
      "typeDefinition": typeDefinitionName,
      "changeSet": changeSetList
    };
    broadcastDatagram(broadcastData, clientId);
  }
}

createDataSyncElement() function

It has the typeDefinitionName and the data parameter describing rows.

Function syntax

DataSyncRpElement createDataSyncElement(typeDefinitionName, data)

Where the typeDefinitionName is a mandatory String, the data is a mandatory List of Map<String, Object> objects, and the function returns the appropriate DataSyncRpElement.

Example createDataSyncElement() function call in DataSync.scolvo Backend script’s onDataSync event

function onDataSync(userId, deviceType) {
  debug("onDataSync " + userId + " deviceType: " + deviceType);
  // For a superUser only the MHUB is the available client type
  if (userId == "superUser") {
    return dataSyncByAdministrator(deviceType);
  }

  // Check user details to make decision about the sync content:
  var user = getUserById(userId);
  debug("Device type is: " + deviceType);
  if (user.role == "administrator") {
    return dataSyncForAdministrator(deviceType);
  } else if (user.role == "someCustomerSpecificRole") {
    return dataSyncForSomeCustomerSpecificRole(user);
  }

  warn("No dedicated DataSync case, returning empty data for user " + user.role);
  return [];
}

function dataSyncForAdministrator(deviceType) {
  debug("Creating data sync content for administrator");
  // For an administrator role only the MHUB is the available client type
  if (deviceType == "MHUB") {
    return [
      createDataSyncElement("user", getUsers()),
    ];
  }
  return [];
}

function dataSyncForSomeCustomerSpecificRole(userDao) {
  debug("Creating data sync content for someCustomerSpecificRole");
  return [
    createDataSyncElement("example_table", getExampleRowsForUser(userDao.id))
  ];
}

External Communication functions

This function group implements functionality for external communication. It supports:

• httpDownloadUrl function downloading content from the given URL and saving the content to a file,

• httpPost function sending POST request with json body or containing file requests,

• httpCall function with generic type of request definition and security configuration possibilities,

• sendToDevices function sending Firebase message,

• sendEmail function sending email message.

httpDownloadUrl() function

It downloads content from the given url to a file defined by fileName parameter (the fileName is taken as pattern).

Function syntax

String httpDownloadUrl(url, fileName)

Where the url is given a mandatory String representing the URL of the desired location, the fileName is a mandatory String, defining the result file name template. Using this template a unique name is generated and returned as result.

Example httpDownloadUrl() function call

function getTheMoon(originId) {
  debug("Downloading moon ... ");
  var moonUrl = "https://spaceplace.nasa.gov/review/all-about-the-moon/the-moon-near-side.en.jpg";
  var resultFile = httpDownloadUrl(moonUrl, "MyMoonPhoto.jpg");

  debug("My Moon is under: " + resultFile);
  return resultFile;
}

httpPost() function

This built-in function sends a POST Http request to the given url.

Function syntax

String httpPost(String url, Map<String, String> headers, String jsonContent, Map<String, String> bodyFileDescriptor)

Where the url is given as String (mandatory String parameter), the headers parameters are merged to the request’s header, and the content is sent as jsonContent String or as Map<String, String> bodyFileDescriptor (one of these latter has to be defined, if both are given, then json string is sent). The result is the resonse body, it is returned as String.

Example httpPost() function call

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

  var jsonObject = {"key": "value"};
  var url = "https://eov8qe6o4c0adbw.m.pipedream.net";
  var headers = {"Authorization": "Basic XYZ", "x": "y"};
  var result = httpPost(url, headers, jsonObject.toString(), null);
  debug("The result is: " + result);

  return result;
}

httpCall() 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 attributes

• 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 attributes

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

sendToDevices() function

This built-in function sends a Firebase request with given parameters to the defined Firebase clients (defined by Firebase tokens). It requires the Firebase related configuration to be set.

Function syntax

void sendToDevices(String title, String body, Map<String, String> data, List<String> registrationTokens)

Where the title, body and data are defining the message, the registrationTokens parameter defines target user audience. In case of any communication error a FirebaseErrorResultException is thrown describing the error cases.

Hint: The List<String> getErrorDetails(), or String getMessage() functions can be used to get error details from FirebaseErrorResultException instance.

Example sendToDevices() function call

function sendMessageToUsers(originId, tokens) {
  debug("Sending firebase message ... ");

  try {
    var data = {
      "key": "someValue"
    };
    sendToDevices("My Important Message", "Dear User, Please do these important staps ...", data, tokens);

    debug("Firebase message has been sent successfully.");
  } catch (FirebaseErrorResultException e) {
    error("Error when sending message to firebase users: " + e.getMessage());
  }
}

sendEmail() function

This built-in function sends an email message with the given parameters. It requies the email sending related configuration to be set.

Function syntax

boolean sendEmail(String from, String toAddressList, String ccAddressList, String subject, String content, List<String> attachments)

Where the from defines the sender email address in String, the toAddressList and ccAddressList are addresses in form of String (separated by coma for multi-address case), the subject and content are describing the message, and the attachments defines the pathes for the attached files (if there is any). It returns true is the sending is successful.

Example sendEmail() function call

function sendMessageToUsers(originId, addresses) {
  debug("Sending email message ... ");
  // example addreses content: "address1@mydomain.com, address2@mydomain.com"
  var attachments = ["/app/documents/stepsDescription.pdf"];
  var result = sendEmail(getEnv("EMAIL_USERNAME"), addresses, null, "Important Information for MyDomain Users", "Message content ...", attachments);
  if (result) {
    debug("The message has been sent successfully.");
  } else {
    debug("The email message hasn't been sent.");
  }

}

Document handling functions

This function group implements functionality for Cloud handling, Local file handling and import/export related functions. It supports:

Cloud functions

• documentGetUrl function generating public URL for a content in a Cloud repository (requires appropriate Cloud repository configuration),

• documentPut function uploading local content to the Cloud repository (requires appropriate Cloud repository configuration),

• documentDownload function downloading content from the Cloud repository (requires appropriate Cloud repository configuration),

Filesystem functions

• createDirectory function creating a directory in local filesystem,

• listDirectory function listing the content of a directory in the local filesystem,

• fileDelete function deleting an entry (file or directory) from local fileystem,

• fileCopy function copying an entry in the local filesystem,

• fileMove function moving an entry in the local filesystem,

Export/import functions

• writeFile function writing content to a file,

• fileToString function reading the content of a file,

• writeCsvFile function writing data to CSV format,

• readCsvFile function reading CSV file to data,

• readExcelFile function reading Excel file to data.

documentGetUrl() 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 uploadCsvFileToCloud(fileName, cloudRelativePath, csvHeaders, content) {
  var filePath = writeCsvFile(fileName, csvHeaders, content, getCsvFormat());
  debug("CsvFile is created on path: " + filePath);

  documentPut(filePath, cloudRelativePath);
  var downloadUrl = documentGetUrl(cloudRelativePath);
  debug("CsvFile public URL is: " + downloadUrl);

  return downloadUrl;
}

documentPut() function

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

Function syntax

void documentPut(String sourcePath, String targetPath)

Where the sourcePath is the path of an existing document in the local filesystem and the targetPath is a path to be created in the Cloud repository.

Example documentPut() function call

function uploadCsvFileToCloud(fileNamePattern, cloudRelativePath, csvHeaders, content) {
  var filePath = writeCsvFile(fileNamePattern, csvHeaders, content, getCsvFormat());
  debug("CsvFile is created on path: " + filePath);

  documentPut(filePath, cloudRelativePath);
  var downloadUrl = documentGetUrl(cloudRelativePath);
  debug("CsvFile public URL is: " + downloadUrl);

  return downloadUrl;
}

documentDownload() function

This built-in function downloads an entry from the configured Cloud repository. (It requires a configured Cloud repository.)

Function syntax

String documentDownload(String sourcePath, String targetPathPattern)

Where the sourcePath is the path of an existing document in the CloudRepository and the targetPathPattern is a path pattern int the local filesystem. It returns the full path (not the same as given in targetPathPattern parameter) to the downloaded file.

Example documentDownload() function call

function downloadCsvFileFromCloud(cloudRelativePath, fileNamePattern) {
  var filePath = documentDownload(cloudRelativePath, fileNamePattern);
  debug("CsvFile is created on path: " + filePath);

  return filePath;
}

createDirectory() function

This built-in function creates a directory in the local filesystem. The actual implementation can create only the last directory, the containing path must exist.

Function syntax

boolean createDirectory(String directoryPath)

Where the directoryPath is the path of the directory to be created. It returns true in only case when the directory is created by this call.

Example createDirectory() function call

function createSubDirectory(containingDirectory, subDirectory) {

  var targetPath = directory + "/" + subDirectory;
  if (createDirectory(targetPath)) {
    return targetPath;
  }

  return null;
}

listDirectory() function

This built-in function lists an existing directory in the local filesystem.

Function syntax

Map<String, Map<String, Object>> listDirectory(String directoryPath)

Where the directoryPath is the path of the directory to be listed. It returns with the content of the directory with a descriptor containg name, size, type, absolute path and last modification time (see the example below).

Example listDirectory() function call

function listDirectoryContent(directoryPath) {

  var content = listDirectory(directoryPath);
  debug("The result is: " + content);
  content.keySet().each(function(fileName){
      debug("----------------------------------");
      debug("   Actual entry is: " + fileName);
      var descriptor = content.get(fileName);
      debug("      Name is:            " + descriptor.get("name"));
      debug("      Type is:            " + descriptor.get("fileType"));
      debug("      Size (in Bytes) is: " + descriptor.get("size"));
      debug("      Absolute path is:   " + descriptor.get("absolutePath"));
      debug("      Last modified is:   " + dateToString(descriptor.get("lastModified"), "yyyy.MM.dd. HH:mm"));
  });

  return content;
}

fileDelete() function

This built-in function deletes the given path and returns the status of the operation (true if deleted, false oterwise).

Function syntax

boolean fileDelete(String path)

Where the path is the path of the local filestem entry to be deleted. If the given path is a non-empty directory, then it is deleted with its child entries.

Example fileDelete() function call

function deleteDirectoryContent(directoryPath) {
  debug("Deleting directory with its content: " + directoryPath);
  return fileDelete(directoryPath);
}

fileCopy() function

This built-in function creates a copy of the source file to the given path.

Function syntax

void fileCopy(String sorcePath, String targetPath)

Where the sourcePath is an existing path in the filesystem, and the targetPath is the path where the file copy has to be created. It is possible to copy a simple file entry or a complete directory.

Example fileCopy() function call

function backupDirectory(directoryPath, backupDirectoryPath) {
  debug("Creating backup of directory: " + directoryPath);

  var content = listDirectory(directoryPath);
  content.keySet().each(function(fileName){
      var descriptor = content.get(fileName);
      var sourcePath = descriptor.get("absolutePath");
      var targetPath = backupDirectoryPath + "/" + descriptor.get("name");
      fileCopy(sourcePath, targetPath);
  });
}

fileMove() function

This built-in function moves an existing file to a new path.

Function syntax

void fileMove(String sorcePath, String targetPath)

Where the sourcePath is an existing path in the filesystem, and the targetPath is the new path of the entry.

Example fileMove() function call

function downloadFileFromCloud(cloudRelativePath, targetDirectory, fileName) {
  var filePath = documentDownload(cloudRelativePath, fileName);
  debug("File is created on path: " + filePath);

  var targetPath = targetDirectory + "/" + fileName;
  fileMove(filePath, targetPath)
  debug("File is moved to path: " + targetPath);

  return targetPath;
}

writeFile() function

This built-in function creates a file with the given content.

Function syntax

String writeFile(String fileNamePattern, String content)

Where the fileNamePattern is the file name pattern of the created file, and the content is a String to be written to the file. It retuns the fupp path of the created file.

Example writeFile() function call

function createMonthlyReport(type, month, content) {
  var fileNamePattern = "Report_" + type + "_" + month + ".txt";

  var resultPath = writeFile(fileNamePattern, content);
  debug("Report File is created at: " + resultPath);

  return resultPath;
}

fileToString() function

This built-in function reads a file content and returns it as String.

Function syntax

String fileToString(String filePath)

Where the filePath is the prat of the file to be read.

Example fileToString() function call

function readInputFile(fileName) {
  var importFilePath = "/import/" + fileName;

  var content = fileToString(importFilePath);
  if(content != null) {
    debug("Read content size: " + content.size());
  } else {
    debug("No content returned from file " + importFilePath);
  }

  return content;
}

writeCsvFile() function

This function writes the given content using header columns and formatting parameters to a CSV file. The path of the created file is returned.

Function syntax

String writeCsvFile(String namePattern, List<String> headerColumns, List<List<String>> data, Map<String, Object> csvFormattingParameters)

Where:

• namePattern is a String mandatory parameter, it is used as a basis for filename construction,

• headerColumns is a List<String> mandatory parameter, a not empty list of the headers,

• data is a List<List<String>> list of content lines (mandatory parameter), a non-empty list of lines,

• csvFormattingParameters is a Map<String, Object> (mandatory parameter), see below description for keys and values.

• it returns the path of the created file,

• it throws FunctionInvokeException in case of errors.

Details of valid CSV formatting parameters:

• The parameters given in Map<String, Object> format,

• format - String, name of the CSV format, if not given, then “Default” is used, (valid values are: Default, Excel, InformixUnload, InformixUnloadCsv, MongoDBCsv, MongoDBTsv, MySQL, Oracle, PostgreSQLCsv, PostgreSQLText, RFC4180, TDF), it is used as a basis of other parameters,

• delimiter - String, the first character taken as delimiter character,

• quote - String, the first character taken as quote character,

• nullString - String, it is set as the null-string value for the formatter,

• skipHeaderRecord - boolean, its value set to skipHeaderRecord of the formatter,

• recordSeparator - String, its value set as record separator,

• charset - String, its value is used to create a charset, if not given, then UTF-8 is used.

Example writeCsvFile() function call

function getCsvFormat() {
  var format = {
    "delimiter": ";",
    "quote": null,
    "nullString": "",
    "skipHeaderRecord": false,
    "recordSeparator": "\r\n",
    "charset": "UTF-8",
  };

  return format;
}

function exportDataToCsv() {

  var csvHeaders = ["StoreDevice_Code", "StoreDevice_DeviceTypeName"];
  var content = [];
  var storeDevices = getStoreDevicesByStatus("active");
  storeDevices.each(function(storeDevice) {
    content.add([storeDevice.deviceCode, storeDevice.deviceTypeName]);
  });

  var reportName = "Data_" + dateToString(nowInMillis(), "yyyyMMdd_HHmm") + ".csv";
  var filePath = writeCsvFile(reportName, csvHeaders, content, getCsvFormat());
  debug("CsvFile is created on path: " + filePath);

  var targetPath = "/export/" + fileName;
  fileMove(filePath, targetPath);

  return targetPath;
}

readCsvFile() function

This function reads the content of the given CSV file to structured List<Map<String, String>> format.

Function syntax

List<Map<String, String>> readCsvFile(String pathToFile, List<String> headerColumns, Map<String, Object> csvFormattingParameters)

Where:

• pathToFile - is a String (mandatory parameter),

• headerColumns - List<String> (mandatory parameter), a not empty list of the headers,

• csvFormatParameters - Map<String, Object> (mandatory parameter), see below the description of keys and values,

• it returns the content in form of List<Map<String, String>> according to the specified format,

• it throws FunctionInvokeException in case of errors.

Example readCsvFile() function call

function getReadCsvFormat() {
  var format = {
    "delimiter": ";",
    "quote": null,
    "nullString": "",
    "skipHeaderRecord": true,
    "recordSeparator": "\r\n",
    "charset": "Cp1250",
  };

  return format;
}

function importDataFromCsv() {
  debug("Importing data ....");
  var filePath = documentDownload("/import/data.csv", uuid());
  var importHeaders = ["Name", "ID", "Size", "Activity_ID", "Exporter"];

  var parsedData = readCsvFile(filePath, importHeaders, getReadCsvFormat());
  fileDelete(filePath);

  return parsedData;
}

readExcelFile() function

This function reads the content of the given Excel file (.xls or .xlsx file) to structured format.

Function syntax

Map<String, List<List<Object>>> readExcelFile(String filePath, int numOfColumns)

Where:

• filePath - mandatory parameter String,

• numOfColumns - BigInteger mandatory parameter, non-negative number, if 0 is given, then every sheet is checked for its max column,

• it returns the sheets defined by lines and cells in form of Map<String, List<List<Object>>>,

• it throws FunctionValidationException for invalid parameters, and FunctionInvokeException for processing errors.

Example readExcelFile() function call

function readImportFromFile(filePath, sheetName) {
  var result = readExcelFile(filePath, 3);

  var sheet = result.get(sheetName);
  var fullContent = [];
  sheet.each(function(line) {
    var content = "[";
    line.each(function(cell) {
      content = content + "'" + cell + "', ";
    });
    content = content + "]";
    fullContent.add(content);
  });
  return fullContent;
}

Reporting repository functions

This function group implements functionality for Reporting repository handling. It supports:

• downloadReport function to download specific report from Reporting repository,

downloadReport() function

This function supports report file downloading from configured Reporting repository. The hendling of the download is asynchronus, in case of success a successTrigger is executed, in case of error the given errorTrigger is called.

Function syntax

void downloadReport(String downloadId, String reportUrl, String reportFileName, String successTrigger, String errorTrigger, Map<String, Object> additionalParameters)

Where:

• downloadId is a String, mandatory parameter,

• reportUrl is a String, mandatory parameter,

• reportFileName is a String, filename base string used when storing locally the downloaded file,

• successTrigger is a String, mandatory parameter, the name of the function to be invoked in case of success,

• errorTrigger is a String, optional parameter, the name of the function to be invoked in case of error,

• additionalParameters is a Map<String, Object>, optional parameter, parameters that have to be added to trigger parameters

Trigger parameters are in case of success (these are put to $IN.data map):

• id - the corresponding download id,

• filePath - the path of the downloaded file in local filesystem,

• additional keys and values from additionalParameters map.

Trigger parameters are in case of error (these are put to $IN.data map):

• id - the corresponding download id,

• errorCode - the code of the error in form of String,

• errorMessage - the error message,

• additional keys and values from additionalParameters map.

Example downloadReport() function call

function onMontlyTodoReportDownloadSuccess(originId) {
  debug("The id of the Report download is: '" + $IN.data.id + "' The path of the downloaded file: '" + $IN.data.filePath + "'");
  debug("The downloadedFile for Store '" + $IN.data.storeName + "' is at " + $IN.data.filePath);

  // Do the logic, e.g. send an email

  var deleteResult = fileDelete($IN.data.filePath);
  debug("Report file has been deleted with result: " + deleteResult);
}

function onMontlyTodoReportDownloadError(originId) {
  error("The MontlyTodoReport download has been failed with id: '" + $IN.data.id + "' The error is: " + $IN.data.errorCode + " - " + $IN.data.errorMessage);
}

function sendMonthlyTodoReports(dueMonth) {
  debug("Sending Monthly to-be-done tasks reports about previous month ...");
  var users = getStoreLeaderUsersWithStore();
  users.each(function(user) {
    info("Store: '" + user.storeId + "', Email: '" + user.email + "'");
    var reportUrl = "https://something/report/monthlyreport/" + user.storeId;
    var downloadId = uuid();

    var additionalParams = {
      "email": user.email,
      "storeName": user.storeName,
      "name": user.name,
      "dueMonth": dueMonth
    };
    downloadReport(downloadId, reportUrl, "UserReport_" + user.email, "MontlyTodoReportDownloadSuccess", "MontlyTodoReportDownloadError", additionalParams);
    debug("Download MontlyTodoReport request is sent for store '" + use.storeId + "' ...");
  });
}

Misc functions

This function group implements a set of utility functions. It supports:

• getEnv function returning environment variables,

• getDictionaryValue function reading backend dictionary values,

getEnv() function

This function retruns the value of the appropriate environment variable defined by the key parameter.

Function syntax

String getEnv(String key)

Example getEnv() function call

function sendMessageToUsers(originId, addresses) {
  debug("Sending email message ... ");
  // example addreses content: "address1@mydomain.com, address2@mydomain.com"
  var attachments = ["/app/documents/stepsDescription.pdf"];
  var result = sendEmail(getEnv("EMAIL_USERNAME"), addresses, null, "Important Information for MyDomain Users", "Message content ...", attachments);
  if (result) {
    debug("The message has been sent successfully.");
  } else {
    debug("The email message hasn't been sent.");
  }

}

getDictionaryValue() function

This function retruns the value of the appropriate dictionary key using the specified locale from backend dictionary files (backend_dictionary_*.properties). If the dictionary is not available, then the backend’s default language (defined by DEFAULT_LANGUAGE env variable) is used to resolve the value. If the requested key is not defined, then a null value is returned.

Function syntax

String getDictionaryValue(String key, String locale)

The function has the following parameters:

• key - String, mandatory parameter,

• locale - String mandatory parameter.

Example getDictionaryValue() function call

function resolveActivityStatusForLocale(status, locale) {
  return getDictionaryValue(status + "_name", locale);
}