Cross Instance Compare Tool (a Global Scope to Scope App journey)

[Tom Hauri]

During my first upgrade, I believe it was Jakarta to Kingston, I wrote a little tool that allowed me to compare records from different instances, because I wanted to know if there are any differences in the plugins installed.

This is the story of the journey to bring that old code to leading practices and do business smart customizations (and yes, you can download the tool as well).

The baseline

The compare application consists of a table to store the compare configuration and results (if you choose to compare a list on a remote system you can save the result as a CSV), some menus and forms incl. UI policies and a UI action that does a AJAX call to a script include that does the compare.

The goal

Since the initial implementation the platform has improved a lot and so has my knowledge about the platform. So I decided to rebuild the application with some leading practices applicable today:

• Scoped application (initial code was in a global app)
• ECMA 21 JavaScript (only available on Tokyo)
• Connection and Credential Alias (initial implementation used an URL and a reference to a Basic Authentication Credential)

The journey

The migration from global app to a scoped app is not supported. All artefacts have to be recreated in the application scope. This allowed me to simplify and harmonize my UI actions, field names and to directly implement the desired changes to use Connection and Credential Alias instead of managing the URL and Credentials in the record itself. 

The basic work of creating the table, the navigation menu and the forms including UI action and policies where completed quickly.

When rewriting the code I was looking for opportunities to leverage the ECMA21 functions to simply code. I found that while there was a lot to be done to improve code clarity by defining more and simpler functions I did not actually have a good use case that would allow me to profit from the supported ECMA21 functions with Tokyo. So in the end, the desire to be backwards compatible to N-2 was more important than to be on the latest technology stack. 

The challenge

The single record compare uses the baseline Script Include DiffHelper and the GlideRecordXMLSerializer scriptable java class to build the HTML code to show in the popup. As I quickly found out they both are not usable in an application scope. 

The Script Include TableUtils is also not available in scoped applications. The TableUtils are used to retrieve all fields for the remote compare in case no field was selected by the user and also in the reference qualifiers used on the keys and fields reference lists.

Here are the options that I looked at to overcome this challenge:

• Create a global scope script include
  • PROS:
    • simple
    • security compliant
  • CONS:
    • cannot package the application ** see comment below, can be fixed
    • requires two update sets and/or two scoped applications ** see comment below, can be fixed
      
      
• Modify the baseline script includes to be accessible from all application scopes and write custom code to serialize the glide record to XML
  • PROS:
    • can package all objects in one scoped application
  • CONS:
    • have at least two manual steps in the deployment
    • create technical dept for the script includes for upgrades (although a small one)
    • create technical dept with the redundant and potentially complex code
      
      
• Try to get around scope boundaries
  
  • PROS:
    • can package all objects in one scoped application
  • CONS:
    • not leading practice
    • legacy security behavior

The solution

----------------------------------------------------------------------------------------------------------------------

UPDATE January 2024: Compare Tool – easily diff instances and snapshots

The rest of the article stays unchanged, as some of the observations might be helpful when you have to find your own preferred option.
----------------------------------------------------------------------------------------------------------------------

As you probably guessed, the preferred solution for me was to build a global script include that contained the functions required. The stated goal is to use leading practices and neither creating technical dept nor using legacy behavior is acceptable.

Instead of using a global update set I decided to leverage the workaround of packaging the global objects into the scoped application and install them with a scheduled script.

The lessons learned

Working in scopes is sometimes tricky if you want to leverage the full power of the platform and while I was waiting for EMCA21 support eagerly it is not required for most use-cases. At least until N-2 supports ECMA21 scripts, I would stay on ES5 unless you have really good reason.

The result

Access the application from the navigation or by calling the table x_snc_xinstcompare_compare.list. 

Single Record Compare (same instance)

Single record compare (remote)

List compare remote

The installation

1. Install the scoped update set.
2. Configure your connection alias (e.g. URL to the instance you want to connect to) and your credential that can access the Table API and the tables you want to compare.
3. Create your first Compare record and configure it accordingly
4. Compare!

I deliberately did not include the documentation here because I hope you will find it intuitive. If not, please let me know in the comments.

The ask

Do you agree with my choices, would you have another, better way of doing it?

Thanks for taking the time, I hope you found it interesting!

Thanks

Very grateful to my manager Christina K for the review and all the great feedback and support!