Select Server Event Notification Registration and Filters

Discussions related to SoftPro Select Server development.

Moderator: Phil Barton

Post Reply
BobRichards
Posts: 917
Joined: Wed Jan 15, 2014 3:50 pm
Location: Raleigh, NC
Contact:

Select Server Event Notification Registration and Filters

Post by BobRichards » Sun May 03, 2020 9:43 pm

Let's discuss event notifications. Select has several that can be used to alert external services, run server handlers, or provide emails when the event occurs. In this case we will use the OrderChangedEvent. This event is triggered whenever a user saves an order. Here is an example notification XML emitted by Select to a handler that has register to get them.

Code: Select all

<?xml version="1.0" encoding="utf-16"?>
<OrderChangedEvent>
    <OrderID>7ee83c9f-6c8d-ea11-9838-f4d1088d5382</OrderID>
    <OrderVersion>43</OrderVersion>
    <IsNew>false</IsNew>
    <OrderNumber>XAT20001043</OrderNumber>
    <ChangedBy>Don Duck</ChangedBy>
    <OwningProfile>Default\NC\Raleigh Branch</OwningProfile>
    <OwningProfileID>0ffd5f36-1191-4b59-88d0-37e260afe5b0</OwningProfileID>
    <SettlementType>0</SettlementType>
</OrderChangedEvent>
In this example we will be sending an email when the user saves an order so we can test this in a development environment. Below is the subscription registration XML file (i.e. "subscription.xml").

Code: Select all

<?xml version="1.0" encoding="utf-8"?>
<Subscriptions xmlns="http://schemas.softprocorp.com/select/notifications/eventing/2008/04">
    <Subscription event="C4EDBD4F-F11D-4C48-BE08-8C105181F5C9">
        <!-- Order Changed -->
        <Filter />
        <Transform />
        <Delivery>smtp</Delivery>
        <Address>receipent@email.com</Address>
        <Guaranteed>true</Guaranteed>
    </Subscription>
</Subscriptions>
Register the XML with Select Server "sps.exe" in the server folder. Change your hostname and password as required.
sps.exe subscribe /s:"http://localhost:8080" /user:"admin,pazzword" subscription.xml
Beware - if you install this on a production system, you may receive tons traffic!

Let's trim down the email to a single order Ownership profile

Consider a case where we want to receive an event notification only when users save orders with an order ownership profile matching a specific profile. We can do that by providing a filter when we create the event notification. The Filter element takes XPath arguments that allow us to do tests on the values in the notification XML and decide if it should be sent or not. The XPath specification can be difficult when creating complex scenarios, but it is not too difficult if you are simply performing a match. This filter means "Send the notification if the OwningProfile matches 'Default\NC\Raleigh Branch'".

Code: Select all

<?xml version="1.0" encoding="utf-8"?>
<Subscriptions xmlns="http://schemas.softprocorp.com/select/notifications/eventing/2008/04">
    <Subscription event="C4EDBD4F-F11D-4C48-BE08-8C105181F5C9">
        <!-- Order Changed -->
        <Filter>/OrderChangedEvent/OwningProfile[.="Default\NC\Raleigh Branch"]</Filter>
        <Transform />
        <Delivery>smtp</Delivery>
        <Address>spam@cheetahwheelies.com</Address>
        <Guaranteed>true</Guaranteed>
    </Subscription>
</Subscriptions>
I will only say this once - XPath is case sensitive. "Default" and "default" will never match with the current XPath filter. XPath does allow you to "get around" this but I can't imagine a reason you would want to do this for paths and it will be left as an exercise for the reader. XPath also supports an logical "or" concept if you need to test multiple profile paths that are unrelated.

Let's get all the orders for an office (include child profiles)

So we have a solution if we only want the order from a single order ownership profile. But what if we want that profile and all its child profiles too? XPath allows us to do that also. This filter means "Send the notification if the OwningProfile matches or starts with 'Default\NC\Raleigh Branch'".

Code: Select all

<?xml version="1.0" encoding="utf-8"?>
<Subscriptions xmlns="http://schemas.softprocorp.com/select/notifications/eventing/2008/04">
    <Subscription event="C4EDBD4F-F11D-4C48-BE08-8C105181F5C9">
        <!-- Order Changed -->
        <Filter>/OrderChangedEvent/OwningProfile[starts-with(., "Default\NC\Raleigh Branch")]</Filter>
        <Transform />
        <Delivery>smtp</Delivery>
        <Address>spam@cheetahwheelies.com</Address>
        <Guaranteed>true</Guaranteed>
    </Subscription>
</Subscriptions>
This is great! So I can do the same thing for TransactionChanged events?

No. Since this event does not have a OwningProfile XML element to test, you can't use this method directly. However, perhaps you only care about orders in a Trust Account. You can test the TrustAccountCode.

Final comments
There are many ways to express the same XPath test. I picked one that can easily be modified to support the "starts-with" function. Your mileage may vary. As always, post any problems or comments.
Bob Richards, Software Developer, SoftPro

Post Reply