Sandboxes¶
A sandbox is a snapshot of the configuration state of your production tenant that is made available as a copy. Use a sandbox to safely make configuration changes, and then promote those changes back to your production tenant.
Tip
Assign the DataGrid Operator policy to DataGrid operators for all work done within your production tenant. Assign the DataGrid Administrator policy to the same users within a sandbox.
This ensures that configuration changes can be made within the sandbox, including being able to access and run all workflows that are required to validate those changes. When the configuration changes are ready they can be pushed to your production tenant.
A sandbox should be short-lived and should be used to make small, iterative changes within your tenant. After these changes are safely promoted to your production tenant, the sandbox should be deleted. Use a sandbox for each iterative change to ensure that you are never making large changes to your production tenant.
Important
Data is not moved between your production environment and a sandbox environment. Only the configuration state is copied to the sandbox environment and only changes to the configuration state are copied back to your production environment.
For example, if you use a sandbox to add the components required by a new data source, such as a courier, a feed, along with a custom domain table in which semantic tags are applied, after promoting those changes from a sandbox environment you will need to run the courier to pull the data to your production environment.
About sandbox workflows¶
A sandbox workflow provides a version history of all changes made in the sandbox, including when they were made, who made them, and which components within Amperity were changed. A record is maintained of all changes that are promoted from the sandbox to the production tenant.
Important
Only Sandbox Administrators are granted permission to merge promoted changes to a production tenant. This means that in many cases, promoted changes must be reviewed and accepted prior to completing the promotion workflow.
Make a request to your Amperity representative and/or to Amperity support for help with getting changes in a sandbox environment promoted to your production environment.
A sandbox workflow is similar to the workflows software engineers use with version control systems: a series of small, iterative changes are submitted and approved for use in the production environment.
Configuration states go in two directions:
Configuration states are pulled from the production tenant to the sandbox.
Note
Data is not moved from your production environment to a sandbox environment.
A banner within a sandbox notifies you if there are states that can be pulled from the production environment or promoted from the sandbox environment, along with notifying you of any conflicts that may exist between the configuration states.
When updates for the sandbox environment are available, a banner similar to the following is shown:
Changes to configuration states that are made in a sandbox may be promoted to your production tenant.
Note
Data is not moved from a sandbox environment to your production environment.
A detailed list of all changes to all components and data sources is available for each promotion workflow.
When changes in your sandbox environment are ready to be promoted, a banner similar to the following is shown:
If there are conflicts between the two configuration states, one of the configuration states must be chosen.
Amperity will run a series of validations against the changes you have made in the sandbox environment against all workflows within the sandbox that depend on the changes you have made.
In some cases, a change will require additional updates to upstream or downstream dependencies within the sandbox that must be addressed before you can promote those changes to your production environment.
For example: a schema mismatch may exist between tables, a database table may be missing, or a data source may be unavailable.
Each validation error will be shown. Click on a validation error to view more details about how you can resolve the validation error.
Request a sandbox¶
A sandbox must be enabled for use in Amperity. To request a sandbox for your tenant, contact your Amperity support representative directly, by using the Amperity Support Portal, or by sending email to support@amperity.com.
Important
When making changes to a tenant which has an SLA workflow, you must make changes in a sandbox to ensure that workflows in your production environment not interrupted.
Access your sandbox¶
A sandbox is accessible from the drop-down menu that is associated with the name of your production environment.
To access your sandbox
Log in to Amperity.
From the tenant drop-down menu, select the sandbox enviroment. A sandbox enviroment should have the same name as your production enviroment, but with “SB” appended to it.
This opens the sandbox enviroment for your production enviroment.
Review updates¶
When your production environment contains changes that are not present in your sandbox environment you will see an Updates available notification in a banner within the sandbox environment.
To review production updates
From an Amperity sandbox environment, next to Updates available, click Pull updates.
Under Updates to pull, a list of changes is shown.
Review each change.
When finished, click Pull.
Pull updates¶
Updates within your production environment must be pulled to the sandbox environment. After pulling these changes, refresh your sandbox environment by running couriers to refresh domain tables, and then regenerate Stitch results for all databases.
To pull updates from your production tenant to your sandbox
From an Amperity sandbox environment, next to Pull updates, click View changes.
Under Updates to pull, a list of changes is shown.
Review each change.
When finished, click Pull.
Resolve conflicts¶
In situations where there is a conflict between the state of the sandbox and the production tenant, that conflict must be resolved before any changes in the sandbox can be promoted to the production tenant.
Sometimes, when you go to pull or promote changes, you’ll see an alert at the top of the merge tool that describes a validation error - these occur when a merge would result in invalid configuration.
When doing a merge, Amperity will attempt to combine the configuration in the sandbox environment with the configuration in the production environment. Sometimes this results in an invalid configuration.
If you need a table or database in both production and sandbox environments, create it in one or the other, and then merge the environments.
If you create a table or database in both environments, one (or more) of the following validation errors will be shown:
Error |
Why this happens? |
Resolution |
|---|---|---|
Table name “X” is used 2 times in database “id-here”. Each table within a database must have a unique name. |
If you add the same table in both production and sandbox environments manually, these tables will have two different IDs. In this case, Amperity will attempt to put both tables into the database, which is invalid. |
Choose to resolve a conflict by removing one of the tables. Remove the table from your sandbox environment if you want to keep the table that exists in your production environment. Remove the table from your production environment if you want to keep the table that exists in the sandbox environment. |
Multiple tables (“X”, “Y”) are tagged with the unique “:customers” tag in database “Stitch QA”. At most one table per database can be tagged with a given unique tag. |
For the same reason as above - the table was added in both production and the sandbox environments manually, and then tagged in both. In this case, Amperity will try to combine them into a single database, which results in this error. |
Same as above - either resolve via conflict or remove the table fro your sandbox or production environments. |
To resolve conflicts between production and a sandbox
From an Amperity sandbox environment, next to Updates available, click Pull updates.
Under Conflicts, for each conflict, compare the changes between the production and sandbox environments.
Enable the Show full configuration checkbox to show additional configuration details.
After identifying the differences between the production and sandbox environments, select the radio button for the production environment or sandbox environment.
This will keep the changes in the sandbox environment or it will pull the change from the production environment to the sandbox environment.
When finished reviewing conflicts, click Pull.
Make configuration changes¶
When your sandbox environment is ready, you can make changes in the Sources, Stitch, Customer 360, and Destinations tabs.
Request to promote¶
Contact your Amperity support representative via the Amperity Support Portal (or send email to support@amperity.com) to request promoting changes from your sandbox environment to your production environment.
Tip
Be sure to run your sandbox environment completely, and then compare the amounts of time required to generate Stitch and your databases in the sandbox environment to the amount of time required within your production environment. You should investigate the causes of any large increases in runtime.
For example, a large increase may be an indicator that expensive SQL actions, such as an implicit cross join across two very large tables, may be present in a custom domain table or database table.
A sandbox environment must be in a valid state before you can promote changes to your production environment.
Review changes¶
When a sandbox environment contains changes that are ready for promotion to your production environment, a banner appears that says Ready to promote.
Note
Only a user who is assigned to the Sandbox Administrator policy may promote changes to production. A non-sandbox administrator, such as a DataGrid Operator is allowed to cancel a promotion after reviewing changes. To complete the promotion process, please request a review from your Amperity support representative and they will help complete the promotion process.
To review changes in the sandbox prior to promoting to production
From an Amperity sandbox, next to Ready to promote, click View changes.
On the Changes to promote page, a list of changes is shown.
Review each change.
When finished, click Cancel.
Promote to production¶
Changes in a sandbox must be promoted to the production tenant by a user assigned the Sandbox Administrator policy. (This user is your Amperity representative.)
Only configuration changes in the sandbox will be promoted to the production tenant. After promoting these changes, refresh your production tenant by running couriers to refresh domain tables, and then regenerate Stitch results for all databases.
Warning
If there is an existing SLA workflow that is affected by changes in your sandbox that are currently running in production, a warning is shown. You must select the Yes, continue promoting these changes to production option to promote changes while that SLA workflow is running.
To promote changes to the parent tenant from the sandbox
From an Amperity sandbox, next to Ready to promote, click Promote changes.
On the Changes to promote page, a list of changes is shown.
Review each change.
When finished, click Cancel.
Roll back changes¶
Changes that are promoted to your production tenant from a sandbox may be rolled back. If your tenant needs to roll back changes that were promoted from a sandbox, please make a request to Amperity Support for assistance.
Important
This action will return your tenant to the state it was in prior to promoting the change from a sandbox. If additional changes were promoted after that sandbox was promoted, those additional changes will be lost.