Considerations for an OrderCloud (commerce) project

Unfortunately this year I didn't end up making it to Symposium, which was bitterly disappointing as it would have been fantastic to also attend the MVP Summit. Though I had prepared a presentation which was accepted by the Symposium team, it was designed to be (and required to be) co-presented with a client who ended up withdrawing. So while I didn't get to present (and I may hopefully yet at a SUG in the new year), I figured I would share the content in a blog post.

Undertaking any sort of enterprise site build is generally a mammoth effort, but when you factor commerce into the mix it can quickly become exponentially more complex, and risky - since there are now direct cost implications. Fortunately I'm here to report that if you keep things reasonably simple, and understand the tools you're working with - in our case, mainly Sitecore 10.2 (headless) and OrderCloud - it's all very much achievable. In our case, the build (for release 1) was around 8 months, which I personally feel is on the quick side.

Preparation

Documentation & Architecture

The first (and in my opinion most important) thing in any project is the preparation, and that means understanding your requirements in detail, and documenting them somewhere easily available to the full team (and any other partner teams who might end up working on the project). Make sure you have very good BAs involved, and I would highly recommend a wiki, or at least something which allows users to comment so that they can ask for clarification on any points that they don't understand, and the page can be updated with further information as it becomes available.  The documentation of business requirements should be as thorough as possible from the start, so that further planning and build (see sections below) can be based on it and prevent any (potentially major, time-consuming) changes if anything is missed.  It's very easy to say "we need the ability for users to apply coupon codes" without realising the deep deep rabbit hole promotions can very quickly become, for example.

Another key first step in any project is to understand (and potentially select) the tools with which you will be working; make sure they provide the capabilities necessitated by your business requirements (documented above); and put together a solution architecture so that everyone knows and understands how the information is flowing.  In our case, like most commerce builds, they key tools involved were:

• Identity provider
• PIM (source of truth for product info)
• CMS (or DXP if you want to be fancy)
• Middleware (optional)
• Payment gateway
• Order management
• Downstream systems such as invoicing or analytics

In our case it was a bit of a rebuild, so the identity provider, PIM, and downstream systems were already in place; Sitecore 10.2 was already in use, so would also be used to enhance the product info; OrderCloud was selected for order management; and the client chose to go with a BFF (backend-for-frontend) pattern (using .NET 8) to support the frontend and extend the OrderCloud APIs.

It's worth pausing a second to reflect on the fact that there are both positives and negatives to having a BFF, particularly when you're using Next.JS for your "head" (which also provides server-side functionality). Personally (obviously heavily project-dependent) I think you can get away without one, but it can certainly come in handy.

• Positive: It can be re-used between frontends, such as websites and mobile apps
• Positive: It can be useful to have an extra layer to extend the OC APIs, merge product data with data from Sitecore, and handle exceptions
  
• Positive: It can be used to house webhook endpoints called by OC (eg. on order submission)
  
• Positive: It can be separately, and more rigorously, secured
• Negative: It requires additional server(s) and infrastructure management
• Negative: It's an extra layer, and one more thing to think about, when you already have "backend" Next.JS API endpoints available

OrderCloud

Another important consideration during preparation is around authentication, considering that OrderCloud provides SSO via OIDC.  In our case we were already using next-auth and another identity provider for other client sites, and SSO between the client sites was a requirement, so rather than rewrite all the client sites to use OC as the identity provider we opted to use OrderCloud impersonation in the BFF layer. It's great that OrderCloud provides flexibility by providing both these options.

Once you've documented your business requirements you will hopefully understand all the attributes and metadata that are associated with your products, and may recognise that you have a parent-child relationship between products. I have documented extensively the options available in OrderCloud around variants and parent-child products so I won't touch on it again here, however I'd highly recommend a read if you haven't already looked into it. Once you have a solid understand your product data I'd highly recommend creating a spreadsheet outlining: whether the data is read-only or can be modified by authors, what the expected values and lengths are, and whether the data is going to be stored in OrderCloud (ie. as Product xp data) or a separate system such as Sitecore. As you may be aware, Product xp has a max limit of 8000 characters, which may seem like a lot but can quickly and easily be used up and is not recommended for things such as rich text. My recommendation would be to use it only for data on which you will be searching / sorting / filtering products, and store the rest in Sitecore where you have almost unlimited flexibility (see build tips below on a note about sync'ing).  One key thing to note here is that if you want to give users the ability to sort products based on price, you will need to store the price in product xp data.  This is probably the biggest limitation I have come across in OrderCloud, but in our case it was easily surmountable as products had quite simple pricing, plus we had the added benefit of the BFF layer to house extra logic, so we were lucky this time. 

