While working with Koji, you will need to apply various changes and deploy new products or bots. This page explains the main concepts you need to understand in order to maintain your Koji environment and describes the tools available in the bot that help you work safely in multiple environments.
When do I need to manage changes?
There are a number of situations where you need to manage your changes:
When modifying configuration of your bot, at some point you will need to review your changes to approve and save them.
When running multiple bots that represent dev, preprod, and production environments, you will need to prepare and check the work before deploying it. Also you will need to push your changes from one environment to another.
When product updates are available, you will need to apply them.
Before taking actions
Instructions provided on this page might be destructive. We recommend that you study these instructions carefully and follow the described logic. If you are unsure about performing any actions, please, contact us via our Support Center and we will be happy to help.
Key concepts
To successfully carry out the tasks described on this page, you must understand a number of key concepts.
Products
Your bot is made of products. Konverso will manage the built-in products, such as kbot (the framework) and all associated solutions (ithd, gsuite, jsdm, etc.). You are in change of two products: a site level product and a customer level product.
Site level product: it contains information that is related only to this specific instance. Typically, this is just the connection information that is only applicable to this particular instance.
Customer level product: it contains information that is designed to be shared amongst all your instances. This product contains your messages, entities, workflows, etc. This is the part that can be deployed to other environment.
Database and files
Kbot works with a database. Everything you view inside the Administration console comes from the DB, and anything you change is saved to the database. The database contains two types of information: configuration and data.
Configuration: this is also saved in Git files.
Data: this is about users, conversations, and analytics. Data stays in the database and it is not a part of the Git managed content.
Configuration flow
The diagram below displays possible environments, their users, DB, and relationships through the Git repository that contains the full environment configuration.
Update procedure
Reviewing changes
There are two main types of changes that you can review. Each type provides you with an opportunity to review the modification carefully before you approve it.
Database vs file
Any changes that are made in the user interface are saved in the Kbot database. Then these changes must be saved to a file, so they can be saved to Git.
The DevOps > Deployment > Manage changes > Select report shows the list of changes, so you can decide whether to approve or ignore them.
Approved changes are copied to a file.
Ignored changes are removed when the system is reloaded.
File vs Git
A Git source control is in place in the bot that allows to manage branches, version history, and merge between version.
The DevOps > Deployment > Manage changes > Git synchronization report shows the changes that can be committed.
Save changes in Git. This makes them persistent with a push to the remote Git repository.
Rollback your changes.
Integrating changes from other environments
Once you have finished previous steps and your changes are checked and saved, you can integrate changes from other environments, such as preprod, prod, or dev Kbot instance.
The DevOps > Deployment > Manage changes > Integrate report helps you integrate changes from another environment, provided that:
A remote environment is running a version lower or equal to the current version.
A remote environment is running on a distinct branch.
Applying changes
Once you have saved your changes and integrated remote changes, you can apply them to your bot. It reloads the bot configuration based on what is defined in your Git file system.
To do so, use the The DevOps > Deployment > Manage changes > Apply updates report.
Changes that are not saved will be erased.
Change management tools
To review and manage changes, use the tools that are designed for this. Go to DevOps > Deployment > Manage changes to see them. Note that you must have proper privileges to access these tools.
Select
The Select report allows you to view the changes made on the bot that are not saved to a file yet.
The report shows the difference in a human readable format, in the form of a text difference. For complex objects, such as workflows, the difference might be hard to read. It is best for the changes to be reviewed and selected by someone who is familiar with the changes done on the project.
The view comes in two forms:
Foreground: this report runs quickly in the foreground. It fails with a timeout if the processing takes more than 5 minutes.
Background: this report runs slower in a separate process task. It is appropriate if the foreground report fails due to a timeout. In general we recommend to use this report only when you work on large classifiers and dataset files, which can cause the report to run over 5 minutes.
Review the changes carefully and click the Approve and save button if you want to keep the changes.
Git synchronization
This report allows you to commit, push, and pull the changes to a remote Git repository.
The report does not get refreshed automatically after actions take place. To get an updated status, please refresh the report manually by clicking the Refresh button.
In general, the recommended set of actions is:
Review the changes and approve them (commit) or reject them (rollback). To perform these actions click the corresponding icon.
Pull the changes from remote servers by clicking a down arrow.
Push the changes to a remote server by clicking an up arrow.
When you finish reviewing, there should be no warnings, changes, or suggested actions.
Integrate
Your bot is typically one bot in a deployment chain such as:
Provided that the versions meet certain requirements, you can merge the changes from the sibling environments. For example, if you are in Pre-prod, you could:
Retrieve the changes made in production. While it is not usual to have configuration changes done directly in production, this might occur for simple things like messages, or corrective actions that are done directly inside the production environment.
Retrieve the changes made in a development environment. This is the expected path. Developers work on dev and commit/push their changes after they are done. You could merge the changes to your pre-production environment to validate them before implementing them in production.
Apply
In this tool you can:
Load the configuration from files, replacing the content in the DB with the content from the files.
Retrieve possible corrections and enhancements made on the product.
Restart a few processes to ensure all changes are fully loaded and in place in the product.
Executing actions in this report results in a downtime of a few minutes.