Callable Service - A container for a service that can be called directly via a URL (from the same application or from another application)

Callable Service is similar to Service in being a generic container for user-defined modeling of a process that executes on the server tier, but while Service is called by other processes in the application by being included in their models, Callable Service is called via a URL (from the same application or from another application).

Callable Service returns either a file or data.

Calling a Callable Service

Callable Service is “called” by referring to the service’s URL (e.g. by typing the service’s URL in your browser).

When the browser (or an HTTP request) is accessing the service, the service retrieves its parameters from the URL and starts executing. When it finishes, it returns its output.

The syntax of the service’s URL differentiates between the various output types (file or data) and usage modes (calling from within a Tersus Application [using a relative URL] vs. calling from another application [using a fully formed URL]). The details are explained below.

Use Cases

1. Display an image file stored in the database

Called:	By a Tersus application.
Returns:	An image file to display.
Service Modeling:	Model a Callable Service that reads the required image from the database and returns it as a File data structure.
Usage:	In the calling application, use an Image display element and set its <Path> element to the URL of the Callable Service. At runtime, whenever the Image element should be displayed, the Callable Service is invoked to obtain the image file.
Try it online:	Go to the File Library perspective in the Examples project, upload an image file to the library, and if you mark it as “Is Image”, you’ll see it displayed in the file list.

A detailed explanation of this implementation is available in the “Detailed Examples” section below.

2. Display a graph based on application data

Called:	By a Tersus application.
Returns:	A graph as an image file to display.
Service Modeling:	Model a Callable Service that uses any of the templates in the Charts category of the palette (for instance Generate Line Chart) to generate a graph image and return it as a File data structure.
Usage:	In the calling application, use an Image display element and set its <Path> element to the URL of the Callable Service. At runtime, whenever the Image element should be displayed, the Callable Service is invoked to generate the graph’s file.
Try it online:	Go to the Web Services - Forex perspective in the Examples project, select a currency and press the Show Graph button.

A detailed explanation of this implementation is available in the “Detailed Examples” section below.

3. Download a file stored in the database

Called:	By any application (or simply the browser).
Returns:	A file for download.
Service Modeling:	Same as in use case 1 - the browser uses the same download mechanism for images it needs to display, as it does for any other file type.
Usage:	You want to provide the ability to access files stored in a database to any applications capable of performing an HTTP request (the browser is one such application). Use the callable service implemented for use case 1.
Try it online:	To open the Welcome to Tersus Studio page stored in the database of the Examples application, enter the following URL in your browser (or click it): http://applications.tersus.com/Examples/File/?_path=File%20Library%2FDownload&Id=1.

4. Display an image file in another application

Called:	By any application (or simply the browser).
Returns:	A file for download.
Service Modeling:	Same as in use cases 1 or 2, depending on the image source.
Usage:	You want to provide access to the images discussed in use cases 1 and 2 to any application capable of performing an HTTP request (such as the browser itself). You can do so by making use of the same callable services.
Try it online:	Enter the following URLs in your browser (or click it), to see the images: Use case 4.1 – Image from database: http://applications.tersus.com/Examples/File/?_path=File%20Library%2FDownload&Id=2 Use case 4.2 – Generated graph: http://applications.tersus.com/Examples/File/?_path=Web%20Services%2FWeb%20Services%20-%20Forex%2FGenerate%20Rates%20Graph&Curr1=EUR&Curr2=GBP

5. Get statistics from a Tersus application

Called:	By an external application.
Returns:	Several counters on the current status of a Tersus application.
Service Modeling:	A Tersus CRM application exposes counters (daily number of cases, resolution rate, etc.) through a callable service. It is modeled to receive the Date for which statistics are requested, and returns them.
Usage:	An external application (e.g. a reporting tool) can access the Tersus application at any time to display the most up-to-date statistics. The external application will issue an HTTP request with a URL similar to the following: http://applications.tersus.com/Examples/Service/?_path=Data%20Service&Date=2008-02-29 Assuming the service has two numeric exits “Cases” and “Resolved Cases”, then the service returns the string ‘{"Cases":\n157\n,“Resolved Cases”:\n134\n} ’. If the external application is implemented using Tersus, you can use Miscellaneous/HTTP Post to perform the request, and Miscellaneous/Parse JSON to parse the result.
Try it online:	Go to the Callable Service view of the Tests perspective in the Examples project, and select a date to see the statistics for that date.

