RELEASE NOTES FOR HIGHSTAGE VERSION 12

❗️ Critical Compatibility Information

This release contains several changes that are not backward compatible.

It is critical that you review the "Mandatory Changes and Customizations" section before upgrading. Necessary updates must be made to your Highstage installation to ensure a successful upgrade.

Please reach out if you have questions or need assistance with upgrading. You can find our contact details by visiting Contact - Highstage.

Introduction

Welcome to the release notes for Highstage Version 12 (Build SW10055-12)!

In this release, we’re excited to introduce fully redesigned solutions for Folder View and Export—along with many other improvements. Our goal is to provide functionality that is intuitive, flexible, and efficient, and we believe this release marks a significant step forward.

Visit our Highlights chapter if you just need a quick TLDR of the biggest changes that we are introducing. Are you going to upgrade, then please visit our chapter on mandatory changes beforehand for a seamless upgrade. We've also introduced great new technical experts to our team. They have valuable insights to share, and you can read more in Simon's personal "tech to tech" letter. If you just need the full overview, you can visit the change note chapter for a complete release overview.

⭐️ Thank you for being part of the journey!

Highlights

What’s in it for me? This release focuses primarily on enhancing the existing Highstage experience—making it easier to use, configure, and adapt to your needs.

• Export Our Export feature—used to export data, files, and generate detailed reports—has been completely redesigned for improved performance, usability, and configuration options.

   

• Folder view A cornerstone of Highstage is the way you interact with files and folders linked to your Documents, Parts, Devices, and Actions. The new Folder View introduces a modern, streamlined interface that brings key features together in one place—offering a fresh, more intuitive user experience.

   

• XML Query Inspector The new XML Inspection tool allows you to search through base types and subtypes across your current Highstage XML configuration, making it easier to explore and understand your setup.

   

• Revised mail tokens We’re introducing extended configuration options for mail subject tokens. This allows emails to be automatically linked to the correct objects in Highstage—eliminating conflicts between different Highstage installations.

   

• What else? Across 32 Engineering Change Orders (ECOs), we’ve addressed over 70 unique requests—including reported defects, feature enhancements, and improvement suggestions. This progress wouldn’t have been possible without your valuable input—thank you!

Mandatory Changes & Customizations

This release includes several changes that are not backward compatible. As a result, upgrading to this version will alter the appearance and functionality of Highstage, and may lead to errors if required updates to settings, configurations, or customizations are not applied beforehand.

Export [ECO:23796]

The Export feature has been completely redesigned—this includes its appearance, functionality, and configuration options. As a result, existing export configurations are no longer supported and must be recreated using the new Export Profile configurations.

Resources: For detailed guidance on use, administration, and configuration, please refer to our Docs portal, where all necessary resources are available.

Managing versioning and folder structure on subtypes [ECO:22975]

Overview

We have moved some settings from .XML, which are now handled directly in Highstage on subtypes from the UI. Specifically, it is now possible for all subtypes to do the following:

• Enable/Disable Revisions Turn on (✔️) or off (❌) whether objects of this subtype should be version controlled.

• Enable/disable StaticPath This setting controls how the file folder for this object type is managed. If checked (✔️), the folder is created when the object is created and remains unchanged through to approval. If unchecked (❌), the object uses a draft folder structure (similar to documents), and the final folder is only created upon review/approval.

This is an important step toward easier maintenance of Highstage, allowing settings to be managed directly from the interface instead of through complex code configurations:

Detailed summary of changes

• Versioning can now be enabled or disabled on all subtypes (previously limited to Parts and Devices).

• Static path can now also be enabled or disabled on all subtypes (previously limited to Parts and Devices).

• The revisions and majorrevisions attributes have been removed and disabled from the <feature name="config-manager" /> element under all <type> definitions. Versioning and static-path is now controlled and enforced directly at the subtype level in Highstage using the Revisions data column.

Automated conversion when upgrading (Important)

To ensure that your Highstage installation retains the settings and configurations it had prior to the update - we will automatically execute a script that sets Revisions and StaticPath on each subtype, to match the configured XML settings in your Highstage installation that we are now making obsolete.

When you upgrade Highstage and execute the setup.aspx, we will execute ts/schema/update_subtypes_revision.aspx. If you've set revisions, majorrevisions, or staticpath in XML on any base- or subtype, these settings will now be copied to the subtype in the database, since the database controls them from now on.

If we find no XML configuration on a type, we simply apply the default setting on the subtype that is associated with its bastype. Default settings are:

• Document subtypes: Revisions enabled (✔️), StaticPath disabled (❌).

• Part subtypes: Revisions enabled (✔️), StaticPath enabled (✔️).

• Action subtypes: Revisions disabled (❌), StaticPath disabled (❌).

• Device subtypes: Revisions enabled (✔️), StaticPath enabled (✔️).

