[Home]

Configuring Connections

You configure connections to tell Illuminated Cloud about your Salesforce organizations, and supply the credentials to use to authenticate yourself against those organizations.

Configuring connections at the application-level means that you can create them once and re-use them across projects. You can also use configured connections for Anonymous Apex and SOQL query execution, viewing logs, and org-to-org deployment even when not associated with any specific project.

You can access these configuration options by selecting Configure Application from the Tools > Illuminated Cloud menu, Illuminated Cloud context menu, or toolbar icon (select View > Toolbar to enable the toolbar, if it isn't visible). You can also access the connection configuration dialog via the Open connection > Manage connections... toolbar top-down entry.

Select the Connections tab to display the options for configuring the following types of connections in Illuminated Cloud:

• Illuminated Cloud native connections
• Connections to new Salesforce DX scratch orgs
• OAuth connections to existing Salesforce orgs (using the Salesforce CLI)

NOTE: The last two types of connections require the Salesforce CLI, so be sure to download and register it with the IDE if you haven't already done so.

Accessing Connections

Any connections you add to Illuminated Cloud will be available wherever you normally access connections. For example, you can log in to the associated org by clicking Open connection and selecting a connection from the list of available connections:

In addition to associating connections with projects, you can also select any configured connection for anonymous Apex or SOQL query execution, viewing logs, unit test execution, and bulk metadata management operations.

Copying Connections

Illuminated Cloud makes it easy for you to use an existing native connection as the basis for creating another one. Simply select the native connection in the list, click the copy icon , and modify settings for the new native connection.

Deleting Connections

If you no longer use or need a connection, select the connection in the list and click the Delete Connection icon . This will remove the connection from the system completely — not just the Connections list — so be sure you no longer have use for a connection before removing it. Otherwise, you'll need to configure the connection again. Scratch org connections are removed using sfdx force:org:delete, and OAuth connections are removed using sfdx force:auth:logout.

Refreshing Salesforce CLI-based Connections

Illuminated Cloud caches details about Salesforce CLI-based connections. This cache may be automatically repopulated when key Salesforce DX configuration files are detected as changed based on Salesforce DX configuration, but you can also explicitly rebuild this cache by clicking the refresh or force refresh toolbar buttons. Refresh uses the Salesforce CLI to query the connection list without querying connection status information. This can be significantly faster but may yield stale results. Force refresh does query connection status information and may take longer, but results will be accurate.

Native Connections

To configure a native connection in Illuminated Cloud, click the Create Connection icon and provide the following information:

Connection name — Provide a unique name that will be used to refer to the connection when associating it with a project or using it with an Illuminated Cloud feature that requires a connection.

Organization type — Select the type of organization to which you'll be connecting:

• Production
• Development
• Sandbox
• Pre-release
• Other (Select this option if you need to specify a custom login URL)

Login URL — This is determined by the organization type you selected above. If you selected Other, provide the fully-qualified domain to login and access the organization.

Username — Enter the username you use to access the organization.

Password — Enter the password associated with the username you provided.

Security token — If required by the target organization, enter the security token associated with the username you provided.

Click Test to verify that you've entered all the information required to connect to the organization correctly. If the configuration information you've provided is valid, you'll be notified that Illuminated Cloud was able to successfully connect to the org:

API version — This is pre-populated with the latest supported API version. You can optionally select an alternate version of the Salesforce API to use for this connection.

Organization namespace — If a namespace has been registered for the organization, it will be detected and displayed here. Illuminated Cloud will then be able to provide code completion and reference navigation appropriate for that namespace. If a namespace isn't available, this field will display <unspecified>.

Use the following options to configure how you want the IDE to interact with the organization:

Require confirmation for all write operations — Check this option if you want Illuminated Cloud to prompt you to confirm ALL operations performed against the connection that could modify data or metadata. (Recommended for Production orgs)

NOTE: If you select this option, you'll be prompted to disable the Ensure field read access option as enabling both options will cause conflicting behavior:

Two additional configuration options are available when write confirmation is enabled for a connection. You can choose the Default confirmation response. This determines the confirmation response that will be used if you press Enter in response to the dialog. Options are Yes, No, or Same as last response

You can also choose to enable the Disable deploy on save option to avoid a prompt each time files are saved in a project configured for that connection.

Check for conflicts on deployment — Check this option if multiple users are collaborating in this organization or you are making changes to metadata both in Illuminated Cloud and in the Web-based tools. Illuminated Cloud will then compare the version of the metadata that exists locally against what's available in the organization upon deployment and alert you if there are any conflicts.

If metadata is being changed in the organization outside of Illuminated Cloud and/or by more than one user, we strongly recommend that you enable this option to help prevent changes from accidentally being overwritten and work being lost.

If Illuminated Cloud detects a conflict, you will be prompted to choose how you want to proceed:

• Overwrite the organization copy with the local copy.

• Retrieve the organization copy into a temporary directory so you can compare the two copies and reconcile the differences manually.

• Cancel the deployment operation.

Illuminated Cloud supports the following conflict detection strategies based on how multiple users access the shared organization:

• Dedicated Logins — Used if each user has a unique username to access the organization. Conflicts are detected if metadata selected for deployment has been modified in the organization by a different user than the user configured for this connection.

• Shared Logins — Used if two or more users share the same username to access the organization. Conflicts are detected if metadata selected for deployment has been modified in the organization more recently than it has been successfully deployed or retrieved by Illuminated Cloud.

Enable workaround for HTTP 411 issue — Check this option only if you have experienced the issue where operations against the Salesforce API fail with an HTTP 411 error. The workaround involves chunking data across the connection which may impact performance.

Use parallel processing — We recommend you leave this option checked as it allows Illuminated Cloud to perform batch metadata operations in parallel whenever possible. This is especially useful for offline symbol table generation and other API-intensive operations.

Ensure field read access — Check this option to enable read access to all SObject fields in the organization. This will enable key Illuminated Cloud features such as code completion and integrated API documentation for those fields. Checking this option will amend your user profile, so we strongly recommend you enable this for developer-owned orgs only.

Click OK to save the connection.

Connections to New Salesforce DX Scratch Orgs

Follow the process below to create new scratch orgs which Illuminated Cloud can use as connections. Illuminated Cloud is also automatically aware of scratch orgs created outside of Illuminated Cloud.

NOTE: You must have authorized at least Dev Hub to be able to create a new scratch org for it. Use OAuth connections to existing Salesforce orgs to connect to a dev hub organization.

To create a new scratch org, click the Create Scratch Org icon and select the Dev Hub you want to use (if you have access to more than one Dev Hub):

Enter the following information for the scratch org (also documented in the Salesforce DX Developer Guide):

Dev Hub — If more than one Dev Hub is authorized, choose the Dev Hub against which the new scratch org should be created. If a default Dev Hub is configured, it will be pre-selected. If only one Dev Hub is authorized, this field is not displayed.

Org Name — The organization name that will be used when listing the scratch org in the Dev Hub. Entering a value here automatically populates the Alias field.

Alias — The friendly alias for the created scratch org which is also used as the Illuminated Cloud name. You may either keep the default org name-derived value or provide a different name for the scrach org alias.

Description — The optional scratch org description, up to 2,000 characters in length.

Edition — The Salesforce edition for the created scratch org. Valid values are Developer, Enterprise, Group, Professional, Partner Developer, Partner Enterprise, Partner Group, and Partner Professional.

Release — The optional release relative to the dev hub, either Preview or Previous, during the release transition.

Duration — The number of days you want the scratch org to exist — defaults to the maximum lifespan of 30 days.

Username — The optional username you will use as the Administrator of this scratch org. Salesforce usernames are globally unique. If no value is entered, a unique username will be generated for you.

Admin Email — The optional email address you will use as the Administrator of this scratch org.

Country — The optional 2-character code for the locale of the scratch org.

Language — The optional language code associated with the locale of the associated Dev Hub.

No Namespace — Creates the scratch org with no namespace. Scratch orgs without a namespace are useful when testing installations of packages with namespaces.

No Ancestors — Prevents the inclusion of second-generation package ancestors in the scratch org.

Include Sample Data — Whether or not to include sample data in the scratch org — defaults to disabled.

Features — Check each feature you want to enable in the scratch org. For each parameterized feature you select, you'll be prompted to add a value for it within the allowed range.

Settings — Optionally provide the scratch org settings as a valid JSON object.

You can also click the Load Scratch Org Definition link and select an existing scratch org definition (.json file) to use as the basis for your scratch org. Illuminated Cloud parses the definition and applies its settings to the scratch org you're configuring. You can then use or modify the settings associated with the definition to configure your new scratch org and, if desired, save the scratch org definition for future use.

Click OK to create the scratch org and make it available as a connection in Illuminated Cloud.

NOTE: Most configuration options available with native and OAuth connections are disabled for scratch orgs as they don't really apply. For example, orgs that are owned by you or not typically shared with others, so Ensure field read access is always enabled. Also, the force:org:push and force:org:pull commands are responsible for conflict detection, and the API version and Organization namespace values are defined in the project's sfdx-project.json file.

The following scratch org-specific configuration option is available to allow the scratch org to be used in a manner similar to a non-scratch org:

Use deploy/retrieve/delete instead of push/pull - When checked for a scratch org, raw metadata operations are used by default instead of scratch org source tracking.

Use legacy push/pull commands - When checked for a scratch org or source-tracked sandbox, the force:source:legacy:push and force:source:legacy:pull commands are used for that connection in the current project. For more details, see the 2.2.1.4 release notes.

OAuth Connections to Existing Salesforce Orgs

Click the Authorize Org with SFDX icon and follow the process below to create an OAuth connection to an existing Salesforce org.

Enter an Alias for the organization. This will be used to refer to the connection both in Illuminated Cloud and from the Salesforce CLI and can be changed any time.

Organization type — Use the drop-down list to select the type of organization to which you'll be connecting:

• Sandbox
• Development
• Pre-release
• Production
• Other (Select this option if you need to specify a custom login URL)

Login URL — This is determined by the organization type you selected above. If you selected Other, provide the fully-qualified login URL for the Salesforce org.

Click OK to close the Authorize Org dialog. Illuminated Cloud uses the information you've provided to connect to the Salesforce org and prompts you to log in via your web browser:

NOTE: If this is your first time using OAuth to log into this organization, you'll also need to authorize the Salesforce CLI:

When you return to Illuminated Cloud, you'll see a notification that you were successfully authorized to access the org. Click OK to dismiss the dialog and refresh your Connections list to include this OAuth connection.

After you configure a connection, you can change its name and any of the configuration options that impact the way Illuminated Cloud interacts with the organization. You cannot change the credentials used to authenticate yourself against the organization—if your credentials change, you'll need to configure a new connection (and remove the old connection) to update the IDE.

The following additional configuration options may be available for the authorized organization based on its recognized organization type:

Use push/pull instead of deploy/retrieve/delete - When checked for a sandbox, sandbox source tracking is used by default instead of raw metadata operations.

Treat as dev hub - This option provides a workaround for Salesforce CLI issue 482 where dev hub orgs are sometimes not reported as such by force:org:list. If you are experiencing this issue, you can use this option to explicitly designate an OAuth connection as a dev hub and that org will become available for scratch org creation.

[Home]