Backend Service Methods - imona/tutorial GitHub Wiki

On the platform, you can develop Restful Web services that are expose to other clients. In order to develop them:
1) Open the editor panel by clicking the "I'm on a Cloud" button on the bottom of the screen.
2) Open the "Services" from the left hand side and click "New" button.
3) Choose a name and description for your service, which will only be used by you, the developer.
4) Choose an Input entity type. This service will need an object of type of the Entity you specified for execution. Each service needs an Input entity type, it is not optional.
5) Choose an Output entity type. This service will need to return an object of the Entity you specified. If it does not return an object of the specified type, platform will raise an error, preventing the service from execution. It is optional, you may choose void if your service will not return anything.
6) Write the script for your service, and click "Save". Now your service can be called from other services within the UI also, and exposed as a Restful service to other clients outside the platform.

While writing a service script, you may use methods that are predefined for you by the platform. You may get assistance and auto-completion by pressing Ctrl + Space at any point while writing a script.

• addDay, addMonth, addYear: These methods are used for adding specified amount of days, months or years to a date. Date format is by default as 'dd.MM.yyyy'. For example: 21.01.2013

• daysBetween2Dates('date1', 'date2'): This method gives you how many days are between two dates as an integer value.

• daysInMonth('year', 'month'): This method returns how many days are there in a specific month of a specific year.

• findMaxDate('date1', 'date2'): Returns the date that comes after the other.

• getDay, getMonth, getYear: Returns the day, month or year of a date, as an integer.

• toDate('dd.MM.yyyy'): Converts a given date string to a date object.

• today(): Returns the current day as a date object.

• validateAGivenDate('dateString'): Validates a given date string, returns true if it represents a valid date, false otherwise.

• callService('serviceName', requestObject): This method takes a service name as its first parameter, and the input object for the specified service as its second parameter. Note that you need to pass an object of the input Entity type of the service, otherwise, the platform will raise an error.
  Example usage:
  callService('addCustomer', customerObject);

• create('entityName'): Creates a new object for the specified entity type. You can store an object in a variable, as may be familiar to you from other programming environments.
  Example usage:
  var customer = create('Customer');
  This statement creates an object from the Customer Entity type and stores it in a variable called "customer". Its properties can be used by adding a dot and typing the field name. At this point, you can press Ctrl + Space to see the fields of the object.
  Example:
  Press "." after typing "customer" to see Customer's fields.

• debug('message'): This is a method that you will use when developing a service. You can give any string to this method as a parameter, and it will print all the messages in a popup window that are given to it when showDebuggingInfo() method is called. As its name implies, this method is most useful for debugging your services.

• query('Customer', "from Customer where name = 'custName'"): This method is used for querying entity objects. Takes the entity's name as its first parameter, and takes an HQL query string as it's second parameter. This method returns a list of entity object. You can use the returned list's items by iterating over the list with a foreach statement.

  Example:

    var customers = query('Customer', "from Customer where name = 'emre' ");
    foreach (cust : customers) {
        warn(cust.name + " " + cust.surname);
    }
  

  The important thing to be careful about when using the query method is that the second parameter to it should be enclosed between double quotes ("), because often the query will contain other string values as parameters to the query and in order for those string values to be correctly parsed, they are enclosed in single quotes ('). The example given above illustrates such a use.

  Another important thing to note while using this method is that you should write your query for returning whole entity objects, by which I mean not any field(s) of it, the object as a whole should be returned.

• save(entity): This method saves an entity to the database. An entity object need to be given to it as its parameter.

• sendEmail('to', 'subject', 'body'): This method sends an email to a specified email address. The first parameter takes an e-mail address to which the email will be sent. The second parameter is the subject of the email and the third parameter takes the message body of the email.

• getTask('taskId'): Returns the task with the given id.

• task(taskName, description, assignee, dd.mm.yyyy, priority): Creates a task with the given parameters. Returns the id of the created task.

• completeTask('taskId'): Completes the task with the given id. Returns true if the task is completed, false if a task with given id couldn't be found or there was another error.

Below is an example snippet that shows how you calculate count of customer that are from city selected in a combobox in Customer screen, and then set the result to another Textfield on the same screen

var city = current.city;
var val = 
query('Customer', "select count(*) from Customer c where c.city = '" + city + "'")[0];
setFieldValue('name', val);

Implicit variables in Service Script Editor

Apart from these methods, there are also some variable that you might use while you are writing a backend service for your application.

current: This represents the input entity object to the service. Its fields can be accessed as a normal entity object variable, by placing a dot and the field name.
Example:
current.name
user: Represents the currently logged in user. Various info about the user can be achieved about the user, type "user." and press Ctrl + space to see the available info about the user that can be used in your script.
organization: Represents the currently logged in user's organization. Its name and code can be used in the script.