CRMGearbox

Users Guide v1.0.173

Vital Engines LLC

www.vitalengines.com

Third Party Notices

Salesforce™, Salesforce.com, and Salesforce CRM are registered trademarks or trademarks of Salesforce.com, Inc. in the United States or its subsidiaries in Canada and other countries.

Microsoft™ and Windows are trademarks or registered trademarks of Microsoft Corporation or its subsidiaries in Canada, United States and/or other countries.

All other trademarks are trademarks of their respective owners.

Table of Contents

1.0 Getting Started 3

1.1 System Requirements 3

1.2 Product Installation 4

2.0 Creating a CRMGearbox Solution 5

2.1 Create your Solution 6

2.2 Create a Salesforce Connection 7

3.0 Using the Model Explorer 9

3.1 Understanding the Model Explorer Options 11

3.2 Exploring the model using Grid Actions 12

3.3 Using the Export button 17

4.0 Using the Compare Models feature 18

5.0 Command Line Options 20

6.0 Additional Information 21

7.0 Release Notes 22

1.0 Getting Started

CRMGearbox is a Windows Desktop based application that enables users to capture information available in their Salesforce instances using the Salesforce APIs. The initial information captured is the core data model elements, Objects and Fields, and their underlying metadata. CRMGearbox extracts this information using the API and saves it locally on your computer, where it can then display the information using a grid that allows users to explore the metadata using filters, sorting, and grouping features, along with the ability to export information into Excel and CSV formats.

This product is available for trial by signing up to the mailing list at the following address:

https://www.vitalengines.com/crmgearbox-trial

Note that fully functional trials are available for 14 days and are not limited in capability. After the trial period has expired that program will cease to function. Trial participants are free to unsubscribe from our mailing list following the trial period.

1.1 System Requirements

CRMGearbox requires the following

  • Windows 10
    • Windows 7 and earlier versions may function if updated, but they are not recommended or supported
  • Intel Core I3 Processor or greater
    • Other processors may function, but CRMGearbox works best with high speed processors due to the volume of data utilized by the application
  • Minimum 4Gb of RAM
    • CRMGearbox performs more effectively with greater RAM due to a large amount of in-memory processing
  • Minimum 150Mb Disk Space for Application
    • For the CRMGearbox application to be installed
  • Minimum 50Mb Disk Space for Data Storage
    • CRMGearbox uses local file storage for information extracted
    • The total amount of data storage required will vary according to how many snapshots are created
  • Microsoft .Net Framework version 4.6.1 or greater
  • Salesforce instance with API Enabled
    • This includes Developer sandboxes, Enterprise, and Ultimate editions or Professional with API Enabled

1.2 Product Installation

The CRMGearbox product installers are located at the following location:

https://www.vitalengines.com/downloads

Download the appropriate build for your operating system. Note that x86 (32bit) and x64 (64bit) builds are available for the application. The x64 build will only run on a 64bit operating system, while the 32bit builds will run on either 32bit or 64bit operating systems. The x64 bit version is recommended. The installer name will follow the naming convention below:

CRMGearbox_[VERSION]_[BITNESS].Installer.msi

For example:

CRMGearbox_1.0.72_win32.Installer.msi

Or

CRMGearbox_1.0.72_win64.Installer.msi

After downloading the appropriate version for your operating system, run the installer and you will be guided through product registration and activation. The registration process involves the following steps:

  1. Enter a Product Key
    1. This key will have been provided during the Trial Request registration process, or via the fulfillment email provided through the Vital Engines LLC webstore
    2. For Trial Keys (evaluation), some information provided during signup will be carried into the registration page
    3. For permanent (subscription) keys, you must provide an email address that will be verified
      1. This ensures that we can identify who has registered each product key for support and licensing purposes
      2. Email addresses are used solely for support and licensing
  2. Provide your Location
    1. Indicate if you are in the United States or International
  3. Enter basic Registration Information
    1. E.g. Name, Company, Location
      1. Email Address will be automatically entered based on the Trial Email Address or what had been previously verified
    2. Only a few fields are required, additional information is optional
  4. Finish
    1. At this point, the application will retrieve a license for the product based on the Product Key you have provided

