Complete Guide to Setting Up and Managing Sandbox Environments in Qntrl | Qntrl Online Help | Sandbox Online Help

Using Sandbox in Qntrl: A Step-by-Step Guide

Step 1 - Setting Up Environments

Environments  Types    

Sandbox is built as a multi-environment model, supporting both simple use cases with direct deployment to Production and complex setups with multiple environments for development and testing.
  • Production Environment: The final live environment, automatically created during Sandbox setup with a default instance. It cannot be edited or deleted, and no new instances are allowed.
  • Staging Environment: Used for extensive and continuous testing. Projects remain associated even after deployment.
  • Development Environment: Dedicated for developing and testing new features. Projects are removed post deployment, allowing the association of new projects for subsequent testing phases.
  • You can create either Development or Staging environments in any order.

  • At least one environment must be created during the initial setup of your Sandbox organization.               

 

Create a New Environment 

  1. Navigate to(settings) >> Advanced >> Sandbox and click Development Systems.
  2. Click New Environment, and add the below environment details.
    • Select Type: Choose between Staging or Development. Refer to the Environment Types section for details.
    • System Environment Name: Enter a name for the environment.
    • Description (Optional): Add a brief description.
  1. Click Create New System Environment.   

The new environment will appear below the Production Environment, ready for adding instances and associating projects. Similarly, you can create multiple environments.


  • You can create up to five environments.
  • You cannot edit or delete an environment after creation.                            

Step 2: Create and Manage Instance 

An instance in Sandbox is where projects are associated and tested. Any changes made within an instance are saved to the corresponding associated project.
To create an instance:
  1. Inside an environment, click Add Instance and enter the new instance details.
    • Instance Name: Give a name for the instance.
    • Description (Optional): Add a description.
    • Associate Project:
      • Choose to create an instance with or without an associated project.

      • Select an existing project from the dropdown or create a new one by clicking New Project. Learn more.
  1. Click Create Instance.  

  

 

Create a New Project (optional with instance creation)      

If you choose to create a new project while creating an instance,
  1. Fill in the following Project details:
    • Project Name: Enter a name for the project.
    • Description (Optional): Provide a description.
    • Repository Branch Name: Specify the branch name from your version control system.
    • Project Members: Add members who can access the project.
    • Parent Project (Optional): If applicable, select a parent project. Applicable only for Sandbox with multi-level environments.
  2. Click New Project.


The project will be created and listed under the Projects list in the Project module.

Associate and Disassociate Projects     

Only one project can be associated with an instance at a time.  
  1. To associate a project to an instance, click the dropdown arrow next to Associated Project in an instance. Select the desired project from the list.
  1. To disassociate a project from an instance, click the delete icon next to the associated project name.

Switching projects replaces the current project's data with data from the newly selected project. This action can only be performed when the instance is in 'Ready' or 'Idle' states, not during 'Development'.

Edit the Instance         

  1. To edit an instance, click the action menu icon and select Edit Instance.


  1. Update the name or description as needed, then click Update Instance to save your changes.

 Limitations 

  • You can create up to seven instances in a Sandbox. Each instance can be linked to a different project.
  • Only one project can be active in a sandbox instance at a time.
  • Only members and admins of the project can access the associated instance.
  • Once a project is associated, the live portal switches to 'read-only' mode. To make changes, disable 'read-only' mode in preferences. Learn more about enabling and disabling Read-only mode.
  • To switch projects within the same instance, disassociate the current project first, then associate the new one. 

Step 3:  Accessing and Working on Instance

Instance States         

  • Ready: Instance is created but no project is associated.
  • Idle: Instance has an associated project with changes saved.
  • Development: Project is associated, but changes are not saved to the repository; switching projects is not allowed in this state.
  • Import in Progress: Data import is underway; the instance status shows as "Import in Progress."
  • Import Failure: Data import has failed.
NotesFor instances in the 'Failed' state, a retry option is available.                          
 

Import a Process in Instance 

  1. After creating an instance and associating a project, the data import begins. The instance will remain inaccessible, showing the state as Import in Progress until the import completes.

  2. The Access Instance button will only be enabled once the import is finished.

  3. You can monitor the import progress and view logs by clicking on Import in Progress Once the installation is complete, click Close.


  1. A replica of the current live environment is created, including cloned boards but without card data. The instance will then switch to the Idle state.

 

 Access the Instance

  1. After the import process is complete, the Access Instance button will be enabled.
  2. Click the Access Instance button. This action will open the instance portal, which displays sections for both saved and unsaved changes. Initially, the unsaved changes section will be empty.  


  1. You can now work on the cloned portal and make the necessary changes. 

AlertWhen working with scripts and functions across different environments, domain-specific values and IDs often need to be hardcoded. To simplify this, use ConfigStore to create parameters and assign dynamic values for each environment. For more details, refer to the ConfigStore module.

 

