Upgrade from version 3.2 to version 4.0
Warning: This upgrading note is a work in progress DRAFT
Introduction
The version 4.0 have some significant changes if compared to version 3.x that requires some attention if you are considering a migration from such a previous version.
Removed features
- Removed support for old technical platforms (e.g. J2EE 1.4), replaced by support for new technical platforms
- Removed features and APIs marked as outdated deprecated in previous version(s), see bellow
- Changed URL patterns (with some backward compatibility however) and removed the legacy web services gateway webapp (replaced by the
/apiendpoint introduced in version 3.1), see bellow - Removed naming flexibility for grant hooks shared script (the previously allowed
GRANTHOOKSname is now forbidden, it must now beGrantHooks)
Old implementation patterns to refactor
These implementation patterns that used to be possible, but already strongly discouraged, in previous versions must be now refactored:
- Any usage of any hard coded URLs (see bellow) in your code or configured items (e.g. shortcuts, UI zones, actions, ...) must be avoided,
you must use the
HTMLToolmethods instead (directly in your code or using `[EXPR:(...)] in configuration items). - Specific JSP pages are not supported anymore. You must now rewrite them as external objects
- As for any previous version making DOM structure assumptions in generic web pages (e.g. using custom low-level JavaScript/jQuery statements to dynamically change inputs, buttons, etc... using their generated DOM Id) is a very bad approach, you should use the client JavaScript APIs instead. If you have any legacy code making such assumptions you must refactor it as many web components have been completely refactored at DOM level.
- Legacy synchronous JavaScript services have been removed (these functions used to be defined in the
service.jsscript and were only versions 2.x's backward-compatibility synchronous wrappers ofSimplicite.Ajax, this script does not exist anymore) - Adding custom global styles using the static
application.cssfile is not possible anymore, this is replaced by the disposition-levelSTYLESresource - Adding custom global JS scripts using the static
application.jsfile is not possible, this is replaced by the disposition-levelSCRIPTresource - When using external authentication (e.g. OAuth2) the user data is now updated automatically, you don't need to handle the
SESSION_INFOparameter anymore (except if you have something more specific to do with it) - The deprecated
$client JavaScript function in legacy UI,$is now the usual alias tojQuery(the old$jalias is kept for compatibility but it is recomended to change it to$), if you have some legacy JavaScript code using the deprecated$instead of the$jQuery alias you must refactor them (e.g.$("myid")must be rewritten as$("#myid")[0]) - In scripted expressions, the deprecated syntax
[<field name>]is not longer supported, you must use the syntax[VALUE:<field name>]instead - The legacy UI components (e.g.
ObjectList) have been removed from default packages imported in Rhino scripts (if you use some of them you need to add an explicit package import statementimportPackage(Packages.com.simplicite.webapp)or an individual class import statement (e.g.importClass(Packages.com.simplicite.webapp.ObjectList)
Deprecated implementation patterns
These implementation patterns are to be considered deprecated, their usage is to be avoided (and any existing usage is to be refactored) as they will be removed in next version:
- Using any of the legacy JavaScript functions and variables not in the
Simplicitenamespace is strongly discouraged
URL patterns
The version 4.0 includes a complete refactoring of the generic UI URL pattern.
Prerequisites
If you are using traditional realm-based or JAAS authentication, make sur to update your web.xml accordingly to the one provided.
In particular make sure to have both /ui/* and /jsp/* as protected URL pattern in the <security-constraint/> bloc:
<url-pattern>/ui/*</url-pattern>
<url-pattern>/jsp/*</url-pattern>And if you are using a form-based authentication make sure your web.xml has the following login page declaration in the <login-config/> bloc:
<form-login-page>/login</form-login-page>
<form-error-page>/login?error=true</form-error-page>You will also need to make sure you have the following error mappings in your web.xml:
<error-page>
<error-code>404</error-code>
<location>/error?code=ERR_HTTP404&status=404</location>
</error-page>
<error-page>
<error-code>500</error-code>
<location>/error?code=ERR_HTTP500&status=500</location>
</error-page>Note: In this version, the old legacy JSP pages and the
/jsp/directory are kept for backward compatibility but they are marked as outdated deprecated. This means they will disapear in the next version.
Custom code impacts
If you are already using the HTMLTool methods (which you should), the changes are transparent.
If you have any hardcoded URL (which you should not), you must now use the HTMLTool methods instead.
URL pattern changes
The changes are described bellow (the new URL patterns are given for information and must not be hardcored but designated using the available HTMLTool methods):
| Old URL pattern | New URL pattern | HTMLTool method(s) to use |
|---|---|---|
| /index.jsp | / or /main | getPublicMainURL |
| /init.jsp | n/a (cf. ServletTool class) |
n/a |
| /logon.jsp | /signin or /login | getLoginURL |
| /logout.jsp | /signout or /logout | getLogoutURL |
| /PUB_work.jsp | /home | getPublicHomeURL |
| /PUB_content.jsp and /jsp/ALL_content.jsp | /content | getStaticContentURL |
| /PUB_resource.jsp | /resource | getResourceURL and variants |
| /PUB_document.jsp | /document or /dbdoc | getPublicDocumentURL |
| /PUB_extobject.jsp?extobject=<external object name> | /ext/<external object name> | getPublicExternalObjectURL |
| /PUB_zone.jsp | /zone | n/a |
| /PUB_gcalendar.jsp | /googlecalendar | getGoogleCalendarURL |
| /PUB_gmap.jsp | /googlemap | getGoogleMapURL |
| /PUB_agenda.jsp | n/a (removed) | n/a |
| /PUB_print.jsp | n/a (removed) | n/a |
| /PUB_data.jsp | /raw/data | n/a |
| /PUB_json_app.jsp | /json/app | n/a |
| /PUB_json_obj.jsp | /json/obj | n/a |
| /PUB_json_pcs.jsp | /json/pcs | n/a |
| /PUB_error.jsp and /jsp/SYS_error.jsp | /error | getErrorURL |
| /GDG_logon.jsp | /connect | n/a |
| /GDG_gmap.jsp | /map | getMapURL |
| /GDG_news.jsp | /news | getPublicNewsURL |
| /GDG_rss.jsp | /rss | getRSSURL |
| /GDG_media.jsp | /media | getMediaURL |
| /webContent.jsp | /web/ | n/a |
| /webContentPage.jsp | /web/page | n/a |
| /rss.jsp | /web/rss | n/a |
| /io.jsp | /io | n/a |
| /health.jsp | /health | n/a |
| /blank.html | /blank | n/a |
| /scripts/core.js (static) | /scripts/core.js (dynamic) | n/a |
| /scripts/common.js.jsp | /scripts/common.js | n/a |
| /images/main.css.jsp | /images/main.css | n/a |
| /images/work.css.jsp | /images/work.css | n/a |
| /jsp/index.jsp | /ui/ or /ui/main | getMainURL |
| /jsp/init.jsp | n/a (cf. ServletTool class) |
n/a |
| /jsp/index.jsp?_header=true | /ui/header | getHeaderURL |
| /jsp/index.jsp?_shortcut=true | /ui/shortcuts | getShortcutsURL |
| /jsp/SYS_mdlchooser.jsp | /ui/modulechooser | getModuleChooserURL |
| /jsp/SYS_subhead.jsp | /ui/subhead | getSubHeaderURL |
| /jsp/index.jsp?_footer=true | /ui/footer | getFooterURL |
| /jsp/SYS_scope.jsp | /ui/scopes | gestScopesURL |
| /jsp/SYS_work.jsp | /ui/home | getHomeURL |
| /jsp/SYS_work.jsp?view=<view name> | /ui/home?view=<view name> | getViewURL |
| n/a | /ui/menu | getMenuURL |
| /jsp/index.jsp?_extra=true | /ui/extra | getExtraURL |
| /jsp/SYS_extrapref.jsp | /ui/extrapreferences | getExtraPreferencesURL |
| /jsp/ALL_view.jsp | /ui/view | getSimpleViewURL |
| /jsp/ALL_export.jsp | /ui/importexport | getImportExportURL |
| /jsp/ALL_doc_edit.jsp | /ui/editor | getEditorURL |
| /jsp/ALL_index.jsp | /ui/indexsearch | getIndexSearchURL |
| /jsp/SYS_log.jsp | /ui/logs | getLogsURL |
| /jsp/GDG_treeview.jsp | /ui/treeview | getTreeviewURL |
| /jsp/GDG_print.jsp | n/a (removed) | n/a |
| /jsp/GDG_chat.jsp | n/a (now an external object) | n/a |
| /jsp/patch.jsp | /ui/undoredo | getUndoRedoURL |
| /jsp/GDG_news.jsp | /ui/news | getNewsURL |
| /jsp/SYS_zone.jsp | /ui/zone | n/a |
| /jsp/SYS_about.jsp | /ui/about | n/a |
| /jsp/SYS_calculator.jsp | /ui/caclulator | n/a |
| /jsp/ALL_docblob.jsp | /ui/document | getDocumentURL |
| /jsp/ALL_extobject.jsp?extobject=<external object name> | /ui/ext/<external object name> | getExternalObjectURL |
| /jsp/ALL_search.jsp?object=<object name> | /ui/obj/search/<object name> | getSearchURL |
| /jsp/ALL_list.jsp?object=<object name> | /ui/obj/list/<object name> | getListURL |
| /jsp/ALL_form.jsp?object=<object name> | /ui/obj/form/<object name> | getFormURL |
| /jsp/ALL_panel.jsp?object=<object name> | /ui/obj/panel/<object name> | getPanelURL |
| /jsp/ALL_select.jsp?object=<object name>&type=R | /ui/obj/reference/<object name> | getReferenceSelectURL |
| /jsp/ALL_select.jsp?object=<object name>&type=O | /ui/obj/objectref/<object name> | getObjectRefSelectURL |
| /jsp/ALL_select.jsp?object=<object name>&type=M | /ui/obj/datamap/<object name> | getDatamapSelectURL |
| /jsp/ALL_help.jsp?object=<object name> | /ui/obj/help/<object name> | getHelpURL |
| /jsp/ALL_update.jsp?object=<object name> | /ui/obj/updateall/<object name> | getUpdateAllURL |
| /jsp/ALL_merge.jsp?object=<object name> | /ui/obj/merge/<object name> | getMergeURL |
| /jsp/ALL_chart.jsp?object=<object name> | /ui/obj/chart/<object name> | getChartURL |
| /jsp/ALL_crosstab.jsp?object=<object name> | /ui/obj/crosstab/<object name> | getCrosstabURL |
| /jsp/ALL_graph.jsp?object=<object name> | /ui/obj/graph/<object name> | getGraphURL |
| /jsp/ALL_print.jsp?object=<object name> | /ui/obj/print/<object name> | getPrintTemplateURL |
| /jsp/ALL_agenda.jsp?object=<object name> | /ui/obj/agenda/<object name> | getAgendaURL |
| /jsp/ALL_placemap.jsp?object=<object name> | /ui/obj/placemap/<object name> | getPlaceMapURL |
| /jsp/ALL_timesheet.jsp?object=<object name> | /ui/obj/timesheet/<object name> | getTimesheetURL |
| /jsp/SYS_template.jsp?object=<object name> | /ui/obj/formpreview/<object name> | getFormPreviewURL |
| n/a | /ui/obj/docpreview/<object name> | getDocPreviewURL |
| /jsp/SYS_objpref.jsp?object=<object name> | /ui/obj/preferences/<object name> | getObjectPreferencesURL |
| /jsp/PCS_start.jsp?pcs=<workflow name> | /ui/pcs/start/<workflow name> | getProcessStartURL |
| /jsp/PCS_search.jsp?pcs=<workflow name> | /ui/pcs/search/<workflow name> | getProcessURL |
| /jsp/PCS_list.jsp?pcs=<workflow name> | /ui/pcs/list/<workflow name> | getProcessURL |
| /jsp/PCS_form.jsp?pcs=<workflow name> | /ui/pcs/form/<workflow name> | getProcessURL |
| /jsp/PCS_help.jsp?pcs=<workflow name> | /ui/pcs/help/<workflow name> | getProcessURL |
| /jsp/SYS_json.jsp | /ui/json/app | n/a |
| /jsp/ALL_json.jsp | /ui/json/obj | n/a |
| /jsp/PCS_json.jsp | /ui/json/pcs | n/a |
| /jsp/ALL_soap.jsp | /ui/soap | n/a |
| /jsp/ALL_wsdl.jsp | /ui/soap?wsdl=true | n/a |
| /jsp/ALL_xsd.jsp | /ui/soap?xsd=true | n/a |
| Legacy webservices gateway webapp URLs | /api/* | n/a |
Notes:
- Some of theses changes were already done in previous versions (typically 3.1 and 3.2) and the main
HTMLToolmethods already exists in these previous versions. You can start anticipating these changes even if you are using a previous version.- Any relative reference to a old JSP page located in the
/jsp/folder must now be done using an absolute reference (e.g./jsp/SYS_work.jsp) but, better, should be refactored using theHTMLToolclass methods decribed above
Dispositions
Responsive UI
In then version 4.0 responsive UI the former "disposition" concept has been split into 2 distinct concepts:
Disposition: that now corresponds only to the page layout (and which uses dedicated HTML resources for that)Theme: that corresponds to the page's styles (CSS, logos, ...)
In the responsive UI it it thus absolutely not required to create a custom disposition if you just want to change some styles. Doing this, as you would have done in versions 3.x, is an anti-pattern that must be avoided (unless you actually want to change the page layout).
Legacy UI
The version 4.0 legacy UI pages structures and CSS styles have been deeply refactored, if you had a 3.x custom disposition
with custom styles chances are it will no render the same in 4.0. You should reset to default disposition and create
new CSS styles overrides.
Upgrade procedure
Prerequisites
The update MUST be done on an up-to-date 3.2 version.
This means that all maintenance releases patches of version 3.2 have been sucessfully applied and verified.
To avoid issues the following system parameters must be reset to their suitable values for 4.0:
DISPOSITIONmust be set todefaultDISPOSITION_RESOURCESmust be set toyesPUBLIC_PAGESmust be set tonoSHOW_MOBILEmust be set to eitheryes(once migrated you will be able to change it todefault,alwaysornoif you want but not before migration)
Procedure
The following upgrade procedure is only applicable to instances managed on an instance manager (SIM), it MUST be done using command line.
- Connect on your instance's account:
sudo su - myinstance - Make a final update of your instance:
sim upgrade - Make a backup of your instance:
sim save - Make a complete backup of the instance's
tomcatfolder (in order to be able to revert manually to previous version if needed):cp -r tomcat tomcat-fefore.version.upgrade - Change your instance's version in the manager's database:
sqlite3 /var/simplicite/data/apps.db "update instances set version = '4.0' where name = 'myinstance'" - Apply all database-level patches:
sim ant-upgrade-configuration-db-only - Stop your instance:
sim stop - Manually check and update if needed your instances's deployment descriptors
META-INF/context.xmlandWEB-INF/web.xmlby comparing them to the default ones of version 4.0 (that you can find in/var/simplicite/template-4.0) - Upgrade tour instance's webapp:
sim ant-upgrade-war - Restart your instance:
sim start - Remove the patch level property file
rm tomcat/webapps/ROOT/WEB-INF/patches/V4.0/patches.properties - Apply all configuration-level patches:
sim ant-upgrade-configuration-xml-only
It is recommended to do a manual global clear cache using the generic web UI at the end of the process.