Sitecore XC stores entities in SQL server in a JSON format. It is possible to query the data that is stored in JSON, but it is a little more difficult and there really is nothing in the XC framework that helps you.
The reason there is no support for flexible querying is that XC gives you the option to index entities in SOLR which gives you really flexible querying.

In XC 10 there are a number of entities that are indexed out-of-the-box:

• Catalog items (Category, Sellable Item, Catalog)
• Orders
• Customer
• Price Cards
• Promotions

The catalog items, orders and customer indexes are mainly there to facilitate searching from the Business tools. The price cards and promotions indexes are used by the business tools as well, but also play a major part in the operations of the Shops role: they are used to get the latest prices and promotions, so you need to make sure these are always up to date, otherwise your promotion or price card will not be applied.

But what if you want to index another identity for instance the gift card entity. What do you need to do to make gift cards searchable?

In this article I will go into the different steps and will find out it is surprisingly easy to do.

Note that this article is specifically about SOLR.

You can find the accompanying repository here: https://github.com/ewerkman/indexed-giftcard

Step 1: Create a new core in SOLR

Note: this might not be the best way to create new SOLR cores. Ask someone that actually knows about SOLR for advice :-).

Every index in XC 10 uses two cores, one active one and one for rebuilding the index. For your new index:

1. Create two new cores in SOLR by copying them from an existing core, for instance the OrdersScope and OrdersScope-Rebuild folders. Copy them to GiftcardsScope and GiftcardsScope-Rebuild respectively.
2. Delete all files from the data folder in the GiftcardsScope and GiftcardsScope-Rebuild folders. When you do a full index, this folder will be filled again with the correct data.
3. Change the name of the cores by editing the core.properties file in both core. Open core.properties and change name to GiftcardsScope and GiftcardsScope-Rebuild respectively.
4. In each core, the conf folder contains the configuration of the core. A file called managed-schema contains the schema for the new core. You need to take out some of the fields that are specific to the index you copied the configuration from and replace them with fields specific for the gift card index.
   The GitHub repository contains the file that you should end up with for my example:
   https://github.com/ewerkman/indexed-giftcard/blob/main/solr/managed-schema.

The most important part there is this section:

    <!-- CommerceEngine Order Unique Id Field -->
    <field name="entityuniqueid" type="string" indexed="true" stored="true" required="true" />
    <field name="entityid" type="string" indexed="true" stored="true" required="true" />
    <field name="entityversion" type="pint" indexed="true" stored="true" />
    
    <!-- CommerceEngine Order -->
    <field name="giftcardcode" type="string" indexed="true" stored="true" />
    <field name="activationdate" type="pdate" indexed="true" stored="true" />
    <field name="balance" type="pfloat" indexed="true" stored="true" />
    <field name="originalamount" type="pfloat" indexed="true" stored="true" />
    <field name="artifactstoreid" type="string" indexed="true" stored="true" />
    <field name="datecreated" type="pdate" indexed="true" stored="true" />
    <field name="dateupdated" type="pdate" indexed="true" stored="true" />

Here the fields specific to the gift card index are defined such as giftcardcode and balance. You want this index to contain all the fields you want to query on.

5. You can now restart SOLR and your new cores should be visible in the admin interface.

Step 2: Configure the new index

Next you need to configure the new index in XC. You can find all of the necessary configuration in this file:

https://github.com/ewerkman/indexed-giftcard/blob/main/policies/Plugin.Giftcard.PolicySet.json

There are 3 things you need to configure:

FullIndexMinion

This is the minion responsible for doing a full index. You configure it by:

• specifying the Sitecore.Commerce.Plugin.Search.FullIndexMinion as the minion to run;
• configuring the GiftCards list as the list to watch for indexing;
• configuring Sitecore.Commerce.Plugin.GiftCards.GiftCard as the entity to index;

Note that the full index minion is not configured to run on a set interval. You only run it if necessary, for instance by using Postman to start the minion.

IncrementalIndexMinion

The incremental index minion is run on a schedule (by default, every 5 minutes) and watches the GiftcardsIndex list. If something changes on a GiftCard it is automatically added to the specified list. The incremental index minion goes through this list and updates the index.

SearchScopePolicy

The SearchScopePolicy configures the index:

 {
    "$type": "Sitecore.Commerce.Plugin.Search.SearchScopePolicy, Sitecore.Commerce.Plugin.Search",
    "Name": "GiftcardsScope",
    "CurrentIndexName": "GiftcardsScope",
    "SwitchOnRebuild": true,
    "SwitchOnRebuildReset": false,
    "SwitchOnRebuildClearPreviousIndex": true,
    "SwitchOnRebuildPrimaryIndexName": "GiftcardsScope",
    "SwitchOnRebuildSecondaryIndexName": "GiftcardsScope-Rebuild",
    "IncrementalListName": "GiftcardsIndex",
    "DeletedListName": "DeletedGiftcardsIndex",
    "FullListNames": [
        "Giftcards"
    ],
    "EntityTypeNames": {
        "$type": "System.Collections.Generic.List`1[[System.String, mscorlib]], mscorlib",
        "$values": [
            "Sitecore.Commerce.Plugin.GiftCards.GiftCard"
        ]
    },
    "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": "GiftcardTable"
            }
        ]
    }
}

Here you specify which cores to use, if you want to do a switch-on-rebuild, which list to use for the incremental index and which one for deleted entities etc.

IndexablePolicy

In the IndexablePolicy you configure which properties are indexed.

Step 3: Create a block to turn an entity into a document

The last step is to create a block that you add to the IFullIndexMinionPipeline and IIncrementalIndexMinionPipeline to create the SOLR document based on a GiftCard entity.
You can find the code for this block here: InitializeGiftcardsIndexingViewBlock.cs

This block takes a list of GiftCard entities and for each gift card it adds the properties to be indexed to an EntityView.

How do I query the index?

The repository contains a sample command that show how you can query the index:

// Filter order on activation date
var filterQuery = new FilterQuery(new AndFilterNode(new LessThanFilterNode(
        new FieldNameFilterNode("activationdate"),
        new FieldValueFilterNode(endDate
                .ToString(SearchConstants.DateTimeSearchFormat, CultureInfo.InvariantCulture),
            FilterNodeValueType.Date)),
    new GreaterThanFilterNode(new FieldNameFilterNode("activationdate"),
        new FieldValueFilterNode(
            startDate
                .ToString(SearchConstants.DateTimeSearchFormat, CultureInfo.InvariantCulture),
            FilterNodeValueType.Date))));

var scope = SearchScopePolicy.GetPolicyByType(commerceContext, commerceContext.Environment,
    typeof(GiftCard));

var searchResults = await _commander.Command<SearchEntitiesCommand>()
    .Process<GiftCard>(commerceContext, scope.Name, new SearchQuery(), filterQuery)
    .ConfigureAwait(false);

It's easy: create a query, get the relevant scope you want to query and search for entities. This will automatically give you a list of entities.

In Summary

Creating an index for entities gives you much more flexibility in querying.

I keep forgetting the location of the item you need to change the link of the Business Tools button in Launchpad, so this post is mostly a reminder for myself but I hope others will also benefit.

You can find it here:

/sitecore/client/Applications/Launchpad/PageSettings/Buttons/Commerce/BusinessTools

Recently I had to set up a Sitecore Commerce Minions role manually. I thought it was simple, because in the past I had already found out that you need to make sure you set the application pool to AlwaysRunning.  So I did.

Unfortunately, I found out that even though it was set to AlwaysRunning, the minions didn't start automatically. And worse, if I started the Minions role manually, it would often die after 20 minutes. So, something was wrong.

Time to dive into the SIF scripts that are used to install the commerce environment on my development machine. There I found out three things:

• On the application pool, you need to set the Start Mode to AlwaysRunning. I already knew that.
• Make sure that Regular Time Interval (minutes) in the Recycle section is set to 0. Should have known that.
• In the advanced settings of the minions website, set Preload Enabled to true. Also didn't know that.

Looking at the SIF script, this should be it, right?

Unfortunately, no. Even though my manually configured Minions settings were now exactly the same as my out-of-the-box version, it would not start automatically.

Looking for more information on how to set up application pools that are always running I found this piece of documentation on the Microsoft site: IIS 8.0 Application Initialization.
That page contains amongst others, the pre-requisites for application initialization:

The Application Initialization feature requires IIS 8.0 to be installed. In addition, the Application Initialization feature within the IIS "Application Development" sub-feature needs to be installed.

I checked the server I was installing the minions role on and indeed, the Application Initialization feature was not installed. After installation, the minion started up automatically.

In summary

For the minions to run automatically you have to make sure:

1. the Application Initialization feature has been installed;
2. the Start Mode of the application pool is set to AlwaysRunning;
3. in the Advanced Settings of the application pool, make sure that Regular Time Interval (minutes) in the Recycle section is set to 0 (in general, make sure there are no recycle settings set that would recycle the application pool under normal circumstance).
4. Preload Enabled is set to true in the advanced settings of the minions website.

