Websydian v6.1 online documentationOnline documentation - Websydian v6.1

Upgrade Guide to Websydian Version 2.0


This Upgrade Guide is aimed at development sites that already have build CA Plex models based on Websydian version 1.3 and want to move those to Websydian version 2.0.

A number of changes have been made in Websydian version 2.0 as compared with version 1.3, and some of these changes result in manual updates that must be done to CA Plex models being moved from Websydian version 1.3 to version 2.0.

This document lists the update steps to be performed on each type of Websydian function (Page Generator, Document Template Generator, Event Handler, Dispatcher) in order to upgrade a model to version 2.0.

As seen from the steps below, the upgrade tasks is quite simple.  You should calculate on spending somewhere between 5 and 15 minutes of work per Websydian function in the model to be upgraded (depending on the complexity of the functions).

When to Upgrade?

You should upgrade your CA Plex model(s) if you are going to use the Sterling Pattern libraries coming with version 3.5 of CA Plex.

Upgrading is also necessary, if you want to use any of the new facilities/modules coming with Websydian 2.0 - e.g. User Management, Audit Control, Shopping Cart, and Utility modules or the stronger features for Document Template generation.

You do not need to upgrade those CA Plex models, where you plan to keep on using the OBASE class library.  In this case, upgrading the 1.3 version of the Websydian libraries to the new versions of CA Plex will do.

Upgrading the Page Generators

The following changes should be applied to each Page Generator function.

Change Inheritance of Page Generators

In version 1.3, Page Generators inherit from either the WSYD Page generator - Details or the WSYD Page generator - Grid pattern.  When upgrading to Websydian 2.0, Page Generator functions must inherit from the PageGenerator pattern or from patterns based on PageGenerator.

In version 2.0, no explicitly Grid Page Generator is defined.  Grid functionality is implicitly specified by declaring fields in the WsyGrid variable.

It is common in a Websydian/CA Plex model to define a 'template' Page Generator pattern from which other Page Generators in the model inherit.  If your design is structured like this, you will only need to change the inheritance of the template function.

Inheritance instead of Name Options

Along with the multiple inheritance capabilities of CA Plex 3.5, the design of Websydian has been changed accordingly.  Instead of having one large pattern where different options can be selected or deselected, selection of additional features are specified by inheritance.

For the Page Generator pattern, this principle has been applied for the following 1.3 options:

1.3 Name Option Corresponding 2.0 Pattern Old Default
WSYD Internal to external PageGeneratorWithFieldConversion Yes
WSYD Map literal values to names PageGeneratorWithValueMapping Yes
WSYD Convert HTML special chars PageGeneratorWithCharConversion Yes

The FullPageGenerator Utility pattern includes all of the above patterns.

Inheritance for Signature

Any Page Generator function using one or more Event Handlers with digital signature must inherit from the PageGeneratorWithSignature pattern.

Use WsyDetails/WsyGrid instead of Details/Grid Variables

In the model editor for each Page Generator function, all references to the OBASE/Details variable must be changed to the WsyDetails variable.  The same step must be performed for the OBASE/Grid variable being changed to WsyGrid.

Adjust Action Diagrams

After having replaced the Details and Grid variables, open the action diagram of the Page Generator function to do the final adjustments.  When opening the action diagram, an error message will appear in the Message Log for each removed reference to the Details and Grid variables.

These invalid references (used in action diagram statements or in parameter mapping) must be replaced with the corresponding references to the WsyDetails and WsyGrid variables.

Change Scope of Event Handler Functions

In Websydian version 1.3, a 'dummy' function needs to be defined for each HTML page in the application scoping the Page Generator function and the Event Handlers of the page.   This structure is necessary for the Document Template Generator function to work correctly.

In version 2.0, Event Handlers are scoped directly under the Page Generator function making the structure more simple (no dummy functions needed).  On the other hand, it is also possible to stay with the old way of organizing the Page Generators.  This is done by setting the Name option WSYD Old scope of the Document Template Generator function to Yes.

This means that for each Page Generator function, you will either have to change structure or to set the WSYD Old scope option of the Page Generator to Yes.

Upgrading the Document Template Generators

The name of the Document Template Generator functions scoped under the Page Generators has been changed from WSYD Document template generator to _DocumentTemplateGenerator.  After having changed the inheritance of the Page Generator functions, each Page Generator will now have two Document Template Generators scoped under them.

Any triple-declaration made for the old WSYD Document template generator function needs to be moved to the new _DocumentTemplateGenerator function (e.g. implementation names and option declarations).  After this, the old Document Template Generator can be deleted from the model.

