Magic Software
Lesson 15Hands-on · ~25 min

Handling Approved Requests

Magic xpi's Publish & Subscribe (PSS) system lets one part of a project fire an event and any number of other flows react to it — without the publisher having to know who's listening. This lesson uses PSS to ship approved requests to delivery.

Publish and Subscribe Utilities

Think of PSS like a magazine subscription. The publisher emits an event; every subscriber that has registered for that topic is notified. The publisher doesn't track subscribers, and subscribers don't poll the publisher — the system distributes the event for you.

In Magic xpi, PSS topics are defined in the PSS Topics Repository. The PSS subsystem is shared across every Server hosting the project, so a publication in one Server can fire flows in another.

Defining the Handle Request Topic

  1. In the Solution Explorer, expand Repositories and double-click PSS Topics.
  2. Click Add.
  3. Set Topic Name to HandleRequest. The repository prefixes the name with P..
  4. Click Save.
Allowed characters. Topic names cannot contain spaces or any of # - & \ / < > { } [ ] ( ) , ; " %, and they cannot contain ???.

Subscribing the Process Request Flow

The subscribed flow does the actual work when a request is approved:

  1. Create a flow named Process Request.
  2. Open Properties » External » Subscribe Name; pick P.HandleRequest from the topic list.
  3. Add a flow variable F.RequestNum — Numeric, size 5.
Subscriber parameters. Every subscribed flow receives three context parameters automatically: a string in C.UserString, a numeric in C.UserCode, and a BLOB in C.UserBlob.

Now read the request number out of C.UserCode into your variable:

  1. Drag a Flow Data utility as the first step. Name it Get request number.
  2. Add a row: Update » Flow » F.RequestNum » expression C.UserCode.

Adding the Delivery Header

  1. Add a Data Mapper as a child of Get request number. Name it Add Delivery Header.
  2. Source: Database source Get_request_header — Requests table, CustomerID column, WHERE [Requests].RequestId = <?F.RequestNum?>.
  3. Destination: Database destination Add_To_Delivery — Delivery table, all columns except DateSent.
  4. Connect CustomerID → Delivery.CustomerID.
  5. On Delivery.RequestID, set Calculated Value to F.RequestNum.
  6. On Delivery.DateEntered, set Calculated Value to Date ().

Adding the Delivery Details

Only valid request lines (Status = 1) get shipped:

  1. Add a Data Mapper as a child of Add Delivery Header. Name it Add Delivery Details.
  2. Source: Database source Get_Request_Details — RequestItems table, columns ProductCode and Quantity, WHERE [RequestItems].RequestID = <?F.RequestNum?> AND [RequestItems].Status = 1.
  3. Destination: Database destination Add_To_Delivery — DeliveryItems table, all columns.
  4. Connect ProductCode → DeliveryItems.ProductCode and Quantity → DeliveryItems.Quantity.
  5. On DeliveryItems.RequestID, set Calculated Value to F.RequestNum.
Status as BIT. The Status column is a Logical field, but in the database itself it lives as a BIT (0 or 1).

Cleaning Up the ODS

Once the request has been delivered, drop the ODS entry to keep storage tidy:

  1. Drag a Flow Data utility as a child of Add Delivery Details. Name it Remove ODS entry.
  2. Click Add; set Action to Delete.
  3. Tick Dynamic.
  4. Set Name to 'Request_' & Trim (Str (F.RequestNum, '5')).

Publishing the Topic

The publisher side fires the event from the Scan for New Requests flow once a request is fully validated:

  1. On Scan for New Requests, add a PSS Publish utility as a child of Check Items.
  2. Name the step Publish the Handle Request.
  3. Open the configuration. In PSS Name, type HandleRequest.
  4. Set the Code parameter to F.RequestNum — this is what subscribers will receive in C.UserCode.
  5. Set the step's Condition to: Trim (F.CustomerName) <> '' AND C.All_Items_Exist

That condition guarantees the topic only fires when the customer exists and every item is in stock.

Exercise

Tighten the workflow.
  1. In Process Request, also delete the corresponding rows from the local Requests and RequestItems tables — system cleanup.
  2. In the Add Customer flow you built last lesson, publish HandleRequest when the customer's request is valid. Remember that to ship a request, every item in the request must have Status = TRUE.

Summary

You should now be able to:

  • Define a PSS topic in the PSS Topics repository.
  • Subscribe a flow to a topic and read the auto-passed parameters.
  • Publish a topic from a step using the PSS Publish utility, with a condition that gates the publish.
  • Coordinate cleanup work (database deletes, ODS removal) inside the subscriber.