Evidence and Verification

To give you a full overview of your settings and the changes we've made, we've generated a report for you. It includes a summary of your XML and database settings and explains the changes based on them:

• You can find the report by navigating to: Tweak > ~ts and access SubtypeRevisionStaticPath-changes.html.

What's next?

To make sure Highstage is set up correctly, please check all subtypes carefully and confirm that the Revisions and Staticpath settings are the way you want them before continuing work in the system.

Tip: You can find a list of all subtypes (as an administrator) by navigating to SYSTEM > Subtypes.

Unique Mail Identifiers [ECO:21587]

As Highstage continues to grow, so does our customer base. We've noticed that some Highstage installations are emailing each other, which can cause confusion when they share the same unique ID numbers. To address this, we're adding new configuration options to prevent emails from being incorrectly linked between installations.

Thus, after the update, your email subject tokens will change from something like [action:12345] to [COMPANY/action/12345] (if you’ve updated your email settings). This change makes sure emails are linked to the right objects when working across different Highstage environments.

• Please navigate to SYSTEM > PARAMETERS > Mail Parameters (as an administrator) to update your new mail parameter settings:

Highstage docs: Details about mail subject tokens, available parameters, and general ingoing email setup can be found in our official Highstage docs.

New Export Feature – Design Decisions and Thoughts (a technical letter to our technical customers)

"For tech by tech" - Simon

We rarely talk technician to technician which I would like to change. The following is a dive into my thoughts and decisions during the design and implementation of the new export feature (BOM export).

I entered the company about a year ago and after a few smaller tasks, the export feature was on my table, the feature had several technical problems, and it was too slow. After three months of digging, it was clear that we had to rewrite. Some time later Oluf joined and was tasked with providing a frontend for the new export feature.

Over the cause of the development, I've had many talks with Oluf and the rest of the highstagers. The export feature released in V12 is a new implementation that contains none of the original export feature's code.

📝 Dynamic report generators

Export reports is an area where everyone wants their own implementation, so we've come up with a solution for that. By having an ASPX implement a C# interface we are able to hand over the reins to you as a customer, you can have any file as a export report if you can put the files content into a C# stream, the interface offers all data from the export for you to consume when you write the report content.

We ship four standard report formats:

• HighstageExcel, excel file that lists the tree hierarchy with the specified columns in the config.

• HighstageHtml, HTML file that lists the tree hierarchy with the specified columns in the config. Shine job done by Oluf.

• HighstageJson, compact JSON file intended for machine reading, it does not use labelling as the other reports do (e.g. "Working" will be "1")

• HighstageTemplatedExcel, excel file that takes another excel file as template that allows you to edit the placement of data, sheets etc.

As well as two ASPX showcases: ConsolidatedSupplierReport.aspx, excel file that consolidates on suppliers, so instead of listing child suppliers they are listed as columns after the parent’s own columns, as well as aggregate the quantities, for example a box created from six plates, where each plate requires four screws will aggregate to 24 screws in total. HighstageHelloWorld.aspx, a boilerplate report that just produces a txt file containing the root key.

I will suggest that if you want to make your own report, copy the HighstageHelloWorld.aspx and rename it, and replace its method content with your own implementation. The ConsolidatedSupplierReport.aspx gives you a teaser to what you could do. This is our most experimental feature, I hope you like it and I really want to hear your thoughts.

I imagine I will be doing a workshop or presentation on how to produce dynamic reports at next HUG (Highstage User Group) meetup.

🧱 Separation

The export feature is separated into several modules:

• Frontend, displays information and interface to the user.

• APIs, offers JSON encoded information via POST or GET, to be consumed by the frontend or you if you can find a use for it.

• Orchestration, sequence control and facade for the APIs.

• Config profiles, validates and parses export configuration, as well as providing fallbacks and defaults, for everything not descripted explicitly in the XML.

• Tree (data structure), builds and manipulates a tree structure of objects (entities, items and custom types), references and files.

• DataReader and SecureRow, provides fast database access and handles read permissions incl removal of field information from the objects that the user is not allowed to see. Offers the option to disable security, if explicitly disabled in the configuration.

• Packer, turns the tree into a zip file.

• Input handling, validates and parses API requests and posts.

• Report Generator, creates reports to be included in export archive (see below).

Each is where applicable built to be a self-contained module for reuse, which sets us up for faster development and maintenance in the future.

💬 Customer-Centric Error Messages

Highstage uses the "yellow screen of death" for any error from which the application cannot recover, and error messages are either system exceptions or hardcoded exception messages. Its not conductive for the operator understanding how to continue and is hard to change the message itself.

We have made a new module that separates out the error messages from the code, as well as transform the errors to JSON for the APIs (see below) and dump a note in the system log. We do not currently use this module outside of the new export, but we will in the future. It’s my hope that better error messages will help identify issues faster and will help the operator forward.

