See the Server Code API here.

Introduction

Server code allows you to write custom app code using JavaScript that will run (execute) on the Appery.io server. Any custom app logic (called script) you write is invoked via a simple REST API call. Server code is a good place to run custom app logic such as sorting large amounts of data or doing calculations.

Quickstart

If you’re new to server code, we recommend this tutorial: getting started with custom app logic.

Server Code dashboard

The Server Code dashboard has information about your scripts, libraries and statistics.

There are tree tabs: Scripts, Plug-ins, and Jobs, where you can:

• Create a new script and a new library.
• Open, clone or delete existing scripts and libraries.
• Review the list of available plug-ins and import them.
• Schedule jobs.

When you open your script, the following views appear:

• Script: Edit the script, load it from a file, or download.
• Trace: See the trace information for the script.
• Statistics: View statistical information.
• Dependencies: Select the libraries your script depends on.
• Versions: Handle your script versions.
• Permissions: Set and change access permissions.
• Settings: Choose the database for managing user access.
• Jobs: Schedule your script jobs.

The Server Code page appears empty if you subscription expires (Subscription status: “Your subscription has expired”). To regain access, sign in any time and purchase a paid plan (or renew your suspended plan payment).

Working with scripts

When you open a script or create a new one, Script view opens. The API information block contains information about your script: Execute URL, Server code script ID and Alias.

You can turn off the ability to call the server code script through the URL by clicking the toggle under Service URL label. That means that the script will not be accessible through the REST services as well.

While editing your script in the JavaScript editor under the Edit tab, you can use Autocomplete and Help hints.

The source code editor has some useful features:

• Code formatting.
• Code collapsible blocks.
• Autocomplete.
• Help hints.
• Toggling to/from full screen mode

You can make your code easier to read by clicking Format code or by using a shortcut <Ctrl>+<Shift>+<F>.

You can activate Autocomplete by pressing <Ctrl>+<Space>. This allows you to choose from a list of base JavaScript constructions and API keywords:

For example, if you start typing Database and press <Ctrl>+<Space>, you will find DatabaseUser completed in the editor. You can also use Autocomplete for object members. For the DatabaseUser object, you will see available methods after you press <Ctrl>+<Space>.

You can use Help hints by pressing <Ctrl>+<Q>. You will see additional useful information about the selected methods:

Here you can find information about all the signatures of the method: description, type and parameters. If you want to get additional information, scroll down and click Read more, which will open a new window with Appery.io documents at the appropriate section.

By pressing <Ctrl>+<H> you can open the history.

Code snippets

Snippets can be used when editing code. There are common snippets for JavaScript APIs (Core snippets), and predefined snippets for Server Code plug-ins, which can be imported and are specific for every plug-in.

In order to insert a snippet, place the cursor in the code, and then from the Snippets list on the Snippets tab, select the necessary snippet, and click insert.

The snippet will appear in the predefined place, (the location selected with your cursor), within the code.

Using the Filter drop-down, you can view and organize available snippets into groups: Core Snippets to show common snippets for JavaScript APIs or All to show all snippets. Once the imported plug-in has finished, any new plug-in groups will be added to this list, and the snippets will be available to insert into the code.

Testing the script

To test the script, in the Script parameters block, define new request parameters:

The Request body block is available for the POST request method only.

In the Trace info block under the Run tab, you can view your last trace information immediately after you’ve run the script.

Testing GET request method

Your script can be executed for an HTTP GET request method. This can be useful when your script returns a resource.

Trace tab

When you switch to the Trace tab, you’ll find information about trace records. The trace order is reversed: the last records are at the top of the list.

Statistics tab

On the Statistics tab, there’s information about scripts such as created and updated dates, runtime, number of times launched, script size and versions.

Dependencies tab

On the Dependencies tab, there’s a list of libraries the script depends on. You can see implicit library dependencies.

Versions tab

On the Versions tab, you can also create, delete, and restore script versions.

Every script has version information: creation date and time, creator username and a label “Current version” or some custom comment that can have length up to 500 symbols. You can see restore and delete links for script versions.

Current version of script can’t be deleted and it doesn’t have restore or delete links.

If you have View permissions only, you won’t be able to create, restore, and delete script versions.

If the script is cloned, its clone doesn’t include created versions.

Permissions Tab

On the Permissions tab, you can specify the access permissions (View, Edit or Delete) you give the users of your team.

Only your team users may access your resources. Information on how to enable or change the permission options for them can be found here.

The user the script was shared with will see it from the Scripts list at the Server Code tab.

The user the script was shared with can open it to view or edit, delete or clone it (if granted such rights).

Editing the shared script will cause the original script to change. To edit the shared script without affecting its original, use Clone to make a unique copy of it.

Settings tab

Under the Server Code Settings tab you can delete or clone the script and manage user access.

User management

