Callback Functions

Overview

The WebsydianExpress runtime offers a number of callback points. Each of these callback points offers the possibility to introduce custom functionality that will be executed each time the callback point is reached by the runtime.

This document describes how you can create functions that are able to be called in these situations - and how you must define these functions in the administration interface to make the runtime call the functions automatically.

The document also describes each callback point implemented by the runtime and offers a short introduction to how the callback point might be used.

How to implement callback functions

Inheritance

WSYAPI/CallbackFunctions.CallbackPoints scopes two functions:

1. Server

2. WebServer

These functions scope the callback points implemented by the WebsydianExpress runtime.

Each callback point scopes an function called AbstractCallbackFunction.

Implement your own callback function for the callback point by inheriting from the scoped AbstractCallbackFunction.

After inheriting from the abstract function, you can make your custom functionality in the action diagram of the function that inherits from the AbstractCallbackFunction.

Handling parameters

As the callback functions are called dynamically, it has been necessary to create a special way to transfer parameters between the callback point and the callback functions it calls.

Instead of using variables placed in the Input and Output variable groups of the action diagram of the callback functions, two local variables CallbackInput and CallbackOutput are used instead.

The runtime populates the variable CallbackInput with values set by the callback point. Use this variable a normal input variable. If there are no fields in the CallbackInput variable, the callback function has no input.

The runtime transfers the values in the fields in the variable CallbackOutput to the callback point when the callback function terminates. Assign values to the fields in this variable as if it was a normal output variable. If there are no fields in the CallbackOutput variable, the callback function has no output.

Adding the callback 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.

Web server callback functions

The web server callback points used by the WebsydianExpress runtime  are scoped under WSYAPI/CallbackFunctions.CallbackPoints.WebServer. The callback points scope the abstract callback functions you must inherit from to implement your own callback functions for these callback points.

ApplicationServiceEnd

Inherit from

Callback.WebServer.ApplicationServiceEnd.AbstractCallbackFunction

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

Inherit from

Callback.WebServer.ApplicationServiceStart.AbstractCallbackFunction

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

Inherit from

Callback.WebServer.BeforeRequestStart.AbstractCallbackFunction

Interface

See Handling parameters for information about parameters for callback functions.

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.

HandlingRequestEnd

Inherit from

Callback.WebServer.HandlingRequestEnd.AbstractCallbackFunction

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.

HandlingRequestStart

Inherit from

Callback.WebServer.HandlingRequestStart.AbstractCallbackFunction

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

When creating the callback function also inherit from PopulateWebInputVariable so webinput fields are available in the WebInput variable.

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

SessionAfterCreate

Inherit from

Callback.WebServer.SessionAfterCreate.AbstractCallbackFunction

Interface

See Handling parameters for information about parameters for callback functions.

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

Inherit from

Callback.WebServer.UserAfterCreate.AbstractCallbackFunction

Interface

See Handling parameters for information about parameters for callback functions.

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 UserSingleFetch. It is then possible to call functions for creating users in the other tables.

UserAfterDelete

Inherit from

Callback.WebServer.UserAfterDelete.AbstractCallbackFunction

Interface

See Handling parameters for information about parameters for callback functions.

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

Inherit from

Callback.WebServer.UserAfterLogin.AbstractCallbackFunction

Interface

See Handling parameters for information about parameters for callback functions.

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.

UserValidateBeforeCreate

Inherit from

Callback.WebServer.UserValidateBeforeCreate.AbstractCallbackFunction

Interface

See Handling parameters for information about parameters for callback functions.

The interface of this function is a bit special. As it can return a number of error messages the ErrorMessage field can't just be added to the CallbackOutput variable. A multi-occurrence local variable ErrorArray has been added. The values placed in the ErrorArray will be transferred to the callback point just as the values of fields in the CallbackOutput variable.

Called When

The function is called from the Insert event on the Insert User page. The function is called before the user is created, but after the validation performed by the administration interface has been executed.

This function can be used to ensure that only users that are acceptable to specific rules will be created.

Influence on later functionality

If the *Returned status is set to *Successful, the user will be created (unless the normal validation performed by the administration interface has found errors).

If the *Returned status is not set to *Successful, the user will not be created.

All error messages in the ErrorArray local variable will be shown to the user on the insert page (NumberOfErrors must specify the number of records to show). If no error messages are returned a generic error message is shown.