This approach also prepares us for more languages and to have different error messages for different users, e.g. a more techy error message for a superuser vs a more operation focused error message for a user. Also, it’s a blast to tell the business to write error messages 😄

🛡 Error-Aggressive

We leaned into an error-aggressive approach. Instead of silently failing or tolerating half-successful operations, we raise clear, hard errors when things go wrong. I believe this is useful as I can assume more about the state of the data structure by failing early. It will also give better error messages, speed up debugging and fewer strange secondary errors. The only deviation from the error-aggressive approach is that we silently skip columns with the column-attribute set to the empty string, I feel this is an error, but the rest of Highstage accepts this and it should be handled in an input sanitation step during config reset that we do not currently have. (Input sanitation is on my wish list)

🌐 Three New APIs

To deliver data to the frontend, we've introduced three APIs. They all respond in JSON, including when an error is encountered. The frontend handles all presentation of results or error. You are welcome and encouraged to use these APIs for your own purposes. I expect us to produce more APIs in the future.

The APIs are implemented as ASPXs which is not how we are going to implement APIs in the future, it was a trade-off made between what we currently have in the tech stack and us wanting to new things. I imagine that these APIs and future APIs will be implemented as web-sockets to make them tamper proof.

All APIs uphold read permissions and will not return information that the user is not allowed to see. There are no write operations, outside of writing the export zip file to the root object.

If you would like to try them out call them directly and they will respond with error messages on what input, you need to provide.

GET ~\ts\export\api_export.aspx

Created to support the export preview page, where the operator can choose options for the export before export execution.

If called directly it will respond with a JSON containing the data specified in the config that the user has permission to see.

xxxxxxxxxx
GET ~\ts\export\api_export_profiles.aspx

URL parameters required: root_type, string representing the basetype that owns the export configuration(s), for example "doc" or "part" root_object_key, string representing the root object for the export, for example "GD10083-1A"

Responds in JSON and gives a list of all available export profiles for that user. malformed export profiles will be silently skipped, to ensure that a single malformed export profile does not block all other export profiles only export profiles that the user has permission to use will be shown.

In addition to permissions check for the export itself, there is also a check for the reading permission of the root object, to prevent the API to be a security loophole, if there is no read privilege to the object an empty list will be returned.

The packer API accepts both GET and POST. Calling this API will write an export (BOM) zip file to the root objects folder.

xxxxxxxxxx
POST ~\ts\export\api_export_pack.aspx

POST input payload sample:

xxxxxxxxxx
{
    "Blacklist":
    {
        "Nodes": ["2", "3.1"],      //nodes to exclude from the export (in addition to the ones specified in the config)
        "Files":                    //files to exclude from the export (in addition to the ones specified in the config)
        [
            {"Node": "ROOT", "Path": "archieve.zip"},
            {"Node": "3.2",  "Path": "GD10097-1A.txt"}
        ]
    },
    "ExportProfileName": "default", //which export profile is used from the config?
    "Structure": "flat",            //should the folder structure be flat or tree?
    "Destination": "root",          //where to put the file? currently only root destination is supported
    "Root":                         //the root of the export
    {
        "PrimaryKey": "GD10083-1A",
        "BaseType": "doc"
    },
    "Hash": -652870161              //used to check if the tree has changed since the preview selection, optional
}

xxxxxxxxxx
GET ~\ts\export\api_export_pack.aspx

Alternative use of this API: If the operator put all files on the blacklist and includes the HighstageJson report in the config, the zip file will contain JSON file that is a full dump of the tree structure included the column data selected in the config.

🧑‍💻 A Modern Frontend

Oluf wrote the frontend in TypeScript instead of using ASPX. While this is not the technology we want for the frontend in the future it was an experiment into a more modern technology stack. This decision lets us leverage modern tooling, reusability, improve code clarity, and makes it easier to catch bugs early.

🧭 Conclusion

We've been able to speed up the export to the point where the calculation is almost exclusively read permission calculation and packing the zip archive file, while we cannot do more about the packing speed. The read permission calculation we can do a lot about but is outside the scope of this feature and we have had to get to a release.

As of writing this I am working on a prototype for faster read permission calculation, which look promising and will likely go into V13 as a full feature.

The benchmarks I have made on production data for producing the zip file gives us a x50-x60 performance increase.

I'm happy about our results, we have and will continue to focus on simplicity in usability and XML configuration, scalability, code separation and readability.

As always, your feedback is welcome. If you have questions, ideas, or concerns, don't hesitate to reach out. And if you want to take a closer look or test the feature ahead of release, let us know — we'd love your input. Hope to see you at next HUG.

Best regards, Simon Svane - "back office" developer simon.svane@highstage.dk

Change Notes

Below is the list of change order requests that have been addressed and resolved as part of this release.