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:

  1. 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:

    Updates for your sandbox are ready to be pulled from production.
  2. 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:

    Changes in your sandbox are ready to be promoted to production.
  3. 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 some users 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

  1. Log in to Amperity.

  2. From the tenant drop-down menu, select the sandbox. The sandbox has the same as production, but with “SB” appended to it.

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

Review changes in your sandbox before promoting them to production.

To review production updates

  1. From an Amperity sandbox, next to Updates available, click Pull updates.

  2. Under Updates to pull, a list of objects that were added, updated, and removed is shown.

  3. Review each change.

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

  1. From an Amperity sandbox, next to Pull updates, click View changes.

  2. Under Updates to pull, a list of objects that were added, updated, and removed is shown.

  3. Review each change.

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

  1. From an Amperity sandbox, next to Updates available, click Pull updates.

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

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

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

Review changes

When a sandbox contains changes that are ready for promotion to production, a banner appears that says Ready to promote.

Review changes in your sandbox before promoting them to production.

Note

Only a full admin may promote changes to production. A non-full admin will only have the option to cancel after reviewing changes. In this situation, 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

  1. From an Amperity sandbox, next to Ready to promote, click View changes.

  2. On the Changes to promote page, a list of objects that were added, updated, and removed is shown.

  3. Review each change.

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

Promote changes in your sandbox to production.

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

  1. From an Amperity sandbox, next to Ready to promote, click Promote changes.

  2. On the Changes to promote page, a list of objects that were added, updated, and removed is shown.

  3. Review each change.

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