+

Search Tips   |   Advanced Search

Upgrading Worklight

We can create an EAR file, and copy Worklight resources into that EAR to keep up to date with the latest Worklight release.

The existing Worklight extension EAR is installed under...

    \PortalServer\theme

We cannot modify this location directly since any changes can be overridden by a fix pack. Create our own custom Worklight extension EAR and install it in \wp_profile. When creating our own EAR, start with a copy of the existing EAR and modify it. During this process, you replace occurrences of wp and wps with custom and occurrences of the current Worklight version number with the Worklight version number.

  1. Export the worklight_extension.ear from the WAS console.

    1. Click...

    2. Click next until you find the worklight_extension application.

    3. Select worklight_extension and click Export on the toolbar.

    4. Click the worklight_extension.ear link to download and save the EAR file to the file system.

  2. Import the worklight_extension.ear into Eclipse or Rational Application Developer with Java EE Developer tools plug-in.

    1. Click...

        File | Import | Java EE | EAR file | Next | Browse | worklight_extension.ear

    2. Rename the EAR project from worklight_extension to custom_worklight_extension and then click Next twice.

    3. In the Project Name field, change the name from...

        wp.theme.worklight.ext to

      ...to...

        custom.theme.worklight.ext

      ...and then click Finish.

  3. Customize the ear in Eclipse or Rational Application Developer for the new version of Worklight.

    1. In the custom_worklight_extension EAR project, delete the folder...

        EarContent\META-INF\ibmconfig

    2. Right-click on the custom_worklight_extension EAR project and select Properties. Select Deployment Assembly.

    3. Select the wp.theme.worklight.ext.war Deploy Path and rename it to...

        custom.theme.worklight.ext.war

    4. Click Apply and OK.

    5. In the custom_worklight_extension EAR project, delete the file...

        EarContent\wp.theme.worklight.ext.war

  4. In the custom_worklight_extension EAR project, modify the EarContent\META-INF\application.xml file. Change the display-name from Worklight Extension to Custom Worklight Extension.

    1. Change the module ID from...

        wp.theme.worklight.ext

      ...to...

        custom.theme.worklight.ext.

      • Change the web-uri from...

          wp.theme.worklight.ext.war

        ...to...

          custom.theme.worklight.ext.war

      • Change the context-root from...

          /wps/worklightExt

        ...to...

          /custom/worklightExt

  5. In the custom.theme.worklight.ext war project, modify the file...

      WebContent\WEB-INF\web.xml

    1. Change the web-app ID from...

        wp_theme_worklight_ext_webapp_1

      to...

        custom_theme_worklight_ext_webapp_1

    2. Change the display-name from...

        Worklight_Extensions

      ...to...

        Custom Worklight Extensions

  6. In the custom.theme.worklight.ext war project, in WebContent, create the new version folder and its contents. First, examine the existing version folder and its contents because that shows the folder structure created.

    1. Right-click on WebContent and select New > Folder.

    2. Enter the Worklight version number we are working with as the folder name. For example, use...

        vyour_new_worklight_version

    3. Right-click on the folder created and create child folders called android and ios.

    4. Locate the Android-specific folders in the Worklight project. In previous versions, they were in \YourWLProject\apps\YourApp\android\native\assets\www\default\js and \YourWLProject\apps\YourApp\android\native\assets\www\default\worklight folders in the Eclipse Worklight project. Copy and paste them into the vyour_new_worklight_version\android folder.

    5. Locate the iOS specific folders in the Worklight project. In previous versions, they were in...

        \YourWLProject\apps\YourApp\iphone\native\assets\www\default\js
        \YourWLProject\apps\YourApp\iphon\native\assets\www\default\worklight

      ...in the Eclipse Worklight project. Copy and paste them into the folder...

        vyour_new_worklight_version\ios

    6. Locate the init.js file in...

        WebContent\vpreviousversion\android\js

      ...and copy it to the folder...

        WebContent\vnew_version\android\js

    7. Locate the init.js file in...

        WebContent\vpreviousversion\ios\js

      ...and copy it to folder...

        WebContent\vnew_version\ios\js

    8. Locate the file...

        worklightprevious_version.json

      ...in the current version folder, where previous_version is the current Worklight version number. Copy it and paste it in the new version folder. Rename the file...

        worklightnew_version.json

      ...where new_version is the new Worklight version number.

    9. Edit the newly copied file, find, and replace all occurrences of the current Worklight version number with the Worklight version number and save the file. This file defines the version-independent meta modules that prereq the version-dependent modules defined in the plugin.xml file in the next step.

  7. Determine whether overrides for Cordova and Worklight APIs are required. HCL WebSphere Portal defines overrides for Cordova and Worklight APIs to improve performance and integrate with HCL WebSphere Portal.

    1. To prevent an error when Worklight resources load, the following functions are overwritten...

      • WL.Utils.loadWLClientMessages
      • WL.Utils.setLocalization

      If these are still needed, locate and copy the portal directory from each of the Android and iOS directories in...

        WebContent\vprevious_version\

      ...and copy them to their respective directories in...

        WebContent\vnew_version\

      Verify the content of these functions accurately reflects the content from the new version of Worklight.

    2. If the Cordova APIs have not changed, copy the changes in files...

        WebContent\vpreviousversion\android\worklight\cordova.js
        WebContent\vpreviousversion\ios\worklight\cordova.js

      ...to the new version of the Worklight folder. This method reduces the number of requests to HCL WebSphere Portal. Or, Leave the Cordova API, and add a <script> element to all the pages that require Worklight resources. The <script> element must reference the cordova.js file directory. To improve performance for Worklight applications in HCL WebSphere Portal, two Cordova APIs were changed. Originally, the Cordova APIs attempt to load all of the Cordova plug-ins individually by dynamically determining their location. However, it is not possible with HCL WebSphere Portal resource aggregation.

      The injectScript and findCordovaPath functions are rewritten to use the ibmCfg.portalConfig.worklightResourcesPath[version_number] JavaScript variable to determine the location of the Cordova resources. This value of this variable comes from the Resource Environment Provider property created in a following step. The version_number used in the variable should be updated to reflect the new version number, which is reflected in the following changes to the resource environment provider property.

    3. Copy the changes in...

        WebContent\vprevious_version\android\worklight\cordova.js
        WebContent\vprevious_version\ios\worklight\cordova.js

      ...and copy them into the new version of Worklight we are upgrading to. This offers a performance improvement, because it reduces the number of requests made to the HCL WebSphere Portal server for the Worklight resources.

    4. Leave the Cordova API as it is and add a <script> element to all pages that require Worklight resources.

      The <script> element must reference the cordova.js file directly.

  8. In the custom.theme.worklight.ext war project, edit file...

      WebContent\WEB-INF\plugin.xml

    1. Change the plug-in ID from...

        wp.theme.worklight.ext

      ...to...

        custom.theme.worklight.ext

    2. Change the plug-in name from Worklight plug-ins to Custom Worklight plugins.

    3. Change the plug-in provider-name from IBM to the company's name.

    4. Find and replace all occurrences of the current Worklight version number with the Worklight version number.

      Find and replace version numbers in both the formats 000 and 0.0.0. These changes must correspond with the changes made previously to worklightprevious_version.json. This plugin.xml file defines the version-dependent modules that are prereqed by the version-independent meta modules defined in worklightprevious_version.json in the previous step.

    5. Locate the wl_android_new_version and wl_ios_new_version modules, where new_version is the new Worklight version number, and verify all of their subcontributions.

      Review the resources for the new version of Worklight, and if there are any differences, modify the subcontributions so that each resource file has a subcontribution. In these modules, each resource is explicitly listed when debug mode is enabled. When it is not enabled, HCL WebSphere Portal provides a single JavaScript layer for the Worklight resources. Create a similar layer for the resources of the new version of Worklight. This layer must be defined as a subcontribution here. If we choose not to create a JavaScript layer for the Worklight resources, add and verify that required resources are listed as subcontributions.

    6. Locate the wl_plugins_android_new_version and wl_plugins_ios_new_version modules, where new_version is the new Worklight version number, and verify all of their subcontributions.

      Review the resources for the new version of Worklight, and if there are any differences, modify the subcontributions so that each resource file has a subcontribution. In these modules, each resource is explicitly listed when debug mode is enabled. When it is not enabled, HCL WebSphere Portal provides a single JavaScript layer for the Worklight resources. Create a similar layer for the resources of the new version of Worklight.

      This layer must be defined as a subcontribution here. If we choose not to create a JavaScript layer for the Worklight resources, add and verify that required resources are listed as subcontributions.

    7. In the custom.theme.worklight.ext war project, delete the folder...

        WebContent\previous_version

      ...where previous_version is the current Worklight version number, and all of its contents.

  9. Export the customized ear as custom_worklight_extension.ear from Eclipse or Rational Application Developer.

    1. Right-click custom_worklight_extension ear project and select...

        Export | EAR file | Browse

      Choose a destination folder and name of custom_worklight_extension.ear.

    2. Click Finish to save the EAR file to the file system.

  10. Add resource environment provider property resources.worklight.extensions.new_version resource environment provider

    1. Click...

        Resources | Resource Environment | Resource Environment Providers

    2. Click Next until you find the WP ConfigService resource environment provider and then select it.

    3. Click the Custom properties link.

    4. Click New from the toolbar.

    5. Enter resources.worklight.extensions.new_version for the name, where new_version is replaced by your new Worklight version number.

    6. Enter...

        /custom/worklightExt/new_version

      for the value where new_version is replaced by your new Worklight version number.

    7. Enter the path to the Worklight vnew_version_number extensions for the description where new_version_number is replaced by the new Worklight version number in the v0.0.0 format.

    8. Click OK.

    9. Click Save to save directly to the master configuration.

  11. Deploy the custom_worklight_extension.ear in the WAS console.

    1. Click...

    2. Take the defaults and click Next.

    3. Take the defaults and click Next.

    4. Verify the Directory to install application field is blank so that it installs to the default location. Delete anything in the field if it is not.

    5. Take the defaults and click Next.

    6. Click Finish.

    7. When the EAR is done installing without error, click Save to save to the master configuration.

    8. Find and check the new Custom Worklight Extension enterprise application and click Start from the toolbar.

      Your EAR is now installed at...

        \wp_profile\installedApps\cell\Custom Worklight Extension.ear

  12. Modify the theme contributions to load the new version of the Worklight extensions.

    You continue to use the same meta module names in the theme profiles, such as wp_worklight_android and wp_worklight_ios. We must change the JSON file in the theme contributions folder to change which version-specific modules the meta modules load.

    1. Use WebDAV to connect to fs-type1:themes\yourtheme\contributions.

    2. Delete the worklightprevious_version.json file, where previous_version is the previous Worklight version number.

      If we back up the file, move it to a different location. Do not rename the file .jsonbak, for example, because every file in the contributions folder is loaded by the system. We must remove the file completely.

    3. Copy the worklightnew_version.json file into the contributions folder.

      The file can be copied from...

        \wp_profile\installedApps\cell\Custom Worklight Extension.ear\custom.theme.worklight.ext.war\vnew_version\worklightnew_version.json

      ... where new_version is replaced by the Worklight version number. If we must revert to the previous version of Worklight, we can get the worklightprevious_version.json file back from...

        \PortalServer\theme\wp.theme.worklight.ext\installedApps\wp.theme.worklight.ext.ear\wp.theme.worklight.ext.war\vprevious_version\worklightprevious_version.json

      ...where previous_version is the original Worklight version number.

  13. Restart the HCL WebSphere Portal server.


Results

The Worklight meta modules, such as wp_worklight_ext, now load and use the resources for the new version of Worklight.


Parent Integrate with IBM Worklight