Writing the code for a Custom Service involves creating a Self-Executing Anonymous function that runs when the Integration Point is called. A context argument containing all the functions and data required to process the request is passed to the Self-Executing function. This structure ensures that the Custom Service request is separated completely from the rest of your code.

When you create a Custom Integration Point in the Admin Console using the New Custom Integration Point wizard, the Compose page displays a template containing a simple sample function to help you get started. It uses an input argument and responds with a JSON object or string. Note that the input parameters (in this case, arg 1) are automatically copied from the parameters defined on the Request page of the wizard.

(function(context) {
context.complete(200, {echo:context.params.arg1});
})(context);

General Principles of Code Construction

Custom Services utilize Node.js code and thus support most JavaScript functions and features. A limited number of Node.js modules are also supported. (For information about how to include these in your code, refer to Permitted Node.js Modules, below). 

As you write your code, keep the following important guidelines in mind:

  • In order for your code to run, all the code added to the template needs to be written inside the enclosed brackets within the context function. Prewritten portions of the code outside this enclosure should not be modified. 
    (function(context) {
    context.complete(200, {echo:context.params.arg1});
    })(context);
  • When you are ready to define the response, you need to call the complete function on the context. If no complete function is called in any of the code branches, the request will reach a timeout. 
    (function(context) {
    context.complete(200, {echo:context.params.arg1});
    })(context);
  • Your code needs to run quickly - generally in 10 seconds or less.

Context Argument 

The context argument that is passed to the Self-Executing function represents this particular request. The argument includes all the functions and data necessary to process the Integration Point request and respond with a result. It also can include a utility function called trace that helps debug the Integration Point while developing it.

MemberDescriptionExample
trace([formatted string]) Allows you to write messages that will be placed in the console area of the Test window. The timestamp will be included.

context.trace(“This is %d”, result)
complete(httpStatus, JavaScript object); Ends the request by returning status and data to the caller. This function is mandatory. context.complete(200, “Hello World”)
params Parameters that are passed to the Integration Point. These parameters are defined on the Request page of the New Custom Integration Point wizard. var a = context.params.arg1;

Permitted Node.js Modules

Since Node.js code is used, any required Node.js modules need to be imported into the code. When creating a Custom Service, Node.js modules are invoked by calling the require function. The following example calls an asynchronous function that waits for two seconds before returning the result to the caller. (The timers function is part of the nodejs module.) Note the use of the required function and the use of the complete function. 

(function(context) {
var timers = require('timers');
timers.setTimeout(function(){
context.complete(200, {echo:context.params.arg1});
}, 2000);
})(context);

The Node.js modules that can be included and run in your code are listed in the following table. 

Note: If  you include a module that does not appear in the list below, or if you use one of the permitted modules without calling the require function, your code will not run.

ModuleDescriptionLink  for More Information
debug Tiny node.js and browser debugging utility. https://github.com/visionmedia/debug
ms Tiny ms conversion utility. https://www.npmjs.com/package/ms
mssql MSSQL database connector for Node.js. https://www.npmjs.com/package/mssql
mysql A Node.js driver for mysql. https://github.com/felixge/node-mysql/
nodejs Code modules that are included with Node.js. http://nodejs.org/api/
pusher A Node.js client to interact with the Pusher REST API. https://www.npmjs.com/package/pusher
request-promise An HTTP client that replaces callbacks with promises. https://www.npmjs.com/package/request-promise
soap Allows you to connect to web services that use the SOAP protocol. https://github.com/vpulim/node-soap/
underscore Underscore.js is a utility-belt library for JavaScript that provides support for common functional programming helpers (each, map, reduce, filter, etc.) without extending any core JavaScript objects. http://underscorejs.org/
xml2js A simple XML to JavaScript object converter. https://www.npmjs.com/package/xml2js 

Checking Syntax and Debugging

The following sections describe tools provided by the New Custom Integration Point wizard to help you check and test your code.

Automatic Syntax Checker

The JavaScript editor used in the wizard is CodeMirror. Its syntax checking and Lint services are therefore available to you as you write your code. 

Lines containing syntax errors are indicated by a red Error icon. A description of the error(s) is displayed in a tooltip when you hover the mouse over the icon.

Syntax errors do not prevent the code from running. When you run the code, any errors are listed in the console.

Testing and Error Handling

The Test button, which appears on both the Compose page and the Response page of the New Custom Integration Point wizard, opens the Test popup. This popup enables you to test your code. To perform testing, enter sample value(s) for your input parameter(s), and then click Run Test

The following example shows a successful test for a Custom Service that receives a zip code, and returns the name of the corresponding city and the current temperature in that city. (For details about how to write this type of Custom Service, refer to Custom Service Examples.) The Response pane includes a timestamp, and the stack trace (message = City by this zip) is shown in the console. 

The next example shows what happens when a non-existent zip code is entered as an input. A general error message is displayed at the top of the popup, listing the cause of the error. A more detailed error description is shown in the console.

 

If the code syntax is correct but you return an HTTP status code which is an error, the response body is returned as expected, and the bad HTTP status is shown in the general error message.

 

Revision:

Comments