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.

For 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.

4. 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.  

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

When 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   

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
  

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.

• 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.

The 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.

5. 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.

3. 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.

3. Changes are added to the Deployment Queue in the production environment.
4. 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].

4. 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.

 

3. 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.

2. 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.

The 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.