Why this Fork

The purpose of this fork is to give you a jump start on setting up a local installation of Sitecore OrderCloud applications.

Besides I wanted to make it possible that for the basic features no account is needed for the various third party services the Headstart solution relies on. So you don't have to deal with costs and regional market peculiarities of third party services right from the beginning.

I hope this helps some of you to avoid some pitfalls and to get a quicker impression of the Sitecore Headstart solution.

Initial Setup - Step by Step (WIP)

Azure ressouces

In preparation for this minimal setup, you need to provide the following Azure resources. The tables below document what resource information you need for the further installation process and where you can find it.

Azure Cosmos Database

You need to configure the Cosmos DB as Core (SQL) - the database itself is created automatically by the Headstart solution.

Property	Can be found in
EndpointUri	Cosmos DB > Overview > URI
PrimaryKey	Cosmos DB > Keys > Primary Key

Storage Account

Property	Can be found in
ConnectionString	Storage Account > Access Keys
BlobPrimaryEndpoint	Storage Account > Endpoints > Primary endpoint

If you want to know a little more about what service is used for what, check out the official readme.

Middleware

This section describes how to set up a local middleware of the Headstart solution. In summary, a marketplace is created and seeded with initial data and the local middleware is set up and made known to ordercloud.io.

1. Create a new marketplace at ordercloud.io and remember the unique identifier as MarketplaceID.

   Hint: Make sure to specify "US West" as the region. Other regions are currently not supported by the Headstart solution and various errors will occur.

2. Open the Headstart solution: src/Middleware/Headstart.sln

3. Update the following settings in the appSettings.json file at the root directory of the Headstart.API:

   • OrderCloudSettings:MarketplaceID
   • StorageAccountSettings:ConnectionString
   • StorageAccountSettings:BlobPrimaryEndpoint
   • CosmosSettings:DatabaseName (Chooese any name)
   • CosmosSettings:EndpointUri
   • CosmosSettings:PrimaryKey

   For more detailed information please read this part of the official Readme.

4. Run the Headstart.API project. After the successful start, the 'Headstart Middleware API Documentation' should open in the browser at https://localhost:5001/index.html.

5. Start seeding the marketplace with a POST request to the /seed endpoint of the middleware with the following body:

   {
       "PortalUsername": "YourUsername",
       "PortalPassword": "YourPassword",
       "InitialAdminUsername": "AnyName",
       "InitialAdminPassword": "AnyPassword",
       "MiddlewareBaseUrl": "https://localhost:5001",
       "MarketplaceID": "IdOfYourMarketplace",
       "OrderCloudSettings": {
           "Environment": "sandbox",
           "WebhookHashKey": "AnyKey"
       },
       "StorageAccountSettings": {
           "ConnectionString": "YourConnectionString"	
       }
   }
   

   Note: For now it's ok to use localhost as MiddlewareBaseUrl, because it's mandatory but not used for local installations.

   For more detailed information read this part of the official documentation.

6. The successfull response contains the following settings of the preconfigured API clients of your marketplace. You will need these data in the further process.

   API Client	Configuration
   Middlware	ClientID ClientSecret
   Seller	ClientID
   Buyer	ClientID_LOCAL

7. Complete the configuration of the middleware by updating the following settings in appSettings.json:

   • OrderCloudSettings:MiddlewareClientID
   • OrderCloudSettings:MiddlewareClientSecret

8. Run/Restart the Headstart.API project.

Expose your local middleware

1. To expose your local server you can use ngrok:
   • Run ngrok authtoken XXXYourToken
   • Run ngrok http https://localhost:5001
   • Extract public ngrok url, like https://5ed8-37-201-144-21.ngrok.io
2. Afterwards you need to persist the ngrok url to the relevant integration event in ordercloud portal. That basically means you have to update the CustomImplementationUrl of the integration event with ID 'HeadStartCheckoutLOCAL' (PATCH Partially update an integration event)'.

Frontend Applications

This section describes how to set up the frontend application for buyers (the ecommerce website) and the backend application to administrate the shop (the admin interface).

Preparation

1. Open Visual Studio Code
2. Installl Angular CLI: npm install -g @angular/cli
3. Install and build the Headstart SDK
   1. Open folder src/UI/SDK
   2. Install dependencies: npm install
   3. Build the project: npm run build

Buyer Application

1. Open folder src/UI/Buyer

2. Install dependencies: npm install

3. Configure App:

   • src/assets/appConfigs/defaultbuyer-test.json:
     • clientID = Id of local Buyer API Client
     • translateBlobUrl = Enter your storage account name
   • src/environments/environment.local.ts:
     • localBuyerApiClient = Id of local Buyer API Client

4. Build the project: npm run build

5. Open http://localhost:4300/ and enjoy

For more detailed information read the official readme of buyer application.

Admin/ Seller Application

1. Open folder src/UI/Seller/src
2. Install dependencies: npm install
3. Configure App:
   • src/assets/appConfigs/defaultadmin-test.json:
     • clientID = Id of Seller API Client
     • translateBlobUrl = Enter your storage account name
     • blobStorageUrl = Enter your storage account name
4. Build the project: npm run build
5. Open http://localhost:4200/
6. Login with your seeded InitialAdminUsername and enjoy

For more detailed information read the official readme of seller application.

First steps

• If you don't have any experience with Sitecore OrderCloud, the Headstart team has made a suggestion for getting started with the Headstart application in this section of the readme
• Specifics of this solution:
  • The shipping costs are always 0, because the EasyPost connection has been disabled.
  • Each address is valid because the US address validation by SmartyStreets has been disabled.
• You find some creditcard data in this section of the official Readme.

Tips & Tricks

• If you've any issue with authorization or tokens, use jwt.io, it saves a lot of time!
• ngrok http 5001 does not work, you will get a 500 server error at checkout. This article explains why.
• In case of any error, take a closer look at the response of the previous integration event (so called Worksheet). For example, I found this error message in the middle of it:

...
"ShipEstimateResponse": {
		"ShipEstimates": null,
		"HttpStatusCode": 503,
		"UnhandledErrorBody": "ngrok gateway error\nThe server returned an invalid or incomplete HTTP response.\r\n\r\nERR_NGROK_3004\r\n",
		"xp": null
	},
    ...