Likely, there will be no additional action diagram coding specified inside the Document Template Generator functions - or this code would have to be transferred as well.

Upgrading the Event Handlers

The following changes must be applied for each Event Handler function in the model.

Change Inheritance of Event Handlers

In version 1.3 of Websydian, Event Handlers inherit from the WSYD Event handler pattern. When upgrading to Websydian 2.0, Event Handler functions must inherit from the EventHandler pattern or from patterns based on EventHandler.

In a CA Plex model using Websydian it is often seen that a 'template' Event Handler pattern is defined from which other Event Handler functions in the model inherit.  If your design is structured like this, you will only need to change the inheritance of this template function.

Inheritance instead of Name Options

For the Event Handler pattern, the following function options have been replace with pattern inheritance - i.e. instead of setting options, the analogous inheritance is specified for the version 2.0 Event Handlers:

1.3 Name Option Corresponding 2.0 Pattern Old Default
WSYD Validate input fields EventHandlerWithValidation Yes
WSYD External to internal EventHandlerWithFieldConversion Yes
WSYD Sign hidden fields EventHandlerWithSignature Yes

The FullEventHandler Utility pattern includes the first two of the above patterns.

Now Possible to Use Views in WebInput and Hidden (Optional)

In version 1.3 of Websydian, the Document Template generation only worked correctly if the input fields of the associated Event Handler functions were declared field by field (with FNC local FLD triples).  In version 2.0, it is now possible to declare entire views for the WebInput (former WSYD View validation) and the Hidden (former WSYD Hidden) variables.

The IdentifyInputFields functions scoped under the Event Handler functions in version 2.0 are called by the Document Template Generators (as well as the Page Generators) and they will identify the input fields and the hidden fields of each Event Handler function.

Use TargetRelations instead of Relation check Variable

The old OBASE/Relation check variable must be replaced by the TargetRelations variable.  The target relations will only be validated if the Event Handler function inherits from the EventHandlerWithValidation pattern.

Use WsyBase instead of Base Variable

If the local field Base<Instance valid> is referred explicitly in any action diagram statements, the field references must be replaced by the WsyBase<InstanceValid> local field.

The WsyBase<InstanceValid> field is only available if the Event Handler inherits from the EventHandlerWithValidation pattern.

Upgrading the Dispatcher

The Dispatcher function of version 1.3 has scoped under it a WSYD Start user session function.  The name of this function has been changed to CallFirstPageGenerator which means that the Dispatcher function during the transition will be scoping the old as well as the new function.

Copy all the triples from the old WSYD Start user session function to the new CallFirstPageGenerator function and do also specify the same action diagram statements in the new function.  Typically, the WSYD Start user session function will only contain a call to the Page Generator function generating the entry page of the application.

Having defined the CallFirstPageGenerator function, the old WSYD Start user session function can be deleted from the model.

Other Upgrading Issues

A few other issues remain in the upgrading process.

Using the Session Library

If the application is implementing Session Management, a few changes will be needed.  A new Session entity should be implemented inheriting from the SessionControl pattern (see the Implementing page of the Session Management module for more details).

The Dispatcher function and all the Page Generator functions and Event Handler functions implementing Session Management will inherit from the abstract functions in Web function suite scoped under the old Session entity.  This inheritance must be changed to the corresponding patterns scoped under the Abstract entity of the new Session functionality.

If the application is already implemented and running with live data, the new Session table should be implemented with the same implementation names (for the table as well as the fields), or the data should be moved to the new Session table.

The SessionID field now inherits from the FIELDS/Surrogate field and the length of the field has been accordingly changed from 15 to 9.  If you want to keep the old length of the Session field, you need to define your own Session ID field to replace the existing SessionID for the Session entity.

When all inheritance triples have been redirected and the correct implementation names have been set, the old Session entity and its scoped objects can be deleted from the application.

Re-generate and Build

All Websydian functions should now be re-generated and re-build - also the new IdentifyInputFields functions scoped under the Event Handlers - and the application should be tested with the updated functions.  The Document Template Generators may be run for test purposes - the generated Document Templates will be identical to the old ones.

Note! Do not replace any of your modified Document Templates!

Cut Relation to the OBASE Library

When this guide has been followed for the entire Websydian application (and the Websydian application is up running again), there will be no more references to objects in the OBASE library - OBASE references should also have been removed for other parts of the application.  When there are no more OBASE references in the model, you can log into group model as Administrator and remove the OBASE library (as well as the old Websydian libraries) from the group model library list.