Workshop: Build an ISV app to extend Salesforce Order Management and B2B Commerce

In this workshop we will be developing and packaging a sample AppExchange ISV app that works with the Salesforce B2B Commerce and Order Management products, which are both part of the Salesforce core platform tech stack. For packaging, we will be using Second-Generation Packaging (2GP).

Big picture steps:

1. Tooling Setup
2. Build our app in the Commerce org
3. Pull the created metadata out of the Commerce org using VS Code
4. Package it
5. Demo: connect our package to your Partner Community publishing console, submit for Security Review and list it on the AppExchange

Prerequisites

Here are the pre-requisites that workshop attendees should have installed on their computers:

• Java/JDK version 17, 11, or 8 (if you click these links, scroll down to the table on the site it opens)
  • more detailed guidance if needed
• Git
• Salesforce CLI
• VS Code
• Salesforce Extensions for VS Code

Step-by-step walkthrough

Use case: The sample app we will be building is a Shipping Calculation app which B2B Commerce will use to calculate shipping costs in real-time once checkout begins, and Order Management will use for re-ship requests. Note: We are keeping the app simple for the sake of this exercise. Realistically, an app may have more to it than this, such as integration with shipping logistics provider APIs, updates on shipping status, etc.

We will be connecting to two orgs: one to build our app inside of, and one to allow us to package the app and list it on AppExchange. We will refer to these as our Commerce Org and our Dev Hub, respectively.

