How do I use feature X/Y/Z in Illuminated Cloud?

Illuminated Cloud extends the base JetBrains IDE's existing functionality to support Salesforce development. As a result, most of Illuminated Cloud's features simply apply the base IDE's powerful feature set to Salesforce source file types. This means that the exact same mechanisms for performing an action in Java, Javascript, HTML, CSS, etc., are used to perform the same action in Apex, Visualforce, Lightning and other Salesforce metadata. These actions can be performed using keyboard accelerators, menu items, and toolbar buttons.


I'll let my own bias show through a bit here. Using a development tool like IntelliJ IDEA/PhpStorm/PyCharm/RubyMine/WebStorm without learning and/or using the shortcut keys is missing half of the point! I highly recommend that you take the time to learn the keys, and you'll be amazed at how efficiently you write new code and how quickly and thoroughly you gain an understanding of your code base.


The following table lists the actions that are explicitly supported by Illuminated Cloud and the default keymap assignments in Windows, Mac OS X, and Linux:

Full descriptions of the default keymaps are available from JetBrains. To ease the transition for those coming from other IDEs and editors, IDEA includes alternative keymaps that mimic the behavior of tools such as Eclipse, NetBeans, Visual Studio, and Emacs.

I'm often asked which handful of keys are the most important to learn in terms of increasing productivity. That's an incredibly difficult question to answer as I honestly use almost every one of the keys listed above on a daily basis. However, ignoring the keys that are common to virtually all application (save, cut/copy/paste, select all, next/previous word, etc.), I would recommend that users incorporate the following into their standard development workflows:

You will also want to become familiar with the time-saving live templates included with Illuminated Cloud.

I could include a few dozen more...and in fact already have in the table above. Seriously, just walk through every single one of these and use them until they're second nature. You won't regret it.

What are the differences between IntelliJ IDEA Community Edition, Ultimate Edition, and PhpStorm/PyCharm/RubyMine/WebStorm? Which should I use?

The most obvious difference between the three is the price. IntelliJ IDEA Community Edition is free, Ultimate Edition is the most expensive but also the most feature rich, and WebStorm falls between the two in price at about 1/3 the price of Ultimate Edition. PhpStorm, PyCharm, and RubyMine are IDEs for PHP, Python, and Ruby respectively, and all include the full Web development feature set of WebStorm as well.

JetBrains provides a nice comparison matrix for IntelliJ IDEA Community Edition vs. Ultimate Edition. For purposes of Salesforce development, the main difference is that Ultimate Edition includes the full Web development feature set of WebStorm which is invaluable when developing JavaScript/CSS-heavy applications in Lightning and Visualforce, especially Lightning Web Components which are based on ES6 and use NPM for dependency management. Illuminated Cloud augments Community Edition with reasonable JavaScript and CSS editor features such as simple code completion and auto-indent capabilities, but they pale by comparison to the full feature set offered by commercial IDE offerings.

Ultimate Edition also includes support for commercial version control systems such as Perforce and TFS (note that there is also a very good free Perforce plugin). If you are using one of those version control systems and want integrated VCS, you will likely need Ultimate Edition.

If your applications do not include Java, PHP, Python, Ruby, etc., components, WebStorm is a great option for Illuminated Cloud as it includes the more sophisticated HTML/JavaScript/CSS features that are also present in IntelliJ IDEA Ultimate Edition. This thread provides a good description of the differences between IntelliJ IDEA Ultimate Edition and JetBrains' lightweight IDEs such as PhpStorm/PyCharm/RubyMine/WebStorm. In my experience the major feature missing from the lightweight IDEs vs. IntelliJ IDEA Ultimate Edition is support for multi-module projects (though multiple source roots per-project are supported). This omission won't likely affect most users, though.

What is the difference between a project and a module? How are those related to connections, offline symbol tables, and SDKs?

JetBrains' documentation provides a definition of projects, modules, and their relationships. In the context of Illuminated Cloud, they play the following roles:

I've installed the plugin but nothing has changed in IntelliJ IDEA/PhpStorm/PyCharm/RubyMine/WebStorm. What's wrong?

There are a few reasons this might happen:

Incorrect file type associations

