Order states

Sales Order states

Sales orders goes through following states: 

• Init: This is the initial state of an order.
  • In Litium backoffice, you would normally not find orders in Init state.
  • If a order has a valid guaranteed payment, but failed to get confirmed for some reason, the order will remain in Init state.
  • Orders that are pending approval (B2B order approval flow) would also be in Init state, until they are approved.
• Confirmed: Order has a guaranteed payment.
  • The payment can be for part of the order. This condition is configured in accelerator, see below.
• Processing: Order fulfilment has started. Usually this means, the order is exported to ERP and further processed.
• Completed: Order fulfilment process is completed.
  • All deliveries are made, and payments for those deliveries are resolved.
  • If a order is cancelled (fully or partially), it will still show a "Completed" state, since the order fullfilment process has come to an end. The shipments for the cancelled order will state, that it is cancelled., and payments will have cancelled transactions.

State transition validation rules

Conditions to enter these states can be configured. If the condition fails, order will stay in its previous state.

Following example shows the condition to consider an order to be in "Confirmed" state.

using System.Linq;
using Litium.Sales;
using Litium.Validations;
using Litium.StateTransitions;

namespace Litium.Accelerator.StateTransitions
{
    public class InitToConfirmedCondition : StateTransitionValidationRule<SalesOrder>
    {
        private readonly OrderOverviewService _orderOverviewService;

        public InitToConfirmedCondition(OrderOverviewService orderOverviewService)
        {
            _orderOverviewService = orderOverviewService;
        }

        public override string FromState => Sales.OrderState.Init;

        public override string ToState => Sales.OrderState.Confirmed;

        public override ValidationResult Validate(SalesOrder entity)
        {
            var result = new ValidationResult();
            //Administrator is not allowed to Confirm orders, they are automatically confirmed when payment is done.
            // At least one payment is guaranteed. In paymentInfo, there is at least one transaction that has TransactionType = Authorize
            // and TransactionResult = success.
            var isPaymentGuaranteed = _orderOverviewService.Get(entity.SystemId)
                .PaymentOverviews.Any(x => x.Transactions.Any(t => t.TransactionType == TransactionType.Authorize
                                                                    && t.TransactionResult == TransactionResult.Success));
            if (!isPaymentGuaranteed)
            {
                result.AddError("Payment", "Payment was not guaranteed.");
            }

            return result;
        }
    }
}

StateTransitionValidationRule::FromState and StateTransitionValidationRule::ToState properties identify when the Rule evaluation is triggered. In above example, it is triggered when order goes from Init to Confirmed state.

If there are any errors added to the ValidationResult returned, it is considered as a validation failure, and the order will remain in the current state. In above example, it will remain in Init state.

Responding to state changes

To respond to state transition events, listen to the event fired when the transition take place. In following example, an order confirmation email is sent, when order enters the Confirmed state.

using Litium.Events;
using Litium.Runtime;
using System.Threading.Tasks;
using System.Threading;
using Litium.Accelerator.Services;
using Litium.Sales.Events;
using Litium.Accelerator.Mailing;

namespace Litium.Accelerator.StateTransitions
{
    [Autostart]
    public class SalesOrderEventListener : IAsyncAutostart
    {
        private readonly EventBroker _eventBroker;
        private readonly MailService _mailService;

        public SalesOrderEventListener(
            EventBroker eventBroker,
            MailService mailService)
        {
            _eventBroker = eventBroker;
            _mailService = mailService;
        }

        ValueTask IAsyncAutostart.StartAsync(CancellationToken cancellationToken)
        {
            _eventBroker.Subscribe<SalesOrderConfirmed>(x =>
            {
                _mailService.SendEmail(new OrderConfirmationEmail(x.Item.ChannelSystemId.Value, x.SystemId, x.Item.CustomerInfo.Email), false);
            });

            return ValueTask.CompletedTask;
        }
    }
}

Litium.Sales.Events namespace contains the list of events that you can listen to in Sales area.

Shipment states

Following is the main state flow of a shipment in Litium.

• When a shipment is first created, it is in the Init state.
• When a shipment is moved to Processing state, payment processing will start. During payment processing, the shipment money is calculated, and if it is needed the relevant amount is captured through payment service provider app.
• When the payments are captured for shipment, the shipment is moved to ReadyToShip state.
  • The ERP system may now handover the package to the shipping company. See process flow here >>.
• When the ERP system has notified that package is handed over, the shipment is set to Shipped state.

Note: No business logic is included in Litium 8.3 for shipment states canceled and returned, but they are now reflected in the UI and they can set via StateTransitionsService.