Callback Functions
Overview
Callback functions are functions that are called from the Websydian Express runtime and not by the developer.
The basic idea is to offer the developer the possibility to customize the behavior of Websydian Express by implementing these callback functions.
Implemented callback functions are delivered with the runtime and do not contain any functionality.
How to use the callback functions
Create a new function that inherits form the callback function and set the implementation name to the same as the inherited callback function.
Setting the implementation name to the one used for the callback function will result in an error. So the way to do this is by first setting the implementation name of the new function to the implementation name of the callback function followed by an "x", and then rename the NAME object to remove the "x".
You are now ready to implement the callback function by inserting action diagram code and/or adding triples.
Web server callback functions
The web server callback functions are scoped under WSYAPI/CallbackFunctions.WebServer. These callback functions reside on the web server and are thus only called by other web server functions.
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.
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.
ApplicationServiceStart, ApplicationServiceEnd, HandlingRequestStart, and HandlingRequestEnd can be used together to write log information about the system to a file.
BeforeRequestStart
Interface
| Field | Variable | Description |
|---|---|---|
| ContinueHandling | Output | Specifies whether the request should be handled by the Websydian Runtime |
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
When creating the callback function also inherit from PopulateWebInputVariable so web input 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.
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.
SessionAfterCreate
Interface
| Field | Variable | Description |
|---|---|---|
| SessionSurrogate | Input | The unique identification of the session that has been created |
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
| Field | Variable | Description |
|---|---|---|
| UserSurrogate | Input | The unique identification of the user |
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
The Websydian Express user table and other user tables used inside the company must be synchronized. Every time a new user is created in Websydian Express 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
Interface
| Field | Variable | Description |
|---|---|---|
| UserSurrogate | Input | The unique identification of the user. |
| LoginName | Input | The login used by the deleted user. |
| UserSitekey | Input | Identifies the site the user was assigned to. The combination of login name and site uniquely identifies the user. |
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 Websydian Express user table and other user tables used inside the company must be synchronized. Every time a user is deleted in Websydian Express 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
| Field | Variable | Description |
|---|---|---|
| SessionSurrogate | Input | The unique identification of the session. |
Called when
The function is called just after a user has logged into Websydian Express 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
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserAuthLevel | Input | Input | The authorization level for the user. |
| UserFolderListID | Input | Input | Identifies the folder list that will be assigned to the user's session. |
| EmailAddress | Input | Input | The e-mail address of the user. |
| LoginName | Input | Input | The login name for the user. |
| FullName | Input | Input | The name of the user. |
| UserSitekey | Input | Input | Identifies the site the user will be able to use. |
| UserPassword | Input | Input | The password (unsigned) defined for the user. |
| UserStatus | Input | Input | Specifies the status the user will have. |
| CrtByUserSgt | Input | Input | Uniquely identifies the user creating the new user. |
| NumberOfErrors | Error | Output | Specifies the number of error messages in the output variable ErrorArray. |
| ErrorMessage | ErrorArray(10) | Output | An array containing up to 10 error messages that will be reported to the calling function. |
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 output variable is 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
Interface
| Field | Variable | ...as | Description |
|---|---|---|---|
| UserSurrogate | Input | Input | The unique identification of the user account that will be deleted. |
| NumberOfErrors | Error | Output | Specifies the number of error messages in the output variable ErrorArray. |
| ErrorMessage | ErrorArray(10) | Output | An array containing up to 10 error messages that will be reported to the user. |
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 is 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.
Server callback functions
The server callback functions are scoped under WSYAPI/CallbackFunctions.Server. These callback functions reside on the backend server and can thus be called by any function in Websydian Express.
IsSessionInIntranet
Interface
| Field | Variable | Description |
|---|---|---|
| SessionSurrogate | Input | The unique identifier for the session. |
| IPIntranetMask | Input | The IP intranet mask specified on site settings. |
| IsIPInIntranet | Output | Set to *Yes (Y) if the IP address on the session belongs to the specified IP intranet mask. Set to *No (N) otherwise. |
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.
Influence on later functionality
Based on the value of the field IsIPInIntranet the assignment of roles to the session will be affected. See here for more information.
Example of use
The IP intranet mask in Websydian Express 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.