Disclaimer: This article includes some basic best practice points about update sets and things I've learned over the years. The information here has been gathered from various sources which I have attempted to reference to, and my own personal experience on the platform. Is it perfect? Nope. One thing I've learned in my IT career is that I don't know everything. Things I think I knew, I knew wrong, and I need to go back every once in a while to square one to review the documentation to correct myself, or to understand new features/fixes. I welcome any comments/suggestions/etc. to make this article more comprehensive and applicable as the platform changes.
Update Set Naming Convention
Most of this is echoing ServiceNow documentation but it's so important.
Make update set names meaningful. You or someone else should be able to pinpoint an update set quickly.
- Related task record, version, release or sprint number
- Brief description
- Developer’s initials OR username
- STRY00123_Incident Mgmt Fields_ABC
- STRY00124_Incident Mgmt Form Layout_ABC
- STRY00125_Incident Mgmt List Layout_ABC
- STRY00126_Incident Mgmt Email_ABC
This is all from the white paper, most of the time, depending on my organizations development standards, I use something like: Story number - username - Short description of story. That way I can search for the update sets by the story number, username, or short description of the story.
Your organization should have a knowledge article detailing their development standards and include this in it. This is paramount for new team members and folks new to ServiceNow. Don't assume everyone has read the ServiceNow documentation on update sets.
Versioning
If needing to create a new update set for issues not fixed in the first update set, or discovered through testing, do not set first, second, third, etc. update set back to In Progress. Instead create a new update set and include the versioning in your naming convention i.e. Story Number - username - Short description of story V2 or Story Number - username - Short description of story.2, literally anything to tell you this is a new update set for the story. Again, this is for your organization to decide what works best for them, as long as there is something!
Note: Descriptions in a Sub-Development update set don't migrate up with using Team Development, so they'll need to be set when creating the new update set.
Updates in the wrong update set
I found this in the ServiceNow Documentation for update sets. Personally, I've NEVER had any issues with changing the update set field value in an update set during development (not when an update set is Complete) and these steps are even confusing to read and the word 'back out' scares me with an In Progress update set (because, how? I'm assuming this documentation needs to be more verbose) but here's the official documentation:
- Switch to the desired update set.
- Modify the object (record) that was originally changed. You can make a trivial change, such as adding a field.
- Save the record.
- Back out the change just performed, and then save the record again. This action ensures that the latest version of the object is included in the desired update set and prevents duplicate updates for the same object in a single update set.
Clean up your update sets
This is something I didn't understand early in my career, and sent a bunch of crap up when promoting my update sets. (SORRY!) Try to make your update sets as clean as possible before promoting them from the source instance. This means moving anything you didn't mean to create out (or somehow snuck itself in, I'm looking at you form sections) to Default or if your update set is super bonked and it doesn't take long to re-create your changes (i.e. save your code in your editor) then complete it, back it out, and make a new one. If you need to delete something you created in an update set, move it to Default, switch your update set to Default, and delete it there. I know this contradicts ServiceNow's documentation, but this is a 'from experience' thing that I've never had an issue with as long as done correctly. Versions on records will thank you, and the person promoting your update set will thank you too.
Migration Path
Your organization should have a process surrounding your team's development. The basic gist of this is, DON'T CREATE UPDATE SETS ON TEST OR PRODUCTION. I know you may be tempted to fix something real quick on Production or especially Test because you gotta get that Test passed ASAP but don't. You're only doing a disservice to yourself and the team, especially when you have to align your environments by either cloning or sending that update set down. It also sets a bad precedence for any Service Owners, etc. that think you can just do something real quick and not follow the process. Speaking to this, this point stresses the importance of using Data Driven(Tables) workflows, System Properties, or Templates. Basically, if you can put something that needs to be changed frequently or more often or not, or basically would be super annoying to do in an update set, i.e. an Assignment Group for a RITM, put it in either a Template, System Property, or Table than great, because this can be done in Production as it's a data change. Just keep in mind you're going to want to probably send that XML down to align your instances for Testing/Development. I cannot stress the importance of establishing data driven workflows and development early enough. The last thing you want is 200+ workflows and then think about using Templates, as it's way too much work and time trying to change that over and try fitting that into your backlog, bleck.
Here's a nifty graphic on the Migration Path from the white paper:
Team Development
There's a lot of mixed feelings about this feature of the platform across the community. Some folks wouldn't touch Team Development with a 10 foot pole, but it can be useful when working with multiple development environments spread across multiple development teams and/or consultants.
I've worked with 3 organizations that used Team Development and here are my takeaways:
- Keep it Simple - Just because you can keep pulling from the same source update set in Sub-Development, doesn't mean you should. Think about your migration and back out plan when promoting update sets via Team Development. Referencing back to Update Set Best Practice, if you've pulled an update set in Team Development, mark it as Complete in the Sub-Development environment and make any changes in a new update set. Why is this important? Think about having to back out an update set in Dev that doesn't align with the number of updates and naming convention in Sub-Dev, what a mess. Who wants different counts and names of things across different instances. NO THANK YOU. I've always aligned the update set I'm creating in Dev with what I've created in Sub-Dev, this way I know I can back out change in V2 or V3 of an update set in Dev without backing out a bunch of other stuff. This gives the developer, or me, time to export V2 and import it back in without the chaos of trying to understand which updates I'm backing out, what update set it's in, etc.
- Backing out in Dev, backs out in Sub-Dev. I promise, promise, this will be painful if you don't understand this concept or communicate with your developers first. Team Development backs out and cascades the back out down through it's children meaning you lose your development on the source instance and have to do it all over again, so please save your update sets and reimport them back in if you need to fix something that has to be backed out with Team Development. I've seen too many 'oh no' moments with this, and always make it a point to export my update sets first if there's an issue on the parent instance in the case I'm working with someone who doesn't understand Team Development.
- This is why we don't use Team Development in Test. 🙂 Imagine losing all of your work because something went awry in Testing, no bueno! Test is meant to be a practice run of how an update set should promote to Production, so using Team Development for this process essentially takes away that test run and leaves you with inaccurate results of how that update set would promote. I love this point from the community post linked below: Also, using update sets in the Test and Production pipeline, allows you to clone from Production to Test instances when your test users need newer data, without impacting your development process and instances. YAS!
- Batching - this I would like to know more about, I don't think you can use batching in Team Development, so keep this in mind. Most organizations begin batching at the Test level anyways for Production development, but I can see why a developer would like to have their batch hierarchy set in Sub-Development in order to keep everything clean.
- If you plan to clone, plan to wait a while after the clone for your Sub-Development environments to reconcile. I've seen this take up to a day, plan for this in your clone procedure.
- Read this community post, and LOOK AT THIS PICTURE AND LIVE IT IF USING TEAM DEVELOPMENT, I can't stress how many times an implementation has been derailed due to someone trying to use Team Development with Test, or how best practice has been curtailed because someone found out how to set it up to work with Test.
Initial Implementation
Please, please do not clone up during an implementation. I know this is the super easy button but this is only done once, during the core setup. This is to ensure the core items are copied to all other instances without doing this individually. After this, update sets are used to promote development up through the instances.
Core Setup (Taken from the White Paper I've attached below)
- Foundation data import - Users, locations, companies, departments, groups, CMDB, etc.
- Integrations setup - Integrations that are part of the initial phase of core setup.
- Instance configuration - Themes, Global properties, time/date, company record, etc.
Why is this important?
- To establish your development lifecycle and get you in the habit of using update sets during your implementation and after your implementation.
- Understanding and accountability for each code change that migrates up throughout your implementation. Your team should know exactly what changes are migrating up and what stories they're tied to.
- Imagine the code gremlins that can be sent up by cloning from Dev each time. Unless you have an eagle eye on all of the code that has been changed you have no idea what crusties you're going to be sending up to Production. Why do that to yourself?
Another nifty graphic from the white paper on how this should work:
Batching
I'm not going to re-document the instructions on the wheel here. The ServiceNow Developer Blog pretty much sums it up. I will however state four points about batching:
- Double-Triple-Quadruple Check you have everything in your batch before retrieving it to another instance. Getting rid of a batch in an instance to re-push it is a PITA depending on the size. Here's how you do it. First, you gotta delete the batched update set in Retrieved Batch Update Sets in Update Sources. But the fun doesn't stop here, if you try to re-retrieve the batch, it won't bring over everything again. That's because each individual child update set is still loaded in the instance under Retrieved Update Sets. To retrieve the entire batch again, you have to delete all of the loaded children from Retrieved Update sets as well. There is literally no documentation on this, and this realization came to me early after using batching and having an 'oh no' moment.
- Batched update sets may take longer to commit than sending update sets individually. Why? I don't have a technical explanation at this time. I'm sure someone at ServiceNow knows. This is from experience. A good best practice is to commit the batch to a QA instance as a test run before your Production release if you can. If not, just allow yourself more time, I'd say 1hr or so more would be a good rule of thumb, but I've seen it take longer. Note: I've also seem some weirdness with Batched Update Sets and Madrid with table additions/deletions - if things seem weird, contact HI (Now Support? I'll always call it HI).
- You can have multiple scopes in your batch, but not your update set. I repeat, you can have update sets with different scopes in your batch, but you cannot have updates with different scopes in your update set.
- Dump merging for batching. Read the developer blog article I posted. Unless there is some necessity for merging, don't bother with it, ESPECIALLY if you're promoting to Production. Why? Because you want to have a solid back out plan. Imagine having to back out your entire release because of one issue in one update set. I've seen it. Merging had it's time and kept everything clean for releases, but batching offers so much more flexibility and CYA that I can't think of a good reason to keep merging.
Some Interesting things to note
- Set completed update sets on the Production instance to Ignore. This state ensures the update set is not reapplied when cloning the instance.
- If update sets are being generated as fixes for problems, consider including the problem ticket in the name (for example, PR10005 - Duplicate Email Issues Fix). Not really a 'WOW' moment, but makes sense. Most of the time developers get so focused on STRY/DFCT that the original issue can get lost.
- Team Development does NOT LIKE big tables. I promise you, some funky stuff will happen if you're trying to add a field onto something that extends task and has over 1 million records. Look into archiving or be aware that you may have to use Update Sources in cases like this.
- Understand how to be flexible, especially if you're using Team Development. It's not perfect. It's old, and hasn't seen a lot of love from ServiceNow in the past couple of years. Most of the time if you keep it simple, it works great, but sometimes it just acts up. Why? I don't know, I don't work for ServiceNow. If I could see behind the curtain I would definitely document it here, but it's not a good use of my time to try understand the bugs I can't see, just to know how to fix them. I've seen workflows not show up in the list of updates in Team Dashboard, to table columns not moved at all (see my point above). Sometimes you're just going to need to shift to Update Sources for a few things. Don't worry, everything will sync up nicely with your next pull.
All in all, if you're a new developer or older, it would behoove you to understand update sets as soon as possible in your development career, as there will always be some errors or problems to troubleshoot, especially if you're working with multiple development teams or using Team Development. The more you know about update sets the faster you can resolve those issues, and prevent issues through proper development.
Resources:
ServiceNow Documentation - Update Sets
Development Best Practices White Paper - Attachment (yes, this is an oldie but still has lots of goodies)
Properly deploy changes using Team Development