Example of use

A user must only be created if the login name is not used in the user table of another application.

Create a new version of the function. Call a function checking whether the login name already is used in the other application. If the login name is already used set the *Returning Status to *Error, write a message stating the problem in the first record of the ErrorArray variable and set the NumberOfErrors field to *One.

UserValidateBeforeDelete

Inherit from

Callback.WebServer.UserValidateBeforeDelete.AbstractCallbackFunction

Interface

See Handling parameters for information about parameters for callback functions.

The interface of this function is a bit special. As it can return a number of error messages the ErrorMessage field can't just be added to the CallbackOutput variable. A multi-occurrence local variable ErrorArray has been added. The values placed in the ErrorArray will be transferred to the callback point just as the values of fields in the CallbackOutput variable.

Called When

The function is called from the Delete event handle on the User GridPage. The function is called just before the user is deleted, but after the validation done by the administration interface programs has been performed. The function is only called if this validation has been successful.

Influence on later functionality

If the *Returned status is set to *Successful, the confirm page for delete user will be shown, and if the user press Delete on this page the user will be deleted.

If the *Returned status is not set to *Successful, the user will not be deleted. The grid page will be shown again.

All error messages in the ErrorArray will be shown shown to the user on the grid page (NumberOfErrors must specify the number of records to show). If no error messages are returned a generic error message is shown.

Example of use

The user is stamped on transaction records in the application database. If the user has created any records he must not be deleted.

Make a new version of the function. In the action diagram code check whether the user has created any records. If he has set the *Returning Status to *Error, write a message stating the problem in the first record of the ErrorArray and set the NumberOfErrors field to *One.

FindServiceProcessor

Inherit from

Callback.WebServer.FindServiceProcessor.AbstractCallbackFunction

Interface

See Handling parameters for information about parameters for callback functions.

Called When

The callback point is called when the runtime has identified a request as being a web service request. At this point the runtime has performed the default identification of the URL element in the service structure based on the URL of the request.

The information about which URL element the runtime has identified is transferred in the CallbackInput<ServiceURLSurrogate> field. If this is blank, the runtime has not been able to identify a URL element.

Influence on later functionality

By adding a callback function to this callback point, you assume full control over which URL element/service processor that will be used to handle the request.

You can either specify the identification of the URL element (ServiceURLSurrogate) in CallbackOutput or you can specify the implementation name of a service processor (ServiceProcessorImplName).

If you specify a ServiceURLSurrogate, the runtime will use this URL element to find the service processor to call and this service processor will be able to use the definitions in the service structure to identify the service handler that will ultimately handle the request.

If you specify a ServiceProcessorImplName instead of the ServieURLSurrogate, this function will be called - but as the URL element in the service structure has not been identified, the program will have to have its own method for determining how the request should be handled.

If you do not specify any value for SerrviceURLSurrogat and ServiceProcessorImplName, the runtime will return an error to the client (unless a callback function called after the current one returns values for one of these fields).

If you in cases where the custom functionality does not determine a special service processor to call want to use the values determined by the runtime/a previously called callback function, you must assign the value for the CallbackInput<ServiceURLSurrogate> to CallbackOutput<ServiceURLSurrogate>.

If several callback functions are called, the last function will determine the URL element / service processor to call.

Example of use

One case could be if it is necessary that all services are provided on the same URL (maybe because this makes it easier to setup special access for the services). This means that the "normal" way of finding a service processor can't be used - as it uses a part of the URL to identify the URL element.

You want to use a special http-header to identify the service processor to call, you can do it in the following manner.

In the service structure, specify the value of the http-header in the URL Mask field.

Create a callback function for this callback point.

In this function, extract the http-header (e.g. using the WSYBASE/GetHeaderOrEnvironmentVariable). Use the GetServiceURLsForSite API to find the URL element that corresponds to the header value and specify the ServiceURLSurrogate for the URLElement in CallbackOutput.

Server callback functions

The server callback point are scoped under WSYAPI/CallbackFunctions.CallbackPoints.Server. Each callback point scopes the abstract callback function you must inherit from to implement a callback function for the callback point.

IsSessionInIntranet

Inherit from

Callback.Server.IsSessionInIntranet.AbstractCallbackFunction

Interface

See Handling parameters for information about parameters for callback functions.

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.