Upgrade from version 3.2 to version 4.0

Note: This document is evolving with every 4.0 release


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

Warning: The old legacy JSPs pages are scheduled to be removed in release P24. Seebeloww to refactor any hard-coded URL involving these JSPs.

Warning: The legacy UI is scheduled to be fully removed in release P25, you now need to consider refactoring all code/components dedicated to this legacy UI

Outdated implementation patterns to refactor

These implementation patterns that used to be possible, but already strongly discouraged, in previous versions must be now refactored:

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:

Warning: The legacy UI is scheduled to be removed in release P25, you now need to consider refactoring all code/components dedicated to this legacy UI

URL patterns

The version 4.0 includes a complete refactoring of the legacy UI URL patterns.

Note: With the responsive UI manipulating URLs does not make sense anymore, you need to use the client-side UI APIs, see this document for details.


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:


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:


You will also need to make sure you have the following error mappings in your web.xml:



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 describedbeloww (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


  • Some of theses changes were already done in previous versions (typically 3.1 and 3.2) and the main HTMLTool methods 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 the HTMLTool class methods decribed above


Responsive UI

In then version 4.0 responsive UI the former "disposition" concept has been split into 2 distinct concepts:

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.

Warning: the legacy UI is scheduled to be removed in release P25, you now need to consider refactoring all code/components dedicated to this legacy UI

Upgrade procedure


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:


The following upgrade procedure is only applicable to instances managed on an instance manager (SIM), it MUST be done using command line.

  1. Connect on your instance's account: sudo su - myinstance
  2. Make a final update of your instance: sim upgrade
  3. Make a backup of your instance: sim save
  4. Make a complete backup of the instance's tomcat folder (in order to be able to revert manually to previous version if needed): cp -r tomcat tomcat-fefore.version.upgrade
  5. 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'"
  6. Apply all database-level patches: sim ant-upgrade-configuration-db-only
  7. Stop your instance: sim stop
  8. Manually check and update if needed your instances's deployment descriptors META-INF/context.xml and WEB-INF/web.xml by comparing them to the default ones of version 4.0 (that you can find in /var/simplicite/template-4.0)
  9. Upgrade tour instance's webapp: sim ant-upgrade-war
  10. Restart your instance: sim start
  11. Remove the patch level property file rm tomcat/webapps/ROOT/WEB-INF/patches/V4.0/patches.properties
  12. 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.