Hi there AppWorks fans,
Welcome to a new installment of AppWorks tips.
In my daily job as a low-code developer I see a lot of questions passing by. This post also covers an interesting topic about the choice to undeploy a package or to roll back a package. Before we can make this choice, we first would like to see what’s happening during these actions before we hit OK on our precious production data.
…A background story…
The initial question triggering this post is a little different as a team of testers wanted to have a clean environment after each deployment of the solution. Testing with a fresh mind-set is always a good thing to do, so we wondered what a nice approach would be. Some approaches we discussed for a solution containing lots of entity modelling and BPMs (where we already discussed the BPM part):
- Clean up at database level; A “no-go” as you want to manage you entity data from an AppWorks UI perspective.
- Building a ‘tooling’ project with cleanup BPMs to automate the job; Possible but takes time to build it and requires deep insights on the solution! On the other hand, you can clean exactly the things you want to clean as you would like to save the configuration entities (when applicable!)
- Set up a SoapUI project and clean the entities from webservice calls; Nice one, but this requires to expose the ‘Delete’ webservice operations on the entities; This could be a step too far!
- Deleting the solution from
/app/admin; Interesting, but this requires to rebuild your configuration entities (if applicable!) after a clean build of the project and publishing it all again; Off-course we can automate the config rebuilt part with a BPM but takes time.
All great discussion topics, but with a mindset from a developer perspective! As we all know, from a TST/ACP/PRD perspective we work with CAP files. So, a clean build and project re-publication is not an option here! There are 2 options left:
- Undeploy/rollback the CAP; Which will also remove entity instances in runtime…As you will see in this post!
- Creating that ‘tooling’ project to clean up the mess
In our case (in TST), we go for an undeploy and redeploy. Why? Well, we just want to remove everything for a fresh start, and we have a BPM in place to generate the configuration entities (80% full functional). We also have a cleaning BPM available but was failing at that moment in time for some strange reason. So, we had a choice to make under the pressure of time. It all depends…as always! Also a wake-up call for our solution; Keep the data-generation and data-cleaning features in place when the storm is coming and use them regularly to keep them work!
…End of the story…
After making the choice we were left with one question! What is the difference in un-deploying a CAP file and rollback a CAP file? And what is happening in runtime when doing so…
Let get right into it…
It all starts with a plan! We need a couple of CAP files versioned after each other; So, this will be our roadmap:
1.0.0: Our first ‘Project’ entity1.0.1: The second ‘Issue’ entity2.0.0: A ‘toMany’ relation from project to issue
We deploy the packages in a specific organization (my regular organization appworks_tips) with the ‘Application Deployer’ artifact in the System / Shared space. After each deployment we’ll create instances in runtime, play with rollback / undeploy actions, and check the result.
FYI: I use a VM with snapshots, so I create, evaluate, and package my solution cycles first; After this I revert to a clean snapshot to install the packages!
Time for some craftsmanship! Move yourself to your favorite project, create a new entity type of document with name project (saved in the entities folder). Just add one property prj_name, generate all the rest, update that ‘List’ BB with a nicer name, and do a publication. Create instances in runtime and make sure it all works as expected. You should be familiar with this task…correct? This is the end-result:
Version 1.0.0 is born! Right-click the project and open the package properties from the context menu:
You get a new modal popup where we update the properties for our own needs. In my case only an update for the deployment space:
Hit OK; from that same packaging context menu, you can create a new package, and also download the package.
Version 1.0.1 and 2.0.0
We continue the build; Add a second entity with name issue. Again, with a property isu_name, make it nice, and do a publication. Make sure it all works in runtime. When ready, go to the package properties, update the minor version number. Save it, and you can create and download CAP file 1.0.1.
Same exercise again; Only this time we add a new to_many_issue ‘Relationship’ BB on the ‘Project’ entity. I also update the ‘Create’ form with a ‘Grid’ type of element:
Ohw…Don’t forget to select a browse-list for this grid element (It’s not in the screenshot)! Me, myself, and I also forget this every time.
With the relation in place and a quick test in runtime, we can create version 2.0.0 of the package. Well, you know the drill by now! I only needed to update the values for the major and minor version in the package properties.
This is my list of packages for you to download:
1.0.0 deployment phase
After the package creation, I move back in time with my VM snapshot like nothing happened. Normally we would deliver these packages to the “Admin” guy/gal in the DevOps-Team for a deployment in TST. So, back in time we enter the shared space of the platform from the /system resource path of the AppWorks URL. From this “shared” space (I log in with the sysadmin account), we can open the ‘Application Deployer’ artifact. We can do the deployment of the 1.0.0 CAP file from this artifact , but we do it the subtle way this time!
Hit the ‘Configure authorization’ button and give your organization access to deploy packages…Like this:
At this time you can move your ass into your own organization and continue with the ‘Application Deployer’ from this perspective…How nice! Upload the 1.0.0 CAP-file and deploy it:
Just follow the wizard…How hard can it be!? Ohw yeah…I have an account awdev with the developer role and administration role applied which makes the difference on what artifacts you eventually see.
Notes:
- On a default AWP installation the package signing security settings are restricted! This is an option in the ‘Security Administration’ artifact in the ‘System’ space where you find yourself a ‘Code Signing’ tab:
- Express deployment option; This is available when you first upload (without direct deployment) and upload later. This skips parts of the full wizard for fast deployment.
- In the deployment wizard, I always mark the option ‘Revert on Failure’; I never understood why this is even an option? Comment me on this one!
Alrighty Then! Solution deployed, time for the runtime and creating entity instances of our precious ‘Project’…NICEEEE! The next step…
Un-deployment phase
Before un-deployment, we first take note on what happens in the database. For this I use the tool HeidiSQL with a view like this:
So, our data is reachable (duh?)…Now the un-deployment! Open the ‘Application Deployer’ artifact again from your own organization (as we authorized), find your package and undeploy it:
Well, what do we expect after this? Well, the solution is gone from the runtime…That’s for sure! How about the data in the database? Let’s query and get yourself informed with a painful result:
Yes my friends…The data is gone! So, be careful when doing these actions on PRD!! To make the solution available again we (express) redeploy the package again, and you end up with a clean solution which is great for TST (and ACP!?).
With the solution back in place, create new project entities in runtime and go to the next step…
Now that we’re up and running again with version 1.0.0, it’s also nice to play with the solution status options in the
app/adminlayer of the organization…Have a look yourself and play with the settings to get a feeling. It’s out of scope for this post, but I just want to make you aware of the practical options on a solution, and it’s a small task with major runtime consequences!
It’s even possible to delete the solution from this same admin layer; You can do this, but to make it available again you still need to undeploy the solution package and redeploy it again. From a development environment perspective, you see this works differently (DEV uses projects; not CAP files)…So, be aware of this!
1.0.1 deployment phase
Back to your own organization with the awdev account and open the ‘Application Deployer’ artifact again. Now we deploy the 1.0.1 CAP file. I first upload the file and do an express deployment after it…Just because we can!
Get yourself informed about the ‘UPGRADE’ detection in the deployment wizard:
Just ‘Deploy’, and ‘Finish’ in the end. Time to enter the runtime where you can verify our new ‘Issue’ entity is available for usage! How about the ‘Project’ entity? Well, it’s still in place with the instances created from the previous section (as expected!). If this was not the case, something is really going wrong in the upgrade procedure of the platform. Create those issue instances and jump to the next section.
Undeploy vs. rollback
Have a look again in the ‘Application Deployer’ artifact. We’re on version 1.0.1 of the package and have an option to choose from:
The options:
‘Rollback’: Will roll back the solution to a previous (selectable) version of the solution. In my case only version 1.0.0.
‘Undeploy’: Will undeploy the complete solution (all versions included); We saw already what happened during this action…Yes, all instances are removed from the runtime; So, use it wisely!
Leaves us with the ‘Rollback’ scenario…Hit it, follow the wizard, finalize it, and see what happened in runtime!? Yes, my friends…Your ‘Project’ instances are still in place, but the ‘Issue’ instances are removed (also at database level!). Can we redeploy 1.0.1 again? For sure, you can, but you are required to created new instances for the ‘Issue’ entity! Wait for that redeploy action as the next step we’ll deploy 2.0.0 directly as try out!
Deploy 2.0.0
Can we do this in one step? With skipping 1.0.1? Yes, we can! Only, we can’t roll back to 1.0.1 as it’s not installed! Can we install it backwards compatible after 2.0.0 is installed? Nope!
I tried the above scenario but get this error:
2
equal to or greater than '1.0.1' is already deployed to 'ORGANIZATION' space.
So, continue deploying and making it a smooth experience by installing first 1.0.1. After this install 2.0.0 too. Your ‘Project’ instances are still available and with version 2.0.0, we introduce a relation with ‘Project’ and many ‘Issue’ instances. Create those instances and relations. Once done, we go to the next step…
Rollback 2.0.0 to 1.0.1
Yes, this is an interesting one! What to expect here? Well, if I understand it all correctly we should end up with only unrelated ‘Project’ and ‘Issue’ entities!? Why? Well, because version 1.0.1 only contains both those entities where 2.0.0 introduces the relation. On database level it’s really simple:
- 1.0.0 contains table:
o2aw_tipsgenericproject - 1.0.1 contains table:
o2aw_tipsgenericprojectando2aw_tipsgenericissue - 2.0.0 contains table:
o2aw_tipsgenericprojectando2aw_tipsgenericissue, AND…o2aw_tipsgenericprojectissue
So, a rollback (I tried it out for you) does exactly what we expect! We’re left with only 2 tables of created instances. When we redeploy 2.0.0 again, we also need to build the relations again!
Concluding thoughts
Well, for our purpose (cleaning up TST / ACP); the undeploy action did its job very well. This post made it small; with a large solution you need to focus on a lot more (like your services containers, roles from OTDS, global configurations, etc.). I also keep out of scope the cleaning on database level for your BPM instances, case instances, etc.
About the rollback option!? Well, we saw it can introduce missing links in your database! So, you want to be aware of the differences between version packages and understand your database structure at a deep level. With a large solution and multiple developers this is a challenging task to figure out. So, in my opinion: When a rollback in PRD is required, you seriously did something wrong in the team collaboration bringing a solution from TST to ACP!
Bringing a version feature-save to production, I recommend the introduction of feature-flags (which do have their limitation)
That’s it…A “DONE” for this post where we learned about un-deploying a CAP package and what will happen in runtime. We even touched the rollback option which require deep insights on the different package deliveries. The post also exposed what happens at database level, and it works as expected. If it’s the correct outcome depends on the required end-result. For TST and ACP it’s fine. The only thing we need to be careful about is not executing this undeploy action on a PRD environment without a solid backup plan for recovery. I leave it with this last conclusion…Have a great weekend and till the next one!
Don’t forget to subscribe to get updates on the activities happening on this site. Have you noticed the quiz where you find out if you are also “The AppWorks guy”?