On the Settings tab you can choose the database to manage user access. If “Allow only authenticated users to call this script” is not checked, the following scenarios are possible:

• If the sessionToken header is specified and valid — the service will login the user and provide his data in request.user property.
• If the sessionToken is specified and not valid — the service will return an error SCSX022.
• If the sessionToken is not specified or empty — request.user will be undefined.

In the case that the sessionToken is not specified or empty, the service will produce an SCSX026 error.

By checking the Allow only authenticated users to call this script, you can prevent the script from launching by non-authenticated users.

The section Share with support is placed at the bottom of the page. When a user enables sharing (turns the toggle “on”), the specified resource appears in the admin section. This feature can be used by the support team for viewing and accessing all resources (apps, databases, server scripts, etc) shared.

Plug-ins

Plug-ins can be used to add out-of-the-box features to Server Code scripts, enabling their customization.

Server Code plug-ins are scripts with particular dependencies. Every plug-in can be composed of a script or a library with their dependent libraries.

The list of available Server Code plug-ins can be found under the Plug-ins tab.

To add a particular plug-in to your account, select it from the plug-ins list and click “import”.

After a plug-in is imported, its scripts and libraries are added to your project.

A plug-in can be imported more than once, if so, another script will be generated and the timestamp will be added to its name. All the previously imported scripts and libraries won’t be affected.

If you need to revert the library to its original state after some changes to it have been done, delete it and then re-import the corresponding plug-in.

After importing a plug-in, new code snippets appear in the snippet list.

If you delete the imported library, the snippets will become unavailable and disappear from the list.

Scheduling jobs

Server code script execution can be scheduled via the job scheduler. Switch to the Jobs tab to open the scheduler.

You can set schedule parameters for script execution by using the convenient Schedule Builder. From the drop-down list to the right of the Script label, choose the script that should be scheduled and specify the time parameters:

If the parameters are specified like the screen shot above, the script will be executed every Monday, eight times from 10.30 to 17.30 (every hour). The execution time can be also set by using the schedule expression. Choose “Schedule expression” to the right of the Use label, and provide the Cron expression based on Quartz:
For example, 30 15 ? ** expression will execute the script at 15.30 every day.

Read more about Cron expressions here.

One important thing to know is that the Appery.io job scheduler doesn’t use a seconds parameter in Cron expressions. So, if you use an expression such as 0 0/5 * * * ? you’ll get an error.

Remove the first number (zero in this case) and the expression will be correct.

There is a limitation of a minimum interval between scripts invocation based on your plan. The error will appear if specified interval is less than the time span for your plan.

See the pricing page to check limitations for your plan.

Once the schedule parameters are set, either by using the schedule builder or a correct schedule expression, clickSave to schedule the execution. The scheduled script name and other parameters will be shown at the bottom of the page.

Click “Refresh” to see the executed scripts and their result status.

Toggle the on\off button in the Active column to pause the script execution.

When the script execution is paused, the time passed is saved. For example, lets say that the script should be executed every 5 minutes. If the script was paused after 3 minutes passed, when the script is resumed it will be executed after 2 minutes.

Code editor shortcuts

The Appery.io server code editor supports several shortcuts for working with code:

Windows

• <Ctrl>+<Shift>+<F> – Format code.
  
• <Ctrl>+<Space> – Auto complete.
• <Ctrl>+<Q> – Show hint.
• <Ctrl>+<S> – Save script.
• <Ctrl>+<D> – Remove current string.
• <F11> – Open script code (or request body) in FullScreen mode.

Mac OS

• <Ctrl>+<Shift>+<F> – Format code.
• <Ctrl>+<Space> – Auto complete.
• <Ctrl>+<H> – Show hint.
• <⌘>+<S> – Save script.
• <F11> – Open script code (or request body) in FullScreen mode.

Working with libraries

You have a set of predefined JavaScript libraries, marked with the label, system library. You can also see the version of the library you are going to use.

You can open and clone the system library, but you cannot edit or remove it. You can perform the following operations on custom libraries:

• Create a new library: open the Server Code tab and click “Create library” on the left panel. In the open window, you can enter the library name and description, add JavaScript code, or load the code from a file. After you click “Save,” other features will become available.
• Rename the library: open the library and change the name. Upon saving, the new name will appear in the upper-left corner.
• Edit source code: you can type your JavaScript code or load it from a .js file (link Load from file).
• Edit description of library: you can select the type of description, and type it or load it from a file.
• Set dependencies: open the library, and switch to Dependencies view to check the libraries upon which the open one depends. The selected libraries appear at the top of the list.
  

  If you check libraries in such a way that they form circular dependency, you will receive an error message and the dependency won’t be created.

• Share the library with other users: open the library, switch to Permissions view, and enter the email(s) of the user(s) you want to give access to your library to. To invite several users, enter multiple emails separated by a comma , or a semicolon ; :
  

  Only your team users may access your libraries.