1. Tooling setup:
   1. First, we will clone the Github repo we’ve prepared for this workshop, in the interest of time we have partially built our ISV app in advance
      1. Go to the commerce-workshop Github repo, click the green Code button, and copy the URL from there
      2. 
      3. Now open VS Code. You may see either the “Get Started” screen in VS Code, or it may open the most recent directory you’ve been working in.
      4. Here is what the Get Started screen looks like:
      5. 
      6. If you do not see this Get Started screen:
         1. Open it, by clicking into VS Code’s Help menu >> Get Started
         2. 
      7. From the Get Started Screen, click on Clone Git Repository...
      8. 
      9. This will open the command palette with instructions to provide the repository URL
      10. 
      11. Paste the URL we copied from Github earlier, and hit the Enter/Return key
      12. 
      13. A popup window will open. Click Desktop, then click Select Repository Location
      14. 
      15. This will open a new popup window. Click Open
      16. 
      17. This will open VS Code in the context of the new repository we have just cloned to our local machine. You should now see commerce-workshop as the root folder in VS Code’s left pane
      18. 
   2. Next, we will connect the Salesforce CLI to the Dev Hub org (so we can later package our app)
      1. In VS Code, click on No Default Org Set on the bottom toolbar, which will open the Command Palette
      2. In the Command Palette, click on SFDX: Authorize a Dev Hub
      3. 
      4. This will open a new tab in your browser with a Salesforce login screen
      5. 1. Note: these instructions are written for a live workshop where I set up the orgs and everyone’s logins beforehand. If you are following along yourself, you can create your own [Dev Hub](https://developer.salesforce.com/docs/atlas.en-us.packagingGuide.meta/packagingGuide/sfdx_setup_enable_devhub.htm) and your own Commerce org (using either a [Trialforce Template and Environment Hub](https://salesforce.quip.com/q9RUACra2Jfa) or a [Demo org](https://partners.salesforce.com/pdx/s/learn/article/demo-station-for-partners-MCUTYORCVUVNCJTIVCKP6VHUKF3M?language=en_US) for the Commerce org) for free
      6. Log in with your username and password for this Dev Hub org:
         1. Username: <>.commerce-workshop-dev-hub
         2. Password: (I will give this to you in the workshop)
      7. Click Allow, which authorizes the Salesforce CLI to connect to this Dev Hub org in the context of your user login
      8. 
      9. If it asks for your phone number, click Remind Me Later
      10. 
   3. Finally, connect the Salesforce CLI to your Commerce org (where we will build our app)
      1. In VS Code, once again click on No Default Org Set on the bottom toolbar, which will open the Command Palette
      2. This time in the Command Palette, click on SFDX: Authorize an Org (not a Dev Hub)
      3. 
      4. This brings up a set of options, click Production
      5. 
      6. Next, for the org’s alias, type commerce-workshop-develop and hit Enter/Return
      7. 
      8. This will open a new tab in your browser with a Salesforce login screen
      9. 
      10. Log in with your username and password for this org:
          1. Username: <>.commerce-workshop-develop
          2. Password: (I will give this to you in the workshop)
      11. Click Agree, to authorize the Salesforce CLI to connect to this org
      12. 
      13. Notice the bottom toolbar of VS Code no longer says “No Default Org Set”, it says commerce-workshop-develop, which is the alias we gave to the Commerce org. It also shows a plug icon to indicate that Salesforce CLI is connected to default org
      14. 
   4. Congrats! The Salesforce CLI is now connected to both orgs we need: the Dev Hub (to package our app later), and the Commerce org (where we will build our app now)
2. Build the app in the Commerce org
   1. Part 1: Push code into the Commerce Org
      1. In VS Code, we will now take two Apex classes, ShippingService.cls and ShippingServiceTest.cls, that we got from cloning the Github repo and push them into the Commerce org so we can use them in the app we’re going to develop
      2. In the left pane of VS Code you should see a file directory. If you don’t see this, click on the topmost icon in the left sidebar to open it.
      3. Click on the force-app folder
      4. 
      5. From there, right-click on the classes folder, which opens a pop-up menu
      6. Click on the SFDX: Deploy Source to Org option, near the bottom
      7. 
      8. You should receive a success message pop-up window near the bottom right of your VS Code window
      9. 
      10. Now, toward the left side of the bottom toolbar, click on the below icon, which resembles a mini browser window. This opens the Commerce org in your browser. Notice you don’t have to log in again!
      11. 
   2. Part 2: Configure a Sample Order Management ISV App
      1. Overview: Since our use case is a Shipping Calculation ISV App, we will clone and modify one of Order Management’s out-of-the-box flows, a reshipment flow, to leverage our ISV app’s functionality
      2. In the Commerce org, click the cog wheel toward the top right of your screen and click Setup.
      3. 
      4. Type “Flow” in the quick find search near the top left of the Setup menu, and click Flows.
      5. 
      6. Find and click on the Flow named Create Reship Order to open it
      7. 
      8. Click Save As
      9. 
      10. In the popup window, click A New Flow
      11. For Flow Label, type Create Reship Order Clone. The API name will be auto-populated to Create_Reship_Order_Clone
      12. Click Save
      13. 
      14. Now in your newly cloned flow, drag the screen to the right on the flow canvas (the big area on the right side), and look for the blue Screen element titled Location Selection
      15. 
      16. From the Flow Toolbox (the panel on the left side of the screen), drag an Action element onto the canvas, to the right of the Location Selection element
      17. 
      18. In the pop-up that opens, for the Category on the left side, click Commerce
      19. Then in the Action box on the right, select Calculate Shipping Price, which is an invocable Apex method in the Apex class we pushed into the org earlier.
      20. Name the element Calculate Shipping Price.
      21. 
      22. For the Label, type Calculate Shipping Price and click Done
      23. 1. The use case is a bit contrived- we are adding a shipping calculation to a re-ship request flow. Usually a re-ship request happens because a customer’s original shipment was lost or damaged and many companies will not charge any money to re-ship, to provide good customer service. This use case educational only, and is not business advice on whether to charge customers for shipping or not.
      24. So that we can easily see the results of this Apex action, drag a Screen element from the Flow Toolbox on the left into the canvas to the right of our new Apex action
      25. 
      26. First, give the Screen element a label on the right side of the pop-up: Shipping Price Confirmation Screen
      27. 
      28. Then, from the left side of the pop-up, drag a Display Text component onto the screen in the center, and then click on it
      29. On the right side, give this Display Text an API name such as ShippingConfirmation
      30. Below that, paste the text: The price to reship will be £{!Calculate_Shipping_Price} or alternatively, type it and click the box that says Insert a resource... and type calc to locate the variable holding the output of our invocable apex and then click on it
      31. Click Done to save the screen
      32. 1. This is an important concept to understand. If you use Apex inside of a Flow, the output of the Apex is automatically stored as a variable and can be referenced later, used in calculations, decisions, business logic, etc.
      33. Change the connections between the elements on the flow canvas:
          1. Click the connector between the Location Selection and Set Stage To Part 4 elements and hit the Delete key
          2. 
          3. Click the white dot at the bottom of the Location Selection element and drag it onto the Calculate Shipping Price element.
          4. Do the same to connect Calculate Shipping Price to Shipping Price Confirmation Screen
          5. Lastly, connect Shipping Price Confirmation Screen to Set Stage To Part 4
          6. 
      34. Save the Flow and then click Activate
      35. 
      36. One last step to surface our new Flow! From Setup, start typing Actions & Recommendations in the quick search box in the top left and click on Actions & Recommendations
      37. On the row that says Summer ’22 Flow Package, click on the dropdown arrow on the far right, then click Edit
      38. 
      39. In the popup window, click Next, then Next again
      40. 
      41. 
      42. Now click the Default tab toward the top left
      43. In the search box that appears, search your new flow, Create Reship Order Clone, and drag it into the list on the right
      44. Click Next again
      45. 
      46. Again search your new flow, Create Reship Order Clone, and check the checkbox on the left of it
      47. 
      48. Click Save
      49. Now it is time to see your flow in action! From the App Launcher (the 9 dots in a square in the top left), type and select Order Management
      50. Search 00001301 and click on the matching Order Summary Record
      51. You should see a screen like this:
      52. 
      53. Look for your Create Reship Order Clone flow in the Actions & Recommendations section. If you don’t see it, click on the blue Add button and then start typing Create Reship Order Clone and then click on it
      54. 
      55. Work your way through the flow until you see our new the screen we added, which shows that our invocable apex method was successfully called by our flow and returned an amount for the shipping price
      56. 
      57. We have successfully finished development on an ISV app for Salesforce Order Management!
      58. Next Steps on your own for further learning:
      59. The Commerce orgs (which you get to keep until they expire) have a more realistic sample implementation of our Shipping app in the Apex class B2BDeliverySample (go to Setup >> Apex Classes to find this in your org), feel free to save the code for reference.
   3. Part 3: Configure a Sample B2B Commerce ISV App
      1. In the org, click the cog wheel toward the top right of your screen and click Setup.
      2. 
      3. Type “Flow” in the quick find search near the top left of the Setup menu, and click Flows.
      4. 
      5. Scroll to find and click on the checkout flow that is currently in use, Checkout Flow Template to open it
      6. 
      7. Click Save As
      8. 
      9. For Flow Label, type Checkout Flow Template Clone. The API name will be auto-populated to Checkout_Flow_Template_Clone.
      10. Click Save
      11. 
      12. Now in your newly cloned flow, drag the screen downward on the flow canvas (the big area on the right side), and find the step that calculates Shipping Cost, and notice that it is a subflow
          1. Subflows are a way to modularize business logic, similar to helper or utility methods in code
          2. 
      13. We will replace this step with a method from our Apex class that we deployed to this org earlier. To keep things simple, we will not use a subflow here.
          1. The use case is, we are swapping out the out-of-the box way that B2B Commerce calculates shipping costs, and replacing it with our Apex class that would normally call out to our off-platform, third party ISV app to perform complex shipping calculations based on inputs such as an array of items and their sizes, weights, quantities, shipping methods, distance needed to deliver, etc. For this workshop we are simply mocking the callout and returning a static currency amount.
      14. From the Flow Toolbox panel on the left side, drag an Action element on to the canvas near the Shipping Cost subflow icon
      15. 
      16. In the pop-up that opens, for the Category on the left side, click Commerce
      17. Then in the Action box on the right, select Calculate Shipping Price, which is an invocable Apex method in the Apex class we pushed into the org earlier.
      18. 
      19. Name the element Calculate Shipping Price and click Done
      20. 
      21. Click on the Shipping Cost subflow element and hit the Delete key
      22. 
      23. Notice the arrows that were connected to the Shipping Cost element disappear too
      24. We will need to re-create those arrows to connect our new Calculate Shipping Price element to the correct existing Flow elements to form a smooth end-to-end Flow
          1. Drag from the white circle at the bottom of the Main Decision Hub element onto the Calculate Shipping Price element and release
             1. If you need to, zoom out by clicking the “-” icon in the bottom left of the flow canvas
          2. 
          3. In the popup window that appears, make sure Shipping Cost is selected and click Done
          4. 
          5. Next, drag from the white circle at the bottom of the Calculate Shipping Price element onto the Assignment Loop element and release
          6. 
          7. We are done with the Flow. Here is what it should look like:
          8. 
      25. Again, this Apex would normally be used to call out to an ISV app. For demo purposes, we are returning a static value to mock this callout
          1. Let’s quickly look at the Apex. Notice the @invocableMethod decorator, which makes it available to use in Flow Builder
          2. 
      26. Click Save in the top right corner to save the Flow
      27. Click Activate
      28. 
      29. Go into Setup, type All Sites in the quick search, and click All Sites
      30. Click on Builder next to the AlpineB2B site
      31. 
      32. In Experience Builder, click Home in the top toolbar on the left, then click on Checkout
      33. 
      34. Click on the Checkout Flow component to bring up a floating panel on the right. In this panel, select your new Flow, Checkout Flow Template Clone so that it will run the newly cloned flow instead of the original checkout flow demoed earlier
      35. In the top right of Experience Builder, click Publish, the Publish again so that your changes can be seen in the Site
      36. 
      37. 
      38. SKIP for workshop Try out the new checkout flow to show the difference
          1. On your tab that still has salesforce open (not the B2B Site), click the app launcher and type Contacts, and click Contacts
          2. 
          3. Search for Bonnie Buyer and click into this record
          4. 
          5. Click on the dropdown arrow in the actions area near the top right of the screen, and click on Log in to Experience as User
          6. 1. Note: if you don’t see this button appearing, click the cog wheel near the top right of the screen, click **Edit Page**, click the top right area with these action buttons, then click **Add Action** near the bottom right, add the **Log in to Experience as User** action to the list, and click **Done**. Click **Save** and then click **Activation** to make sure the page is assigned as the Org Default, then return to the page by clicking the left arrow in the top left of the edit screen
          7. Add one of the products to your cart, click the cart icon, and click Checkout to see our flow working
      39. The development work is complete!
3. Pull the created metadata out of the org using VS Code
   1. Note: Today we are developing in a non-scratch org due to scratch org tooling for Order Management still being worked on. If we were developing in a scratch org, all of our changes to the org’s metadata would automatically be tracked, and we could just pull changes without having to remember every piece of metadata we created or changed
   2. To retrieve our B2B Commerce flow, paste the following command into VS Code’s embedded terminal:
      1. sfdx force:source:retrieve -m Flow:Checkout_Flow_Template_Clone
         1. You should receive a confirmation message:
         2. 
      2. To retrieve the Order Management flow, paste sfdx force:source:retrieve -m Flow:Create_Reship_Order_Clone into VS Code's embedded terminal
   3. All of the functionality that we developed inside the org, along with the pre-written code we got from Github initially, is now in our local directory which can be seen in VS Code’s left pane. Next step is to package it for distribution and sale
   4. We are going to skip a few steps of development lifecycle here. Here is an opinionated view of the steps we are skipping:
      1. Normally, we would deploy the metadata into a scratch org to test whether it can be deployed successfully and that it functions as expected inside a different org (Unit tests, QA, UAT, integration test, etc.)
      2. If the above tests are successful, we would stage & commit the changes to git and push to the developer’s personal branch on the Github repo
      3. We would open a Pull Request, which would trigger a CI/CD job which would run a static code analysis, deploy the metadata into a scratch org, run all apex (and any other types of) tests, and if everything passes, notify a dev lead to do a code review
      4. A Dev Lead merges the Pull Request into, for example, a release branch
      5. Then we are ready to package the app (or just create a new package version, if it is an existing packaged app)
4. Package your app
   1. We are going to go fast here. See this terrific documentation for more context on each step we do here:
   2. Paste and enter the following commands, in order:
      1. sfdx force:package:create -n "Commerce Workshop App B2B" -r force-app -t Managed
         1. Note: you will likely get the error “The package name must be unique for the namespace”. Modify the command above to add some characters to then end of the name so that your name is unique, and run it again. Use this new name in the below steps as well.
      2. sfdx force:package:version:create —p "Commerce Workshop App B2Bv2" —w 10 -x -c -f config/project-scratch-def.json
         1. We are once again skipping steps here - Normally we would install the package (before promoting it) into a scratch org to test that we can install/upgrade successfully, and that the functionality works as expected
      3. sfdx force:package:version:promote -p "Commerce Workshop App B2B@0.1.0-1" -n
5. Submit package for Security Review & List on AppExchange
   1. At this point we are ready to connect our package to our Partner Community login so that we can submit it for Security Review and list it live on the AppExchange
      1. We will just demo this, since we don’t want to actually list this sample app on AppExchange or dirty your data
   2. Some background: typically your company receives its PBO (Partner Business Org) when the first person from the company creates a login in the Partner Community as an ISV.
      1. This person’s username and password to log in to the PBO and to the Partner Community are the same
      2. We strongly advise ISVs to use this PBO as their Dev Hub, which means it will own all 2GPs (second-generation packages)
   3. To connect your package to your Partner Community login:
      1. Log in to the Partner Community
      2. 
      3. 
      4. 
      5. Click on the Publishing tab
      6. 
      7. then click on the Organizations subtab
      8. 
      9. If you don’t see your Dev Hub org, click the Connect Org button and log in to it
      10. 
      11. Now go to the Packages subtab and you should see your package
      12. 
   4. Notice there are options here to Start Review and Create Listing. These can be done in parallel. Security Review takes time, so in the meantime you can design and optimize how you want your future AppExchange Listing to look
      1. Security Review goes a lot smoother if you understand what best practices it will check for before you start developing a real ISV application
      2. Here is how to prepare for and submit for Security Review, and a requirements checklist to help you ace your review. Please read this carefully, as Security Review can cause major go-live delays if we have to have many cycles of submitting, rejection, and resubmitting
   5. Once you are notified that your app has passed Security Review, you can go to the Listings subtab and click the Publish Listing button to make your app live on the AppExchange for customers to find!
   6. 
   7. Congratulations, your live AppExchange listing will now start generating leads!