Implementing a Callback Point

Overview

This document describes how you can create your own callback point. This can be useful if you want to deliver the same business processes to several customers/installations - and want to make it possible to let the customers influence the functionality in specific situations.

In addition to this, it describes how you can implement callback functions for a callback point. This is the exact same functionality for the system defined callback functions and for the callback point you develop yourself.

Create a Callback Point

The first thing you must do is to create an implementation function for the callback point. This is done by inheriting from the abstract CallbackPoint function found in the WSYAPI model:

Create definitions for AbstractCallbackFunction

The callback point scopes a function called AbstractCallbackFunction.

You must determine whether the function is going to be called from a from a webserver function (e.g. EventHandlers, PageGenerators, ProcessEntryPoints) or from a Server function (e.g. a SingleFetch, BlockFetch,ProcessGroup).

Depending on this, inherit from either Abstract.WebServerCallback or Abstract.ServerCallback - e.g:

Handle parameters

The callback point will call the callback functions based on database entries. This means that the callback functions will be called dynamically. The consequence of this is that you can't use normal parameters to transfer information between the callback point and the callback functions.

As it is obviously necessary to be possible to transfer information between the callback point and the callback functions an alternative way to transfer the parameters has been implemented in the abstract callback point and callback function.

The callback point function scopes a function _Interface. You use this function to specify the interface for the call by adding fields to the local variables CallbackInput and CallbackOutput.

Fields added to the CallbackInput variable are transferred from the callback point to the callback function. Fields added to the CallbackOutput are returned from the callback function to the callback point.

So if you have a field "MyInputField" that you need to transfer from the callback point to the callback function and you have a field "MyOutputField" that you need to return to the callback point, specify the following:

The callback point contains functionality that reads the content of the local variable CallbackInput just before the calls to the callback functions. This information is made available for the callback functions. The callback functions reads this information and uses it to populate the CallbackInput variable.

As the callback function terminates, it reads the content of the CallbackOutput variable and makes it available for the callback point. After each call, the callback point uses this information to populate the CallbackOutput variable.

WinC functions - change source code

The callback point function scopes three different source code objects. These are used to perform the dynamic calls to the callback functions. For the Java and the RPG variants, the source codes can be used as they are, but for the WinC version you need to change the name of two variables.

Define the callback point using the administration interface

Enter the administration interface and select "Callback Functions". On the page, press the button to the right of the drop down box to enter the callback point maintenance. Here you can create your own callback point.

Specify custom handling in the callback point

Before calling callback points:

In the edit point "Before fetch functions" - populate any fields in CallbackInput with the values you want to transfer to the callback functions.

After each call to a callback function:

In the callback point function, there are two edit points: "After Successful Dynamic Call" and "Error from Dynamic Call".

After each call to a callback function, the functionality specified in one of these edit points will be executed (based on *Returned Status).

Here you can e.g. transfer the values from the CallbackOutput variable to the Output variable - you can also determine whether you should call the rest of the defined callback functions based on the output from the previous call.

If you want to stop calling callback functions set:

Set BaseWorks<APIFields.ContinueProcessing> = <APIFields.ContinueProcessing.No>

This stops the handling of callback functions - the callback point will terminate.

Example

Look at the local modifications in the action diagram for: WSYAPI/CallbackFunctions.CallbackPoints.WebServer.BeforeRequestStart to see an example of how to modify a callback point.

The input to the callback point is made available for the callback functions.

As soon as one callback function has returned No in the field ContinueProcessing - no further callback functions are called.

Implementing a callback function

Whether you want to enter your own functionality in a system defined callback point or whether you want to enter it in one of your own, you must create one or more callback functions. These callback functions is where you perform the functionality you want to execute at the callback point which you add the callback function to.

Create the function

To create a callback function that can be called by the callback point, create the following triples:

After doing this, you can add the custom functionality to the callback function.

Please note that by adding the input and output fields to the _Interface function, the fields will also be available in the callback function. The CallbackInput fields are automatically populated, and you can use them as if they were normal input fields.

Before terminating the function, you must populate the fields in the CallbackOutput variable with the values you want to return to the callback point. These values will automatically be made available for the CallbackPoint.

Add the function to the callback point

The runtime needs to know that there is a callback function to be called for the callback point. Use the Administration interface menu item "Callback Functions" to add the callback function to the callback point.

Examples

As examples of implemented callback points, we have delivered the implementation of the callback points used by the WebsydianExpress runtime in the WSYAPI model. You can find these callback points scoped by the function: WSYAPI/CallbackFunctions.CallbackPoints.