Customizing assyst Enterprise Web Edition

From wiki.axiossystems.com

The customizing of assyst Enterprise Web Edition can be done on two levels; the assyst Customizer , and directly within an EAR file. This topic deals with the customizations within the EAR file.

Contents 1 EAR Customizations 2 Manipulating the assystCustomisations.ear 3 Manipulating an EAR File 4 Deploying the assystCustomisations.ear File 5 Property Files 6 CSS 7 JavaScript 8 Terms and Conditions 9 Seriousness/Priority Icons 10 Time-Zones

EAR Customizations

From assyst 8 there are two methods of applying EAR file customizations in assyst Enterprise Web Edition: Via the in the standard assystEnterprise.ear file, or via the assystCustomisations.ear. The direct benefit of using the assystCustomisations.ear file is that this can be transferred between releases, whereas if customizations are made within the standard assystEnterprise.ear file these will be lost when assyst is upgraded.

Note: The assystCustomisations.ear functions fully with SSL (Secure Sockets Layers) when operating under JBoss.

The assystCustomisations.ear file supports the following types of customization:

• Adding/overriding property file entries for applets and the assyst Web Client (where a property file is used to provide internationalization, the standard approach is supported where appropriately named locale-specific property files should be provided):
  • ChangeCalendar.properties
  • Common.properties
  • Customiser.properties
  • ImpactExplorer.properties
  • ServiceExplorer.properties
  • ProcessExplorer.properties
  • ResourceManager.properties
  • changecalendar-colors.properties
  • processexplorer-colors.properties
  • assyst.properties
• Adding/overriding CSS styling:
  • axios_css_ext.jsp
  • customStyles.css - for assystNET
  • axios_chat_css_ext.jsp - for the Chat window
• Providing JavaScript to be executed on page load:
  • axios_js_ext.jsp
• Providing terms and conditions to be displayed by the login screen.
• Providing icons for seriousness and priority values.
• Providing additional spell-check dictionaries.
• Restricting the set of time-zone options available.

Note: The ear also contains a "keyboardshortcuts.properties". This file is not functional and is only distributed as an example of what can be added in the external customized assyst.properties file.

Manipulating the assystCustomisations.ear

The above customizations are achieved by manipulating content of the assystWEB.war file within the assystCustomisations.ear file. These files can be expanded/contracted using the WrapEar and UnWrapEar utilities used to expand/contract the standard assystEnterprise.ear file and its constituent WARs.

Note: If you are required to perform any such customizations to the web front end, then you will need to expand the appropriate .ear file(s) so that you can work on the individual files. While JBoss can function with an expanded .ear file deployed, it cannot do so across a cluster. WebSphere also cannot operate on an expanded .ear. It is therefore recommended that only .ear files rather than expanded ears are deployed to an application server.

Manipulating an EAR File

Axios provide two utilities for working with .ear files. These are located on the installation DVD or Downlaod. To use them copy them from the CD to a location on your PC’s hard drive. In the examples below, these files have been copied to d:\tmp (where a copy of assystCustomisations.ear also resides). Entering the command:

java –jar UnWrapEar.jar assystCustomisations.ear

will take the named .ear file and expand it. It will also expand any .war files that are contained within the .ear. Once this command has finished, the file assystCustomisations.ear will have been replaced with a directory called assystCustomisations.ear.

To take an expanded directory and compress it to a single .ear file, there is another command to use:

java –jar WrapEar.jar assystCustomisations.ear

this will take the directory named assystCustomisations.ear and convert any .war subdirectories into files, it will then convert the named directory into a file of the same name. This is the opposite of the UnWrapEar command.

Note: Due to limitations of the WrapEar and UnWrapEar utilities, they can only be run from the same partition as the file/directory that they are working on.

You must also ensure that the %JAVA_HOME%\bin directory is in your environment PATH so that the WrapEar utility can find the Java jar.exe utility.

The assystMOBILE.war WAR file is provided for future use.

Deploying the assystCustomisations.ear File

A structured, blank, assystCustomisations.ear file is available in the root of your assyst distribution DVD (or download). This file contains the a mirror of the customizable elements of the assystEnterprise.ear file.

The assystCustomisations.ear file can then be deployed to an application server instance using standard mechanisms. For JBoss, simply copy the EAR file to the same location as the standard assystEnterprise.ear.

