Server Code Syntax

When writing your server code, you will follow the syntax explained in this page.

You can write your server code like any other JavaScript code. Server code can leverage various Kii Cloud functionalities by using the Kii JavaScript SDK. To learn more on the Kii JavaScript SDK, see JavaScript Programming Guide.

There are two series in Kii Cloud SDK for JavaScript: v2 and v3 series. In your server code, you can leverage features supported by v2 series.
For more information, read Difference between Kii Cloud SDK for JavaScript v2 series and v3 series.

Synchronous and asynchronous server code

The Server Extension feature allows you to write your server code either synchronously or asynchronously. The syntax is almost the same for both cases. The only difference is that the asynchronous server code will have a callback function in its third argument.

• Synchronous server code

  Here is the basic syntax of synchronous server code. When the function is called, the code will be executed sequentially. The code execution finishes when the return function is called.

  function funcName(params, context) {
    // Your code comes here...
    return "Hello!";
  }
  

• Asynchronous server code

  Here is the basic syntax of asynchronous server code. The code execution does not finish even if the function is done. It finishes when the callback function done specified in the third argument is called and when the control returns from it (as explained in asynchronous execution, the function must finish after executing the done).

  function funcName(params, context, done) {
    // Your code comes here...
    done("Hello!");
  }
  

  You will need to use asynchronous server code when you use the features that rely on asynchronous calls like non-blocking APIs.

Endpoint parameters

Endpoint parameters vary depending on the execution method of server code. See the following sections for parameters of each execution method.

If you execute your endpoint in multiple ways (e.g. executing a function manually and also with a trigger-based hook), the parameters and the value returned by the API will change according to the execution method).

• Parameters for Manual Operation
• Parameters for a Trigger-based Hook
• Parameters for a Schedule-based Hook
• Parameters for a Thing-IF Trigger

Asynchronous execution

For asynchronous server code, the server code is considered as done when the callback function specified in the third argument is executed or when an exception is thrown. It is, therefore, important to call the callback function at the end of the server code even if your server code does not need to send any results to the client; the timeout exception will be thrown otherwise.

If you omit writing a failure case in the callback function or incorrectly write a catch handler with Promise, you could introduce a path without the done() invocation. The server code will time out in these cases.

Note that the server code execution itself does not end by executing the callback function. For example, done("SUCCESS!!") will be executed even after executing done("ERROR!!") in the following server code.

function asyncFunc(params, context, done) {
  if (!context.getAccessToken()) {
    done("ERROR!!");
    // You need a return statement here.
  }
  done("SUCCESS!!");
}

Make sure to call the callback function only once by executing the return right after calling the callback. If the callback function is called more than twice, the value passed on the first call becomes the return value. Other values, although not returned to the client, will be recorded in the developer log.

If you use a non-blocking API in the server code, the callback function of the non-blocking API will be called even after the done is called. In the following sample code, for example, the callback function of the authenticate will be executed after the login is done, and the log will be recorded. The done in this sample code is not in the correct place; it should be placed as the last process (inside the callback function in this example).

function asyncFunc(params, context, done) {
  KiiUser.authenticate("aaaa", "bbbb", {
    success: function(theUser) {
      console.log("User authenticated!");
      // Call the done() function here.
    },
    failure: function(theUser, errorString) {
      console.log("Error authenticating: " + errorString);
      // Call the done() function here.
    }
  });
  done("OK");  // You shouldn't call the done() function here.
}

Using asynchronous execution deepens the code nesting and makes your code less readable. Consider using Promises supported by the JavaScript SDK. You can also jQuery.Deferred().

Timeout

By default, an exception is thrown when the timeout occurs.

You can also send the specific value to the client when the timeout occurs. To send the value, set it in the context object like the following example:

function main(params, context, done) {
    context._timeoutReponse = {customField: "my_custom_message"};
}

When you set the value like above, the timeout will be handled as a successful termination rather than an exception. The client can extract the value just like the normal execution result. See Timeout to learn more.