The final aspect of OrderCloud planning I'll touch on is the webhooks / integration events available. You should certainly familiarise yourself with the Order Checkout integration event, which is used during calculations (eg. tax), validation (eg. promotions), and of course order submission, so you probably won't be able to get away without implementing this one.  The other one which we found extremely handy is product synchronisation, which is fired whenever a product is created or modified, and can be handy to calculate and populate xp values (see paragraph above). This is fired for both parent and child products, and also when a product's price schedules are modified, so it's an extremely handy tool to have in your back pocket.

Project Planning

I'm no Project Manager, but it would be remiss of me to neglect to mention project planning in the preparation phase. Ensure you have your boards / user stories / tasks in whatever tool you use, and make sure your epics and sprints are defined, or you've at least understood the main phases of the project.  As I touched on in the foreword I would highly recommend launching an MVP (whatever that means for your project) and quickly following that up with a second release to flesh out the functionality, just to reduce complexity of the initial build, and keep timelines manageable.  

Key components of a commerce site you'll want to factor in: product listing page (PLP) including search / sorting / filtering, product details page (PDP), wishlist (optional), cart, checkout, confirmation, previous order listing, and of course all your standard web pages along with banners, carousels, rich text, and the like.

Build Considerations and Learnings

I feel at this stage (at least at the time of writing) Sitecore has gone all-in on Next.JS (before you comment: yes it seems this is likely to change in the near future), so depending on when you're reading this it's likely you've selected the Next.JS route, however it's still important to understand whether you're going SSR or SSG, what your ISR interval will be (how often are your products or content changing?), where your logic will live (Next.JS APIs?), and of course where your head is going to be hosted.