2.0 Creating a CRMGearbox Solution

CRMGearbox allows users to create Solutions to group a list of Salesforce Connections together. Typically, users will have a Production Salesforce instance and additional Sandbox instances that they would like to access frequently and be organized with each other. Before creating a solution, consider the following best practices:

  1. The name for your Solution should include some concept of the realm you intend to work in
    1. if you have just one production Salesforce instance, but multiple sandboxes, consider naming it after your company
      1. For example, ACME Corporation has a single SFDC production instance
        1. Name your Solution “ACME Corporation”
    2. If you have multiple instances, consider naming with your company name followed by the instance purpose
      1. For example, ACME Corporation has two SFDC production instances
        1. One instance is the Sales Cloud and another is Service Cloud
        2. Consider creating two solutions
          1. ACME Corporation Sales
          2. ACME Corporation Services
    3. It is not mandatory to use company name as a solution name, nor is it required to split connections into multiple solutions
  2. The solution name you choose will create a file and folder for the storage of the CRMGearbox SFDC Connections and any metadata downloaded from your Salesforce instances
    1. If you intend to move the CRMGearbox Solution file (ends with a .cgs suffix), you must also move the folder with the same name adjacent to the .cgs file
      1. The .cgs file and solution folder must be in the same directory
  3. CRMGearbox will create a default directory named “CRMGearbox” in the users “Documents” folder
    1. Any new solution will be placed in the default folder and can be moved to an alternate location later
    2. It is recommended that users use the default location to avoid any Windows related folder permissions issues

The next section will guide you through the steps to create your first solution.

2.1 Create your Solution

From the File menu select New -> Solution

The following dialog will appear. Enter a name for your solution and click Create.

An additional File Save dialog will appear. Click Save to continue.

2.2 Create a Salesforce Connection

Click on the solution name in the Solution Explorer navigation area and then enter a Connection Name along with your user credentials and click Create. Note that Salesforce user names are unique and are tied to a given instance. If you are attempting to connect to a sandbox, click the “Use Sandbox Connection” checkbox. For Salesforce Developer (non-sandbox) instances, do not use a sandbox connection.

The connection will be validated and after saving the connection will appear under the solution name. Additional connections can be created from this (the Solution Home) tab.

Click on the Salesforce Connection to view your connection. From this tab, connection properties can be changed and connections can be tested.

3.0 Using the Model Explorer

The Model Explorer allows users to take snapshots of metadata in their Salesforce instances and view the information in a configurable grid. Each snapshot represents a point in time capture of the metadata which allows users to see changes over a period of time. Each time the Snapshot button is used, a new copy of the metadata is extracted and saved to the user’s local computer.

If no changes to a model are detected, the last model is used and no information is saved to reduce diskspace needs. Performing a snapshot is a high intensity operation, making several API calls to retrieve and correlate the information; some system and application lag may be expected. To begin, click on the Snapshot button.

Once the snapshot has finished, the grid will populate with metadata from the currently selected Salesforce Connection.

3.1 Understanding the Model Explorer Options

The Model Explorer has several options available in a ribbon area within the tab. These options help users explore information in the grid by enabling filtering and setting export options.

  1. Display Options
    1. Flat View
      1. This view is the default and shows each field and object in a non-hierarchical manner
      2. This view allows further drill down into the Picklist Values for an object when the Field Options -> All Attributes option has been selected
    2. Tree View
      1. This view can be selected to show Object->Field information in a hierarchical manner
      2. This view allows users to drill down into Fields an object
      3. This view allows further drill down into the nested metadata for an object when the Field Options -> All Attributes option has been selected
  2. Field Options
    1. Basic Attributes
      1. This setting is used by default and displays only the high level detail for an Object or Field
    2. All Attributes
      1. This setting can be used to toggle the grid to show nested properties with low level details
        1. When Flat View is selected, this setting will only show the Picklist values for a Field
        2. When Tree View is selected, this setting will show the following additional information
          1. Record Type Information
          2. Child Relationships
          3. Named Layouts
          4. Action Overrides
          5. Supported Scopes
          6. Fields