A detailed explanation of this implementation is available in the “Detailed Examples” section below.

Triggers

Callable Service does not require any triggers, but can have as many user-defined triggers as needed (to pass parameters to the service).
Trigger values are passed as URL parameters, identified by name. For example, in use case 5 above the Callable Service has a trigger named ‘Date’, so the URL referring to the service contains a ‘Date’ parameter.
Generally, all mandatory triggers must have a matching parameter on the URL (but the URL may contain additional parameters as well, which are not passed to the callable Service).
For a service returning data:

http[s]://host[:port]/application_name/Service/?_path=callable_service_path_and_name[&param1=value[&param2=value[&...]]]

Italicized elements should be replaced with the actual values for your implementation. Values must be encoded, e.g. replacing a space by ‘%20’, a forward slash by ‘%2F’, etc. otherwise some browsers might cause problems (Tersus applications can do so using Text/Encode URL).
[elements] in square brackets are optional.
Response is returned as a JSON formatted data structure, which includes all exit values of the service (in Tersus applications, you can parse it using Miscellaneous/Parse JSON).
Calling application can perform an HTTP POST or HTTP GET operation to get the response (Tersus applications can do so using Miscellaneous/HTTP Post or Miscellaneous/Read Resource respectively).

For a service returning a file:

http[s]://host[:port]/application_name/File/?_path=callable_service_path_and_name[&param1=value[&param2=value[&...]]]

Alternative shorter syntax for a service returning a file:

http[s]://host[:port]/application_name/callable_service_path_and_name[?param1=value[&param2=value[&...]]]

The returned value (the exit value of the service’s single exit) must be a File structure, which is handled by the browser according to the content-type specified in File/Content Type field.

Exits

If a Callable Service is used to return a file, then it must have one exit, which should be of type File.
If the Callable Service is used to return data, then an unlimited number of user-defined exits of any type can be added. In runtime, all values returned through the exits are included in the JSON formatted data structure that is passed to the caller.

Notes

To make a Callable Service accessible, it must be located in a System which in turn must be either the root system or one of its descendants. If the Callable Service is not placed in the root system, the URL used to access it must include the full path of systems leading to it.

Detailed Examples

The Examples project (which is part of the standard installation of the Tersus Studio) contains the following examples of Callable Service:

Use Case 1 – Display an image file stored in the database

The Examples project model contains a Callable Service called Download (in the File Library system) that expects an Id parameter, and retrieves the file specified by that id from the database:

When we want to show an image file using an Image display element, we simply set the <Path> element of the image to the URL of the Callable Service (including the parameters for the service):

Note that the URL is specified as a relative URL, which means that when processed by the browser it will use the current application prefix.

Use Case 2 – Display a graph based on application data\

The Examples project model contains a Callable Service called Generate Rates Graph (in the Web Services/Web Services - Forex system) that creates an image file with the graph of exchange rates of 1 or 2 currencies against the USD:

When we want to show the graph using an Image display element, we simply set the <Path> element of the image to the URL of the Callable Service (including the parameters for the service):

Use Case 5 – Get statistics from a Tersus application

The Examples project model contains a simplified example of the use case which includes a Callable Service called Data Service (in the root system) that returns fictive data, based on the date passed to it:

Accessing this service is demonstrated in Test Data Service/View. When the user enters the date for which he’s interested in statistics and exits the Date Row/Date input field, the <On Change> event is fired, issues the HTTP POST request, parses the results, and updates the Response Row display:

Note that the Get Base Callable Service URL and Get Request processes, construct the separate URL (e.g. http://applications.tersus.com/Examples/Service) and Request (e.g. _path=Data%20Service&Date=2008-02-29) strings required to perform an HTTP POST request.