By its nature the assystCustomisations.ear will only supersede the command of the default assystEnterprise.ear where it contains a differing value; so while it is in blank or empty state it has no effect on the assyst system, therefore for example if you only enter a single line in a .properties file within the assystCustomisations.ear, only that line will have an effect against the default assystEnterprise.ear state.

The assystCustomisations.ear file should be deployed within the same application server instance as the standard assystEnterprise.ear. Where assyst is deployed in a cluster, the same assystCustomisations.ear file should be deployed alongside each standard assystEnterprise.ear.

Property Files

The assystCustomisations.ear provides property files that mirror the significant property files contained within the assystEnterprise.ear file.

If new properties are required, those properties should be added to the appropriate property file(s) within assystCustomisations.ear.

If new values are required for existing properties, appropriate entries should again be added to the appropriate property file(s) within the assystCustomisations.ear. These property values will override those defined by the assystEnterprise.ear file.

The assystCustomisations.ear only provides locale-neutral property files (such as assyst.properties). If locale-specific property values are required (e.g. to override values defined by assyst_de.properties), the appropriately named file(s) must be created and copied into the same directory structure position as the locale-neutral equivalent within the customizations EAR.

CSS

The assystCustomisations.ear allows you to extend and/or override the CSS styles defined in assystEnterprise.ear.

For assystNET, this is done by editing customStyles.css located in ...\assystCustomisations.ear\assystSelfService.war\styles. If new selectors and styles are required, appropriate CSS should be added to this file.

For the assyst Web client, this is done by editing axios_css_ext.jsp located in ...\assystCustomisations.ear\assystWEB.war\styles. If new selectors and styles are required, appropriate CSS should be added to this file.

Additionally, an axios_chat_css_ext.jsp file is included for both assystNET and the assyst Web client to allow you to override the CSS styles of the Chat window in both applications.

If new styling is required for existing CSS selectors, appropriate CSS should be added to the same file to override the default style definitions for those selectors. These styles will take precedence over those defined by assystEnterprise.ear.

JavaScript

The assystCustomisations.ear provides a single file used to define additional JavaScript to be executed when pages are loaded: axios_js_ext.jsp.

Empty JavaScript functions init() and destroy() are defined within this axios_js_ext.jsp file located within the \scripts directory within the assystWEB.war within assystCustomisations.ear.

These functions are called when pages are loaded. The init() function is called before any other JavaScript is executed on page load; the destroy() function is called after all other page-load JavaScript has been executed. You can add content to these empty functions.

Terms and Conditions

Terms and conditions can be displayed on the assystNET and assyst Web Client login screen by editing two instances of the file rename_to_termsandconditions.jsp in an expanded assystCustomisations.ear folder.

To provide terms and conditions to be displayed by the assyst Web Client login screen:

• Rename the file rename_to_termsandconditions.jsp to termsandconditions.jsp within the assystCustomisations.ear\assystWEB.war\login directory.
• Add content to that JSP as required.

To provide terms and conditions to be displayed by the assystNET login screen:

• Rename the file rename_to_termsandconditions.jsp to termsandconditions.jsp within the assystCustomisations.ear\assystSelfService.war\login directory.
• Add content to that JSP as required. HTML Tags can be used to style your text. For a list of tags supported by the Flash player in assystNET, visit http://livedocs.adobe.com/flex/3/langref/flash/text/TextField.html

Seriousness/Priority Icons

The assystCustomisations.ear file provides directories for seriousness and priority icons.

Icons for seriousness and priority values could previously be provided via an assystCustomisations.war file. Image files should now be copied into the appropriate directory within the assystWEB.war within assystCustomisations.ear as specified below.

• Seriousness icons should be copied into the \shared\images\seriousness directory within the assystWEB.war within assystCustomisations.ear.
• Priority icons should be copied into the \shared\images\priority directory within the assystWEB.war within assystCustomisations.ear.

Time-Zones

The assystCustomisations.ear provides a single file used to exclude time zone options defined within the assystEnterprise.ear file: excludeTimeZone.properties.

To exclude a time zone option defined within assyst.properties within the assystEnterprise.ear file, add the corresponding property to the excludeTimeZone.properties file located within the root directory of the assystWEB.war within the assystCustomisations.ear The property should be given the value “false”.

For example to exclude the time zone option “MIT”, add “user.preferences.value.MIT=false” to excludeTimeZone.properties.