If you've used the JetBrains IDE to edit Salesforce source files prior to installing Illuminated Cloud, it's possible that some of Illuminated Cloud's file extensions are already associated with other file types.

To resolve this issue, open Settings | Editor | File Types and verify that the following file type associations exist, re-establishing them if necessary:

Additionally make sure that the extension *.resource is not associated with any file type. The easiest way to do this is to try to associate that extension with any existing file type. The IDE will show any existing association. In either case, remove either the newly-created association or the existing association.

Illuminated Cloud automatically associates all other Salesforce metadata extensions with the XML file type.


Enable debug logging for the feature(s) that are not working properly, then examine the file idea.log using Help | Show Log in Explorer/Finder/Files. Do you see any errors or exceptions? If you do and it's not obvious why things are failing, please send the log to Support.

I'm getting an error about being unable to reach the server. What can I do?

When working on networks with limited connectivity, you may need to configure the base IDE for a corporate proxy server. Open Settings | Appearance & Behavior | System Settings | HTTP Proxy and choose Manual proxy configuration, then enter the proxy server settings. Unfortunately the licensing software used by Illuminated Cloud doesn't support automatic proxy configuration.

Some proxies or firewalls perform SSL certificate substitution. This will manifest as an invalid or unverified SSL certificate error. If you see this type of error, you can configure the base IDE to accept the substitute certificates by opening Settings | Tools | Server Certificates and either checking Accept non-trusted certificates automatically or by adding the substitute certificates explicitly to Accepted certificates. The licensing software is intolerant of substitute certificates, so this will only help with other aspects of the IDE such as access to Salesforce organizations.

If there are still issues after configuring the IDE for SSL certificates, you may need to configure the key store for the entire process as described here (under Resolution) and here (under Configuring JVM options).

If you are unable to configure your workstation to communicate with the licensing servers, you can use Offline Activation to activate and re-activate your Illuminated Cloud license key.

Why isn't completion/navigation/etc. working properly?

There are a few reasons this might happen:

The Offline Symbol Table has never been generated or needs to be regenerated

When new packages are installed in the org, metadata is deployed outside of Illuminated Cloud, or after a Salesforce platform upgrade, the Offline Symbol Table can become stale.

To resolve this issue, (re)generate the Offline Symbol Table from Illuminated Cloud | Generate Offline Symbol Table.

Module dependencies are not configured properly for base packages and extension packages

The IDE's project configuration allows modules to depend on other modules. Illuminated Cloud uses this information to resolve references, in particular when developing metadata for multiple managed packages in a single development organization.

To resolve this issue, configure the appropriate module dependencies in Project Structure | Project Settings | Modules. Under the Dependencies tab for the dependent modules, click the + button, then Module Dependency..., and select any dependency modules. Make sure to click OK or Apply to save the module settings.

After making these changes, you may want to rebuild caches as described below.

Illuminated Cloud's caches and indices are stale or inconsistent

Both the base JetBrains IDEs and Illuminated Cloud use file-based indices and in-memory caches to provide quick access to features such as completion and navigation. While inconsistency in these caches and indices should be rare, it can happen. When it does happen, features can behave improperly.

To resolve this issue, you can ask the base IDE and Illuminated Cloud to rebuild their caches and indices. To rebuild only Illuminated Cloud's caches and indices, open Illuminated Cloud | Configure Project and click the Rebuild button. It is highly recommended that you restart the IDE or minimally close and reopen the active project to ensure that caches and indices are properly rebuilt.

If for some reason this doesn't resolve the issue, you can rebuild all of the IDE's caches and indices using File | Invalidate Caches.... Note that indexing may take several minutes after the IDE is restarted.

Why does Offline Symbol Table generation take so long?

In order to create its Offline Symbol Table, Illuminated Cloud uses the Salesforce Tooling, Metadata, and Partner APIs to retrieve various subsets of metadata. The good news is that this should be an infrequent operation; the bad news is that it can take a while based on the volume of metadata deployed to your organization, your organization edition/type, the number of installed packages, and the performance of your organization's host instance at the time.

Be assured that I'm always looking for ways to make this operation more efficient!

Why aren't my metadata files deploying and/or retrieving? Why are unwanted metadata files deploying and/or retrieving?