Additionally, authentication can be more complex than you expect, especially if you require SSO between other sites in the same ecosystem. As mentioned above, we went with the next-auth route (I'm keen to know what other options others may have gone with, let me know), but it's important to keep your auth and OC token in sync (if you're not authenticating through OC, at least).  Make sure users are logging out of both, anon carts potentially being deleted, and of course sessions and tokens are ending at the same time.

You may have content or products which should change or show/hide depending on your visitors' region, as we did. You can, of course, take advantage of the browser geolocation API, but if you happen to be running XP (as we were) you can also take advantage of Sitecore's geo-IP lookup - just don't forget to enable geo-IP in your Sitecore license.

If you're building a commerce site one of your primary considerations will likely be getting your products sold, so SEO should be front of mind. Of course you should aim for a fantastic pagespeed score, use the usual HTML and opengraph metadata, and have a sitemap, but also consider using microdata such as Product to enhance your page markup.  If you're migrating from a previous commerce implementation, or regularly removing products, you should also factor in setting up redirects from previous product URLs to your new product URLs, or just to PLP, as Google penalises 404 responses.

Tips and Tricks

• Get used to working with an OC token (JWT) and using impersonation - your token is your context user (with specific permissions allowed), and even in the OC Portal you are actually using impersonation and have a token
• OrderCloud xp properties are case-sensitive - OrderCloud will happily allow you to add price and Price which may not be very obvious when you go to deserialize/read it from your code
• OrderCloud allows you to move users between Buyers, however you can’t move users with “open” orders (you must ensure they are "completed")
• Make sure your BAs and developers are familiar with order of operations eg. promos are applied before tax is calculated
• If you want to read Cart data (as opposed to Order data), there is a hidden (or at least not well documented role) that you will need: UnsubmittedOrderReader
• Get used to writing a lot of loops: OC will only let you retrieve 100 items at a time
• Facet values returned in the metadata are based on the first 50 results
• Try to avoid using the .NET decimal type in xp - you might try to store 0.5m but end up seeing 0.5000001 stored in the xp
  
• Webhook secrets have a 50 character limit
• There is nothing stopping you from having a negative total, so make sure you cap your promotions
  
• For guest/anonymous users, you cannot add items to a cart once it has been submitted. You must get a fresh token and create a new cart.
• Don’t forget to assign your checkout integration event to your API client(s) otherwise you might end up wondering why it's not firing
• For product facet values: take advantage of ProductSync events to create custom xp values which correspond with the facet values you need (eg. Price Range $100-$200)
• Create publish event handler / publish webhook in Sitecore to sync data from Sitecore to OC, so that you can take advantage of in-built OrderCloud search/filtering features (if you're not using a third-party search tool)
• Always validate your payment in the backend. This can be a good opportunity to patch your payment with Accepted=true.
• Whenever you add a new cart line item, or patch the cart or a cart line item, you must call the order calculate method. Before submission you must also call order validate. Whenever you add a payment you must also (again) call order validate before you submit (ensuring that your payments with Accepted=true add up to the order total).

Testing

Performance should always be a key consideration throughout any project, and hopefully also being tested throughout, but there will likely be a specific load testing phase. Like any project, scale your servers appropriately (automatically if you can) and I would recommend notifying the OC team when you are planning to conduct your load tests so that they don't send concerned emails your way.  A key thing to note is that OrderCloud implements throttling in non-production environments (and don't publish any metrics around how throttling is implemented) and we certainly hit this during our testing. 

Depending on your code, you could implement their Throttler or just aim to reduce the requests you make to OC as much as possible. An example would be instead of using a loop in your code to GET individual products by ID, perform a single GET with ?ID=id1|id2|id3. We didn't end up needing to cache data but that is certainly an option depending on your load and the frequency with which your data changes. 

Finally, use a filter over a search where possible. Instead of ?searchOn=ID&search=id1 just use ?ID=id1. This applies to pretty much any entity.

Security is also hopefully also always front of mind by all architects and developers, but likely you will have a penetration testing phase of the project. Make sure that any security tests don't make it through to OC - ie. make sure that any user fields, query strings, or anything else that might end up in API calls to OrderCloud is sanitised. Sitecore/OrderCloud has a usage policy which prohibit testing of their services, and testing of your application may inadvertently appear as though you are testing OrderCloud.

Additional security considerations:

• Make sure you are using a secret string for your webhooks (secret) / delivery configurations (secret) / integration events (hash key) which you are validating in the backend - note that some of these fields have a 50 character limit
• You may also need to allow OrderCloud access to your webhooks through things like CloudFlare or WAFs.  If you are using CloudFlare, you may want to also additionally validate the webhook secret using a CloudFlare worker. After sending a request via email, the OrderCloud team kindly (and quickly) agreed to implement a user-agent which we found was previously causing the requests to be blocked by default WAF rules. Thanks so much guys!
• OrderCloud is PCI compliant (assuming you don't go doing something silly like storing credit card data in xp)

Release

The release for every project will likely be different, so I won't dive into too much detail. Assuming you have ensured you have your environment variables are up to date with things like OrderCloud marketplace ID, API keys, webhook URLs, and secrets, most of your focus will be on other systems such as Sitecore or your "head".  Like any release, you will hopefully have a release plan outlining the various systems and order in which they will be deployed, and OrderCloud will likely be towards the beginning as it likely does not have many - if any - dependencies.

One thing I would highly recommend is having a script to create or update the data for your environment(s), whether they be non-production or production.  This could be in the form of a Node or .NET script, or a simple Postman collection that you run.  Note that entities need to be created in a certain order (eg. catalogs before categories before products) and that when creating a new environment from scratch you may have a couple of manual steps, such as copying the API keys (which have IDs generated on creation) to impersonation configs.

After Launch

Of course, things don't end after launch! It's important to sanity check not only your visitor-facing content (and check for any broken links) but also monitor how things are running behind the scenes.

Make sure you keep a close eye on, at least:

• your server metrics, 
• your logs,
• analytics - your visitor count, and any purchase data,
• your pagespeed score, 
• your SEO ranking

It's not specific to a commerce implementation, but you should always ensure that you have sufficiently detailed logging to allow you to debug issues. Make sure you're not just logging that an error occurred, but who triggered it, what they were trying to do, and any other context which you may need to associate the debug log with an email or support ticket that customers may raise. When you're dealing with a commerce site you have the

Finally, ensure you scale your servers based on your metrics (or better yet, implement auto-scaling) to ensure you're not over-spending!

Conclusion

While undertaking an enterprise commerce site build can be a mammoth and daunting task, having a solid understanding of your requirements and tools, as well as keeping things simple for first launch, can go a long way to keeping things manageable (dare I say enjoyable?).  Sitecore has been around forever at this point, its capabilities are well known and documented, and they play very well when cooperating with OrderCloud (a relatively new player by comparison). While OrderCloud has a couple of limitations (which may affect you more than it did us) it is an easy to use, flexible, and performant solution, which should allow you to get up and running quickly and painlessly. If in doubt, reach out to Sitecore and see if you can get access to an OC Solution Engineer to assist with you on your journey.

This ended up being quite the essay, and I considered breaking this into multiple blog posts, but hopefully it's easy to skim and come back to later where required to refresh your memory. Hope you enjoyed the read and got something out of it. Good luck on your commerce journey!

Sitecore Commerce 9 - Custom Search Index

Update: The commerce team have put up a page on Creating a Custom Index which is a similar, but slightly different way of doing this

---

There are many scenarios where you might want to have a custom Solr (/Azure, though I will be focusing on Solr in this post) index on the Commerce Engine side of things - in our case we were storing a large number of a particular custom Entity in Commerce, which should be searchable by (a search box in) Sitecore.  If the search was on one particular field and/or an exact match on a field, it might have been quicker and easier to use managed lists, however in our case it was very much a search query (wildcard etc.) across a few different fields.

In the examples below I will refer to a dummy Entity called MyObject. You can replace this with the name of your custom Entity.  Obvious disclaimer: I haven't spent hours testing this code, so don't go throwing it straight into a production environment.

Solr 

core + managed-schema

Duplicate one of the existing Solr core folders (eg. OrdersScope) by taking its conf folder and copying it into a new folder called MyObjectsScope. Don't add the core to Solr yet.

In your new conf\managed-schema file swap out the specific fields for those that you want to index.  eg. in the Orders managed-schema these are the fields under the comment <!-- CommerceEngine Order -->.

In the next section below (with <copyField ... dest="_text">), in the source attributes, put each of the fields that you want to be able to search from your Sitecore (/Postman) call.  This will include the field values you've specified in each source attribute into the field called _text_ (defined a couple of sections above, in the file) which is the field that the Search endpoint searches.

Once you've finished with your config modifications, add the core to Solr.

Commerce Engine 

A quick look at the ISearchPipeline 

If you open Postman, expand the SitecoreCommerce_DevOps collection and hit the 'Get Registered Pipelines' endpoint, you can see that the search pipeline consists of the following (without any customisations):

• Sitecore.Commerce.Plugin.Search.Azure.QueryDocumentsBlock
• Sitecore.Commerce.Plugin.Search.Azure.ProcessDocumentSearchResultBlock
• Sitecore.Commerce.Plugin.Search.Solr.ParseQueryTermBlock
• Sitecore.Commerce.Plugin.Search.Solr.CreateFilterListForQueryBlock
• Sitecore.Commerce.Plugin.Search.Solr.QueryDocumentsBlock
• Sitecore.Commerce.Plugin.Search.Solr.ProcessDocumentSearchResultBlock
• Sitecore.Commerce.Plugin.Search.ProcessDocumentSearchResultBlock
• Sitecore.Commerce.Plugin.Customers.ProcessDocumentSearchResultBlock
• Sitecore.Commerce.Plugin.Orders.ProcessDocumentSearchResultBlock
• Sitecore.Commerce.Plugin.Catalog.ProcessDocumentSearchResultBlock
• Sitecore.Commerce.EntityViews.IFormatEntityViewPipeline

If you want to get the gist of how search works I'd recommend having a look at the 3 blocks in bold, which make use of the policies, fields, and parameters we will define below. The first builds and calls the Solr query, the second parses the Solr response, and the third formats the results a bit more generically.

If you want to modify any part of how the query is built, you will need to customise (swap out) the QueryDocumentsBlock (either Solr or Azure version depending on what you're using).  For example, you'll see the ...Solr.QueryDocumentsBlock calls SolrContextCommand.QueryDocuments(...) which adds the artifactstoreid filter to your Solr query (to filter results on the current store) - this may not be functionality that you want / require.

PlugIn.Search.PolicySet-1.0.0.json

In the section of type Sitecore.Commerce.Core.PolicySet at the top, in the Policies array, duplicate one of the objects and replace with your Entity name. eg:

{
  "$type": "Sitecore.Commerce.Plugin.Search.SearchViewPolicy, Sitecore.Commerce.Plugin.Search",
  "SearchScopeName": "MyObjectsScope",
  "ViewName": "MyObjectsDashboard"
},

I'm not sure if ^ this part is required (haven't tested without it), but it's probably good to have in case you add functionality to the business tools later.

Duplicate one of the SearchScopePolicy sections and rename the entities/lists so you have something like this:

{
  "$type": "Sitecore.Commerce.Plugin.Search.SearchScopePolicy, Sitecore.Commerce.Plugin.Search",
  "Name": "MyObjectsScope",
  "IncrementalListName": "MyObjectsIndex",
  "FullListName": "MyObjects",
  "DeletedListName": "DeletedMyObjectsIndex",
  "EntityTypeNames": {
    "$type": "System.Collections.Generic.List`1[[System.String, mscorlib]], mscorlib",
    "$values": [
    "Feature.MyFeature.Engine.Entities.MyObject"
    ]
  },
  "ResultDetailsTags": {
    "$type": "System.Collections.Generic.List`1[[Sitecore.Commerce.Core.Tag, Sitecore.Commerce.Core]], mscorlib",
    "$values": [{
      "$type": "Sitecore.Commerce.Core.Tag, Sitecore.Commerce.Core",
      "Name": "MyObjectsList"
    }]
  }
},

Duplicate one of the IndexablePolicy sections and rename the name and properties:

{
  "$type": "Sitecore.Commerce.Plugin.Search.IndexablePolicy, Sitecore.Commerce.Plugin.Search",
  "SearchScopeName": "MyObjectsScope",
  "Properties": {
    "EntityId": {
      "TypeName": "System.String",
      "IsKey": true,
      "IsSearchable": true,
      "IsFilterable": false,
      "IsSortable": false,
      "IsFacetable": false,
      "IsRetrievable": true
    },
    "ArtifactStoreId": {
      "TypeName": "System.String",
      "IsKey": false,
      "IsSearchable": false,
      "IsFilterable": true,
      "IsSortable": false,
      "IsFacetable": false,
      "IsRetrievable": false
    },
    "Name": {
      "TypeName": "System.String",
      "IsKey": false,
      "IsSearchable": true,
      "IsFilterable": false,
      "IsSortable": true,
      "IsFacetable": false,
      "IsRetrievable": true
    },
    "DisplayName": {
      "TypeName": "System.String",
      "IsKey": false,
      "IsSearchable": true,
      "IsFilterable": false,
      "IsSortable": true,
      "IsFacetable": false,
      "IsRetrievable": true
    },
    // ... etc. for rest of your fields
}

You will need to include ArtifactStoreId, as Sitecore will filter on this field automatically (with the ID of the current store) when generating the Solr query.  I haven't tested which fields are mandatory, but I think it's a good idea to index these 4 at a minimum.

Plugin.Habitat.CommerceMinions.json

In order to call the full / incremental index minions (or have them run automatically) to have your object indexed in Solr, you will need to create a couple of policies referencing your object.

{
  "$type": "Sitecore.Commerce.Core.MinionPolicy, Sitecore.Commerce.Core",
  "ListToWatch": "MyObjects",
  "FullyQualifiedName": "Sitecore.Commerce.Plugin.Search.FullIndexMinion, Sitecore.Commerce.Plugin.Search",
  "ItemsPerBatch": 10
},
{
  "$type": "Sitecore.Commerce.Core.MinionPolicy, Sitecore.Commerce.Core",
  "WakeupInterval": "00:03:00",
  "ListToWatch": "MyObjectsIndex",
  "FullyQualifiedName": "Sitecore.Commerce.Plugin.Search.IncrementalIndexMinion, Sitecore.Commerce.Plugin.Search",
  "ItemsPerBatch": 10,
  "SleepBetweenBatches": 500
},
{
  "$type": "Sitecore.Commerce.Core.MinionPolicy, Sitecore.Commerce.Core",
  "WakeupInterval": "00:03:00",
  "ListToWatch": "DeletedMyObjectsIndex",
  "FullyQualifiedName": "Sitecore.Commerce.Plugin.Search.DeleteIndexDocumentsMinion, Sitecore.Commerce.Plugin.Search",
  "ItemsPerBatch": 10,
  "SleepBetweenBatches": 500
}

InitializeMyObjectsIndexingViewBlock.cs

Again we can base this off an existing class (eg. Sitecore.Commerce.Plugin.Orders.InitializeOrdersIndexingViewBlock).  This block is run during the index (full or incremental depending on what you put in ConfigureSitecore.cs below) and sets the values of the properties to be indexed.

public class InitializeMyObjectsIndexingViewBlock : PipelineBlock<EntityView, EntityView, CommercePipelineExecutionContext>
{
  public override Task<EntityView> Run(EntityView arg, CommercePipelineExecutionContext context)
  {
    Condition.Requires(arg).IsNotNull(string.Format("{0}: argument cannot be null.", Name));
    SearchIndexMinionArgument indexMinionArgument = context.CommerceContext.GetObjects<SearchIndexMinionArgument>().FirstOrDefault();
    if (string.IsNullOrEmpty(indexMinionArgument?.Policy?.Name))
      return Task.FromResult(arg);
    List<CommerceEntity> entities = indexMinionArgument.Entities;
    List<Entities.MyObject> source = entities != null ? entities.OfType<Entities.MyObject>().ToList() : null;
    if (source == null || !source.Any())
      return Task.FromResult(arg);
    KnownSearchViewsPolicy searchViewNames = context.GetPolicy<KnownSearchViewsPolicy>();
    source.ForEach(myObject =>
    {
      EntityView entityView = arg.ChildViews.Cast<EntityView>().FirstOrDefault(v =>
      {
        if (v.EntityId.Equals(myObject.Id, StringComparison.OrdinalIgnoreCase))
          return v.Name.Equals(searchViewNames.Document, StringComparison.OrdinalIgnoreCase);
        return false;
      });
      if (entityView == null)
      {
        entityView = new EntityView()
        {
          Name = context.GetPolicy<KnownSearchViewsPolicy>().Document,
          EntityId = myObject.Id
        };
        arg.ChildViews.Add(entityView);
      }

      entityView.Properties.Add(new ViewProperty()
      {
        Name = "EntityId",
        RawValue = myObject.Id
      });
      entityView.Properties.Add(new ViewProperty()
      {
        Name = "ArtifactStoreId",
        RawValue = context.CommerceContext.Environment.ArtifactStoreId
      });
      entityView.Properties.Add(new ViewProperty()
      {
        Name = "Name",
        RawValue = myObject.Name
      });
      entityView.Properties.Add(new ViewProperty()
      {
        Name = "DisplayName",
        RawValue = myObject.DisplayName
      });
   
      // ... etc. for rest of the fields
   
      }
    });
    return Task.FromResult(arg);
  }
}

You can also call other pipelines, or grab Components, (pretty much do whatever you like) to set property values.  You apparently cannot set values to null (unlike computed fields in Sitecore), you will have to use an empty string.

ConfigureSitecore.cs

From (again) taking a look at how the existing blocks are added, we can add ours:

.ConfigurePipeline<IIncrementalIndexMinionPipeline>(c => c.Add<InitializeMyObjectsIndexingViewBlock>().After<InitializeIndexingViewBlock>())
.ConfigurePipeline<IFullIndexMinionPipeline>(c => c.Add<InitializeMyObjectsIndexingViewBlock>().After<InitializeIndexingViewBlock>())
// Also add this (see next section)
.ConfigurePipeline<IConfigureServiceApiPipeline>(configure => configure.Add<ConfigureServiceApiBlock>().After<Sitecore.Commerce.Plugin.Search.ConfigureServiceApiBlock>())

See the file below for an explanation for why we want to add our ConfigureServiceApiBlock after the one added by the Search plugin.

ConfigureServiceApiBlock.cs

What could we possibly need to add here? For some reason the existing implementation of the Search(...) call in the Engine (in Sitecore.Commerce.Plugin.Search.ConfigureServiceApiBlock) has omitted the "scope" parameter, so let's add it back in.  This is so that we can specify that we want to search our custom index (scope).

ActionConfiguration search = modelBuilder.Procedures.FirstOrDefault(p => p.Name == "Search") as ActionConfiguration;
if (search != null)
{
  search.Parameter("scope");
}

This code assumes the procedure has already been added by the Search plugin, which is why we need to patch our block after the Search block (the section above ^).  Note that this will add the "scope" parameter after the other parameters (ie. as the last parameter).  I'm sure you could add a bunch of extra code to swap the parameters around, but that is left as an exercise for the reader.

Test the Engine index/search endpoints

At this point you should be able to run the Run FullIndex Minion call in Postman (in the SitecoreCommerce_DevOps collection) with your scope name in the "WithListToWatch" body parameter.  After a few seconds you should see some entries in your Solr index.

You can then open the SearchApiSamples/API/Search call in Postman, change the name of the "scope" body parameter to the name of your index, and should see your indexed results towards the bottom of the response (search for "Name": "SearchResult" in the json response).

Sitecore

Sitecore.Commerce.ServiceProxy project

Make sure you update your CommerceShops endpoint, as it should now have the Search method with the scope parameter included!

MyObjectManager.cs

(Or wherever you want to search from in your code)
You can use the following code to call the Search endpoint and return a list of results:

public MyObjectsResult SearchMyObjects(string shopName, string customerId, string term = "*", string filter = "", string orderBy = "", int top = 10, int skip = 0)
{
  var myObjectsResult = new MyObjectsResult();
  try
  {
    Sitecore.Commerce.Engine.Container container = EngineConnectUtility.GetShopsContainer(shopName: shopName, customerId: customerId);
    var result = Proxy.GetValue(container.Search(term, filter, orderBy, top.ToString(), skip.ToString(), MyObjectsScope));
    myObjectsResult.Success = true;
    if (result != null && result.Models.Count > 0)
    {
      EntityView ev = result.Models.First() as EntityView;
      if (ev != null && ev.ChildViews.Count > 0)
      {
        // ev.ChildViews is the list of results
        myObjectsResult.MyObjects = ev.ChildViews.Select(cv =>
        {
          EntityView myObj = cv as EntityView;
          return new Engine.Entities.MyObject
          {
            Id = myObj.GetPropertyValue("entityid"),
            Name = myObj.GetPropertyValue("name"),
            DisplayName = myObj.GetPropertyValue("displayname"),
            // ... etc.
          };
        });
      }
    }
  }
  catch (Exception ex)
  {
    Log.Error($"Unable to search myobjects using term:'{term}', filter:'{filter}', orderBy:'{orderBy}', top:'{top}', skip:'{skip}'", ex, this);
  }
  return myObjectsResult;
}

Which is referencing an extension method I've created, to grab a property from the EntityView

public static string GetPropertyValue(this EntityView ev, string property)
{
  return ev.Properties.FirstOrDefault(p => p.Name == property)?.Value;
}

Test it out!

That's all there is to it! If you could get results from your Postman call in the Engine section above, you should now get the same results in Sitecore.

Hopefully this comes in handy for some of you out there doing Commerce work.  Let me know if you come across any issues or better ways of going about searching a Commerce index.

Big thanks to Andrew Sutherland (knower of all things Commerce) for his Commerce help. Check out his blog for lots of great Commerce posts.