Customizing BMC Helix ITSM applications by using overlays

Use the AR System Overlays feature to customize applications and avoid conflicts with future application versions. By using overlays you can track customizations and preserve changes to your application objects even if they are modified during an application upgrade.

An overlay is a copy of a AR System structure or workflow object that is used in place of the origin object. Out-of-the-box AR System application and server objects, and objects created in the Base Development mode of Developer Studio, are origin objects.

To customize out-of-the-box AR System objects and ensure that the customizations are not lost when an AR System application or server is upgraded, create an overlay of the origin object, and modify the overlay instead of the origin object.

At runtime, the AR System server and clients (such as the Mid Tier) use overlay objects in place of the origin objects.

During upgrades, an AR System installation program ignores overlays, and does not undo, overwrite, or delete their modifications. The installation program changes only the objects that were installed with the application or server. After the upgrade, the application or server continues to use the overlays instead of the origin objects for runtime operations.

Overlays also make it easy to identify all the customizations in your applications.

Restrictions on using overlays

Overlays don't perform the following functions:

• Preserve customizations made to an object that is deleted during an application upgrade. If an existing object in your production environment is deleted during an application upgrade, any overlay of the object is deleted as well.
• Automatically merge customizations with functionality added during upgrades; for example, if a filter has three new actions in an upgraded application, those actions are not automatically added to an existing overlay of the filter. Instead, if you decide to use them, you must identify the new actions by comparing the overlay to the upgraded origin object and then add them to the overlay.
• Enable you to make all possible changes to AR System objects; for example, you cannot make changes that would alter the underlying database, such as changing the data type of a field.

Objects that allow overlays

You can create overlays for the following objects:

• Active links
• Images
• Active link guides
• Local applications
• Escalations
• Menus
• Filters
• Packing lists
• Filter guides
• Views
• Forms
• Web services
• Fields
• Deployable applications

Objects that don't allow overlays

You cannot create overlays for the following items:

• Custom objects—Upgrades do not modify custom objects. 
• Overlaid objects—You cannot create multiple overlays for the same object.
• Overlay objects—You cannot create overlays of overlays.
• Form data—BMC Helix Distributed Server Option (DSO) mappings, DSO pools, flashboards, Skins, and templates are stored as data in forms. Any modifications that you make to them might be lost when an application or server is upgraded.

Best practices for BMC Helix ITSM customizations

To make code changes to BMC Helix ITSM applications that are retained when you upgrade:

• Make any customizations to out-of-the-box workflows by using overlays when you are customizing BMC Helix applications. Overlays protect the customization from being lost during an upgrade.
• Use an overlay to customize a field; however, ensure that the field continues to be used for the its original purpose. Overlays do not protect the contents of fields. Re-purposing an existing field can cause issues in the applications.
• When you change a user interface, make a form overlay and then make an overlay of the view that you are working on. During an upgrade, your changes are saved; however, you must ensure that making these changes as overlays will not merge user interface changes in future application releases with the overlaid view.
• Consider performance when making any code changes. If you add an active link workflow, you must ensure that it does not make the same server calls as an existing workflow, which would impact performance. Tune user interface widgets such as table fields to use indexes and chunking. They should display data only when that data is required.
• In the BMC Helix ITSM environment, you must use overlays to customize objects. Also, when you use overlays you must test your customizations after you upgrade.