KBEC-00344 - Considering downstream impact when making changes in CloudBees CD (CloudBees Flow)

Making changes to objects inside CloudBees CD (CloudBees Flow) can have a downstream impact for pre-existing references to the object being changed. This article outlines some considerations when making such changes, or when designing your solutions to limit the impact downstream.

If you think about typical software development practices involving procedures, when you make a change to a procedure’s signature (re: parameter set), you might need to be changing a set of other files containing code which reference that procedure to keep things in synch. Otherwise, your code will most likely fail in compiling cleanly. Fixing those references is not an easy thing to automate - although some tools may provide means of identifying for you where you need to make changes, you still need to manually ensure that the right variables or values are being passed in by the caller of the changing procedure - and such changes usually require extra testing too. With Databases, the term used for trying to address related references is: "Referential Integrity".

Similarly, with CloudBees CD (CloudBees Flow), if you make certain changes, there can be a downstream impact that you will need to consider. For example, if you change a procedure’s signature, you have now impacted any direct calls to that procedure. This might include sub-procedure calls, schedules, workflows, pipelines etc…​. Unfortunately, cleaning those references up is again not an easy thing to automate. While there may be some improvements in the future to better alert users to the downstream impact of certain changes, and perhaps some way of helping to identify what might be impacted, it’s unlikely going to be a pure solution, since you could also have scripts outside of the product that are using the runProcedureAPI that would also need to be updated to match the change.

Some examples of the types of changes that could have an impact on referential integrity in your environment are changing:

BTW - The impact such changes can have on your environment is a good example of why having an CloudBees CD (CloudBees Flow) TEST system in place to allow you to explore change impact is better than directly making such changes to your production environment, or live system.

The more "architecting" you do for your system up front, the better off you can be in limiting the costs of having to hunt down the impact of such changes. As the saying goes: "an ounce of prevention is worth a pound of cure", so planning your use of common utilities etc…​ early on in your design work, can make your life easier when your procedures start to evolve with the your user-base needs.

Keeping your system well defined so that references between objects in specific projects are well documented might help to make hunting down the impact of such changes a little easier too. Similarly, limiting the use of objects with the same name can help reduce the burden in looking for where a reference might exist. Granted, properties with generic names like "buildname" can be impractical to avoid duplicating, but for such commonly named objects, try keeping them at a similar scope, so that you can easily know you are referencing some job-level property, for example. This can then allow you to ignore having to search for downstream impacts of changing such properties. Formulating some syntax to help identify the scope of objectnames would also be a consideration that might be helpful too. (re - perhaps use a form of prefix or suffice to help denote the level of the object)

If you do make one of the changes listed above that might have a downstream impact, what steps should you then be taking?

The action to take will typically involves some form of "scan and replace" activities as outlined here:

Renames

If references to Projects/Procedures or properties are kept within the current procedure or project in question, then searching for code that may need changing can be simplified. You may eyeball the steps involved, or if it’s a larger procedure or project, you might benefit by taking an XML export:

eg:

Then scan through that export using a tool like "find " or "grep" for where your original object name is being used.

If the property is more global in scope, then the search will becomes more difficult, as you may need to export the entire system rather than just a particular project. (This is why pre-defining which projects reference your current project can be helpful)

If you happen to have DSL code written with an CloudBees CD (CloudBees Flow) v6.0.x (or later) version, then scanning that code for your property names might allow you to avoid having to take exports.

Moves

If you are moving an object, like a procedure, or property, then the pointers above would be similarly useful to ensure that the reference paths to the object in question get correctly updated.

Parameter Changes

When adjusting the signature of a procedure, any references to that procedure will require an update. In the case of direct calls to that procedure, you will need to update the sub-procedure calls to ensure the correct parameter values are being passed in. You will also need to re-save any of the schedules that are tied to this procedure, or you will likely see subsequent launches of the schedule showing a failure event for a mismatched set of properties.

External References

For any of the changes listed above, references to objects within scripts residing outside of the CloudBees CD (CloudBees Flow) database will need to be scanned to update the code to match with the underlying change.