In this article, we'll explain a typical Agility setup, the website environments, and our best-practice development workflow.
Agility is a multi-tenant CMS, managed in the cloud, by the Agility product team. For each digital property, a customer will have a single production instance, a dedicated database which is abstracted away from developers, as well as a storage container for all media and documents. These are considered the platform components and are all maintained by Agility.
The website(s) itself, is managed by you, or your development partner. Websites are registered as Syncing Web Servers within Agility. When content is published, that content is synced to your Syncing Web Servers. That content is stored within the Agility Content Repository and readily available to the website.
While you only have a single production environment, all content can be previewed prior to publishing. When you Preview your content from the CMS, Agility will open a new tab in your browser and initiate a preview session on your default preview web server. This allows you to preview content on any website environment.
It is important to note that due to the decoupled nature of the CMS and your website, you can have as many website environments as you see fit. For example, a typical setup will involve having a local development website environment, a uat/staging website environment as well as a production website environment. This allows you to develop locally, and test and review code updates in uat/staging prior to deploying your code to production.
While you can have multiple website environments, there is only one Agility CMS instance that houses your configuration settings and content. Therefore, care must be taken to understand the impact of changes to your CMS architecture. In this regard, Agility should be treated much like a headless CMS.
Development Workflow - Best Practice
The following describes a standard development workflow all the way from requirements gathering to deployment.
- Requirements Gathering - Ensure you have a clear scope of work and you understand what changes need to be made.
- Design Phase - Typically this involves a series of wire-frames, and design work. The end goal is this phase is to have the "finish line" defined so that you and your customer on the same page as to what the final outcome and solution is.
- Architecture Preparation - Make a list of any changes to the CMS architecture (i.e. content/module definitions, or page template definitions) that will be need to be modified to support the agreed upon solution.
- Review the Impact of Architecture Changes - Make sure you understand the impact of changes to your CMS architecture and try to avoid breaking changes. Often the best way to do this is to only add NEW fields to existing definitions. You can also make copies of existing definitions and update them as needed.
- Implement and Review the Architecture Changes - Before you even start coding, make your definition updates in the CMS and review the implementation with the end user. This is a great opportunity to validate your updates with the end user and watch how they interact with your update. If you need to make additional changes, at least you don't need to update your code.
- Content Entry - Where possible, once the architecture has been validated, get the end user to start content entry. They won't be able to see the front-end yet, as you haven't coded it, but you'll get real content which can help catch bugs early and will ultimately speed up your development process.
- Local Development - Now you can start coding your updates for the website. You can run your website locally in Visual Studio with the web.config value for DevelopmentMode set to False. This will ensure that your local website will fetch the latest content (staging and published) so you can interact with your new architecture updates, and any new pages, or content that are not yet published.
- Deployment to UAT/Stage- Now that you've completed your local development, you'll want to deploy that to a UAT/Stage website environment so that the end user can provide user acceptance testing on your solution. The process for making a deployment to your website can vary depending on where it is hosted. Common options include Web Deploy, FTP, or via CI/D tools.
- User Acceptance Testing on UAT/Stage Environment- After you've deployed your code to UAT/Stage, it is important to provide instructions to the end user on how to test your changes. By default, your UAT/Stage environment should be in Live Mode, meaning it will only show published content. Depending on the nature of your changes, it is likely you'll need to provide a Preview Link for the end user so that they can preview your code changes with content that is not yet published. You can use the Email Page button from the preview bar when previewing the site to send over a link, or you can simply instruct them to click Preview within Agility.
- Prep for Production Deployment: Content - If you haven't already, test out how the UAT/Stage environment is functioning in Live Mode (i.e. not preview mode) since this will mimic what will occur when you deploy to production. Make note of any piece of content that will need to be published when you deploy to production.
You can keep a running list of these items manually, or you can use the Batches functionality of Agility to group together content and publish as a whole when needed.
A common error here is to only preview on UAT/Stage environment, everything works, then deploy to Production environment and it doesn't work because some dependent piece of content is not yet published.
- Prep for Production Deployment: Website Regression Testing - Ensure you test your website to ensure you aren't introducing a breaking change to other existing functions - you should be able to test this on UAT/Stage in Live Mode.
- Prep for Production Deployment: Agility Regression Testing - In addition to testing custom website features, it is also recommended to test core Agility features.
-> Does publishing still work? You can test this by publishing a change and verifying it is showing up on the UAT/Stage environment in Live Mode
-> Is Output cache still functioning? You can test this by viewing the HTML source of a page within a browser on the UAT/Stage environment in Live Mode and verify that the timestamp on the meta tag is not refreshing on each page view.
- Production Deployment - Now that you've tested everything in UAT/Stage in Preview Mode and Live Mode, and have a list of any content items that need to be published as part of the deployment, you can now proceed to deploying to production. This would be similar steps you took to deploy to UAT/Stage environment.
Deploy your build to production and publish any necessary content.