[Home]

Retrieving Metadata

Illuminated Cloud can update your project's local metadata files with metadata from your Salesforce organizations. This process is called metadata retrieval.

Illuminated Cloud provides flexible mechanisms for choosing the subset of metadata you wish to retrieve, the organization from which you wish to retrieve, and whether you wish to overwrite the project's local metadata files or compare the retrieved metadata with the project's local metadata to reconcile and merge differences.

The available options for metadata retrieval vary based on whether you're working against non-scratch orgs such as Developer Edition orgs, Sandboxes, or Production orgs, or whether you're working against Salesforce DX scratch orgs.

There are several ways you can retrieve metadata from the associated Salesforce organization into your local Illuminated Cloud project:

• Retrieve a specific subset of metadata, directly replacing any existing versions of the same metadata. Use this operation when you want to retrieve new metadata from the server and aren't concerned with potential conflicts.

• Review and retrieve metadata, comparing differences before choosing which changes to merge into your local project. Use this operation when you want to retrieve new metadata from the server and/or are concerned about potential conflicts.

• Retrieve the latest version of the metadata available on the server, for which you already have a local version. Use this operation when you want the latest version of the metadata you already have locally and aren't concerned about potential conflicts.

• Compare and retrieve the subset of metadata that has changed on the server, based on the context of your current selection.

Retrieving Against Non-scratch Orgs

You can use the IDE to retrieve a set of metadata files in bulk, in a single request. You can access the Retrieve Metadata, Refresh Metadata, and Compare With Server commands from the Tools > Illuminated Cloud menu, Illuminated Cloud context menu, the toolbar (in most cases a toolbar icon is available), or using the respective keyboard shortcuts.

NOTE: Select View > Toolbar to enable the toolbar, if it isn't visible.

Retrieval-specific Options

After you've familiarized yourself with the options available to specify the scope for all bulk metadata operations, it's important that you also understand the retrieval-specific options:

• Replace/Merge/Skip the retrieved package.xml file against the local package.xml file — When retrieving all files for the current module (including module with dependencies and project), the generated package.xml file returned with the retrieval payload may differ from the project's local package.xml file. This option allows you to specify how the retrieved package.xml file should be handled relative to the local one when performing a Retrieve operation (as opposed to a Retrieve for Merge).

  • Replace — Select this option to replace the local package.xml file with the retrieved package.xml file.

  • Merge — Select this option to use the IDE's file diff tool to compare and merge the retrieved package.xml file (displayed on the left) into the local package.xml file (displayed on the right).

  • Skip — Select this option to discard the retrieved package.xml file and leave the local package.xml file untouched.

• Source root for unmatched retrieved files — When retrieving a custom selection for a single-module project with multiple source roots, a specific source root can be selected for unmatched retrieved metadata. The initial source root value is based on the contextual selection at the time that the metadata retrieval was started.

Retrieving Metadata

To select the exact subset of metadata which will be retrieved from the organization into the local project, directly replacing any existing version of the same metadata, select Retrieve Metadata .

After you have specified the organization from which you wish to retrieve metadata and the exact subset of metadata you wish to retrieve from that organization, click either Retrieve or Retrieve for Merge to begin the retrieval operation.

Retrieve

If you click Retrieve, the selected subset of metadata will be retrieved directly into the project's local directory structure, overwriting matching local metadata files and added new metadata files to the respective locations.

Retrieve for Merge

If you click Retrieve for Merge, the selected subset of metadata will be retrieved into a temporary directory, restructured to match the project's local directory structure, and the IDE's directory diff tool will be opened with the retrieved metadata on the left-hand side and the project's local metadata on the right-hand side for reconciliation and merging.

TIP: If you'd prefer to use a third-party tool such as Beyond Compare or Araxis Merge, you can configure the IDE to use an external diff tool.

NOTE: To update your local project files with metadata retrieved from the server, copy files and/or text blocks from left-to-right in the diff tool. Copying right-to-left will have no effect as the metadata retrieved from the server is stored in a temporary directory and discarded when the IDE is closed. To perform a full local/server synchronization, do the following:

1. Use Retrieve Metadata > Retrieve for Merge to merge all desired server metadata files and differences into the project's local metadata files.

2. Use Deploy All / Modified Metadata to deploy all merged local metadata files to the server.

When the retrieval operation is complete, details about the retrieved metadata — including any errors encountered during retrieval — are displayed in the Messages window.

Refreshing Metadata

To update the project's local metadata files with the latest version of the server metadata, select the Refresh Metadata menu item, context menu item, toolbar icon , or keyboard shortcut. The selected subset of metadata will be retrieved directly into the project's local directory structure, overwriting matching local metadata files.

NOTE: It is not possible to add new metadata files to a project using Refresh Metadata. To add new metadata files to the project, use Retrieve Metadata instead.

Comparing With Server

To visually compare the project's local version of one or more metadata files with those from the server, select one or more metadata objects in the list and select the Compare With Server or Compare With... menu item, context menu item, toolbar icon / or keyboard shortcut. Compare With Server automatically selects the project's configured connection as the comparison target, and Compare With... prompts the user to select a configured connection as the comparison target.

The selected subset of metadata will be retrieved into a temporary directory, restructured to match the project's local directory structure, and the IDE's directory diff tool will be opened with the retrieved metadata on the left and the project's local metadata on the right for reconciliation and merging.

Retrieving Against Scratch Orgs

When working with scratch orgs, the Salesforce CLI is used to update the project's local metadata files with any changes to the associated scratch organization's metadata, via its Push and Pull operations.

In Illuminated Cloud scratch org projects, you'll use the Push Metadata and Pull Metadata commands to deploy metadata to and retrieve metadata from scratch orgs. This terminology is also reflected in the bottom status bar and Problems view to indicate when the IDE is “Pulling…” a change, and in "Pull Complete" messages.

When you need more fine-grained control over the metadata you want to push to your scratch org, you can use the Retrieve Metadata command described above. For more information, see Specifying the Scope for Bulk Metadata Operations.

[Home]