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.
General Principles of Code Construction
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.
- 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.
- Your code needs to run quickly - generally in 10 seconds or less.
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.
|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)|
|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.
var timers = require('timers');
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.
|Module||Description||Link 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/|
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
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.