Now for the nuts-and-bolts step: Development! We have covered requirements gathering, analysis and prototyping, and design. These process steps are necessary to maximize the highest quality software even for the smallest story.
After having done all the work with analysis, prototyping, and design the development stage should be relatively straight-forward. Essentially you will be following the instructions you set up for yourself in the design documentation. There should be no surprises, no technical hurdles, no blind-siding with new requirements right?!
Well, unfortunately that isn't always the case. The purpose of all of this work is to mitigate risk of failure or poor quality. These phases will reduce risk to a high degree.
In the diagram I show everything going back to requirements should a problem be found. However, this can also go from the current to any previous step depending on what was found, and the severity of the issue.
So what is involved then at the development phase? Let me list what I consider necessary for successful development, and then drill-down on each topic:
- Environment - ideal setup, promotion steps, cloning strategy. Announcement of clone. Export of in-work Update Sets, and reapplication. Stability considerations vs. working with the latest clone.
- Coding - best practices and standards.
- Unit and Integration Testing - from design document, exercising the code.
- Update Sets
- Peer Review - prior to deployment. Development, Update Set(s), Fix Scripts and data uploads.
- Test Deployment - what is being promoted, installation steps and necessary documentation (the dry run; treat like a deployment to production). Fix Scripts and data uploads.
Ideal Promotion Environment and Cloning Strategies
So why do I bother to tackle this topic in an article on development? This is probably the most important part of developing in ServiceNow. Without a solid cloning strategy to encompass the development life-cycle; all post-development stages have a higher degree of risk associated with out-of-date-software or incompatibility with the Production environment. If your development environment is not updated from production on a regular basis then there is a higher degree of failure when your software is installed.
1. Best Environment Setup
The best development to production setup would include a Quality Assurance instance, and a User Acceptance Testing instance as intermediary stages between development and production. This isolates each step from the other, and reduces the need to clone back to the development instance after every push to production.
a. Developers should never have access to the QA, UAT, and Production instances. The temptation is too great to do in-place modifications as defects are discovered. As defects are discovered by QA they will be communicated to the developer who will rectify them on the development instance. The developer will open a new Update Set that will capture a number of these for each round of QA testing. After testing has been successfully completed all of these will be merged into a single update set which will be promoted to QA for a final test. Again, don't skip these steps. They produce high-quality code, and significantly reduce risk!
b. There are a number of strategies for a promotion environment. These are listed from best to least desirable.
i. Development -> Test (QA) -> Staging (UAT) -> Production
ii. Development -> Test (QA) -> Production
iii. Development -> Production
NOTE: A lot of companies view the UAT instance as not necessary. My feeling is that if the budget allows for it; it is the best approach. A UAT environment should be as close to production as possible, and not have QA testing/development defect correction going on while users test. QA, on-the-other-hand will be somewhat shifting-sand as the back-and-forth between development and QA; as defects are found and corrected, will cause too many interruptions (think resets) for UAT to be quickly completed. I will address this topic in more detail in a future article.
2. Team Development
Let me take a moment to address Team Development. If you have a large shop with several development teams this is a terrific way to approach the difficulty of each team interfering with the other. With this strategy you have multiple development instances that allow for merging when ready for integration testing.
3. Best Cloning Strategy
This is perhaps one of the most controversial topics I have run into with ServiceNow! I have spoken with a lot of different admins, and management, and some guy I bumped into on the sidewalk in Chicago, and every one of them has a different opinion on how this has to be handled!
So here is my two cents worth:
1. Clones should always be done from Production.
2. It is a good practice to clone back to ALL instances after a major production push to bring everything into sync. This would be items such as table structure, code, lookup table data, CI relationship data, etc. I would advise against cloning the actual production table data itself as this might contain sensitive information. Use some thought when cloning over the user table data as you might be clobbering special access accounts that will have to be recreated. Don't clone the logs (this will reduce your clone time significantly).
3. Maintenance releases are a different story. It may be that you will want to clone back periodically (once a month perhaps) after every so many of these. Such a release would consist of defect fixes, data refresh of lookup tables, minor table structure additions, and so on.
4. When cloning to DEV and development for a future release is ongoing it is an obvious practice to have all of the developers export their current update sets to disk prior to the clone. Then upload them after the clone. Communication is all in this situation! I have seen work lost because of the lack of communication. It wasn't pretty.
5. When cloning to QA/UAT again make sure that all parties are communicated with. QA may have specialized tests that need to be exported to disk prior to the clone.
6. After any major or minor ServiceNow release. This is an interesting situation as the implementation of a patch or major release usually progresses from Sandbox to Dev to QA to Prod. Then clone back to all from Prod after the final release. Remember that to clone you have to be on the same version of ServiceNow in both instances.
NOTE: You might say: Why bother cloning at all? With promotion from Dev to Test to Prod don't you already have the same structure? The same code? The same everything? Not necessarily. With QA maybe, but with DEV you want to do periodic refreshes to keep things in sync. Dev just receives too many changes; a significant number of which may never see the light-of-day in production.
DEVELOPMENT
Development Constraints:
1. Development should only be done in the DEV environment. Do not make changes in QA or Prod. Period. As a matter-of-fact if your development team and admin team are different teams it is recommended that developers NOT have access to anything but DEV. This reduces the temptation to fix a defect at the location it was discovered. Remember: All problems should go through process. Accumulate minor issues into a single release. Major issues into their own release. As a rule: do not do development in your production instance. Exception: you have just installed ServiceNow for the first time, and have yet to activate it for production use (what we like call a phase 1).
2. If possible do QA and UAT on their own respective instances. I know that some shops only have a DEV and PROD instance. If that is the case then STOP all development on DEV prior to doing QA testing (and during). Control your environments! Reduce the risk of a shifting sand situation where the very code you are testing may be changing while it is tested!
3. Production is your "pristine" environment. Keep it that way. It should only be modified as far as configuration (a term that has many meanings in ServiceNow). This means properties, and data; NOT code. I am talking development here remember.
4. It is a best practice to turn on auditing for the more important table structures. This reduces the "who the heck changed that!" problem considerably.
5. Code repository. This is another really hot topic of discussion at our company. So how do you do versioning? Baselining? Document repository? What is the process? Can you reset back to a baseline? How would you do that? Well, I'm going to leave these questions for a future article. It would triple the size of this one!
6. All development should be in an update set.
7. Use Fix Scripts for code that has to be run pre- or post-update set implementation. These have the beauty of being included in an update set. They are usually for data preparation.
Development Process
1. Create an Update Set. Standardize on naming. This should be something that will help you, at-a-glance, know what is in the Update Set. If you are an Agile shop the story or epic name could be used for example. Try to keep your update set small and manageable. Use comments for each change in the update set. All of this helps with audit and traceability. Greater granularity allows for easier rollback of a particular set of features; while allowing others to proceed.
2. Adopt coding standards for your scripts (Douglas Crockford's site is a good start, as is the ServiceNow Coding Best Practices wiki site). Use variable and function naming standards. Use code formatting. Use comments where it makes sense to describe a difficult to understand piece of code. Think carefully on the maintainability of your code!
3. Adopt interface standards for your Forms. Keep them simple. Bust up busy forms into sections that can be viewed as tabs in the tabbed format.
4. Unit test during development. Use Fix Scripts and/or Scripts - Background to check portions of your code. I have created a simple way to test Business Rules with these tools as well (Current Factory).
5. Communicate with other developers while doing development! Don't step on each other. Coordinate with each other. Don't work blindly in a vacuum assuming all will be well and no one could possibly be modifying the same bits as you. Danger, danger! The coordination will save a lot of headaches.
6. Use peer reviews. Code review with someone who is not familiar with what you have been working on. Sometimes when explaining my code to another developer I find things that weren't done quite the way they should have been. Better to catch it at this juncture than when it goes to QA! When another coder asks: Why did you do it that way? Don't get offended! Be prepared for an answer. Defend your implementation. If you can't you need to make some changes! BTW, the peer review process in ServiceNow code is rarely involved, and usually takes only a little time. Make room for this step. Remember: Quality of code.
7. Don't be afraid to ask for help should you run into something you can't solve. There are several resources on the community; you can usually get your question answered in a lot less than 24 hours. Research your code solutions (this should have been done in the Analysis and Design phases, but it is too late after the development has been done and it is in QA!). There are tons of code examples, and solutions for most of your needs on the web. Don't forget about ServiceNow share!
You, as a developer, are responsible for ensuring that your code is as good as you can make it prior to handing off to the test team. Do NOT expect the test team to find your mistakes for you! Frankly, I find it humiliating and embarrassing when a bug makes it to the testers. As the developer I am the beta tester, not them. Your reward should be the immediate gratification when the test team (and management) exclaim on how smooth testing your code went! Be personally responsible. Police your code. Be proactive, don't be lazy.
Note: This is a good place to plug something that also gets left out of the picture a lot. Even with time constraints; over-engineer your coding solutions! Put in try/catch, and error catching code wherever it makes sense. Even the catch-all: "An error occurred that should not ever have occurred" is a great thing to have in your solution. Try to anticipate the weak points in your code and compensate for them. Be the true software engineer!
UNIT TESTING and INTEGRATION TESTING
You know, I often get the impression that this is the elephant-in-the-room that everyone tries to ignore. This is the step where you, as the developer, should be testing the tar out of your code! If I had a nickle for every time I have run across developers throwing their code out to QA untested; well I would be a rich man!
Don't expect QA to alpha- or beta-test your code! This, in my book, is irresponsible. A conscientious developer should be paranoid about their code making it to QA with ANY bugs in it.
1. Exercise all facets of the changes you are implementing. This is the nature of the unit test.
2. It is important to try to anticipate the unit tests needed during the Design phase. These will not necessarily be all-inclusive. As you build your solution you will run across tests you didn't know you needed. Back-fill these to your Design document. Personally I like handing all of my unit tests to QA so they have a starting place to be begin constructing their tests. Don't view this as doing their job for them! Don't assume that you as the developer know how to do their job.
3. Integration test your solution. This is NOT unit testing. Instead you are checking to see if your solution plays well with others. Try to anticipate what other applications in ServiceNow might be affected by your changes. Don't assume that it will not. Back-fill these tests into your Design document as well. This is a best practice.
4. Write up your test results. I like doing this in a spread sheet for easy organization. I usually have this as an attachment to my Design doc; if there are a lot of them. Use what makes sense. Don't get too hung up on the format. I go for thoroughness of the testing; as a bit of overkill is a good thing.
Format (organize by functional area if possible):
a. Test Number
b. Test Description - what is being tested
c. Test Steps (numbered)
d. Requirements being addressed (just the numbers)
e. Expected Results
f. Actual Results
5. Have a notification process. Status reports are a good thing. Make sure your project management know your progress to completion of the plan. Flag problems immediately. Don't sit on them hoping they will resolve themselves!
6. When you are done with all coding and testing, and have verified that all of the requirements have been met, you are ready for release to QA.
7. Pull everything together: Documentation, implementation order (if there is more than one update set, and/or Fix Scripts to run; to prepare data, and/or data to upload). This documentation will be used by the admin who actually installs on the QA environment. Note down anything that did not install as expected, and refine your installation process accordingly. The idea is to work out all of the kinks prior to the final move to production.
Conclusion:
Having a development process in-place is a best practice. It improves quality by having steps that reduce the number of defects and improve code maintainability. Even a one-person shop should still have a development process. Don't cut this corner just because you have a small group of one!
BTW, our company keeps a Knowledge Base. These are articles for capturing any new techniques or coding breakthroughs. Our developers are encouraged to contribute to this repository. This has proven very useful, and keeps us from having to reinvent the wheel when covering the same or similar ground at a later time. Add this to your Analysis research step: Search the KB!
In my next article I will be talking about the importance of Quality Assurance and User Acceptance testing!
Steven Bell
If you find this article helps you, don't forget to log in and "like" it!
Also, if you are not already, I would like to encourage you to become a member of our blog!