Illuminated Cloud can be configured on a per-module basis for the metadata content that should be associated with each module. The available options for metadata content selection are:

To resolve this issue, verify that the desired option is selected in the Project Structure | Project Settings | Modules | module name | Illuminated Cloud under the General tab. If the Package.xml option is used and the deployed/retrieved metadata is still not as expected, verify that the package.xml is correct. If the Selected option is used and the deployed/retrieved metadata is still not as expected, Refresh the metadata tree and verify that the selections are correct. If the metadata tree contents are not correct after being refreshed, verify that the user associated with the Illuminated Cloud connection is authorized for the missing content.

What is the difference between Retrieve Metadata and Refresh Metadata? When would I use which?

This is probably the single most frequently asked question. You can find a full description of each of these operations in the description of Metadata Management under the section Metadata retrieval and reconciliation.

Why are my unit tests reported as Ignored?

This is almost always the result of an invalid compilation state in the organization. For example, assume you have ClassA with a method named doSomething() that is called by ClassB, and both ClassA and ClassB have been successfully deployed into your organization. If you rename doSomething() to doSomethingElse() and deploy ClassA, you will not receive any errors even though technically ClassB's usage of doSomething() is now invalid. When you next attempt to run Apex code that exercises these classes, you will see transitive failures. However, if you attempt to run unit tests you may see one or more test classes reported as Ignored because the Salesforce APIs do not include test results for those classes.

In most cases you can find the root cause of this type of issue by opening the Web Setup UI, navigating to Apex Classes, and clicking Compile All Classes. Unfortunately that action is not exposed as a public API for Illuminated Cloud to invoke and assist with this type of issue. Once you resolve the root cause issue, tests should again behave properly.

This may also happen if you have removed an Apex test class or method from the server but not locally and you attempt to run tests. Verify that your local test classes match your and server test classes and run tests again.

Note that I am always looking for ways to improve error reporting in these types of situations to make the path to remediation more obvious.

Can I manage the IDE project files in version control? Which files should or should not be checked in?

Yes, you absolutely can and should include a core subset of the IDE configuration files in your version control system. This helps to share key configuration with the team and to accelerate the onboarding process for new team members. JetBrains provides documentation for which standard IDE configuration files should and should not be managed under version control. In addition I recommend that the following files be checked into version control for the best team development experience:

The following should not be checked into version control as they represent user-specific configuration:

I'm also often asked whether the Offline Symbol Table should be checked in. There's no definitive answer to that question. If the project metadatain particular the SObjects and fieldsare quite stable, it's generally safe to check in the OST archive and share it with the team. The advantage, of course, is that it minimizes the need for potentially expensive OST generation. However, if new custom objects and/or fields are being added, removed, or modified on a regular basis, the OST archive may be quite volatile and not a good candidate for inclusion in version control. Personally I don't check in the OST, but in most of the organizations against which I work, OST generation takes only a minute or two.

Why does Illuminated Cloud keep telling me my evaluation period is about to expire/has expired?

Have you purchased a license key for Illuminated Cloud? If not and you wish to continue using Illuminated Cloud after the 30-day evaluation period, or if you have purchased a license but don't know how to use the provided license key, please follow the instructions for purchase and activation.

If you have followed the instructions for activating Illuminated Cloud and are still being warned about the evaluation period, please log a bug or contact me.

Can I use my Illuminated Cloud license on another machine?

By default each registered license for Illuminated Cloud 2.0 entitles one user to activate Illuminated Cloud on two machines. Additional activations for use by the same licensee are available by request. If you need to move your Illuminated Cloud license to another machine, you should deactivate the license on the current machine and it will be available to activate on the new machine. If you do not have access to the original machine, you can use a self-service Web application to view and manage license activations. If you are experiencing other issues deactivating a license, please contact me.

How do I uninstall/remove Illuminated Cloud from IntelliJ IDEA/PhpStorm/PyCharm/RubyMine/WebStorm?

I'd certainly like to understand why you want to uninstall or remove Illuminated Cloud! If you're doing so because of a bug or missing feature, please log a bug or enhancement request or contact me with the details using the information below.

If you still want to uninstall Illuminated Cloud, follow these steps:

If for some reason this process doesn't work properly to uninstall the plugin, you can manually uninstall the plugin: