Learnsmarter is a native built Salesforce application an as a direct consequence of this, install failures can and do occur. Most of the time these install failures happen for reasons that are logical and clearly understood and with a little bit of preparation the vast majority of them can be avoided making installs and upgrades a simple and predictable process.
We have never yet encountered a customer org that we couldn’t get a successful install in.
If your org has customizations (including button click type configurations) on any of the following standard Salesforce objects, or on any Learnsmarter custom objects, then these can give rise to install failures related to our test code:
The most common reason why install failures occur is because when test code runs it creates temporary records and even though the temporary records only ever exist for the purposes of testing, these ‘virtual’ records are subject to all of the same scrutiny and actions that any record created normally within your org would be subject to.
This can lead to problems with:
Requirements not met by our test code
Learnsmarter apps have extensive test code coverage (required minimum is 75%). When the test code runs it creates ‘virtual’ records and this includes records in standard Salesforce objects such as Accounts, Contacts, Products and Opportunities. These records never actually exist in your org, but they are required for testing. So to make a registration, we need a contact to register and so we have to have create that virtual record. After the test has completed, the records all disappear. When we create these virtual records, then any customizations you have such as validation rules, workflows, triggers, processes, flows and data.com duplication rules will all run as normal. So, if your customization requires a field to be completed that is not completed by our test code or a process tries to run and has insufficient information, then we’ll get an install failure and an error will be returned. Note that there can be multiple failures in a test class, but we won’t necessarily know about all of them the first time around. This is why understanding all of the conflicts can be an iterative process.
Changes to records that conflict with our test code
This problem is similar to the conflicts one. Let’s say our test code creates a phone number on an account and we create that phone number as 1234567890. Our test code then checks that that record has been created correctly, so it looks to see “is the phone number 1234567890?”. If you have a customization that automatically changes all phone numbers that have been input to a standard format such as 123-456-7890, then that’s not the same as 1234567890 and our test code will fail at that point.
If you use data.com de-duping rules or a third party de-duping tool, then this can cause install failures where there is a requirement in your rule that our test code data does not comply with. There are instances when we create multiple contact records to test a registration, for example, and not all of the values in these records will be unique. This only becomes an issue where test code is run in a particular client environment where de-duping rule requirements exist that we have not encountered before.
Install failures can also happen because of API version clashes and bugs or weaknesses in our test code.
The APIs that Salesforce uses are updated with every major release of Salesforce (Spring/ Summer/ Winter). Learnsmarter does not update all API versions to be compatible with every new Salesforce release as a matter of course because generally this isn’t necessary and because API updates can break existing features – most notably PDF pages.
There was a problem previously because Process Builder could clash with any classes created prior to API 32. In Learnsmarter version 2.67, all APIs that could be updated were updated to API version 38 or later, so this should no longer be an issue.
Test code bugs
We are not perfect but we do conduct a range of install tests on every release, installing across a variety of org configurations. In most cases it is also highly likely that the release will have been installed in other customer orgs before it is installed in yours. However, from time to time we do encounter failures because of bugs in our test code that only become apparent in certain org configurations. The solution in this case is for our development team to fix the issue which is normally something we can do within 24 hours and frequently much sooner.
An iterative approach
We always recommend testing the install in a sandbox first.
You can try to predict any failures ahead of time and pre-empt them by making your org install friendly as explained below. It isn't always easy to work out what needs to be done, so often an iterative trial and error process is effective.
The iterative process is pretty simple, but can take a while. All you need to do is to run the install and see what happens. If it works first time, great. If not, then deactivate any obviously clashing rules, triggers and processes and then run the setup again. Document everything that has been deactivated, including the version number (processes created using the process builder). Repeat this process until you have a successful install.
If there are no obviously clashing items, contact Learnsmarter support. Learnsmarter should receive copies of all install failures anyway and we may often be working on fixes for any bugs in the code before you contact us.
Once you have a successful install, you should reactivate everything before conducting any required UAT. It should be possible to repeat the install in another sandbox or a production environment by following the documented steps.
If you do experience install issues due to clashes with your org configurations, then we strongly recommend that you consider taking steps to make your org more “install friendly”, particularly if you have problems with any triggers which are not easy to deactivate in production. It's an easy and quick thing to do and can save a great deal of time.
Working with Learnsmarter Engage
If you have Learnsmarter Core and Learnsmarter Engage, run the Core setup first and then run the Engage setup before you reactivate any clashing elements. It is possible that you may need to deactivate additional elements before installing Learnsmarter Engage.
It is vital to understand that your version of Core and your version of Engage must be compatible with each other. Engage is always installed after installing Core. If your version of Engage is ahead of the version of Core, then the Engage install will probably fail. If your version of Core is ahead of Engage, then Engage may not work as designed.
You should always ensure that you have a successful install of Engage and Core in a sandbox that has been built from the current production environment before upgrading your production instance. It is recommended that you deactivate Engage whilst you are running updates of Core and Engage in production.
Automatic updates are subject to the same issues as user initiated updates. If we tried to push updates to our users, many of these would fail. It is also the case that many customers want to conduct a period of UAT in a sandbox environment before installing any upgrade in a production environment.
Making your org install friendly
Updating your org can be an unnecessarily time-consuming process unless you take steps to make your org install friendly. Luckily, making your org install friendly is an easy thing to do. The principle is very simple and can have benefits installing other packages and not just Learnsmarter apps. What you need to do is to create a switch to turn off all of your configurations for the installing user only with one checkbox and in the same way re-enable everything once the install is complete.
1. Add a custom checkbox to the user record called Running Update. Make sure that this new field is visible in the User page layout. You can make this visible to all users, but only the system administrator needs to be able to update this.
It is also a good idea to include an automatic reset function, so that the switch will reset itself if you either forget or are unable to do so. This is easily accomplished with a workflow rule and a time trigger. The rule is activated when the Running Update field is set to true and a number of hours later, the time trigger resets the value to false.
2. Modify your workflows, validation rules, triggers, processes and so on to only execute when “Running Update” is false for the current user.
For workflow rules and validation rules, this is very straightforward.
For process builder and flows, the recommendation is to build a very simple flow that does nothing.
You can then call this flow from the first step of any Process that you build with the Process Builder.
When you're creating the criteria for the step, a simple formula works well.
3. Mandatory fields are trickier if you make the field mandatory at the object level. Making fields mandatory on the page layout has no impact on our test code. If you do have a field that is mandatory and you get install failures because of this, then the options are limited. Our recommendation is to replace a mandatory field setting on the object with a validation rule and then you can make the validation rule install friendly. If that’s not possible, the only thing you can do is to edit the field, make it non-mandatory, run the install and then edit the field and make it mandatory again.
4. When you want to run an install or an update, edit your user record to say Running Update = True
5. Run the update
6. IMPORTANT! When you have finished running the update or updates, edit your user record to say Running Update = False (and have a back up Workflow rule just in case you are unable to do so)
Post install scripts
Post-install scripts do not run as the running user so can cause install issues even when steps have been taken to make the org install friendly. Learnsmarter avoids creating unnecessary post install scripts whenever possible, however these are sometimes unavoidable and for these releases, installing upgrades may require additional steps.
An alternative option
Julia Doctoroff wrote a post here: https://sfdcparty.wordpress.com/2017/02/28/speaking-about-creating-a-custom-setting-to-disable-validation-rules/ to do the same thing, but instead of a setting on the user record, she used a custom setting. The end result is the same, but the custom setting could be a good way to turn the setting off for groups of users in one go.
Questions you may have
Q: Why doesn’t Learnsmarter update API versions as a matter of routine?
A: There are many articles that discuss this online. Sometimes changing an API will cause code to break – this is most obvious with PDF pages. If we update every API every time Salesforce issues a new release, then that could potentially cause an issue anywhere in our application. It is generally sensible and accepted practice to only upgrade API versions when necessary.
Q: If we reactivate the things we had to deactivate, then will it cause problems for our users because of clashing code?
A: No. The clashes only occur because our test code doesn’t follow your org rules. If your users follow your rules, then the records they create will be compliant and you won’t get errors in day to day use.