Understanding Sandbox Specific Behaviour   

When working in sandbox environments, some behaviors, especially around scripts, IDs, and users, differ from production.

Script & ID Handling in Sandbox       

  • Avoid hard-coding IDs (like layout or project IDs) directly in URLs or scripts.
    Instead, use Config Store and pass the ID values dynamically.
  • If you reference an ID in a script (like a layout ID or a ZValue) and publish it:
    • When the script is migrated to a sandbox, that production ID is automatically replaced with a corresponding sandbox ID.
    • This ID mapping is handled automatically during:
      • Sandbox creation
      • Deployment to higher environments
      • Syncing from production (reverse sync)
  • This applies to:
    • CodeX Scripts
    • Client Scripts
    • Custom Functions
Example:
If your script includes a layout ID and you move it to a sandbox, the system swaps the original ID with the layout ID created in the sandbox.

User Availability in Sandbox       

  • Only users associated with the linked project will be migrated to the sandbox.

  • Teams and roles are carried over, but only project-specific users within those roles will be available.

Example:
If your org has four users but the project includes only two, only those two will appear in the sandbox—even if they all belong to the same team.
  • You cannot add users directly in sandbox environments.
  • If user-specific changes are needed, they must be made in production.   

Step 4: Generate Changes in Instance  

After making changes in your portal, the Generate Changes option will be enabled in the Unsaved Changes section, where these modifications will initially appear.

NotesThe Generate Changes button is only enabled after making modifications.               

To generate changes  :
  1. Navigate to your instance and click on Unsaved Changes. Alternatively, access the instance from the main portal by navigating to the project-associated instance.
  2. When any modification occurs, the instance's state will change to 'Development', restricting users from disassociating or switching the project.
  3. Click Generate Changes; a pop-up window will display logs as the system generates the changes.
  4. The project-associated instance will be locked to prevent further changes during this process.


  1. If all logs are in a completed status, close the pop-up to find changes listed in the Unsaved Changes tab. Each change includes the name of the last modifying user.
The Unsaved Changes tab will highlight the differences between the saved project data and the current instance data.

 

You can continuously generate changes as you work by clicking the Generate Changes button again, available in the top-right corner.


Limitations:

While generating differences, the below details are not captured:
  • Any modification in Business rule criteria
  • Any modification in the criteria of Conditional fields
  • In Public Forms, background and logo changes
  • In Webhooks, change in fields such as credentials, method, execute in bridge, parameters in JSON format and other parameters
  • In Custom Functions, change in fields such as return type, arguments

Step 5: Save to repository 

Once changes are generated and reviewed, it has to be saved to the repository. The repository option in the Sandbox provides a centralized space to save project configurations and changes. 

It offers benefits such as version control, environment sync, and the ability to view differences between saved versions. Only configuration data is stored, keeping updates secure and focused on system setup.

To save the changes to the repository:
  1. Click Save to Repository and in the pop-up, enter a message describing the changes made in the project for reference.
  2. Confirm by clicking Save to Repository again.

  1. A pop-up with change logs will appear. Upon successful completion, click Close.


The saved changes will now be reflected in the Saved Changes list, including details like the message, author, date, status.


After saving, you can review the changes between previously saved changes and the current version for validation in the Saved Changes section by clicking View Differences under the DIFFERENCE column.


Post-Save Actions   

  • The changes will be saved to the repository created during project setup and will be reflected in the sandbox environment, where you can view the status and the number of changes made.
  • You can view differences between previously saved changes and the current version by clicking View Difference.
  • Saving changes to the repository unlocks the associated instance, changing its status to Idle. This allows you to dissociate the current project and associate a new one if needed.
  • In the live portal, navigate to(settings)>> Advanced >> Sandbox >> Development Systems. View the number of changes and click View Difference to compare live data with the project associated with the instance.


Step 6: Synchronize Changes and Send to Upper Environment / Production

What is Synchronization?     

Synchronization pulls changes from the upper environment into the instance in the current environment, ensuring your instance is aligned before deploying changes forward.
In Sandbox environments, changes must be synchronized and deployed in a structured sequence depending on your setup. This ensures environment consistency and prevents conflicts or data loss.

Best Practise
Syncing before deployment is optional, but is strongly recommended to prevent data loss or conflicts. Skipping this may result in inconsistency between environments.

  • If your Sandbox setup includes multiple environments (e.g., Staging, UAT), you must first sync the changes with the next upper environment. You cannot send changes directly to Production in this case.
  • If your setup includes only one environment apart from the default Production environment, you will only be allowed to send changes directly to Production.
  • Button Labels dynamically reflect your target environment:
  • For Production: Sync with Production and Send to Production.
  • For other environments: Sync with Instance and Send to [Environment Name].
 