Sitecore has great personalization features. Personalization in Sitecore is based on the content you visit and the actions you perform on the website.
You use content profiling to gain a better understanding of the interest of your visitor. You assign profile cards to your content items to indicate which "type" of user the content is interesting for.
You can use the outcome of content profiling for a particular visitor and any other information you have (like the visitor's location, contents of the cart etc.) to personalize the site.

Personalization conditions for Commerce

Out of the box, you get the following conditions in Sitecore XP when you install the Sitecore Commerce Connect Core package:

Cart conditions

• where the quantity of all products in user's cart compares to specific value
• where the user's cart total compares to specific value
• where the quantity of product product id in user's cart compares to specific value

Stock count conditions

• Current Product has stock count compares to specific stock count
• Current Product has stock count compares to specific stock count in location equals to specific location
• Product with ID specific product id has stock count compares to specific stock count
• Product with ID specific product id has stock count compares to specific stock count in location equals to specific location

Stock status conditions

• Current product has stock status equals to specific stock status
• Current product has stock status equals to specific stock status in location equals to specific location

You can add your own conditions by implementing them in the normal way as you would a Sitecore XP condition. But be aware that if you need to call the commerce engine to get information for your condition, your condition could be costly with regards to performance. So make sure the data you are working with is cached in some way.

How does content profiling work on a catalog?

Content profiling in Sitecore XP basically works by labelling your content with values that tell which audience it is interesting for (and I know I'm simplifying). For example, if you have a company website, you have different audiences: potential customers, people that are already a customer, people looking for a job at your company etc.

By labelling your content with the intendend audience you can probably determine which kind of visitor is on your site by looking at the content she visits. If she is looking at content that is labelled for potential customers the likelyhood that your visitor is a potential customer goes up. You can use that information that personalize the site, for instance by adding banners or showing content on the homepage targeted at your visitor's audience group.

You can do this with "normal" content, but you can do exactly the same with your products (as they are also content).

You "label" your content for different audiences by assigning profile cards or set profile keys on your content. To assign profile cards to a catalog item you do the same as you would do for any normal content item. You click the Edit Profile Cards button for a sellable item or category and specify a profile card. Easy.

Now you just have to do this for the hundreds, thousands or hunderds of thousands of other products you have in your catalog.

Obviously, doing this by hand doesn't scale. So, how can we scale this up?

Scaling personalization

If we want personalization to scale we need some way to automate the assignment of profile cards to catalog items.

Profile cards are saved on a sellable item or category in the ExternalSettingsComponent. The ExternalSettingsComponent is the place where all Sitecore XP related settings are saved. They are saved in a serialized JSON format.

The ExternalSettingsComponent has one property called Settings which is used to store the Sitecore XP settings serialized as JSON.

The structure of the contents of Settings is as follows:

    {
        "<sitecore node id>": { 
            "<language 1>": {
                    <language specific settings for language 1>
                },
            "<language 2>": {
                    <language specific settings for language 1>
                },
            "shared": {
                <shared settings>
            },
        "<sitecore node id>": { 
            "<language 1>": {
                    <language specific settings for language 1>
                },
            "<language 2>": {
                    <language specific settings for language 1>
                },
            "shared": {
                <shared settings>
            }
            
    }

You might be wondering why there are two sitecore nodes (represented by two sitecore node id entries)? Well you have to realize that a sellable item has a different sitecore id based on the location of the item in the category tree. So the sitecore id of sellable item A in category B is different from the same sellable item A in category C.

The unique Sitecore id for a node is generated based on the sitecore id assigned to the sellable item by the engine concatenated with the sitecore id assigned by the engine on the category (using a pipe symbol to separate them) which is then hashed using MD5.

This also means that if you set the profile card for one location of a sellable item in the category structure, you will also need to set it for any other location. This does mean that your profile card configuration can be category (so context) specific which is a good thing and gives you more flexibility.

The profile cards are not language specific so are stored in the "shared" key.

Automating setting profile cards

How can we automate setting of profile cards? We first need to know which calls the data provider does to the commerce engine to retrieve sellable items. After some investigation using Fiddler, you can see it is doing calls to https://localhost:5000/api/GetCatalogItemAllLanguages(...) (this is on XC 9.2, depending on which version you have, you may have a different call).

This call executes a 'GetCatalogItemConnectCommand', which calls the IGetSellableItemConnectPipeline to retrieve the sellable item. Notice that the commands and pipelines that have Connect in their name are there specifically for the Commerce Data Provider in Sitecore XP.

So now we know we can extend the IGetSellableItemConnectPipeline to add a block that includes logic to set the profile card information. For this proof-of-concept, we're not going to save the profile information on the sellable item but depending on your needs you could do that as well. As saving is an expensive operation, just make sure you only do this once when retrieving the item for the first time.

You can find all the code for this example in this repository: https://github.com/ewerkman/Sitecore.Commerce.Plugin.ProfileCards

This repository contains two projects:

• One (Sitecore.Commerce.Plugin.ProfileCards) for a plugin that extends the IGetSellableItemConnectPipeline with a block that parses the tracking field in the external settings component and puts the data into a nice model and then calls a custom pipeline called ISetTrackingFieldPipeline for each parent category;
• Another plugin (Sitecore.Commerce.Plugin.ProfileCards.Sample) that is a sample implementation which adds a block to ISetTrackingFieldPipeline, which sets the profile card each time the pipeline is called.

Sitecore.Commerce.Plugin.ProfileCards

This plugin is not really complicated:

• It contains ,odels so we can represent the information that is in the tracking field in the external settings component in an easier to use way.
• Defines a custom pipeline called ISetTrackingFieldPipeline;
• It extends the IGetSellableItemConnectPipeline with a block called SetTrackingFieldBlock that parses the external settings component on a sellable item, deserializes the XML in the __Tracking field using the models. It then calls the custom pipeline ISetTrackingFieldPipeline providing it with the sellable item and the tracking model. The result of that pipeline is then again serialized into the __Tracking field and set on the ExternalSettingsComponent.

Sitecore.Commerce.Plugin.ProfileCards.Sample

This is a sample plugin that shows you how to use the functionality in the Sitecore.Commerce.Plugin.ProfileCards plugin. It adds a block called SetInterestProfileCardBlock to the ISetTrackingFieldPipeline, which sets the Interest profile for any sellable item that is run through the pipeline. Of course this is a little bit basic functionality, but as you have the sellable item information available in the TrackingFieldArgument.SellableItem property you can act on the information you have there to set the correct profile information.

Conclusion

This is a sample and simple implementation, but you can imagine how you can extend this. The sample is now only for sellable items but it is possible to extend this to categories and catalogs.

One thing to consider is that while you can have different values for the profile based on the category a sellable item is in, you cannot change the profile based on any customer specific information as the information on a sellable item is cached and not specific for a user.

Happy profiling!

As you know (hopefully), Sitecore XC stores all its entities as Json-serialized strings in the database. This makes it really flexible, as any components and policies you add to an entity are just serialized and stored. And if you need to change the entity, you deserialize it and the entity is again available to you to work with.

That is until you introduce something breaking. For instance, you decide to change the name of a component. Now, any serialized instance using the old name, cannot be deserialized. Now you have a problem, because how do you fix this?

IEntityMigrationPipeline to the rescue!

Fortunately, there is a solution. The FindEntityPipeline is responsible for retrieving an entity from the database. Within that pipeline, the DeserializeEntityBlock does the deserialization of the entity. If, during deserialization, a JsonSerializationException is thrown, the IEntityMigrationPipeline is run. It takes a FindEntityArgument as its input and returns the translated entity (if possible) as its output. This is what it looks like in my version of the Commerce Engine:

The IEntityMigrationPipeline starts with the FindEntityJsonBlock. This block retrieves the entity from the database and puts the Json as a string in the SerializedEntity property of the FindEntityArgument. Any block after the FindEntityJsonBlock can be used to "fix" the Json so it can be deserialized and returned as the correct entity.

If you need an example on how to do this, the Commerce SDK contains a project called Plugin.Sample.Upgrade which contains PatchEnvironmentJsonBlock. This block patches the environment Json so that the type Sitecore.Commerce.Plugin.Customers.Cs.ProfilesSqlPolicy is changed to Plugin.Sample.Customers.CsMigration.ProfilesSqlPolicy.

In "A simple payment method" I implemented a really simple payment method. But there was one piece missing: If you created an actual order with the simple payment method you would see that the status of the payment would remain "pending". In this part, we will settle the actual payment (in a really simple way) and also implement a way to do a simple refund.

Before we do some coding, you need to know about an entity called SalesActivity:

"A SalesActivity represents an instance of a charge or credit that occurs related to an Order.
When you provide your payment information and place the order, it is often the case that the actual charge to your payment instrument doesn't occur right away. We return back the Order confirmation and process the payment asynchronously (after validating in the PendingOrders minion, that the item can actually be delivered).
This may be due to buying a backorder or preorder or some other situation (fraud alert, inventory issue, etc) which causes you to delay settling the charge. When the order is settled, a SalesActivity is generated, representing that charge.
It is also often the case where multiple SalesActivities are generated during the lifecycle of an Order. For example, if the order is split and charges are done at two different times, a SalesActivity is generated, when each Order piece is fulfilled.
It is also possible to have a negative SalesActivity. If an Order is placed and then the customer subsequently returns all of some of the items in the order, when the customer is refunded, a SalesActivity with a negative number is generated.
These can be thought of as Debits and Credits in a Ledger and represents the history of charges/credits related to a specific order. The sum of the SalesActivities should match the GrandTotal of the Order."

(Source: https://sitecore.stackexchange.com/questions/14136/xc9-sales-activity-definiton)

About a sales activity

So, how is a SalesActivity created? This is done, in the IPendingOrdersMinionPipeline. It contains a block called CreateOrderSalesActivitiesBlock which does the following for each payment method:

• It creates a SalesActivity entity;
• It sets the Amount of the sales activity to the amount paid with that payment method;
• It sets the PaymentStatus of the sales activity to Pending;
• It adds the payment component from the order
• It adds the sales activity to a list of sales activities called OrderSalesActivities;
• It adds the sales activity to the SettleSalesActivities list;

The SettleSalesActivities list is monitored by the SettleSalesActivitiesMinion. It runs every 5 minutes (of course you change that) and takes all the sales activities from the list and runs them through the ISettleSalesActivityPipeline. If you need to check whether an order has been paid, this is the place to do it. The Braintree plugin adds two blocks to this pipeline to check the payment and update the order.

The last block in the ISettleSalesActivitiesPipeline is the MoveAndPersistSalesActivityBlock. It will move the SalesActivity to a different list based on it's status:

• Pending: sales activity remains on the SettleSalesActivities list;
• Settled: sales activity moves to the SettledSalesActivities list;
• Problem: sales activity moves to the ProblemSalesActivities list;

Note that in Sitecore Commerce 9.2, the Settlement Minion has been merged into the Released minion, to overcome risk of concurrency issues between the two minions. The release notes contain more information (look for TFS No. 325520)

Settling a simple payment

For my simple payment method I added a SettleSimplePaymentBlock. It's Run method looks like this:

public override Task<SalesActivity> Run(SalesActivity arg, CommercePipelineExecutionContext context)
{
    Condition.Requires(arg).IsNotNull($"{this.Name}: The order cannot be null.");

    var salesActivity = arg;
    var knownSalesActivityStatuses = context.GetPolicy<KnownSalesActivityStatusesPolicy>();
    if (!salesActivity.HasComponent<SimplePaymentComponent>()
        || !salesActivity.PaymentStatus.Equals(knownSalesActivityStatuses.Pending, 
            StringComparison.OrdinalIgnoreCase))
    {
        return Task.FromResult(salesActivity);
    }

    var payment = salesActivity.GetComponent<SimplePaymentComponent>();

    // Perform logic to check whether the payment was settled
    var settled = PaymentHasBeenSettled();

    // Settle sales activity
    if (settled)
    {
        context.Logger.LogInformation($"{this.Name} - Payment succeeded: {payment.Id}");
        salesActivity.PaymentStatus = knownSalesActivityStatuses.Settled;
    }

    return Task.FromResult(salesActivity);
}

This code:

• First checks whether the sales activity is in the correct status (it should be pending);
• As I don't have anywhere to check whether the payment has been settled I randomly decide whether the payment has been settled or not;
• If payment has been settled, it will change the status to Settled;

The block is added to the ISettleSalesActivityPipeline:

.ConfigurePipeline<ISettleSalesActivityPipeline>(c => 
    c.Add<SettleSimplePaymentBlock>().Before<MoveAndPersistSalesActivityBlock>())

Note that the MoveAndPersistSalesActivityBlock moves the sales activity from the SettleSalesActivities list to the SettledSalesActivities list (if the status is Settled').

A simple refund

There will be situations where a customer returns all or part of an order. Sitecore Commerce has returns functionality out-of-the-box. Of course, you also need to return all or part of the payment.

Once the item has been received, the IRefundPaymentsPipeline is run, so a refund can be started. For our simple payment method we are going to add a simple refund by adding a block to this pipeline:

public async override Task<OrderPaymentsArgument> Run(OrderPaymentsArgument arg, 
    CommercePipelineExecutionContext context)
{
    Condition.Requires(arg).IsNotNull($"{this.Name} The arg can not be null");
    Condition.Requires(arg.Order).IsNotNull($"{this.Name} The order can not be null");
    Condition.Requires(arg.Payments).IsNotNull($"{this.Name} The payments can not be null");

    var order = arg.Order;
    if (!order.HasComponent<SimplePaymentComponent>())
    {
        return arg;
    }
                
    if (!order.Status.Equals(context.GetPolicy<KnownOrderStatusPolicy>().Completed, 
        StringComparison.OrdinalIgnoreCase))
    {
        var invalidOrderStateMessage = $"{this.Name}: Expected order in '{context.GetPolicy<KnownOrderStatusPolicy>().Completed}' status but order was in '{order.Status}' status";
        await context.CommerceContext.AddMessage(
                context.GetPolicy<KnownResultCodes>().ValidationError,
                "InvalidOrderState",
                new object[] { context.GetPolicy<KnownOrderStatusPolicy>().Completed, order.Status },
                invalidOrderStateMessage);
        return null;
    }

    var existingPayment = order.GetComponent<SimplePaymentComponent>();
    var paymentToRefund = arg.Payments.FirstOrDefault(p => 
        p.Id.Equals(existingPayment.Id, StringComparison.OrdinalIgnoreCase)) as SimplePaymentComponent;
    if (paymentToRefund == null)
    {
        return arg;
    }
    
    if (existingPayment.Amount.Amount < paymentToRefund.Amount.Amount)
    {
        await context.CommerceContext.AddMessage(
            context.GetPolicy<KnownResultCodes>().Error,
            "IllegalRefundOperation",
            new object[] { order.Id, existingPayment.Id }, 
            "Order Simple Payment amount is less than refund amount");
        return null;
    }

    // Perform logic to reverse the actual payment
    
    if (existingPayment.Amount.Amount == paymentToRefund.Amount.Amount)
    {
        // Remove the existingPayment from the order since the entire amount is refunded
        order.Components.Remove(existingPayment);
    }
    else
    {
        // Reduce the existing existingPayment in the order
        existingPayment.Amount.Amount -= paymentToRefund.Amount.Amount;
    }

    await this.GenerateSalesActivity(order, existingPayment, paymentToRefund, context);

    return arg;
}

This block does the following:

• It checks whether the order has a SimplePaymentComponent. If not, the block doesn't have to do anything and just returns;
• Next, it checks whether the order is in the correct state (Completed);
• It checks if the amount to refund is equal to or smaller than the actual amount paid. If it's not, it will report an error.
• It then retrieves the existing payment, retrieves the payment to refund and then does the actual refunding. In our simple refund example, this just consists of creating a sales activity to note the refund and changing the amount of the original payment, but you can imagine in other scenarios you will order a payment provider to do a full or partial refund;

The block is added to the IRefundPaymentsPipeline:

.ConfigurePipeline<IRefundPaymentsPipeline>(c => 
    c.Add<RefundSimplePaymentBlock>().Before<PersistOrderBlock>())

A simple conclusion

This blog post and the previous one show you how to create a new payment method in Sitecore Commerce. Admittedly, it's a really simple one and your own implementations will probably be more complicated if you have to talk to a payment provider, but I hope these two blog posts give you the basis to successfully implement your own!

You can find the source code of this blog post on GitHub: https://github.com/ewerkman/Commerce.SimplePayment

Sitecore Commerce comes with two payment methods out of the box: Federated Payment using Braintree as the payment provider and a gift card payment method. During development you often have a need for a payment method for which you don't need to enter any information and that just allows you to save the cart as an order. In this post I'm going to create the simplest payment method I could create that can be processed by the commerce engine. Note that this doesn't involve any third parties so there are no connections to payment providers, just adding a payment method to a cart so you can save it as an order.

You can find all the code on Github: https://github.com/ewerkman/Commerce.SimplePayment

Adding a payment method to the Sitecore Commerce Control panel

In Sitecore Commerce Control Panel, go to: Sitecore > Commerce > Commerce Control Panel > Shared Settings > Payment Options and add a new payment option called Simple. Note the Item ID of the newly created item, you're going to need it later.

Next go to your Storefront settings (Sitecore > Commerce > Commerce Control Panel > Storefront Settings > Storefronts > Your storefront > Payment Configuration and add the newly created payment method under Payment Options. Save it.

The engine part

Let's start with extending the engine. So how are payment methods processed by the engine?

Some things to know:

• You can add multiple payment methods to a cart. So you can add a credit card payment and a gift card payment to a cart.
• You add a payment to cart by adding a component that inherits from Sitecore.Commerce.Plugin.Payments.PaymentComponent. It has two properties you need to set: Amount and PaymentMethod. Amount is of type Money and is the amount paid for this method. PaymentMethod is an EntityReference. The PaymentMethod references the ID of the Payment Method you define in the Sitecore Commerce Control Panel.
• When you turn a cart into an order, the out-of-the-box engine takes all the payment methods, adds up all the paid amounts and checks if it is equal to the total amount of the order. If it's not, the cart is not turned into an order.

Coding

For the engine I created a new plugin. Let's go through it:

SimplePaymentComponent

The SimplePaymentComponent inherits from PaymentComponent and, because we ant to keep it simple, is an empty class.

public class SimplePaymentComponent : PaymentComponent
{
}

CommandsController

A CommandsController class that inherits from CommerceController and contains one method called AddSimplePayment that takes a cart and a payment as it's input.

[HttpPut]
[Route("AddSimplePayment()")]
public async Task<IActionResult> AddSimplePayment([FromBody] ODataActionParameters value)
{
    if (!this.ModelState.IsValid || value == null)
    {
        return (IActionResult)new BadRequestObjectResult(this.ModelState);
    }

    if (!value.ContainsKey("cartId") || 
        (string.IsNullOrEmpty(value["cartId"]?.ToString()) || 
        !value.ContainsKey("payment")) || 
        string.IsNullOrEmpty(value["payment"]?.ToString()))
    {
        return (IActionResult)new BadRequestObjectResult((object)value);
    }

    string cartId = value["cartId"].ToString();

    var paymentComponent = JsonConvert.DeserializeObject<SimplePaymentComponent>(value["payment"].ToString());
    var command = this.Command<AddPaymentsCommand>();
    await command.Process(this.CurrentContext, cartId, new List<PaymentComponent> { paymentComponent });

    return new ObjectResult(command);
}

This method:

• does some checking of it's input;
• retrieves the cart id;
• deserializes the payment part of it's input to a SimplePaymentComponent instance;
• executes the AddPaymentsCommmand to add the payments to the cart;

Configuration

Lastly, we need to configure the OData model by implementing a ConfigureServiceApiBlock.

public override Task<ODataConventionModelBuilder> Run(ODataConventionModelBuilder modelBuilder, CommercePipelineExecutionContext context)
{
    Condition.Requires(modelBuilder).IsNotNull($"{this.Name}: The argument cannot be null.");

    modelBuilder.AddEntityType(typeof(SimplePaymentComponent));

    ActionConfiguration addSimplePaymentConfiguration = modelBuilder.Action("AddSimplePayment");
    addSimplePaymentConfiguration.Parameter<string>("cartId");
    addSimplePaymentConfiguration.Parameter<SimplePaymentComponent>("payment");
    addSimplePaymentConfiguration.ReturnsFromEntitySet<CommerceCommand>("Commands");

    return Task.FromResult(modelBuilder);
}

And we implement ConfigureSitecore to add this pipeline block to the ConfigureServiceApiPipeline:

public class ConfigureSitecore : IConfigureSitecore
{
    public void ConfigureServices(IServiceCollection services)
    {
        var assembly = Assembly.GetExecutingAssembly();
        services.RegisterAllPipelineBlocks(assembly);

        services.Sitecore().Pipelines(config => config
            .ConfigurePipeline<IConfigureServiceApiPipeline>(configure => 
            configure.Add<ConfigureServiceApiBlock>())
            );

        services.RegisterAllCommands(assembly);
    }
}

The website part

In the website part we create the code to integrate our new payment method into Commerce Connect. Let's start by creating the code to add a payment to the cart. This involves creating an instance of a class that inherits from PaymentInfo and creating a request to add it to the cart:

var simplePaymentInfo = new SimplePaymentInfo();
simplePaymentInfo.PaymentMethodID = "D652AC0F-C832-450B-BBDD-2CBBDA95E3CC"; 
simplePaymentInfo.Amount = cart.Total.Amount;
simplePaymentInfo.PartyID = billingAddress.ExternalId;

var payments = new List<PaymentInfo>();
payments.Add(simplePaymentInfo);

var addPaymentInfoRequest = new AddPaymentInfoRequest(cart, payments);
var addPaymentInfoResult = cartServiceProvider.AddPaymentInfo(addPaymentInfoRequest);

What does SimplePaymentInfo look like? Again, it's a simple class:

using Sitecore.Commerce.Entities.Carts;

namespace Web.SimplePayment.Entities
{
    public class SimplePaymentInfo : PaymentInfo
    {
        public decimal Amount { get; set; }
    }
}

If you run this code, you will see that you get an error when executing the cartServiceProvider.AddPaymentInfo(addPaymentInfoRequest); code and the error indicates that SimplePaymentInfo is an unsupported payment type.

So, what happens under the covers is that Sitecore Commerce Connect executes the commerce.carts.addPaymentInfo pipeline (in Sitecore XP). Out of the box this pipeline consists of one processor: Sitecore.Commerce.Engine.Connect.Pipelines.Carts.AddPaymentInfoToCart.

If you take sneak dotPeek at the code for this processor, you will notice it only supports two payment methods: Federated and Giftcard. It even goes so far to declare an error if you added a different payment method.

We can handle our own payment method by adding a processor to this pipeline and handling any payment that is of type SimplePaymentInfo.

The code for the processor that handles adding a simple payment method to the cart looks like this:

public class AddSimplePaymentToCart
{
    public void Process(ServicePipelineArgs args)
    {
        AddPaymentInfoRequest request;
        AddPaymentInfoResult result;

        request = args.Request as AddPaymentInfoRequest;
        result = args.Result as AddPaymentInfoResult;

        if( request.Payments.Any(p => p is SimplePaymentInfo))
        {
            var cart = request.Cart;
            var container = EngineConnectUtility.GetShopsContainer(shopName: cart.ShopName, customerId: cart.CustomerId);

            foreach (var payment in request.Payments.Where(p => p is SimplePaymentInfo).Select(p => TranslatePayment((SimplePaymentInfo) p)).ToList())
            {
                var command = Proxy.DoCommand(container.AddSimplePayment(cart.ExternalId, payment));
                result.HandleCommandMessages(command);                   
            }

            // Remove the SimplePaymentInfo payments from the list of payments, so they are not evaluated by other processors
            request.Payments = request.Payments.Where(p => !(p is SimplePaymentInfo)).ToList();
        }

    }

    private SimplePaymentComponent TranslatePayment(SimplePaymentInfo paymentInfo)
    {
        return new SimplePaymentComponent()
        {
            Id = Guid.NewGuid().ToString("N", CultureInfo.InvariantCulture),
            PaymentMethod = new EntityReference { EntityTarget = paymentInfo.PaymentMethodID },
            Amount = Money.CreateMoney(paymentInfo.Amount)
        };
    }
}

First we check if there are any payment methods of the type we can handle (SimplePaymentInfo) in the list of payment methods that is added.

if( request.Payments.Any(p => p is SimplePaymentInfo))

If there are, we loop through the payments of type SimplePaymentInfo, translate each SimplePaymentInfo to a SimplePaymentComponent that Commerce Engine understands and send it to the engine, where it will be picked up by the CommandsController we created earlier.

Finally, we remove any payment from the list of payments so it's not processed by the other pipelines.

Configuring the pipeline

We add the processor created to the commerce.carts.addPaymentInfo pipeline using the following configuration:

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <pipelines>
      <commerce.carts.addPaymentInfo>        
        <processor type="Web.SimplePayment.Pipelines.AddSimplePaymentToCart,Web.SimplePayment" 
                   patch:before="processor[@type='Sitecore.Commerce.Engine.Connect.Pipelines.Carts.AddPaymentInfoToCart, Sitecore.Commerce.Engine.Connect']" />    
     </commerce.carts.addPaymentInfo>
    </pipelines>
  </sitecore>
</configuration>

Adding the Simple payment method to your cart

You add the simple payment method to the cart using this code:

var simplePaymentInfo = new SimplePaymentInfo();
simplePaymentInfo.PaymentMethodID = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"; // Replace this with the id of the Simple payment method you added in the Commerce Control Panel. Be careful to REMOVE the { and }
simplePaymentInfo.Amount = cart.Total.Amount;
simplePaymentInfo.PartyID = billingAddress.ExternalId;

payments.Add(simplePaymentInfo);

var addPaymentInfoRequest = new AddPaymentInfoRequest(cart, payments);
var addPaymentInfoResult = cartServiceProvider.AddPaymentInfo(addPaymentInfoRequest);

The PaymentMethodID should be set to ID the payment method you created earlier in the Sitecore Commerce Control Panel. When setting the PaymentMethodID be careful not to include the { and } (I spent some time trying to figure out why my payment method wouldn't work).

Summary

This is the simplest payment method I could add. You are probably going to use a payment provider, in which case you can use the PaymentComponent to save specific information on the payment, like a transaction id etc.

(Don't forget to read the exciting next part: A Simple Payment Method - Part 2)

In the last couple of months I have wondered how I could make installing Plumber easier. I tried using a Chocolatey but thought it was too complicated, I tried Powershell and that worked but installing locally has so many variables that I was afraid it still needed customization. And both options meant there was something else to maintain.

Then I suddenly realized that you don't need to install Plumber locally (duh!): you just need to be able to access Plumber and be able to change the configuration of Plumber. Because Plumber is a single page application that talks directly to your local Sitecore Commerce Engine it completely runs in your browser.

Now, one thing needed to change and that was how you configure Plumber. Up till now you did that in a config.json file you hosted locally, but of course with a hosted version that wouldn't work.

So I added a Settings dialog to Plumber:

There you can set up the url for the Commerce Engine you want to connect to and the url for your Identity Server and change the Identity Server client id. Settings are saved in a cookie.

Now there are still two things you need to do locally:

• Configure Identity Server to allow Plumber to connect;
• Configure your Commerce Engine to allow Plumber to connect;

Because hosted Plumber is always coming from the same domain, setting that up is not difficult.

And one other advantage is that you always have the latest version of Plumber.

One disadvantage: it doesn't work with Sitecore Commerce 8.2.1 (but you should be upgrading anyway ;-))

So, now it's even easier to install and use Plumber!

You can access hosted Plumber at https://vwr.plumber-sc.com

Happy plumbing!

This post is part 3 in a 3-part series of posts on how to extend the Sitecore Commerce Business Tools. The other parts are:
The Commerce Business Tools: How does it work?
The Commerce Business Tools: How to extend it?

So, what if I want more?

Extending and adding new entity views and adding actions is nice, but what if I want to do something more exciting? What if I want to offer the user a different way to input data?

Well, now we’re coming in uncharted territories and as you know, there be dragons…

But, we’re developers and not afraid of dragons. So let’s face some dragons…

When you install Sitecore Commerce you will notice that it consists of a large number of zips. Each zip represents a part of Sitecore Commerce. You have the Commerce SDK, Identity Server, the SXA components for Storefront, two zips with images and some packages that deal with Sitecore Commerce Connect.

There are also two packages that start with Sitecore.BizFx. One of them ends with SDK. Software Development Kit.

Now, for a developer something ending with SDK sounds intriguing and exciting. Because an SDK should mean that it is something you can build upon, something you can extend.

When you install Sitecore Commerce, the zip that contains the Business Tools SDK is not used, it’s just that other zip that gets installed into an IIS site and a button is added to the dashboard so you can access them.

The zip with the SDK is not touched during installation, so it remains a bit of a mystery. If you look through the documentation there is also not too much information on what is in the zip.

But…there is a README

The SDK contains everything you need to build the Business tools yourself. If you follow the README (and you need to follow the instructions, otherwise it won’t work) you will have it all up and running in no time.

You need to:

• Unzip the SDK into a folder;
• Run:
  • npm install speak-ng-bcl-0.8.0.tgz
  • npm install speak-styling-0.9.0-r00078.tgz
  • npm install @sitecore/bizfx
• Run: npm install

Once you have done all this you do:

ng serve

Wait a little and you will have an instance running of the Business Tools. It will listen on port 4200 so don’t forget to stop the IIS site running on the same port.

The nice thing is now that you can just start changing or adding stuff and it will automatically recompile which makes developing very easy.

The business tools use Angular. Angular is an application framework, much like React or VUE that helps you create applications that run in a browser. The latest versions of Angular use Typescript instead of Javascript for developing.

I don’t know too much about Angular and I am also not a Javascript or Typescript expert. Whenever I am in a situation like this I use a highly scientific method of developing where I basically throw code at the wall and see what sticks.

The source code of the business tools look quite simple:

Every Angular application has an app folder which is where you do most of your development work.

The app folder contains a components folder. Components are an important part of Angular:

“A component controls a patch of screen called a view.”

A component is the way to display things in the browser.

The components folder in the business tools contains two subfolders: actions and views.

Let’s start with the views folder, as it contains the components to render the different views. As you may remember, when creating an EntityView you can specify a UIHint. Examples of these UIHints are TableView, ListView or FlatView.

The UIHint determines which one of these components is rendered.

The actions folder contains the components to render things like edit boxes, a date-time editor, a media picker etc. So this is the place where you will find components that deal with editing data.

This is also where we will concentrate our efforts to extend the business tools. As an example I wanted to add a component that allows you to add tags, but with a better UI than the standard tag editor.

Now of course, I am not going to create this component myself, but rather use the power of the internet to find me a prebuild component.

After some searching I found a component called Selectize.js (https://selectize.github.io/selectize.js/) which fitted what I wanted to do. You can supply a list of items that can be used in a dropdown and it allows multi-select.

If you are using a framework like Angular you cannot just add the javascript to an HTML page and expect it to work. If you want it to work you will need to provide some plumbing around it.

Luckily there is a cornucopia of packages available for Angular for all kinds of components so a little Google search brought up a Angularized version of Selectize called ng-selectize (https://www.npmjs.com/package/ng-selectize).

I followed the instructions to add the component to angular which involves:

Installing it using npm:

npm i --save ng-selectize jquery selectize

Adding references to stylesheets to the file .angular-cli.json;

"../node_modules/selectize/dist/css/selectize.css",
"../node_modules/selectize/dist/css/selectize.{your chosen theme}.css"

Adding references to scripts to that same file

"../node_modules/jquery/dist/jquery.min.js",
"../node_modules/ng-selectize/selectize/selectize.standalone.js" 

And importing the component as a module by adding the following lines to app.module.ts:

import {NgSelectizeModule} from 'ng-selectize';
imports: [..., NgSelectizeModule, ...],

Now you can add a new component. You do this with an Angular command line generator:

ng generate component selectize

In this line, selectize is the name of the component I want to generate.

This will create a folder called selectize in the apps folder and creates all the plumbing you need for the new component. It will also automatically add the component to app.module.ts so you are all set to start using your component.

A component in Angular consists of:

• A stylesheet;
• An HTML template;
• A specification file you can use for testing the component;
• A “code-behind” file that contains the logic behind the template;

Now we need some place to add the new component to the existing business tools.

Remember that the business tools are data-driven and we want our new component to display when a user edits a sellable item. We can specify how a property on a sellable item should be rendered by setting the UIType property of the ViewProperty to true.

In the commerce engine code we change the creation of the EntityView so that the UIType is set to Selectize:

targetView.Properties.Add(new ViewProperty
{
    Name = nameof(FeaturesComponent.FeatureList),
    RawValue = component.FeatureList?.ToArray<string>(),
    IsReadOnly = !isEditView,
    IsRequired = true,
    UiType = isEditView ? "Selectize" : "Tags",
    Policies = new List<Policy> { selectizeConfig },
    OriginalType = "List"
});

Note that we only use Selectize when the view is in edit mode, otherwise we use a standard way of rendering called Tags.

What did we do up till now?

• We unpacked the Business Tools SDK;
• Installed a number of npm packages;
• We have created a new component called Selectize;
• We have changed the plugin that creates the views to edit the component to use Selectize as the UIHint;

But when we go to the Business tools now, we don’t see any changes. The Features field is still rendered as a text box.

Apparently, just supplying a UIType with the name of the component, does not automatically mean it will use the component.

So, how do we render the component? For that I looked into the source code of the Business Tool and I found the answer in file with the name: sc-bizfx-actionproperty.component.html

This is a template for a component and it is used to render a property on an edit form. This component is rendered for each property that is in the view.

If you look at the code it starts with the following HTML:

<div *ngIf="property && !property.IsHidden">

  <div [formGroup]="actionForm" class="action-property-container">

    <div [ngSwitch]="property.UiType">

      <div *ngSwitchCase="'Autocomplete'">
        <label for="property-{{property.Name}}">{{property.DisplayName}}</label>
        <sc-bizfx-autocomplete [property]="property"></sc-bizfx-autocomplete>
      </div>

As you can see, the last line starts a switch statement in the Angular template which is based on the UIType property.

It then contains a case for each UIType it can render. In the example above you see how it renders a property for which the UIType is Autocomplete and it also contains a case for each type it knows how to render.

Apparently this is the place to add our new selectize component.

So what I did is add a ngSwitchCase

      <div *ngSwitchCase="'DownloadCsv'">
        <button scIconButton="secondary" id="download-action" type="button" (click)="downloadCsv()">
          <sc-icon icon="download" size="small"></sc-icon>
        </button>
      </div>

      <div *ngSwitchCase="'Selectize'">
        <app-selectize></app-selectize>
      </div>

      <div *ngSwitchDefault>

        <div [ngSwitch]="property.OriginalType">

I added my Selectize case just before the ngSwitchDefault statement. ngSwitchDefault is used when the UIType is not caught by any of the ngSwitchCase statements. It then looks at the OriginalType property to see how it should render the property.

So, I refresh the browser and see what the result is

Ok, I have a result!

Now what I want to do is show my selectize component. I change the template to use my component:

    <ng-selectize></ng-selectize>

I refresh the browser and edit the Features component and now I see this:

Victory! My new component is visible, but of course it doesn’t do anything yet.

So, how do I hook this up?

Looking at the documentation for the Selectize component I can supply a configuration object and I can supply the options the user can select from.

<ng-selectize [config]="..." [options] = "..." 
[placeholder] = "..."  {other-attributes}></ng-selectize>

So first, let’s see if we can get that to work by supplying some dummy options.

I added the following code to the component:

export class SelectizeComponent implements OnInit {

 config: any = {
   plugins: ['dropdown_direction', 'remove_button'],
   dropdownDirection: 'down',
   labelField: 'DisplayName',
   valueField: 'Name',
   searchField: ['Name'],
   maxItems: 10
 };

 options: any = [{Name:"option1", DisplayName:"Option 1"}];

 constructor() { }

 ngOnInit() {
 }
}

And changed the template to:

<ng-selectize [config]="config" [options]="options"></ng-selectize>

And this was the result:

As you can see, some result but not completely visible.

I am not a css expert, but after trying some stuff I settled on changing the template to:

<div class="form-group">
 <ng-selectize [config]="config" [options]="options"></ng-selectize>
</div>

And adding the following line to the style sheet for the component:

.form-group { height: 200px; }

Now the result looked like this:

So, now I know how to add options and to configure the selectize component to do what I want. But how can I set and get the value of the selectize component?

If you look at the other components used in the SDK, you can see that they get their input using a property attribute. The markup for the autocomplete control looks like this for example:

<sc-bizfx-autocomplete [property]="property"></sc-bizfx-autocomplete>

If you have a look at the code for the auto-complete component you will see this:

export class ScBizFxAutocompleteComponent extends ScBizFxBaseService implements OnInit, OnDestroy {
   /**
   * Defines the property to render
   */
   @Input() property: ScBizFxProperty;

The property attribute is connected to the property variable specified in the class. @Input() indicates this variable should gets its value from the property specified in the markup.

The ScBizFxProperty type is directly tied to the property we supply from the commerce engine when we create the entity view, so it gets all the information including the value and the UIType.

So I add the following line to my class:

    @Input() property: ScBizFxProperty;

That gave me the following errors when Angular tried to compile my code:

ERROR in C:/workspace/bizfx-extension/src/bizfx/src/app/selectize-2/selectize-2.component.ts (11,4): Cannot find name 'Input'.
ERROR in C:/workspace/bizfx-extension/src/bizfx/src/app/selectize-2/selectize-2.component.ts (11,22): Cannot find name 'ScBizFxProperty'.
ERROR in C:/workspace/bizfx-extension/src/bizfx/src/app/selectize-2/selectize-2.component.ts (11,4): Cannot find name 'Input'.
ERROR in C:/workspace/bizfx-extension/src/bizfx/src/app/selectize-2/selectize-2.component.ts (11,22): Cannot find name 'ScBizFxProperty'.

So, not good. I get the feeling I need to import some stuff. And sure enough after adding the following lines everything worked compiled again:

import { Component, OnInit, Input } from '@angular/core';
import { ScBizFxProperty } from '@sitecore/bizfx';

Next question: How do I get the input from the selectize component into my component. This took some experimentation as I was not sure how this should work. After some trial and a lot of error I found that if I changed my markup to look like this:

<ng-selectize [config]="config" [options]="options" [(ngModel)]='items'></ng-selectize>

And adding the following property to my class:

export class SelectizeComponent implements OnInit {
 items = [];
 @Input() property: ScBizFxProperty;

the values the user entered in the selectize component were put in the items array.

So, now I have a way to get the value into my component and away from the Selectize component. Now I need to tie it all together.

I first started to see if I could get the value out of the component. I looked again for inspiration in the SDK and found that the tags component that comes with the SDK uses something called a FormGroup to send the value back:

@Input() actionForm: FormGroup;

And it used the following code to convert the array to a string (because we cannot send back an array to the commerce engine):

``javascript
onInputBlurred(): void {
const current = [];
this.items.forEach(item => {
current.push(item.value);
});
this.actionForm.controls[this.property.Name].setValue(JSON.stringify(current));
}

So I made some changes.

First I added the actionForm input to my class:

```javascript
    @Input() actionForm: FormGroup;

FormGroup is a type you need to import so I added:

import { FormGroup } from '@angular/forms';

Then I changed the switch case for my component to this:

<div *ngSwitchCase="'Selectize'">
       <app-selectize [property]="property" [actionForm]="actionForm"></app-selectize>
     </div>

And finally I added code to turn the items array I get from the selectize component to a JSON string that the Business Tools and the commerce engine code can work with:

onInputBlurred(): void {   this.actionForm.controls[this.property.Name].setValue(JSON.stringify(this.items));
 }

So, now I can retrieve the input of the Selectize component and send it back to the Business Tools and Commerce Engine. What I still need to do is set the initial value of the Selectize component. To do that, I changed the code of my ngOnInit method to look like this:

 ngOnInit() {
   this.items = JSON.parse(this.property.Value);
 }

This takes the value property which is a stringified piece of JSON we get from the Commerce Engine and parses it back to normal JSON and sets the items array to this value.

Adding a list of options

Now we know how to edit things, but how do we add a list of options for the user to select?

One way of course would be just to hard code that list in the component. That would maybe be an option, but not a very good one. The best way to do this of course would be to have the commerce engine add a policy to the property.

I created a policy called SelectizeConfigPolicy and this policy can be used to configure the Selectize component. It is added by the commerce engine when creating the entity view.
For maximum flexibility it gets the available options from Sitecore XP, which makes it easier for users to add new options.

To retrieve these options, you have to create a pipeline with some blocks to retrieve the values.

It starts by trying to retrieve the options from the cache. If it cannot find it in the cache, the next block will retrieve it from Sitecore and the last block will put it in the cache for the next time.

This pipeline is used to retrieve the options and add them to the policy and the policy is added to the ViewProperty, which is sent to the Business Tools.

In my SelectizeComponent I need to take the policy from the property and use it to configure my component.

This code will do just that:

var availableSelectionsPolicy : any;

   availableSelectionsPolicy = this.property.Policies
           .find(p => p['@odata.type'] === '#Plugin.Sample.Notes.Policies.SelectizeConfigPolicy');
   if(availableSelectionsPolicy)
   {
     this.options = availableSelectionsPolicy.Options;
     this.placeholder = availableSelectionsPolicy.Placeholder;
   }

What can you do with all this knowledge?

• Well, the next time your customer asks you to create a management interface to update the status of an order, use your knowledge to add the specific actions your customer might need to the existing order interface.
• Your customer might want to be able to send a custom e-mail about an order and needs some way to trigger it.
• These are all things you can easily do by extending the Business Tools.

You can find the code for everything discussed in these articles on GitHub: https://github.com/ewerkman/bizfx-extension

This post is part 2 of a 3-part series of posts on how to extend the Sitecore Commerce Business Tools. The other parts are:
The Commerce Business Tools: How does it work?
The Commerce Business Tools: Creating your own Angular components

How do I extend it?

In Commerce Business Tools: how does it work? you learned how the business tools work and which pipelines are involved to customize the tools.
The next question will be: how do you extend the business tools?

Well, that depends on what you want to do.

For most scenarios you don’t need to touch the BizFx SDK because you can do it by extending the engine.

About naming stuff

• Editable in the Commerce Control Panel
• Look in the Commerce Engine Setting > Commerce Terms > Business Tools > View Names / View Action Names / View Property Names

How do I extend an existing view?

Now you know which pipelines are involved in the process and how entity views work, the next question is of course: how can I extend this?

We’ll start with the easiest way to extend the business tools and that is by adding an additional property to an existing view.

Let’s say we want the creation date and last update date of a sellable item to show in the Summary view.

At the moment this view, looks like this:

We want to add the date the sellable item was and last updated date to this view.

You might think that one way to do this is, is to create a subclass of the block that creates the view and extend this. That is certainly possible, but not the best way to do this.

Instead what we will do is create a new PipelineBlock called ExtendSellableItemDetailsViewBlock and add this to the IGetEntityViewPipeline.

public class ExtendSellableItemDetailsViewBlock : PipelineBlock<EntityView, EntityView, CommercePipelineExecutionContext>

Remember that the IGetEntityViewPipeline gets called for each view requested by the business tools, so it contains all the blocks responsible for creating all the views. Each block has to decide by itself whether it needs to add something to the requested view.

So the first thing the ExtendSellableItemDetailsViewBlock has to do is decide whether the requested view is the one it wants to add something to. It does this by checking whether the name of the requested view is Master:

Condition.Requires(entityView).IsNotNull($"{this.Name}: The argument can not be null");
var policy = context.GetPolicy<KnownCatalogViewsPolicy>();
EntityViewArgument request = context.CommerceContext.GetObject<EntityViewArgument>();

if (string.IsNullOrEmpty(request?.ViewName) || !request.ViewName.Equals(policy.Master, StringComparison.OrdinalIgnoreCase))
{
	return Task.FromResult(entityView);
}

and whether the requested entity is a sellable item:

if (!(request.Entity is SellableItem) || !string.IsNullOrEmpty(request.ForAction))
{
  return Task.FromResult(entityView);
}

If it is, it will add two properties to the view, one with the created date:

var dateCreatedProperty = new ViewProperty() { 
    DisplayName = "Date Created",
    Name = nameof(sellableItem.DateCreated),
    IsReadOnly = true,
    RawValue = sellableItem.DateCreated
};
entityView.Properties.Add(dateCreatedProperty);

and one with the last update date of the sellable item.

var dateUpdatedProperty = new ViewProperty() {
  DisplayName = "Date Updated",
  Name = nameof(sellableItem.DateUpdated),
  IsReadOnly = true,
  RawValue = sellableItem.DateUpdated
};

entityView.Properties.Add(dateUpdatedProperty);

return Task.FromResult(entityView);

Now we only need to add the new block to the IGetEntityViewPipeline after the block that creates the original summary view (GetSellableItemDetailsViewBlock). The code looks like the code below and we add it to a ConfigureSitecore class:

services.Sitecore().Pipelines(config =>
   config.ConfigurePipeline<IGetEntityViewPipeline>(c =>
      c.Add<ExtendSellableItemDetailsViewBlock>().After<GetSellableItemDetailsViewBlock>()
   ) 
);

Something to note about the GetEntityViewPipeline: At the end of GetEntityViewPipeline it calls the IFormatEntityPipeline which will do some magic. If you add your block after this pipeline, you might not see anything if you only added stuff to the RawValue property because that pipeline makes sure the Value property is filled.

After we run the Commerce Engine, the end result looks like this:

So now we have added two properties to an existing view.

Remember how you do this:

• Create a new pipeline block;
• Find the name of the view you want to extend;
• Add the properties you want to add to this view;
• Finally add the new block to the IGetEntityViewPipeline, making sure you add the block after the block that creates the view you want to extend;

You will find the code for this block here.

How do I add a new (child) view?

Adding a child view builds on what we did for adding a property to an existing view.

Let’s say you want to display the data of a component you added. It’s a component that merchandisers can use to add notes and warranty information to a sellable item.

The code for the component is simple and looks like this:

namespace Plugin.Sample.Notes.Components
{
    using Sitecore.Commerce.Core;

    public class NotesComponent : Component
    {
        public string InternalNotes { get; set; } = string.Empty;
        public string WarrantyInformation { get; set; } = string.Empty;
    }
}

We want to display the data in this component on the entity view page for a sellable item.

Again, we create a new block, this time we call it GetNotesViewBlock.

[PipelineDisplayName(nameof(GetNotesViewBlock))]
public class GetNotesViewBlock : PipelineBlock<EntityView, EntityView, CommercePipelineExecutionContext>
{
    protected ViewCommander Commander { get; set; }

    public GetNotesViewBlock(ViewCommander commander)
        : base(null)
    {
        this.Commander = commander;
    }

    public override Task<EntityView> Run(EntityView entityView, 
	CommercePipelineExecutionContext context)
    {
        Condition.Requires(entityView).IsNotNull($"{this.Name}: The argument can not be null");
	.
	.
	.

As with the previous block we created, first thing we need to do is check if the request we receive is for the entity view we want to extend. The standards views are called Master most of the time. Of course, this doesn’t give you enough information to determine whether this is the right view to extend. So the other thing you need to check is the type of the entity.

You can do this using the following code:

// Make sure that we target the correct views
if (!isMasterView && !isConnectView && !isNotesView)
{
    return Task.FromResult(entityView);
}

var request = this.Commander.CurrentEntityViewArgument(context.CommerceContext);
// Only proceed if the current entity is a sellable item
if (!(request.Entity is SellableItem))
{
   return Task.FromResult(arg);
}

We check the view name and check whether the request is for a sellable item entity.

If all conditions are met, we create a new child entity view:

 var view = new EntityView
               {
                    Name = notesViewsPolicy.Notes,
                    DisplayName = notesViewsPolicy.Notes,
                    EntityId = entityView.EntityId,
                    ItemId = variationId,
                    EntityVersion = entityView.EntityVersion
                };

  entityView.ChildViews.Add(view);

We create a new child entity view and set it’s properties, like the id of the Entity we are targeting and the version of that entity.

Then we add the newly created view to the childviews of the entity view.

Next we retrieve the NotesComponent from the Sellable item and use this to add the properties we want to display to this new view:

var component = sellableItem.GetComponent<NotesComponent>(variationId);

targetView.Properties.Add(new ViewProperty
{
    Name = nameof(NotesComponent.WarrantyInformation),
    RawValue = component.WarrantyInformation,
    IsReadOnly = !isEditView,
    IsRequired = false
});

targetView.Properties.Add(new ViewProperty
{
    Name = nameof(NotesComponent.InternalNotes),
    RawValue = component.InternalNotes,
    IsReadOnly = !isEditView,
    IsRequired = false
});

return Task.FromResult(entityView);

And don’t forget to add it to the IGetEntityViewPipeline.

services.Sitecore().Pipelines(config =>
    config.ConfigurePipeline<IGetEntityViewPipeline>(c =>
           c.Add<GetNotesViewBlock>().After<GetSellableItemDetailsViewBlock>()
    )
);

Then, restart the commerce engine and see if the new view is visible in the merchandising manager.

As you can see, the Notes view has been added displaying the notes that were added to the sellable item.

In summary, to add a new view:

• Create a new block
• Find the master view you want to extend
• Add an entity view as a child view
• Add properties to that entity view
• Add block to IGetEntityViewPipeline

You can find the code for this block here.

Discuss item links:

• EntityLink
• ItemLink
• SubItemLink

See also: http://andrewsutherland.azurewebsites.net/2018/10/02/business-tools-ui-hints-and-ui-types/

How do I create a new navigation item?

What if you want to add a whole new navigation item or dashboard, for instance because you have created your own entity and want some way to view or edit it.

Well, as with almost everything having to do with the business tools, it’s easy: add a block to a pipeline.

In this case you will have to add a block to the IBizFxNavigationPipeline.

Out-of-the-box the IBizFxNavigationPipeline looks like this:

As you can see, it contains one block for each navigation item/dashboard in the business tools. If you want to add a new dashboard, you just add a block.

The code for this block is quite simple:

public class GetCartNavigationViewBlock : PipelineBlock<EntityView, EntityView, CommercePipelineExecutionContext>
{
    protected ViewCommander Commander { get; set; }

    public GetCartNavigationViewBlock(ViewCommander commander)
        : base(null)
    {
        this.Commander = commander;
    }

    public override Task<EntityView> Run(EntityView entityView, CommercePipelineExecutionContext context)
    {
        Condition.Requires(entityView).IsNotNull($"{this.Name}: The argument can not be null");

        EntityView cartsView = new EntityView();

        cartsView.Name = context.GetPolicy<KnownCartViewsPolicy>().CartsDashboard;
        cartsView.ItemId = context.GetPolicy<KnownCartViewsPolicy>().CartsDashboard;
        cartsView.Icon = "luggagecart";
        cartsView.DisplayRank = 2;

        entityView.ChildViews.Add((Model)cartsView);

        return Task.FromResult<EntityView>(entityView);
    }
}

First you create a new entity view.

EntityView cartsView = new EntityView();

Next, you set the properties of the entity view. You can use the Icon property to specify the icon you want displayed and you can use DisplayRank to specify which position you want the new navigation item to be in.

cartsView.Name = context.GetPolicy<KnownCartViewsPolicy>().CartsDashboard;
cartsView.ItemId = context.GetPolicy<KnownCartViewsPolicy>().CartsDashboard;
cartsView.Icon = "luggagecart";
cartsView.DisplayRank = 2;

Finally you add the created view to the entity view:

entityView.ChildViews.Add((Model)cartsView);

The result of the IBizFxNavigationPipeline pipeline is an entity view with a child entity view for each dashboard.

And this is what the result looks like.

You have a new navigation item called Carts which you can then use to create views to display the carts.

You can set the icon you want to display and set the place you want to display the in.
You might ask: which icons can I use? The icons you can use are in a style sheet in a Speak package: speak/icon-fonts/dist/sitecore-icons.css

In summary, to create a new navigation item:

• Create a new block
• Add a child view to the entity view for the navigation item
• Add the block to the IBizfxNavigationPipeline

You can find the code for this block here.

How do I add a new action?

Now we know how to view things, but how do we influence that data? How do we edit a component on a sellable item, change the status of an order or create the inventory for an product.

That's where the actions come in.

Actions are added to the view as a policy, called ActionsPolicy. An ActionsPolicy contains one or more EntityActionView instances.

Actions are added to the Entity Views in the IPopulateEntityViewActionsPipeline.
It contains a block for each feature that needs to add actions to an entity view.

The IPopulateEntityViewActionsPipeline is run after the IGetEntityViewPipeline for each entity view.

To add a new action, you create a new block:

[PipelineDisplayName(nameof(PopulateCartLineItemsActionsBlock))]
public class PopulateCartLineItemsActionsBlock : PipelineBlock<EntityView, 			EntityView, CommercePipelineExecutionContext>
{
   .
   .
   .
}

As with the entity views, you only want to add an action to a specific entity view so you need to check the name of the entity view.

The code looks like this:

public override Task<EntityView> Run(EntityView entityView, CommercePipelineExecutionContext context)
{
    Condition.Requires(entityView).IsNotNull($"{this.Name}: The argument can not be null");

    var viewsPolicy = context.GetPolicy<KnownFeaturesViewsPolicy>();

    if (string.IsNullOrEmpty(entityView?.Name) || !entityView.Name.Equals(viewsPolicy.Features, StringComparison.OrdinalIgnoreCase))
    {
        return Task.FromResult(entityView);
    }

    var actionPolicy = entityView.GetPolicy<ActionsPolicy>();

    actionPolicy.Actions.Add(
      new EntityActionView
      {
          Name = context.GetPolicy<KnownFeaturesActionsPolicy>().EditFeatures,
          DisplayName = "Edit Sellable Item Features",
          Description = "Edits the sellable item Features",
          IsEnabled = true,
          EntityView = entityView.Name,
          Icon = "edit"
      });


    return Task.FromResult(entityView);
}

First you check if the supplied entity view is the one you want to add your actions to. If that is the case you retrieve the ActionsPolicy and add an EntityActionView to it. Remember to always add it and not create a new ActionsPolicy, because there might have been another block that already added an action to the view.

Looking at the properties of an EntityActionView there are some things to note:

• First, there is the Name property. You will need to act on this name later so it should be unique.
• The DisplayName and Description can be localized
• Set the RequiresConfirmation to true if you want to create an action that requires confirmation. In that case you can use the ConfirmationMessage property and ConfirmationTerms property to create a meaningful message to the user.
• EntityView is the name of an EntityView that you want to display in a modal popup when the action is executed. The IGetEntityViewPipeline is run to retrieve the properties for this entity view.
• If you don’t need confirmation and you don’t want to show a popup, set EntityView to null and set RequiresConfirmation to false.

When you run the engine this will be the result.

You have two new actions.

Executing an action will always lead to one of the following happening:

• If EntityView is empty, an action is performed by running the IDoActionPipeline;
• If RequiresConfirmation is true, a confirmation dialog is shown and if the user clicks OK, the IDoActionPipeline is run;
• If EntityView has been set, this entity view is first retrieved using the IGetEntityViewPipeline and after the user has clicked OK, the IDoActionPipeline is run;

The IDoActionPipeline is where the action is performed, for example, the changed properties of a sellable item are saved or a cart line is deleted.

The input for the IDoActionPipeline is again an EntityView object, containing the data the user entered in the dialog and the Action property set to the name of the action supplied in the EntityActionView.

The IDoActionPipeline contains a block for each action that can be performed. Again you have to check whether your block needs to do something based on information in the EntityView object.

Here is an example for a block that deletes the line in a cart:

[PipelineDisplayName(nameof(DoActionDeleteCartLineBlock))]
public class DoActionDeleteCartLineBlock : PipelineBlock<EntityView, EntityView, CommercePipelineExecutionContext>
{
    protected CommerceCommander Commander { get; set; }

    public DoActionDeleteCartLineBlock(CommerceCommander commander)
        : base(null)
    {

        this.Commander = commander;

    }

    public override async Task<EntityView> Run(EntityView entityView, CommercePipelineExecutionContext context)
    {
        Condition.Requires(entityView).IsNotNull($"{this.Name}: The argument can not be null");

        var knownCartActionsPolicy = context.GetPolicy<KnownCartActionsPolicy>();

        if (string.IsNullOrEmpty(entityView?.Action) ||
            !entityView.Action.Equals(knownCartActionsPolicy.DeleteCartLine, StringComparison.OrdinalIgnoreCase))
        {
            return entityView;
        }

        var updatedCart = await Commander.Command<RemoveCartLineCommand>().Process(context.CommerceContext, entityView.EntityId, entityView.ItemId);

        return entityView;
    }
}

The Run method first checks whether it needs to react to this request. It checks for the Action. If it is not the correct action, it just returns the EntityView.

If it can handle the request, it will execute the RemoveCartLineCommand, supplying the id of the entity and the itemid, which in this case is the id of the line to delete.

In summary, to handle an action:

• Add a block to the IPopulateEntityViewActionsPipeline to show the actions
• Add a block to the IDoActionPipeline to handle the selected action

You can find the code for these blocks here.

Create an action that requires confirmation > set requiresconfirmation on Action and don’t set EntityView
If you don’t require confirmation, don’t set an entity view name and set requiresconfirmation to false ?

How does authorization work?

The business tools give users access to potentially sensitive data, which means we want to make sure not everybody can access that data.

You have already seen that you need to log in to get access to the business tools and that Sitecore Identity Server is used to authenticate you. How does that work?

Once you have successfully logged on, Sitecore Identity Server gives a token to the business tools and this token is subsequently used to authenticate with the authoring server. This token not only validates that you are who you say you are, but it also contains your roles.

Management of users is done through the Sitecore XP User manager. This is where you assign commerce roles to users. Out-of-the-box, Sitecore Commerce has the following commerce specific roles:

• Commerce Administrator
• Commerce Business User
• Customer Service Representative
• Customer Service Representative Administrator
• Merchandiser
• Pricer
• Pricer Manager
• Promotioner
• Promotioner Manager
• Relationship Administrator

If you want to access the Business tools, you always need at least the Commerce Business User role. Also note that even the admin user needs to be assigned a Commerce role, otherwise you won’t have access.

So, how is decided what you get access to?

This is actually a two-step process and it’s all configured by policy sets. There are two policy sets that play a role here.

First there is the ControllerMethodRolesPolicySet, which enforces access to the API by checking if the user has the Commerce Business User role.

Secondly, there is the AccessByRolesPolicySet which you will find in Plugin.AccessByRoles.PolicySet-1.0.0.json.

It contains an ActionsRolesPolicy which contains a list of ActionRoleModels
An ActionRoleModel has four string properties:

• View
• Action
• EntityType
• Role

Here is an example of what an ActionRoleModel entry looks like:

If you want to limit the actions somebody can do, you always specify the view for which the actions have been defined. (So Action always requires a View)

The View property supports wildcards.

How is this enforced?

Remember that the last step in the IGetEntityViewPipeline is to run the IFormatEntityViewPipeline? The IFormatEntityViewPipeline also takes care of authorization, removing any view that you do not have access to. There are a couple of blocks that are responsible for this:

• DisableEntityActionsBlock
• ValidateViewBasedOnRolesBlock
• ValidateViewActionsBasedOnRolesBlock

If you create new roles, note that you need to add them to the Commerce Administrator role if you want your admin user to still be able to access the parts you are limiting, otherwise he doesn't have access.

This post is part of a 3-part series of posts on how to extend the Sitecore Commerce Business Tools. It contains all the contents I presented at SUGCON EU in London in April 2019 and adds some additional insights.
The other parts are:

• The Commerce Business Tools: How to extend it?
• The Commerce Business Tools: Creating your own Angular components

The Sitecore Commerce Businesss Tools represent a great way to extend Sitecore Commerce with new functionality and it is easy to do. These blog posts show you how the Business Tools work and how to extend them in different ways.

How does it work?

When I started working on the presentation for SUGCON, the first thing I was wondering was, how do the business tools actually work?

Now there is actually a fair bit of documentation on how the business tools work, but if you look for BizFx or business tools you won’t find it immediately, because it is hidden under the innocent sounding term Commerce Views Service.

There you can read the following:

“The Commerce Views plugin provides a data-driven mechanism for servicing a dynamic business experience. The views provide a mechanism for narrowing or translating data from core entity storage into a dynamic API that can be directly leveraged by the business experience.”

Now, I don’t exactly know what that means but it is full of experience and experience is always good.

But what it boils down to is that the output from the views service, drives what the user sees in the business tools.

It is what’s called a data-driven application.

The business tools is a single page application (SPA) and it is written in Angular. It gets its data from the commerce service you connect it to and normally that would be the authoring service.

When you start up the business tools for instance by going to https://localhost:4200 and you trace which calls the business tools is doing to the authoring service, you will see the following:

If you look closely you will see that these calls are actually done twice: once with the OPTIONS method to check if the call is available and once with the GET method to get the actual data.

These calls are going to the Commerce Engine Authoring role. They retrieve data that is used to drive the user interface

If you look at the data, for instance for the GetNavigationView() call, you will see the following:

If you have worked with the commerce engine before you will recognize the OData structure.

These 4 calls, lead to the following UI being displayed in your browser:

It’s easy to see which call is responsible for which part of the screen.

• The first GetNavigationView call renders the navigation in the left sidebar;
• The GetEnvironmentsView call renders the list of environments in the upper left corner;
• The GetLanguagesView call renders the list of languages;
• And finally the second GetNavigationView call renders the main navigation in the center screen;

If you look at the structure of the data for each call you will see that they all return an EntityView.

An EntityView represents “a flattened, dynamic service response focused on supporting a dynamic user experience”.

An EntityView has:

• a name
• Policies;
• Child entity views;
• Properties;
• UIHint (an indication on how the view should be rendered);

If you look at the result of GetNavigationView for instance, it consists of a main view called Navigation and 8 child entity views called:

• MerchandisingDashboard;
• InventoryDashboard;
• PricingDashboard;
• PromotionsDashboard;
• OrdersDashboard;
• CustomersDashboard;
• RelationshipsDashboard;
• ComposerDashboard;

Let’s go back to our main dashboard and let’s click on Merchandising.

If you look at the URL in the browser, you will see the url looks like this:

http://localhost:4200/entityView/MerchandisingDashboard

which basically means show the entity view called MerchandisingBoard. In Angular this is called a route and Angular will update the user interface based on the route. Note that changing the url is not doing any calls to the server, because there is nothing listening there for it.

If you have a look at the network panel to see which call the Business tools are doing, you will see the following;

This time, the GetEntityView method is called. What is interesting to know of course, is which parameters are used to call GetEntityView. For GetEntityView, the PUT method is used and the payload looks like this:

As you can see the requested view(Name) is called MerchandisingDashboard. You will also note 3 other parameters, which we’ll have a look at later.

If you look at the OData response, you will note that it returns an EntityView called MerchandisingDashboard with two child views:
Search;
Catalogs;

You will also notice the Catalogs view has two child views, both have the name Summary. Each child view contains 5 properties, which you see displayed in the table of catalogs:

• Name;
• Display Name;
• Price Book Name;
• Promotion Book Name;
• Default Inventory Set Name;

The response we get is rendered like this.

You can recognize each entity view and the properties.

Notice that the Catalogs view has two UI elements we haven’t seen before:

These two buttons are called actions. The first button lets you create a new catalog and the second can be used to delete a catalog.

Each Entity View can have a number of actions. Here they are represented as buttons, but if there are more than 3 actions for a view, they are represented as a drop down menu.

We’ll see later how you can add an action to a view.

Let’s click on the first catalog name and see what happens.

First thing you should notice is that the URL now looks like this:

http://localhost:4200/entityView/Master/1/Entity-Catalog-Habitat_Master

There’s a fair bit of information in this url:

• Master refers to the name view we want to be displayed;
• 1 indicates the version of the entity we want to see;
• Entity-Catalog-Habitat-Master is the id of the entity we want to view;

This url renders the following screen:

This screen consists of a total of 5 entity views (of which you see 3 in the image).

All elements of an entity view should by now look familiar.

Behind the scenes

So, what happens behind the scenes when the business tools do a call to the commerce engine.

If you know a little bit about the commerce engine, you will know there is one concept that is very important which are the pipelines.

Each of the javascript calls we have seen, triggers the running of a pipeline.

For instance, to create the languages view, GetLanguagesView runs the IBizFxLanguagesPipeline:

And GetNavigationView() runs the IBizFxNavigationPipeline:

And GetEntityView() runs, you can probably guess the GetEntityViewPipeline.

Now you know which pipelines are involved in the process and how entity views work, the next question is of course: how can I extend this? You can read how to extend it in the next blog post.

Plumber Configuration Viewer for Sitecore Commerce version 1.1 is out and it includes a new feature to generate a code template for pipeline blocks.

Using the new pipeline block generator

Just navigate to a pipeline in Plumber, click the location where you want to include your new custom pipeline, configure the namespace and the name of the new block and copy the code for the block and code to configure the pipeline:

What else is new?

• Upgraded to the latest version if Vue;
• Added better messages when there is something not right with your configuration;
• Made some cosmetic changes to the UI;

Installing/Upgrading

You can get the latest version on Github: https://github.com/plumber-sc/plumber-sc/releases/tag/1.1

Something to note is that the config.json file that contains your environment specific configuration has moved from the static folder to the root.

Easiest way to install is:

• Make a backup of your config.json file;
• Remove everything in the folder where you installed Plumber;
• Unzip the new version and put it's contents in the folder of the previous version of Plumber;
• When upgrading, replace the config.json that's in the new version with the backup you created.

Let me know if you like the new feature!

If you could not make it to SUGCON 2019 in London or you were at the conference but missed my talk, you can now download the full presentation including video's and text.

As mentioned in the presentation, sample code is available on GitHub

I still intend to do a write-up of the contents. I have some extra material on authentication and localization. Coming soon(ish)...