Picklist Values are also available (when they exist) under each field

  1. Data Options
    1. Provides a filter based on type of object (defaults to All Objects)
      1. Standard
      2. Custom
      3. Namespaced
      4. External
      5. Metadata
      6. Custom Settings
      7. Tooling
      8. All Objects
  2. Export Options
    1. When selected, the Export Button will export the current grid information to the desired file format
      1. CSV
      2. Excel
  3. Select Model Snapshot
    1. Enables users to Select a snapshot and Load to grid, take a new Snapshot, or Delete

3.2 Exploring the model using Grid Actions

The Model Explorer grid is an interactive way to filter, sort, and group the metadata in the models captured using the Snapshot feature. Grid operations occur in memory in order to maximize performance, and some operations may cause a slight delay in responsiveness after execution. This section will only highlight a few key use cases for using grid actions.

Sorting via Column Name – Using Create Date or Last Modified Date to determine what has recently changed.

Click on any Column Header to toggle sorting.

Grouping by Creator

Drag the Column Name to Group By into the grouping header. To ungroup, drag the column out of the grouping header.

Filter by Object Name

Type the name of the Object to filter in the filter area under each column name.

More filtering options are available using the icon to the right in the column name filter area.

Group by field Type by dragging into the grouping header.

Additional nested attribute information is available by clicking the expand/collapse arrow on the far left side.

Perform a deep inspection of object nested properties.

Use the expand/collapse arrows to view nested details.

View Picklist values for a field

3.3 Using the Export button

The Export button will export what is currently available in the grid, including nested properties, to a CSV or Excel format. This example will export just the properties for the Account Type picklist field and its nested picklist values. After clicking Export a File Save dialog will appear. You will be prompted to open the file once export has completed.

Sample Excel export for the given criteria.

4.0 Using the Compare Models feature

The Compare Models features allows users to view changes to the model on a granular level. To use the feature, click on the Compare Models tab, then select the Source and Target Snapshots you wish to compare and click the Compare button. Note that the Compare Models grid is identical to the Model Explorer grid in terms of features (sort, group, filter, export)

Higher resolution view of changes

Notes on Compare Models

  • Compare Models is an exploratory feature and can result in very large result sets, which may cause confusion for less advanced users.
  • In addition to Field and Object level changes, Picklist value changes (including the actual picklist value) are presented
  • Some internal Salesforce tables (Field Permissions) are presented as they have been changed as well
    • This is considered “under the hood” and can be ignored, although it is interesting to note these system level changes
    • The Date Changed information is available for this object and will default to your instance creation date and organizational owner

5.0 Command Line Options

CRMGearbox can perform snapshots from the command line, using command line arguments, which enable users to execute schedules via batch files and scheduled Windows jobs, or by using other command line schedulers. The application currently does not support any additional command line options. To perform a snapshot use the following syntax:

CRMGearbox.exe [FULL_CRMGEARBOX_SOLUTION_PATH] /snapshot:[CONNECTION_NAME]

Execution of this command will require the CRMGearbox.exe to be in the system path, or be fully qualified with a path. The FULL_CRMGEARBOX_SOLUTION_PATH is the path to your .cgs file, which contains your Salesforce Connections. The CONNECTION_NAME is the name of your connection.

E.g.

CRMGearbox.exe mycompany.cgs /snapshot:devsandbox

6.0 Additional Information

Using CRMGearbox can reveal a whole new world of information that is available, but typically hidden away from user view or difficult to access. As users become more familiar with CRMGearbox, they will gain better insight into the complex models that make up their organizational instance. At Vital Engines, we want to help companies understand how the information provided from CRMGearbox can be used to improve the vitality of their Salesforce instance. Please reach out to us with any additional questions at support@vitalengines.com and we will be glad to help.

7.0 Release Notes

1.0.173 – Minor Updates

  • Change API defaults to v51.0 (Spring 21 Release)
  • Reduced API batch size to address incomplete fetch of metadata

1.0.172 – Minor Updates

  • Change API defaults to v49.0 (Summer 20 Release)
  • Address Large Exports to Excel by using XSLX format by default

1.0.171 – Minor Updates

  • Change API defaults to v47.0
  • Address timeout issue on solution creation

1.0.168 – Initial Production Release

  • Added support for Salesforce Winter 20 Release