From AgileApps Support Wiki

GearIcon.png > Administration > Account Management > Sandboxes

Sandboxes provide safe environments for development and testing that are separated from the production environment. They allow object definitions and platform elements to migrate to and from the production environment, and between sandboxes.

About Sandboxes

When you log in to the platform, you log into your organization's tenancy. (Basically, your organization is a tenant in the platform.) When you set up a sandbox, you create a "sub tenant" that can interact with the main tenancy, and with other sub tenants.

In a sandbox, you can modify and test an application without changing the production version. You can then deploy the application Package to a Q/A sandbox for testing, or to the main tenancy (the "production" system).

To use a sandbox, you log into it, giving the username and password of a user defined in that sandbox. (The initial sandbox admin-user is created automatically. But you can change the name of that user anytime.)


  • The Sandboxes option is enabled by your Service Provider.
  • The default single sign-on setting on on-premises installation is Off.
  • The default single sign-on setting on the cloud is Off. (Contact Support to make changes.)
  • Sandboxes can be created only when logged into the main tenancy. They cannot be created from a sandbox.
  • All capabilities that are enabled in the main tenancy are enabled in the sandbox, when the sandbox is created. (After creation, changes made to either one do not affect the other.)
  • Packages cannot be published from a sandbox (to make them available to other tenants). They can only be published from the main tenancy.
  • When you deploy a package, data does not migrate, only data structures (object definitions) and other platform elements. To copy data between sandboxes, use the Export and Import mechanisms.

Working with Sandboxes


Users that have the Manage Sandboxes permission can create and delete sandboxes. 

Creating a Sandbox

  1. Go to GearIcon.png > Administration > Account Management > Sandboxes
  2. Click [New Sandbox]
  3. Fill in the Sandbox name.
  4. Click [Save].
    The sandbox is created. An email is sent with the name and password for the initial-admin user. (The password is randomly generated. You are asked to change it when you log in.)
  • The name can contain only letters, numbers, and underscores.
  • The name must be unique within your tenancy, so no other sandbox in your organization is given the same name.


Tip: A good naming strategy is to combine a job function with a user's name. For example: QA_Fred, or Dev_Sally.

The name you provide is combined with the name of your organization's tenancy to create a Sandbox that is unique in the platform. For example: YourOrganization - YourProject_Jessie - Sandbox.

The initial admin-user created in the new tenancy has the name {yourLoginName}.{yourSandboxName}. For example:


Tip: Change the username to the project name, followed by your name. For example: yourProject.yourName. That way:

  • Your browser can auto-complete the username after the first few characters you type.
  • There is no conflict with others who work on the same project, because you added your name.

To make the change, go to GearIcon.png > Administration > Access Management > Users and edit the default (and only) user entry.

Using Your Sandbox

When creating an application, you'll probably stay in the admin-user role, adding on all of the required Developer Privileges, so you can easily develop features and make any system-level changes that need to be made, without switching roles. For testing, though, you'll probably want to use roles with much more limited permissions (the same kinds of roles that typical users will have).

To log into the sandbox in either role, it's best to log out of your current tenancy, and then log back in with the desired username and password, which connects you to the appropriate sandbox as the specified user.


For convenience, there is a [Login] button on the Sandbox page. But:

a. That button always logs you in as the initial admin-user, which may not be desired.
b. That button does a Proxy Login. In effect, the new session is running "under" the existing session. In general, things work well. But that mode is intended only for quick in-and-out fixes, not for lengthy use.

If you do use the [Login] button, you'll find a Switch Back option in the dropdown that appears next to your login name, just above the logout option. Use that link to come back to your login session.

Learn more: Using the Agent Portal#User Options

Establishing Deployment Rules

Deployment Rules specify the targets (sandbox tenants and the main tenancy) to which a Package can be deployed. In general, you'll want development sandboxes to be able to publish to each other to share work. You may want one or more sandboxes designated as "integration points" that can publish to the Q/A sandbox, where testing is done. The Q/A sandbox would then be the only sandbox tenancy that is allowed to publish to the production tenancy, so that only a fully tested application is deployed.

To set up a Deployment Rules:

  1. From the main tenancy, visit GearIcon.png > Administration > Account Management > Sandboxes
  2. Click [Deployment Rules]
  3. For each sandbox tenant listed on the left, choose the tenants to which packages can be deployed.
  • Deployment Rules can only be specified from the main tenancy.
  • The main tenancy and all sandbox tenancies are listed on the left
  • Only the designated targets will appear as options when deploying a package.
  • If no deployment targets are specified for a sandbox, it will not be possible to deploy a package from it.

Deploying a Package from a Sandbox

If you created the application in your sandbox, you'll need to create a Package that contains all of the application elements. On the other hand, if you acquired the Package from the main tenancy or from a development sandbox, you only need to make sure that anything new you've developed in the sandbox is included in the package.

Once the package is ready, you're ready to deploy it:

  1. Visit GearIcon.png > Administration > Account Management > Packages > {package}
  2. Click [Deploy].
  3. Choose the tenants to deploy to, where the choices that appear are determined by the Deployment Rules.
  4. Choose whether or not to send an email notification.
  5. Choose whether to deploy the package immediately, or to specify a future date and time.
  6. Click [Deploy].

The deployment is added to the processing queue, either immediately or at the time you specify. When deployment occurs, you get an email with a success or failure message.

To check on the status of the job in the meantime, visit GearIcon.png > Administration > Monitoring > Mass Operation Status.



  • When deploying to a development sandbox, make sure the package is unlocked, so its contents can be changed as needed.
  • When deploying to a Q/A sandbox or the production tenancy, make sure the package is locked, to prevent the structure of the application from being changed accidentally.

Learn more:About Locked and Unlocked Packages

Deleting a Sandbox

When a sandbox is deleted, everything it contains is erased, and cannot be recovered.

To delete a sandbox:

  1. Visit GearIcon.png > Administration > Account Management > Sandboxes > {sandbox}
  2. Click [Delete].
    A confirmation dialog appears.
  3. Click [Ok].