Skip to main content
Kinetic Community

Sample REST Handler


A template handler that shows a GET and POST request with error handling.


By downloading this file, you acknowledge that you agree to our Terms of Service

Detailed Description

This handler is a template for how to handle different actions in a handler. The following are topics covered in the handler:
Note: If you want to download a version of this handler with all of these comments included alongside their use in the handler, it can be downloaded here.

Handler Naming Convention

Generally handlers are named in the form of service_structure_action_v1.

ie. You are creating a handler to create SharePoint Documents. In this example, the service would be SharePoint, the structure is a Document, and the action is Create, for a final name of sharepoint_document_create_v1

Error Handling

The following parameter and corresponding result allows a user to choose between a ruby error stopping handler execution to raise the error and having a handler continue executing after encountering the error while returning the error as a part of the handler return values.

<parameter id="error_handling" label="Error Handling" required="true"
    tooltip="Determine what to return if an error is encountered." 
    menu="Error Message,Raise Error">Error Message</parameter>

<results format="xml">
    <result name="Handler Error Message">

Parameter Input Types


A parameter with a menu attribute takes a comma separated list of values and displays those values as an dropdown option list to the user when they are setting up a handler.

<parameter id="menu_dropdown" label="Menu Dropdown" required="true"
    tooltip="Select between 2 different menu options (Default to 'Automatic')."
    menu="Automatic,Manual">Selection A</parameter>

Depends On

A parameter with the dependsOnId and dependsOnValue attribute will only show up to the user if they have entered the matching value into the parameter with a matching id. Most useful if used together with a Menu parameter.

<parameter id="manual_input" label="Manual Input" required="true"
    tooltip="Manual Input. Required if the 'Manual' option was selected in the 'Menu Dropdown' parameter."
    dependsOnId="menu_dropdown" dependsOnValue="Manual"/>


An optional parameter. If left empty, the parameter input will be processed as an empty string.

<parameter id="optional_param" label="Optional Parameter" require="false"
    tooltip="This is a parameter that can be optionally filled in."/>

Backwards Compatability

Starting with Task 4, the version of JRuby that Task uses comes pre-packaged with the OpenSSL and JSON libraries. In previous version of Kinetic Task (3 and lower) these libraries had to be manually loaded in the dependencies file. To create a backwards compatible handler, include the following if block in the dependencies.rb file and load the OpenSSL and JSON libraries inside of that. That way they will load for versions of Task 3 and below but will use the libraries included in the JRuby release for Task 4 and above.

if KineticTask::VERSION.split(".").first.to_i < 4
    # Load JOpenSSL

    # Load JSON

    # Load any other libraries that are only needed for previous JRuby versions

GET and POST Http Requests

The sample handler goes through the process of creating an Http Request including:

  • Authentication (Basic and Token/Header based)
  • Headers
  • Building POST JSON payload
  • Parsing JSON response
  • Handling Http Errros


Name Description
Menu Dropdown Select between 2 different menu options (Default to 'Automatic')
Manual Input Manual input. Required if the 'Manual' option was selected in the 'Menu Dropdown' parameter.
Optional Parameter This is a parameter that can be optionally filled in.

Sample Configuration

Parameter Example Configuration
Menu Dropdown Manual
Manual Input "{\"key\" : \"A manual input JSON String\"}"
Optional Parameter


Name Description
Method   The HTTP method that was used to submit the request.
Created Id The id of the fictional record that was created.

Change Log

Version Date Description
1 2017-04-06 Initial Version