Sandboxes¶
A sandbox is a full copy of your tenant from which a user who is assigned to the DataGrid Administrator role can make changes. For example, adding a data source and feed, adding a destination, and managing workflows with SLA status. After these changes are validated, they can be safely promoted 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 sandboxes to ensure that all configuration changes are validated before they are pushed to your production tenant.
About sandbox workflows¶
A sandbox workflow is similar to the workflows software engineers use with version control systems:
Configuration states are pulled from the production tenant to the sandbox.
When updates for the sandbox are available, a banner similar to the following is shown:
Changes made to the configuration state in the sandbox may be promoted to the production tenant. A detailed list of all changes to all components and data sources is available for each promotion workflow.
When changes in your sandbox 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.
A banner within the sandbox notifies you if there are states that can be pulled from the production tenant or promoted from the sandbox, along with notifying you of any conflicting differences between the configuration states.
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.
Only Full 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.
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 tenant’s workflow is not interrupted.
Access your sandbox¶
A sandbox is accessible from the drop-down menu that is associated with the name of your production tenant.
To access your sandbox
Log in to Amperity.
From the tenant drop-down menu, select the sandbox. The sandbox has the same as production, but with “SB” appended to it.
This opens the sandbox for that tenant.
Review updates¶
When your production tenant contains changes that are not present in your sandbox you will see an Updates available notification in the sandbox banner.
To review production updates
From an Amperity sandbox, next to Updates available, click Pull updates.
Under Updates to pull, a list of objects that were added, updated, and removed is shown.
Review each change.
When finished, click Pull.
Pull updates¶
Updates within your production must be pulled to the sandbox. After pulling these changes, refresh your sandbox 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, next to Pull updates, click View changes.
Under Updates to pull, a list of objects that were added, updated, and removed 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 a red box at the top of the merge tool with an error (or several) in it. These are validation errors - these occur when a merge would result in invalid configuration. When doing a merge, we try our best to combine your sandbox’s configuration with production configuration and this will sometimes result in invalid configuration.
In order to resolve these errors, you need to choose a different resolution for a conflict or modify the configuration in production or your sandbox. The validation error itself should point you to where the error is.
If you need a table or database in both production and your sandbox, create it in one or the other and do a merge. If you create it in both places, you’re going to get one or more of the validation errors listed below.
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 your sandbox manually, these tables have two different IDs. In this case, we try to put both tables into the database, which is invalid. |
Choose to resolve a conflict by removing one of the tables (like it may show that a particular table is deleted in production) Remove the table in your sandbox (if you want to keep production) or remove it in production (if you want to keep the sandbox version). |
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 manually and tagged in both. In this case, again, we try to combine them into a single database, which results in this error. |
Same as above - either resolve via conflict or remove the table in your sandbox or production. |
To resolve conflicts between production and a sandbox
From an Amperity sandbox, next to Updates available, click Pull updates.
Under Conflicts, for each conflict, review the production and sandbox changes.
Enable the Show full configuration checkbox to show additional configuration details for that object.
After identifying the differences between the production and sandbox tenants, select the radio button for the production or sandbox tenant. This will keep the changes in the sandbox tenant or it will pull the change from the production tenant to the sandbox.
When finished reviewing conflicts, click Pull.
Make configuration changes¶
When your sandbox 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 to your production tenant.
Tip
Be sure to run your sandbox completely, and then compare the amount of time required to generate Stitch and your databases in the sandbox to the amount of time required by your production tenant. 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.
Review changes¶
When a sandbox contains changes that are ready for promotion to production, a banner appears that says Ready to promote.
Note
Only a user who is assigned to the Full Administrator policy may promote changes to production. A non-full admin, such as a DataGrid Operator is allowed to cancel a promotion after reviewing changes. To complete the promotion process request a review from your Amperity support representative and they will 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 objects that were added, updated, and removed 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 Full 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 objects that were added, updated, and removed 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.