Online documentation - WebsydianExpress v3.5 |
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.
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.
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.
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.
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.
Callback.WebServer.ApplicationServiceEnd.AbstractCallbackFunction
No input or output parameters.
ApplicationServiceEnd is called when the Application Service exists.
None.
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.
Callback.WebServer.ApplicationServiceStart.AbstractCallbackFunction
No input or output parameters.
ApplicationServiceStart is called when the Application Service starts.
None.
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.
Callback.WebServer.BeforeRequestStart.AbstractCallbackFunction
Field | Variable | Description |
---|---|---|
ContinueHandling | CallbackOutput | Specifies whether the request should be handled by the Websydian Runtime |
See Handling parameters for information about parameters for callback functions.
BeforeRequestStart is called after the request has been received by the runtime, but before any handling of the request has been performed.
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.
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.
Callback.WebServer.HandlingRequestEnd.AbstractCallbackFunction
No input or output parameters.
HandlingRequestEnd is called when the processing of a request is ended.
None.
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.
Callback.WebServer.HandlingRequestStart.AbstractCallbackFunction
No input or output parameters.
HandlingRequestStart is called when a request is received and the request parameter string has been parsed and written to memory.
None.
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.
Callback.WebServer.SessionAfterCreate.AbstractCallbackFunction
Field | Variable | Description |
---|---|---|
SessionSurrogate | CallbackInput | The unique identification of the session that has been created |
See Handling parameters for information about parameters for callback functions.
SessionAfterCreate is called immediately after the session has been created by the initial request. This is done before the site is loaded.
No direct effect - but the possibility to e.g. add roles to the session can result in significant effects on the site load.
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.
Callback.WebServer.UserAfterCreate.AbstractCallbackFunction
Field | Variable | Description |
---|---|---|
UserSurrogate | CallbackInput | The unique identification of the user |
See Handling parameters for information about parameters for callback functions.
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.
None.
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.
Callback.WebServer.UserAfterDelete.AbstractCallbackFunction
Field | Variable | Description |
---|---|---|
UserSurrogate | CallbackInput | The unique identification of the user. |
LoginName | CallbackInput | The login used by the deleted user. |
UserSitekey | CallbackInput | Identifies the site the user was assigned to. The combination of login name and site uniquely identifies the user. |
See Handling parameters for information about parameters for callback functions.
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.
None.
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.
Callback.WebServer.UserAfterLogin.AbstractCallbackFunction
Field | Variable | Description |
---|---|---|
SessionSurrogate | CallbackInput | The unique identification of the session. |
See Handling parameters for information about parameters for callback functions.
The function is called just after a user has logged into WebsydianExpress and the session has been updated with the user and user roles.
None.
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.
Callback.WebServer.UserValidateBeforeCreate.AbstractCallbackFunction
Field | Variable | Description |
---|---|---|
UserAuthLevel | CallbackInput | The authorization level for the user. |
UserFolderListID | CallbackInput | Identifies the folder list that will be assigned to the user's session. |
EmailAddress | CallbackInput | The e-mail address of the user. |
LoginName | CallbackInput | The login name for the user. |
FullName | CallbackInput | The name of the user. |
UserSitekey | CallbackInput | Identifies the site the user will be able to use. |
UserPassword | CallbackInput | The password (unsigned) defined for the user. |
UserStatus | CallbackInput | Specifies the status the user will have. |
CrtByUserSgt | CallbackInput | Uniquely identifies the user creating the new user. |
NumberOfErrors | CallbackOutput | Specifies the number of error messages in the output variable ErrorArray. |
ErrorMessage | ErrorArray(10) | An array containing up to 10 error messages that will be reported to the calling function. |
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.
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.
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.
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.
Callback.WebServer.UserValidateBeforeDelete.AbstractCallbackFunction
Field | Variable | Description |
---|---|---|
UserSurrogate | CallbackInput | The unique identification of the user account that will be deleted. |
NumberOfErrors | CallbackOutput | Specifies the number of error messages in the output variable ErrorArray. |
ErrorMessage | ErrorArray(10) | An array containing up to 10 error messages that will be reported to the user. |
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.
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.
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.
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.
Callback.WebServer.FindServiceProcessor.AbstractCallbackFunction
Field | Variable | Description |
---|---|---|
ServiceURLSurrrogate | CallbackInput | The unique identification of the URL element in the service structure that the runtime or a previously called callback function has determined as the one to use to find the service processor to call. |
SiteKey | CallbackInput | The unique identification of the site targeted by the request. |
RequestID | CallbackInput | The identification of the request being handled. |
EntryURL | CallbackInput | The URL specified for the request. |
ServiceURLMask | CallbackInput | The URL extension that is used by the runtime to find the URL element in the service structure. |
ServiceProcessorImplName | CallbackInput | The implementation name of the service processor to call as it has been determined by the runtime or a previously called callback function. |
ServiceURLSurrrogate | CallbackOutput | The unique identification of a URL element. Specify a value for this field if you want to a URL element in the service structure to control the further handling of the request. |
ServiceProcessorImplName | CallbackOutput | The implementation name of a service processor.
Specify a value for this field if you do not want to use the service structure to control the further handling of the request. The specified program must have the interface specified by the Abstract.ServiceProcessor function. |
IntranetOnly | CallbackOutput | If you do not specify a value for the ServiceURLSurrogate, you can use this field to specify whether the service processor specified by the ServiceProcessorImplName is allowed to be called if the request comes from outside the intranet. |
See Handling parameters for information about parameters for callback functions.
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.
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.
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.
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.
Callback.Server.IsSessionInIntranet.AbstractCallbackFunction
Field | Variable | Description |
---|---|---|
SessionSurrogate | CallbackInput | The unique identifier for the session. |
IPIntranetMask | CallbackInput | The IP intranet mask specified on site settings. |
IsIPInIntranet | CallbackInput | The current setting of the Flag determining if the session is in the intranet. |
IsIPInIntranet | CallbackOutput | Set to *Yes (Y) if the IP address on the session belongs to the specified IP intranet mask. Set to *No (N) otherwise. |
See Handling parameters for information about parameters for callback functions.
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.
Based on the value of the field IsIPInIntranet the assignment of roles to the session will be affected.
Find more information here
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.