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 inrequest.user
property. - If the
sessionToken
is specified and not valid — the service will return an errorSCSX022
. - 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 (linkLoad 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:
- You can automatically generate the services via
CREATE NEW > Server Code Services
. - 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:
1 2 |
var name = request.get("name"); //Find the "name" parameter in the request response.success("Hello, " + name + "!"); //Send the response which looks like Hello, <name>! |
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:
1 |
https://api.appery.io/rest/1/code/043d7960-64c9-4fb7-a0eb-debf3dd8ae2a/exec?name=Dan |
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:
1 2 3 |
var body = request.body(); //Saving the request body var name = request.get("name"); //Saving the request parameter "name" response.success(name + ":" + "\n" + body); //Output them both |
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”:
1 |
https://api.appery.io/rest/1/code/a4837f7a-4679-4ca3-8214-fa1f6aecc4fe/exec?name=Dan |
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:
1 2 3 4 5 |
var body = request.body(); var name = request.get("name"); response.success({ name:name, description:body}); |
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.