Start tracking your progress
Trailhead Home
Trailhead Home

Convert and Deploy an Existing App

Learning Objectives

After completing this unit, you’ll be able to:
  • Describe the Salesforce CLI command to set a password on a scratch org.
  • Describe how use the CLI to convert from metadata format in to source format that can be used with a Salesforce DX project.
  • Demonstrate how to use the CLI to deploy metadata to your testing org.

So Many Options, So Little Time

We live in a world where we have choices. Do you want bran flakes or yogurt for breakfast? Hey, did you say bacon? Developing on the Salesforce platform is like a breakfast buffet of options—so many ways to successfully complete a development project.

And consequently, there are several methods to convert an existing app to source format. Source format is the decomposed file structure for the Salesforce DX project. To assist you on this journey, we’re going to show you one approach by taking advantage of an existing sample app called the Mutual Fund Explorer.

This app contains all kinds of metadata. It also showcases best practices for Aura components. While we’re converting this app, you learn about a few more Salesforce CLI commands. At the end of this unit, you deploy the app to your Trailhead Playground org. You get to use all your newfound knowledge for a real hands-on challenge.

Did You Already Set Up Salesforce DX?

Did you skip unit 1? If you did, head back there to perform the setup tasks required to complete this unit.

Got everything installed? Grab a cup of coffee, and let’s get started.

Create a Project and Scratch Org

Part of the beauty of the package development model is that you isolate each development project you’re working on in its own space. So for this exercise, you’ll create a new project and a new scratch org.

To demonstrate how you work with an existing app, you’ll install an unmanaged package in to a scratch org. This scratch org simulates what you can already have in a sandbox or production org. When you’re done, you can delete this scratch org. That’s the whole premise of the scratch org and its ephemeral nature. Spin up one for a specific purpose or task, then delete it once you’re done.

  1. Create a project called MutualFundExplorer:
    sfdx force:project:create -n MutualFundExplorer
  2. Change to the MutualFundExplorer directory.
    cd MutualFundExplorer
  3. Create a scratch org with the alias TempUnmanaged:
    sfdx force:org:create -f config/project-scratch-def.json -a TempUnmanaged

    When you create a scratch org, certain values are automatically set for the org.

  4. View the configuration data for the scratch org:
    sfdx force:org:display -u TempUnmanaged

    Notice that the output provides the Instance URL, which is the My Domain value for the scratch org. You need this, along with the username and password, to install the package.

  5. Create a password:
    sfdx force:user:password:generate -u TempUnmanaged
  6. Reissue the org:display command to see all the required values to install the package:
    sfdx force:org:display -u TempUnmanaged
    The output looks something like this:
    KEY               VALUE
    ───────────────   ─────────────────────────────────────────────────
    Access Token      008jF!xxx
    Alias             TempUnmanaged
    Client Id         SalesforceDevelopmentExperience
    Created Date      2017-04-26
    Dev Hub Id        0J746000000PBp9
    Edition           Developer 
    Expiration Date   2017-05-04
    Id                00D3D0000008bjF
    Instance Url
    Org Name          Acme
    Password          4739223f
    Status            Active

Notice how the alias for our scratch org, TempUnmanaged, came in handy for all these commands. A little easier to type than Right?

Install the Unmanaged Package

With the username, password, and instance URL, you can now log in to the UI for installing the unmanaged package for the Mutual Fund Explorer app, which is called DreamInvest.

  1. Copy the value of the Instance URL from the output of the org:display command.


    To make sure you install the package in the correct org, log out of any existing orgs.

  2. Browse to this URL.

  3. In the login screen, click Use Custom Domain.

    If you don’t see this option, select Log In with a Different Username.

  4. In the Custom Domain field, paste the instance URL without the https://.

    Use Custom Domain dialog

  5. Click Continue and enter the username and password for the scratch org listed in the output of the org:display command.

    Once you log in, you see details about the package.

    Install DreamInvest dialog

  6. Click Install and then Done.

    You get redirected to your scratch org where you can see the DreamInvest package has been installed.

    Installed Packages dialog

Create the Permission Set

Before we finish in the org, let’s create a permission set that we’ll use to provide access to the custom objects added by the DreamInvest app.

  1. From Setup, enter Permission Sets in the Quick Find box, then select Permission Sets.
  2. Click New.
  3. For Label, enter DreamInvest.
  4. Click Save.
  5. Under Apps, click Assigned Apps | Edit.
  6. Under Available Apps, select DreamInvest (DreamInvest), then click Add to move it to Enabled Apps.
  7. Click Save.

    Now, let’s extract this permission set into our source.

  8. Run the following command in the CLI:
    sfdx force:source:pull -u TempUnmanaged
You see the source extracted into your project:
───────  ───────────  ───────────── ───────────────────────────────────────
Changed  DreamInvest  PermissionSet <path>/DreamInvest.permissionset-meta.xml

Extract the Package Source to Your Project