The user that the library was shared with will see it from the Libraries list on the Server Code tab.

The user with whom the library was shared can open the library to edit or view it, delete or clone it.

Editing the shared library will cause the original library to change. To edit the shared library without affecting its original, use Clone to make a unique copy of it.

How to use the Server Code API

The Server Code API can help you create your own scripts with custom logic. You can use it in two simple steps:

Writing the code

To create a new script, go to the Server Code tab and “Create script.”

Try Getting started with custom app logic tutorial.

You’ll see the default script template. You need to remove it and paste your code instead. Once the code is finished, save it by clicking Save.

Testing the code

After the script has been saved, you can test it by clicking Save and run. You can use a GET or POST command to test your code.

If you’re using a POST command, you can pass any parameters with the request and body. If you’re using a GET command, the request body isn’t available.

Invoking via REST

There are two ways to define a server code script as a REST service:

1. You can automatically generate the services via CREATE NEW > Server Code Services.
2. Manually define the REST service.

Auto-generate REST service

Appery.io provides the ability to create services from a builder, based on existing server code scripts. There is no need to create it manually. All of the parameters, specified in the Server Code > Test tab, will be also saved and transferred to the REST service.

To import the server code as a REST service, go to the Appery.io builder, and select CREATE NEW > Server Code Services. Choose one of the existing server code scripts from the drop-down list, and click Import selected services .The imported service will be listed under the Services folder.

Now the imported service can be used normally. Double click on the new service to open its Settings. The Execute URL is used as the service URL, so there’s no need to refresh or recreate the service when the server script is changed.

At the end of the URL, there are request parameters which were specified in the Test.

Request parameters and body values are listed in the Request tab. Response parameters were also automatically generated, based on the response object structure.

To test the service from the builder, go to the Test tab, and click Test. The input and output data of the imported services can be mapped normally.

View more information about REST services mapping here for jQuery Mobile projects.

Manually define REST services

Create and configure the service

To test your scripts from the app builder, you’ll need to create the REST service and invoke it. You’ll also need to copy the Service URL which displays when you save the script, and use it as a URL in the REST service.

To create a new service in the app builder, select CREATE NEW > Service.

Enter the REST service name and click Create Service. Paste the Execute URL into the URL field.

To specify any parameters, go to the Request tab. Also, you can add any parameter under Headers when you need to pass headers. You can test your script from the Test tab by clicking “Test.”

If there are no errors, you’ll see the response. If you’re using a Console API to trace data, you’ll see all the outputs from the script trace info. Go to the Server Code tab, choose your script, and you’ll see it.

You can display what the service returns by mapping the data to a page. First, you need to specify the response fields. You can do it automatically by clicking Import as Response, or you can do it manually in the Response tab.

Invoking the service

You can invoke the service in multiple ways. For example, you can use Invoke service action for jQuery Mobile projects. See how to invoke REST services for AngularJS projects here.

Passing parameters to the script

GET method

In the Appery.io builder, you can pass any parameters you want to your server code. You can parse retrieved data on the server side and return any result as a response. There are several ways to do this. Let’s consider simple server script, which answers with the word “Hello.” The code is simple:

Read more about the Request API here.

To say “Hello” to somebody using his or her name, like “Hello, Dan!,” you need to pass the user name to your server script. In the case of the GET command, you can do this in several ways. The first is to add an additional parameter to the end of the script URL:

Note the text after “exec.” You can do the same thing, but in a more convenient way, by using an Appery.io feature. In the Request tab, you can add any parameters you want:

Both methods work equally well. Test your service and you’ll see the greetings.

POST method

Via the POST command you can send a request body. It can contain any information and can be parsed separately from the parameters.

For example, you want to send information about somebody and list it in the response. The server code will look like:

To do this from the Appery.io builder, you need to change the request method to POST:

Now, every parameter specified in the Request tab will be considered as a request body. To send the parameters, you can use a URL, as in the case of the GET method. Put additional parameters on the end of the URL after “exec”:

Specify some parameters to describe the person in the Request tab:

Now you have specified the request body (Hair:Blonde, Eyes:Blue) and the request parameters in the URL (name=Dan). Let’s see what happens when we test the service:

In the response, we have a name parameter (Dan:) and the body, which is listed as a key-value pair. It’s better to wrap your response in JSON format. This will gave you the ability to conveniently map response data. For example:

If you test the service and use the “Automatically Create Service Response” feature, you’ll get two response parameters – name (String) and description (String).

Then you can easily map it to the page.

See the Server Code API here.

Server Code errors

See the Server Code errors here.

More help resources

More help resources are links to the blog, our YouTube channel and other web sites.

• Learn How to Add Geocoding Lookup in Your App With Server-side JavaScript