Skip to content
iTwin Studio Logo iTwin Studio Logo iTwin Studio

Switching environments between PROD and QA

This article will explain how to switch between PROD and QA environments.

Note the option to switch between PROD and QA only exists in beta builds. Publicly released Studio builds will be locked to PROD environment due to security concerns.

Please refer to our article explaining iTwin Studio variants/versions if you are unfamiliar with these terms.

Prerequisites

Section titled “Prerequisites”

  • Studio

    To use an iTwinStudio Beta Build:

    1. Install iTwin Studio Beta
    2. Verify the installation worked by running iTwinStudio --version. You should see “Beta” in the build description.
    3. Verify the installed Studio version is 1.00.90 or higher. Older versions of beta (formerly pre-release) builds will be locked to QA only.

  • App

    If your app is published using @bentley/create-itwin-studio-app publish scripts, ensure that you are using v0.7.8 or newer. You will need to publish a new version of your app to QA if all of the following are true:

    • You wish to use “production” data in a beta build of iTwin Studio
    • Your app was published using @bentley/create-itwin-studio-app v0.7.7 or older
    • Your app is providing authentication configuration in app.config.json
    • Your app uses different scopes than the default iTwin Studio authentication client.

    Context: older versions of @bentley/create-itwin-studio-app strip the PROD authentication configuration from app.config.json when publishing the app to QA.

Runtime behavior of setting iTwin Studio beta builds to production

Section titled “Runtime behavior of setting iTwin Studio beta builds to production”

TLDR: IMJS_URL_PREFIX will be set to "" during runtime. Apps will be downloaded and updated from the QA endpoint.

Switching iTwin Studio beta to PROD means:

  • iTwin Studio will auto-update to the latest internally released version.
  • Studio apps will be downloaded from QA (latest internally released version).
  • Studio apps will auto-update from QA (latest internally released version).
  • Production iTwins, iModels, User info, etc. will be used during the session.
  • process.env.IMJS_URL_PREFIX will be set to "" during the session.

To sum up, this will allow you to test/demo/use the latest internal iTwin Studio and app features and production data.

Authentication

Section titled “Authentication”

When using iTwin Studio beta builds in PROD, you might be asked to sign-in multiple times:

  • Once for PROD (used to query iTwins, iModels, etc)
  • Once for QA (used to update any installed apps)

Note that the second sign-in will directly open a new browser window/tab and ask for your credentials, without displaying the sign-in window in Studio itself.

Switching between PROD and QA

Section titled “Switching between PROD and QA”

There are multiple ways to toggle between PROD and QA in beta builds of iTwin Studio.

Default behavior:

CLI flags

Section titled “CLI flags”

If you are launching your app from CLI, e.g. using iTwinStudio apps run [your app], the easiest way to switch to production is by using CLI flag: --useEnv=production.

The following CLI flags will take precedence over Env Switcher and IMJS_URL_PREFIX variable:

  • --useEnv=production - force “prod” environment
  • --useEnv=dev - force “dev” environment
  • --useEnv=qa - force “qa” environment

Using Connect Client Env Switcher (Windows only)

Section titled “Using Connect Client Env Switcher (Windows only)”

iTwin Studio will, by default, respect the environment set by Connect Client env. Switcher.

Env Switcher can be downloaded from published artifacts in Connect Client’s build pipeline.
Download link for the latest Switcher at the time of writing: ClientEnvSwitcher.

Instructions:

  1. Download the ClientEnvSwitcher.exe and run it (granting admin permissions will be required).
  2. Click on the desired Environment.
  3. Restart iTwin Studio.

Ignoring Connect Client Env Switcher

Section titled “Ignoring Connect Client Env Switcher”

If you don’t wish to match iTwin Studio env. to the one set by ClientEnvSwitcher, there are a few ways to disable it:

  1. Launch iTwin Studio with --useEnv=runtime CLI flag. IMJS_URL_PREFIX env variable will be used instead.
  2. Remove the env set by the switcher:
    1. In registry editor, navigate to: HKCU\Software\Bentley and delete BuddiRegionCode key
    2. If the above is not set, check HKLM\Software\Bentley and delete BuddiRegionCode key.
    3. Restart Studio
    4. Connection client will now run on PROD, whilst Studio will use IMJS_URL_PREFIX env variable.
  3. Use the CLI flag to choose the env. instead.

Using IMJS_URL_PREFIX env. variable

Section titled “Using IMJS_URL_PREFIX env. variable”

iTwin Studio will default to setting IMJS_URL_PREFIX to qa- during runtime. This can be changed by:

  • Explicitly set env. variable IMJS_URL_PREFIX to empty string before starting Studio
    • Windows: we recommend doing this in VS code or other scripts, since CMD does not allow setting empty string values for env. variables.
    • Mac: run IMJS_URL_PREFIX="" ./iTwinStudio apps run mstn-view-sync
    • VS Code: set IMJS_URL_PREFIX="" in the launch.json config for launching Studio.
  • Remove IMJS_URL_PREFIX=qa- from .env.development file. Note - this isn’t recommended, since the variable will be reset after each Studio update. .env.development file can be found in:
    • Windows: %LocalAppData%/Programs/Bentley/iTwinStudio/v1-beta/resources
    • Mac: /Applications/iTwinStudio.app/Contents/Resources

Troubleshooting

Section titled “Troubleshooting”

I’m not sure what environment my app is running in

Section titled “I’m not sure what environment my app is running in”

The easiest way to tell the environment Studio is using is to check the browser window title bar. In beta (internal) builds of Studio, the title bar uses the following format: [name of the app] (env). As such, Foo (Production) means that the app Foo is running with production data.

If the title bar only displays Foo (without the env), it means that you currently have the “released” Studio build installed. Released versions of Studio will always point to PROD.

I cannot switch to environments

Section titled “I cannot switch to environments”

Ensure that your installed version of Studio meets the prerequisites

If you are trying to point to PROD by setting IMJS_URL_PREFIX, ensure that it is set to an actual empty string, rather than "" (string that has two quote marks). If you are having trouble doing so via the terminal, we recommend using the cli flag instead: --useEnv=production

Windows

Section titled “Windows”
  1. If you ever used Env Switcher on your machine, iTwin Studio will honor the env. set by it (even if it was set a long time ago)
  2. If you are trying to use the Env Switcher, ensure that in its UI, use AppSettings is toggled off.