The next step is to pull the existing application out of the org. There are many ways to do this task. You can create a package.xml file and pull your source using the Metadata API retrieve method. If you already have your source stored in VCS, you can use the method you prefer. In this unit, we’ll use CLI commands for the Metadata API to retrieve the contents of a package.

First, create a new directory in your project for the exported metadata.

  1. Within your project, using the tool of your choice, create a folder called mdapipackage.
  2. Retrieve the contents of the DreamInvest package into the mdapipackage folder:
    sfdx force:mdapi:retrieve -s -r ./mdapipackage -p DreamInvest -u TempUnmanaged -w 10
    You see something similar in the command window:
    Retrieving source...
    === Status
    Status: InProgress
    jobid: 09S9A0000008Xq3UAE
    === Result
    Status: Succeeded
    jobid: 09S9A0000008Xq3UAE
    Wrote retrieve zip to /Users/jdoe/MutualFundExplorer/mdapipackage/
  3. Change to the mdapipackage folder and verify that the file appears.
  4. Unzip the file.
  5. Delete the file:

Now you have all the source for the app in metadata format. Next, convert the source files to source format.

Convert the Source and Push It to a New Scratch Org

Why do we convert the metadata source to source format? Metadata format was never designed for developers to work with. It’s stored in one massive file in the production org. Source format breaks up the metadata into smaller files. This makes it easier for development teams to interact with the source and use a VCS.

Fortunately, conversion is easy—there’s a command for that!

  1. From the MutualFundExplorer folder, convert the contents of the mdapipackage folder:
    sfdx force:mdapi:convert -r mdapipackage/

    Voila! All the converted source is now in the force-app folder. Why that folder? Because that’s the default specified in sfdx-project.json.

  2. Clean up your project by deleting the Metadata API source:
    rm -rf mdapipackage
  3. Delete the scratch org:
    sfdx force:org:delete -u TempUnmanaged

Verify Your Work

Did all of that work? The easiest way to find that out is to spin up a new scratch org and try it out. Since you didn’t create this app, you’ll assign a permission set that gives you access to the app.

  1. Create a new scratch org:
    sfdx force:org:create -s -f config/project-scratch-def.json

    Notice the command sets this new scratch org to be the default for this project. This way, any commands you issue are run against this scratch org.

  2. Push your local source and metadata to the scratch org:
    sfdx force:source:push
  3. Assign a permission set:
    sfdx force:user:permset:assign -n DreamInvest 
  4. Open your org:
    sfdx force:org:open

At this point, everything works! You’ve fully converted the app. If you were going to continue to work on this app, you’d commit the current source into your VCS and continue your development.

Now you’re ready to deploy your app to a testing org.

Deploy the Converted App Using Metadata API

Next, we’ll walk you through the steps to use Metadata API to deploy your app into an org. From there, you can use existing technology—packaging, change sets, Ant Migration tool, or Metadata API—to move it in to your production environment.



These steps work regardless of whether you built a new app or converted an existing app.

Similar to the conversion process, we have CLI commands to perform these tasks.

Register Your Testing Environment

Most of the time you’ll use a sandbox for testing, but for purposes of this module, go ahead and use your Trailhead Playground org for this step. That way we can check your work and you can earn your badge!

Trailhead Playground orgs have My Domain turned on. Do not change the My Domain settings in your Trailhead Playground. For future reference, if you want to follow these steps in your production org, follow the instructions in the User Authentication module to enable My Domain. Otherwise, your Lightning components won't deploy.

  1. Log in to your Trailhead Playground org and create an alias for it.
    sfdx force:auth:web:login -a MyTP

    If you don’t know the username and password for your Trailhead Playground, see Find the Username and Password for Your Trailhead Playground.

  2. Confirm that this org is available:
    sfdx force:org:list

Convert Source to Metadata Format and Deploy

Next, convert the source format back to metadata format. The conversion process is straightforward and only involves a few commands.

  1. Create a folder to put the converted files called mdapioutput.
    mkdir mdapioutput
  2. Next, run the convert command:
    sfdx force:source:convert -d mdapioutput/

    Now, your source is in a format that works with the Metadata API.

  3. Deploy it to your testing environment:
    sfdx force:mdapi:deploy -d mdapioutput/ -u MyTP -w 100

    This command deploys everything to your Trailhead Playground.

  4. Assign a permission set:
    sfdx force:user:permset:assign -n DreamInvest -u MyTP
  5. Run your tests and interact with the app:
    sfdx force:org:open -u MyTP

    Be sure to indicate the -u flag to open the correct org. If you forget the username option, this command opens the scratch org you indicated as the default.

Congratulations! You’ve just walked through a large chunk of the package development life cycle. You created an app, converted an existing app, and deployed the app to an org. You’ve obtained official Salesforce CLI ninja status for the commands you’ll use most often. But you just touched the tip of the iceberg here. So check out the resources to get the complete picture of everything you can do.