For Single-Environment Setups     

(e.g., Development or Staging → Production)
If your Sandbox has only one testing environment apart from Production:

1. Synchronize with Production

  1. Click Sync with Production at the top-right corner of your portal to pull the latest production changes.
  2. You can monitor live logs during the sync. Once the sync is complete, click Close. 

2. Send to Production
  1. Once changes are synced, click Send to Production.
  2. In the pop-up window, enter a deployment message and click Send to Production.
  1. Changes are added to the Deployment Queue in the production environment.
  2. The Send to Production button is then disabled until new changes are available.
 

For Multi-Environment Setups     

(e.g., Development → Staging → Production)
If your Sandbox setup includes multiple environments, changes must pass through each upper environment in sequence and finally to the production environment.

1. Synchronize with Upper Environment Instance  

  1. Click Sync with Instance in the top-right corner of the current instance.
  2. In the prompt, use the drop-down to select a source instance from the upper environment and click Sync with Instance.

Once synced, the last synced project will automatically replace any previously associated parent project. You can now send your changes to the next environment.
 

2. Send Changes to Upper Environment  

  1. Click Send to [Upper Environment Name] at the bottom of your portal.
  2. In the pop-up, the target instance will display the synced instance.
  3. Enter a deployment message and click Send to [Upper Environment Name].
  1. The changes will be added to the Deployment Queue in the upper environment.
 

3. Deploy to Upper Environment

To access deployment queue:
  1. In the target environment portal where changes from the previous environment are sent, navigate to(settings) >> Advanced >> Sandbox >> Deployment Queue.
  2. You have the option to either deploy or reject the deployment from the queue. Click Deploy in the top-right to initiate deployment and confirm your action.

 

  1. After deployment, click View Logs to check deployment status and details such as deploy message, user, and timestamp.
Repeat the sync and deploy steps for each upper environment in order.


4. Send to Production

  1. Once changes reach the final environment before Production, click Send to Production. In the prompt, enter a deployment message and click Send to Production.

  1. The changes are added to the Deployment Queue in the production environment, and the Send to Production button will be disabled until more changes are available.
InfoThe Deployment Queue holds all requests until actioned. Developers can request to deploy their changes to a parent environment or production by sending their changes to this queue.

 

 Repeat for Additional Environments (Optional) 

  • Apply these steps to subsequent environments before deploying to production.

  • After completing deployments in all upper environments, follow the steps to deploy the changes to production.


Step 7: Deploy to Production 

To complete the deployment process:
  1. In your production portal, navigate to(settings) >> Advanced >> Sandbox >> Deployment Queue.
  2. Select the request and click Deploy.
 

After deployment, click View Logs to track the outcome and see details.


Reverting a Deployment (Optional)         

If any issues arise due to the most recent deployment, the deployer or an admin has the option to revert the deployed changes once in the Production environment.
To revert a deployment:
  1. Navigate to(settings) >> Advanced >> Sandbox >> Deployment Logs.
  2. Click Revert Changes in the top-right corner of the page and confirm your action.

  • Only the latest deployment can be reverted.

  • Once reverted, the same project cannot be redeployed as-is.

  • To redeploy, you must make additional changes and send the project again through the deployment process.

 

Post-Deployment Handling 

After a successful deployment, the project behaves differently depending on the type of lower environment:
  • Development Environments: The project is removed from the lower environment instance, and its state is updated to Ready.
  • Staging Environments: The project remains in the lower environment, and its state is updated to Idle.






    • Related Articles

    • Quick onboarding guide

      Introduction to Qntrl Qntrl is workflow automation software that helps organizations take the lead in automating their everyday workflows. The mainstay of organized businesses are their time-tested workflows, seasoned with practice and expertise. To ...
    • Key Concepts in Sandbox

      Key Terms to Understand Sandbox A testing clone of your live environment. Environments A container for one or more instances. Sandbox can have multiple environments for various levels of testing. Types include Development, Staging, and Production. ...
    • Working with Projects

      Step 1: Create a Project An admin or user with Manage Settings permission can create Projects. To create a project (test environment): Navigate to and select Projects under Advanced. Click New Project at the top-right corner. Enter the following ...
    • Build Extensions using Qntrl Studio

      Early Access Qntrl Studio is not enabled for all users. If you’d like to try it out, please email our support team for early access. Extension is a software module that can be installed to expand the functionality of Qntrl. It could be a feature ...
    • Step 2: Design Blueprint

      Once a form is created, the next step is to design blueprints to capture the complete workflow. Blueprints help you define the step-by-step approach of a workflow. A blueprint is a replica of offline business processes where the processes are split ...

    You are currently viewing the help articles of Qntrl 3.0. If you are still using our older version and require guidance with it, Click here.