There are many different ways to add new functionality to or modify the existing functionality of Aras Innovator. You can easily add new ItemTypes and Forms, and you can just as easily modify the functionality of the client through features like CUI. However, there are specific circumstances when the exact piece of functionality we want to change is only accessible through the source files where you installed Aras Innovator: what we refer to as the codetree. In this blog post, we will cover the best practices to keep in mind when making changes to these files.
Before you make any codetree changes
Codetree changes can be a powerful tool in the hands of an experienced developer, but they do come with some fairly substantial downsides. Actually developing the functionality can take much more time. Finding the exact file or piece of code we want to change can be a hassle on its own, and testing these changes requires clearing the local browser cache and reloading Innovator which can add even more to the development costs. In addition, deploying these changes also requires setting a flag that will effectively clear the cache for each user connecting to our instance. These can lead to a substantial, albeit not long-lasting, impact on our users' performance as they are required to retrieve the new versions of the files from the server to rebuild their cache.
With these costs in mind, it's important to do the following before we make any codetree changes.
Consider all other options
Modifying the source files should be seen as a last resort. A large number of use cases and requirements can be met by making modifications to the database alone, so we should consider if the change we have in mind could be better accomplished with:
- CUI
- A custom dialog
- A new Form
- A PWA or another external application
If we have considered each of these options and have found that a codetree change is still the best approach, there are some extra steps we can do when we make our changes that will make maintaining these changes far easier for the future.
Plan ahead
Our end goal when we make codetree changes should be maximizing the ease with which we can extract and move those changes to another instance. With that in mind, we can do a few things up front before and while we make our changes that will make the process of moving them drastically easier.
- Take a backup of the "clean" codetree
- Before we make any changes to the database, we should take a complete backup of our installation folder. This can be accomplished by copying the /Innovator/ folder at the root of our installation directory to another location. This will take several minutes at least, but we will only need to perform this operation a single time. This backup will be our saving grace if, in the heat of development, we forget to take the next few precautions. It will also be an immense help if and when we migrate our changes to a newer version of Innovator.
- Take a backup of any files before making any changes to them
- Before making any changes to a specific file, we should make a copy of that file and rename it to something like codetreeFile_old.js or codetreeFIle_clean.js. This can serve as a kind of version control if we severely break anything while developing our new functionality.
- Mark whatever changes are made inline in the file
- For each section of code we add or modify, we should include a comment before and after it to point out what pieces have been changed.
Making the changes
The next problem we need to tackle is finding exactly where to make our changes. As codetree files can sometimes change dramatically between versions, it can be difficult to pin down exactly where the file we want to change exists. We can use the list below as a general rule of thumb though further investigation will likely be required on a case to case basis.
- Modifying the functionality of an Aras application like PM or MPP
- /Innovator/Client/Solutions/
- Modifying some core application like Query Definitions or Tree Grid Views
- /Innovator/Client/Modules/
- Modifying a core dialog like Where Used or Structure Browser
- /Innovator/Client/scripts/
After making our changes, we will need to do one of the following in order to test them.
- Clear the browser cache
- Start an Incognito session
- Increment the filesRevision tag in the Client's web.config
Once we are able to pull in our changes, we should test them thoroughly. As codetree changes can have more far reaching impact, this testing should include all standard smoke tests in addition to any feature-specific tests for the functionality we just added.
Packaging the changes
Once we've finished making and testing our changes, we will need to package up these changes so we can move them to our QA or Production instance. The end goal of this package is to create a folder that contains all of the files we changed, in the relative locations within the codetree that they usually are. We can then simply copy the top-level folder of our pacakge and paste it on top of another instance in order to apply the change. To accomplish this, we will want to create a new /Innovator/ folder that will hold the relative paths to each of the files that we have changed.
We can see an example of this in the Method Editor Theme Preference community project. This community project adds an option for developers to change the theme they want to use for the standard Method Editor. To accomplish this, we needed to modify a file in the codetree that controls how the Method Editor gets loaded, and if we look at the files included in the community project, we'll see that it includes a relative path down to the /Innovator/Client/scripts/CodeEditor/MethodEditor.html file.
Conclusion
Codetree changes should be made only if there is no other option. In the cases where codetree changes are deemed necessary, there are still steps to take to ensure that they are made responsibly. Have you needed to make codetree changes for any of your previous projects? If so, what were they? Let us know in the comments!