FAQ
Frequently Asked Questions
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.
<soapBox>
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.
</soapBox>
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:
Go to type, file, or symbol (Ctrl + N / Cmd + O, Ctrl + Shift + N / Cmd + Shift + O, Ctrl + Alt + Shift + N / Cmd + Opt + O) - Quickly navigate to an Apex type/trigger, metadata file, or identifier (method, field, etc.) by name.
Go to declaration, implementation (Ctrl + B / Cmd + B, Ctrl + Alt + B / Cmd + Opt + B) - Quickly navigate to the declaration or concrete implementation(s) of the current identifier.
Go to related (Ctrl + Alt + Home / Ctrl + Cmd + Up) - Quickly navigate between related files, e.g., source and meta.xml files, Lightning bundle files, Visualforce pages/components and their controller classes, Apex product classes and the unit test classes that verify them, etc.
Show usages (Ctrl + Alt + F7 / Cmd + Opt + F7) - Quickly see and navigate to usages of the current identifier without opening new docked windows.
Navigate back/forward ( Ctrl + Alt + Left/Right, Cmd + Opt + Left/Right) - Use browser-style navigation to move back and forth through navigation drill-down paths.
Increase, decrease selection (Ctrl + W / Opt + Up, Ctrl + Shift + W and Opt + Down) - Just try this one and you'll see what I mean. In particular place the cursor on the first line of a statement or class/method declaration and increase the selection. It's by far the fastest way to select exactly what you want.
Quick documentation (Ctrl + Q / Ctrl + J) - Integrated API documentation is a huge timesaver, even more so when you spend the time to document your own APIs via ApexDoc, JSDoc, and documentation metadata.
Parameter info (Ctrl + P / Cmd + P) - View the allowed parameters of the current method or function. The current parameter is even highlighted as you move through the invocation arguments.
Quick definition (Ctrl + Shift + I / Opt + Space or Cmd + Y) - View the definition of the current identifier without having to navigate to it.
Show intention actions and quick-fixes (Alt + Enter / Opt + Enter) - As more and more code inspections and intentions are added to Illuminated Cloud, this action should become your go-to for quickly managing and evolving your code. It's also a shortcut for running the Apex test class or method under the cursor.
Code completion (Ctrl + Space) - The IDE will start completions for you as you type, but Ctrl + Space will allow you to initiate it at any time, even on an existing identifier that you'd like to change. Also become familiar with the various ways of accepting completions for insert vs. overwrite and even begin the next component of a chained completion.
Rename (Shift + F6) - Rename the current identifier.
Extract variable (Ctrl + Alt + V / Cmd + Opt + V) - Extract the current expression into a variable.
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:
Project - Projects are containers for one or more related modules, but they don't actually reference source roots directly. A single project can contain modules of different types, e.g., Java modules as well as Illuminated Cloud modules for a hybrid application. Each project is opened in a separate IDE window.
Module - Modules are where source roots are "mounted" and builds take place. Each module has a "module type" that determines which language(s) apply to that module, what builder (i.e., compiler) is used, etc. Modules can express dependencies on one another as well. All the modules for a project can be found in the Project View tree for that project. Note that the lightweight IDEs do not explicitly expose the concept of a module and projects and modules have a one-to-one relationship.
Connection - Connections are the coordinates, credentials, and configured behavior of a Salesforce organization in Illuminated Cloud. Connections are configured at the application-level and can be associated with multiple projects via their modules. It's also possible to choose different connections for metadata management operations, anonymous Apex and SOQL query execution, and debug log analysis, e.g., to develop against a sandbox or developer edition org and deploy occasionally against a test or production org.
Offline symbol table and SDK - Illuminated Cloud generates an offline symbol table for each connection that includes the interfaces of all system classes, server-only custom classes, and SObjects in the associated organization. The offline symbol table has a one-to-one relationship with a configured connection and is bound to a module as its SDK for dependency resolution purposes. Illuminated Cloud is fully responsible for the creation and association of the SDK.
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:
Apex Class - *.cls, *.trigger, *.apex, and *.soql
Apex Metadata - *-meta.xml
SObject Type - *.object
Visualforce Page - *.component and *.page
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.
Other
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:
All/Package - If the module is not configured for a development package, all metadata in the local filesystem for the module is deployed and all metadata in the organization is retrieved. If the module is configured for a specific development package, all metadata in the local filesystem for the module is deployed and only the metadata associated with that package is retrieved.
Package.xml - Only the metadata specified in the selected package.xml file is deployed and retrieved.
Selected - Only the selected metadata in the tree is deployed and retrieved. If the set of metadata isn't current, use the Refresh button to update the tree contents with the latest metadata in the organization.
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:
*.iml - Module configuration files should be checked in.
.idea/.name - This is optional. If the desired project name should be different from the parent directory name, include this file with just the project name as its contents.
.idea/codeStyleSettings.xml and .idea/codeStyles/* - I recommend that the team agree upon a common set of project-level (vs. IDE-level) code formatter settings for Apex, HTML, JavaScript, CSS, etc., configure the project to use project-level settings, and check them in. This will ensure code style consistency across the team.
.idea/illuminatedCloud.xml - This file contains project-specific configuration for Illuminated Cloud. Note that for the best results when sharing configuration, it's important that connection names be used consistently by all team members. Connection details themselves are stored at the application level under the user's home directory, so the credentials can vary across team members so long as the connection name is consistent.
.idea/misc.xml - This contains simple project-level configuration and should be checked in.
.idea/modules.xml - This contains the list of modules for the project and should be checked in.
.idea/vcs.xml - This includes the high-level version control configuration for the project. It does not include user-specific credentials or similar that should not be shared and should be checked in if version control is used.
.idea/copyright/* - If using IntelliJ IDEA's Copyright plugin, a project-level copyright profile should be created, configured for the project, and checked in.
.idea/fileTemplates/* - If custom or customized file templates are used, they should be configured at the project-level and checked in.
.idea/inspectionProfiles/* - If custom inspection profiles are configured, they should be stored and associated at the project-level and checked in.
.idea/runConfigurations/* - Minimally an All Tests Apex unit test run configuration should be created as a Shared configuration and checked in. Other project-level run configurations may be included as well.
.idea/scopes/* - If custom scope definitions are created, e.g., for Salesforce-only metadata such as Apex source, they should be stored at the project-level and checked in.
The following should not be checked into version control as they represent user-specific configuration:
.idea/workspace.xml
.idea/tasks.xml
.idea/shelf/*
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 metadata—in particular the SObjects and fields—are 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 you have a registered license for Illuminated Cloud, please deactivate the license first so that it is available to be activated elsewhere if desired. You can deactivate the license in Illuminated Cloud | Configure Application | About by clicking Deactivate license.
To uninstall the Illuminated Cloud plugin, open Settings | Plugins and either type Illuminated Cloud into the search box or scroll to Illuminated Cloud in the list of installed plugins. Select the plugin and click Uninstall plugin in plugin details on the right-hand side. Click OK and restart the IDE.
If for some reason this process doesn't work properly to uninstall the plugin, you can manually uninstall the plugin:
Make sure that the base IDE is not running.
Under that directory find the sub-directory config/plugins.
Under that directory you should find a sub-directory named IlluminatedCloud2. You can either delete this directory or move it outside of the user configuration directory.