Quick Start

Top  Previous  Next

The goal of this chapter is to enable a developer to quickly become familiar with Backendless custom business logic feature. At the end of the instructions provided below you will have a Backendless application with a custom API event handler which modifies an object before it is saved with the Backendless API.

 

Using Code Generator

1.Login to Backendless console and create a new application called OrderManagement. You can use an existing application, however this guide assumes that certain data tables are created, which may conflict in an existing app. Use caution if you decide to use an existing app.
2.Click the Data icon to navigate to the Data/Schema browser section of the console:
backendless-data-section.zoom70
 
3.Click the "plus" icon in the lower left corner of the screen to add a new table. The reason a table should be created first is because one of the next steps will be registering an event handler for this table. Name the table "Order".
create-table.zoom50
 
4.Click Save to create the table. Select Yes in the popup to modify the table schema. Click Add Column and enter "customername" in the Name field as shown below:
customername-popup.zoom80
 
5.Click Save to add the column.
6.Click the Business Logic icon to navigate to the custom business logic section:
navigate-to-biz-logic.zoom80
 
7.Select Data Tables in the Service Events Handlers section. This is needed because you will be creating an event handler for a Data Service API call:
data-tables-handler
 
8.Every category of service event handlers contains three tabs: Code Generation, Debug and Production. Each tab represents a state of the code and displays a "model" of the code available in the corresponding state. A model is a collection of event handlers and timers.
Code Generation - a state containing a model created by the developer and lists the event handlers and timers for which the code should be generated.
Debug - displays a model recognized by CodeRunner™, a special utility used for local debugging of custom business logic.
Production - contains a model deployed into the backend for production purposes. This is the currently active model in the application.
event-handler-tabs
 
9.Select JS from the Language listbox on the Code Generation tab. This selection sets the programming language for the generated source code when event handlers and timers are added. Language selection can be changed at any time, which will result in the regenerated source code for the selected language.
js-selection
 
10.Click the Add Event Handler button.
 
11.In the New Data Event Handler popup, select the Order table in the Context drop down:
new-data-event-handler
 
12.Click Save to create the handler. The system adds a new handler to the code generation model and automatically creates the necessary framework code which you will use to add your custom business logic. Additionally, the code generator automatically creates a class definition for the table referenced in the event handler. For instance, for the Order table, the generated code includes order.js:
generated-js-code
 
13.Click the Download Code button located under the source code tree. Backendless generates a zip file with the same name as the name of the application. The zip file contains all the generated source code as well as project files:
download-code

 

Customizing and Running Code

1.The generated zip archive contains a complete project with all the necessary dependencies and source code which can be easily modified. Expand the zip file into a directory. The directory where you unzip the file will be referenced in this guide as [project-home].
2.Open the project in IntelliJ IDE (you can use other JavaScript IDEs, however Backendless recommends IntelliJ. Generated code includes project files for the IDE).
3.If you use IDEA, open the Terminal window, otherwise open a command prompt window and change the current directory to [project-home].
4.Make sure node and npm are installed on your computer.
5.Run the following command to download the CodeRunner™ for JS dependency into the generated project:
 

npm i

 
Once the command execution completes, you should see the output similar to the one in the screenshot below:
npm-i-output
 

6.Open /app/handlers/persistence/order/beforeCreate.js for editing and modify as shown below. The modified version of the event handler contains a line of code that changes the customername property of the Order object to upper case.
/* global Backendless */

/**
* @param {Object} req The request object contains information about the request
* @param {Object} req.context The execution context contains an information about 
*                             application, current user and event
* @param {Order} req.item An item to create
*
* @returns {Order|Promise.<Order>|void} By returning a value you can stop further 
*          event propagation and return
*          a specific result to the caller
*/
Backendless.ServerCode.Persistence.beforeCreate('Order', function(req) {
  console.log( "Received order object. Customer name - " + req.item.customername );
  req.item.customername = req.item.customername.toUpperCase();
});

 
7.Return to the Terminal (or the command prompt) window and run the following command which starts CodeRunner™ in the local debug mode (make sure the command is ran from the [project-home] directory:

npm run debug

 

9.Once CodeRunner™ starts, it produces the following output:

your-comp-name:bin username$ npm run debug
> OrderManagement-servercode@1.0.0 debug /Users/mark/Downloads/OrderManagement
> coderunner debug
 
2016-03-20T13:25:41.407Z - CodeRunner(tm) Backendless Debugging Utility                                                                                 2016-03-20T13:25:41.410Z - Copyright(C) 2016 Backendless Corp. All rights reserved.
2016-03-20T13:25:41.410Z - Version 1.2.0
2016-03-20T13:25:41.648Z - Starting Debug Code Runner...
2016-03-20T13:25:41.666Z - Building Model..
2016-03-20T13:25:41.669Z - Model Build completed: event handlers: 1, timers: 0, custom types: 1, services: 0, errors: 0
2016-03-20T13:25:41.670Z - Registering Code Runner on https://api.backendless.com
2016-03-20T13:25:42.138Z - Runner successfully registered.
2016-03-20T13:25:42.139Z - Registering Model on https://api.backendless.com
2016-03-20T13:25:42.420Z - Model successfully registered
2016-03-20T13:25:42.421Z - Waiting for Server Code tasks..

 

10.At this point CodeRunner™ is connected to Backendless and the code is ready for local debugging. Return to Backendless Console. The Debug tab shows the event handler in the debug state:
event-handler-in-debug

 

11.To test the code you must issue an API request to store an object in the Order table. You could write a client application using any programming language of your choice:
Java                - Create object using Backendless SDK for Java
Objective-C        - Create object using Backendless SDK for iOS
JavaScript        - Create object using Backendless SDK for JavaScript
ActionScript        - Create object using Backendless SDK for Flex/AIR
C#/VB                - Create object using Backendless SDK for .NET
 
or with REST        - Create object using REST API

 

12.This guide uses the REST API to create an API request to store an object. The REST request with the curl utility is:

curl -H application-id:APP-ID -H secret-key:REST-SECRET-KEY -H Content-Type:application/json -X POST -d "{\"customername\":\"foobar corp\"}" -v https://api.backendless.com/v1/data/Order

The APP-ID and REST-SECRET-KEY values must be obtained from the Manage > App Settings screen in Backendless Console:
app-id-secret-key.zoom70

 

13.Run the curl command in a separate command prompt window. Once the API call completes, notice the following output in the window where CodeRunner™ runs. The second line of the output comes from the custom code you developed:

2016-03-20T13:33:57.212Z - New task arrived! [id:394A4E1B-F57E-59D5-FF81-B7C78C4A8200]
Received order object. Customer name - foobar corp
2016-03-20T13:33:57.221Z - [394A4E1B-F57E-59D5-FF81-B7C78C4A8200] Processing finished

 

14.To make sure the custom code has executed properly, return to Backendless Console and switch back to Data section. Select the Order table and check the object stored in the table:
custom-code-result-data

 

Deploying Code to Production

Deploying code to production uploads your custom code and any required dependencies to the Backendless Cloud servers. To deploy the code run the following command in a Terminal window:

 

npm run deploy

 

When the deployment script runs, it produces the following output:

your-comp-name:bin username$ npm run deploy
> OrderManagement-servercode@1.0.0 deploy /Users/mark/Downloads/OrderManagement
> coderunner deploy
2016-03-20T13:49:15.731Z - CodeRunner(tm) Backendless Debugging Utility                                                                              
2016-03-20T13:49:15.734Z - Copyright(C) 2016 Backendless Corp. All rights reserved.
2016-03-20T13:49:15.734Z - Version 1.2.0
2016-03-20T13:49:15.973Z - Building Model..
2016-03-20T13:49:15.990Z - Model Build completed: event handlers: 1, timers: 0, custom types: 1, services: 0, errors: 0
2016-03-20T13:49:15.990Z - Preparing app zip file for deployment..
2016-03-20T13:49:15.993Z - 2 files added into deployment archive
2016-03-20T13:49:15.996Z - Registering Code Runner on https://api.backendless.com
2016-03-20T13:49:16.351Z - Runner successfully registered.
2016-03-20T13:49:16.351Z - Registering Model on https://api.backendless.com
2016-03-20T13:49:16.620Z - Model successfully registered
2016-03-20T13:49:16.621Z - Publishing Model to server
2016-03-20T13:49:17.225Z - Successfully published

 

Once the code is deployed to production, it is immediately plugged into your application. You can verify the production deployment in Backendless Console. Open the Business Logic section, click Data Tables under the Service Events Handlers section and click the Production tab:
service-handler-production

 

An event handler running in production can be disabled by clicking the checkbox in the Enable column.

 

This concludes the Quick Start. You can try repeating the process for other event handler or timers. If you run into any problems or have any questions, do not hesitate contacting us at http://support.backendless.com.


Please let us know how we can improve the documentation by leaving a comment. All technical questions should be posted to the Backendless Support forum. We do not respond to the technical questions on the documentation pages.: