Implementing callback functions

Overview

This document will show how you can implement your own callback function for the callback points provided by the WebsydianExpress runtime.

The callback functions offers the possibility to add custom functionality to the functionality performed by the WebsydianExpress runtime in specific situations.

The document also contains a short description of each of these callback points.

For each callback point you can specify any number of callback functions.

Creating the function

There is no templates provided for the callback functions. To create the function you want to implement, create a function of type "Execute external function".

Retrieving input

As the callback functions are called dynamically by the runtime, you can't specify any parameters for the function.

But there is still some of the callback points that transfers information for the callback functions. This information can be retrieved by calling the API CallbackInputGet.

When calling this function you must specify the name of the parameter to get - for example:

For each parameter used by the system defined callback points conditions has been specified for the field W2E/CallbackParmName - the description for each callback point found below specifies which parameters you can retrieve.

Setting output

For some of the callback functions there is also the option to return some information. You make this information available for the calling function by calling the API CallbackOuputSet.

As for the CallbackInputGet function, you must provide the name of the field together with the value - information about which information you can set is of course also found in the description of the callback points found below.

Adding the callback function to the callback point

After generating and building the function, you must specify that the function should be called for the callback point. This is done using the administration interface menu item Callback functions.

System defined callback points

ApplicationServiceEnd

Interface

No input or output parameters.

Called when

ApplicationServiceEnd is called when the Application Service exists.

Influence on later functionality

None.

Example of use

Used to perform clean-up processing that must be done before the Application Service exits.

If you have used the ApplicationServiceStart callback point to connect/logon to a back-end system (e.g. an ERP system), you need want to disconnect from/log off this system.

ApplicationServiceStart, ApplicationServiceEnd, HandlingRequestStart, and HandlingRequestEnd can be used together to write log information about the system to a file.

ApplicationServiceStart

Interface

No input or output parameters.

Called when

ApplicationServiceStart is called when the Application Service starts.

Influence on later functionality

None.

Example of use

Used to allocate resources that should be used by the Application Service and are shared by all requests; e.g. connection to back-end systems (for example ERP systems).

ApplicationServiceStart, ApplicationServiceEnd, HandlingRequestStart, and HandlingRequestEnd can be used together to write log information about the system to a file.

BeforeRequestStart

Interface

Call the API CallbackOutputSet to return the information to the calling function.

Called when

BeforeRequestStart is called after the request has been received by the runtime, but before any handling of the request has been performed.

Influence on later functionality

Setting the output parameter to Yes will let the normal handling proceed.

Setting the output parameter to No will stop all handling of the request.

This means that the callback function offers the possibility to take full control of the handling of a request.

Please note that this includes all handling - including calling a PageGenerator function if you want anything to be sent to the browser.

You must also note that the request has not been parsed or in any way interpreted by this function. If you do need to use this function contact websydian support with a description of your case to obtain information about how you can retrieve the relevant request headers and the request body.

Example of use

The case for this callback function was an installation, where it also was necessary to be able to process web service requests.

By checking the content type header it was possible to find the requests that contained xml - and to let the function call a service function that was specially designed to handle the web service requests. After calling the service function that handled the web service request, the ContinueHandling flag was set to No to prevent the normal handling of the request.

HandlingRequestStart

Interface

No input or output parameters.

Called when

HandlingRequestStart is called when a request is received and the request parameter string has been parsed and written to memory.

Influence on later functionality

None.

Example of use

At this point, you can use the GetInput API to retrieve information about the parameters specified on the request.

ApplicationServiceStart, ApplicationServiceEnd, HandlingRequestStart, and HandlingRequestEnd can be used together to write log information about the system to a file.

HandlingRequestEnd

Interface

No input or output parameters.

Called when

HandlingRequestEnd is called when the processing of a request is ended.

Influence on later functionality

None.

Example of use

Used to perform any clean-up processing that must be done at the end of a request.

ApplicationServiceStart, ApplicationServiceEnd, HandlingRequestStart, and HandlingRequestEnd can be used together to write log information about the system to a file.

IsSessionInIntranet

Interface

Use the API CallbackGetInput to retrieve the input parameters and the API CallbackOutputSet to return the output parameter to the calling function.

Called When

The functions is called when a session is created in order to determine whether a session belongs to the Intranet or the Extranet.

The function is called immediately after the runtime has determined whether the session is in the intranet based on the intranet mask specified in the site settings.

Influence on later functionality

Based on the value of the field IsIPInIntranet the assignment of roles to the session will be affected.

Example of use

The IP intranet mask in WebsydianExpress is specified as a partial IP address, e.g. "192.168.".

In more complex network environments it could be necessary to specify a more advanced IP mask. E.g. like "192.168.0.0/255.254.0.0". In this case it will be necessary to implement this callback function and check whether the IP address on the session belongs to the specified IP mask.

As for all the callback points, several callback functions can be defined for the IsSessionInIntranet callback point. This means that there is the possibility that the one runtime has determined that the session is not in the intranet, one callback function has determined that the session is in the intranet and yet another function has determined that it is not in the intranet (all based on the rules implemented by the callback functions). In all these cases, the output last callback function determines whether the session will be handled as being in the intranet.

To make it possible for the callback function to take the results of the runtime and any previously called callback functions for the callback point into consideration, the current state of the IsIPInIntranet is transferred as an input parameter to the callback function. It is up to the developer to determine whether he will take this value into account.

You can specify the sequence in which the callback functions will be called using the administration interface menu item callback functions.

SessionAfterCreate

Interface

Call the API CallbackInputGet to retrieve the session id.

Called when

SessionAfterCreate is called immediately after the session has been created by the initial request. This is done before the site is loaded.

Influence on later functionality

No direct effect - but the possibility to e.g. add roles to the session can result in significant effects on the site load.

Example of use

If the initial request contains information that can be used to log a user in to the session, the user check and the update of the session can be done here. By updating the user and roles for the session (e.g. by calling the API SetUserAndUpdate) the site will be loaded as if the user had logged in using the "standard" login page.

UserAfterCreate

Interface

Call the API CallbackInputGet to retrieve the user id.

Called when

The function is called from the Insert event handler function on the Insert User page. It is called just after the call to the function creating the user if the creation has been successful.

Influence on later functionality

None.

Example of use

An example could be the case where the WebsydianExpress user table and other user tables used inside the company must be synchronized. Every time a new user is created in WebsydianExpress a corresponding user must be created in the other user tables.

The implemented callback function can read the information for the created user by calling the server API UserGet. It is then possible to call functions for creating users in the other tables.

UserAfterDelete

Interface

Call the API CallbackInputGet to retrieve the information.

Called when

The function is called from the Delete event handler function on the Confirm Delete User page. It is called just after the call to the function deleting the user if the deletion has been successful.

Influence on later functionality

None.

Example of use

The WebsydianExpress user table and other user tables used inside the company must be synchronized. Every time a user is deleted in WebsydianExpress the corresponding users must be deleted in the other user tables.

As the user at this point has been deleted more information cannot be found by calling API functions, but depending on how the user tables references each other either the user surrogate or the combination of login name and site key should be sufficient to identify the records in the other tables.

UserAfterLogin

Interface

Call the API CallbackInputGet to retrieve the information.

Called when

The function is called just after a user has logged into WebsydianExpress and the session has been updated with the user and user roles.

Influence on later functionality

None.

Example of use

This callback function can be used to add extra roles to the session after a user has logged in, based on some external information; e.g. an ERP system.

Examples

In the delivered 2E model WXPMDL, you can find two simple implementations of callback functions. Both functions are scoped by the file WebsydianExpress Example.

The first example: "SessionAfterCreate.CB" shows how you can retrieve an input value specified by the calling program while the second example: "BeforeRequestStart.CB" shows how you can specify a return value for the calling parameter.