Events

Owned by Maroš Grman
Last updated: Oct 27, 2023 by Pricefx Learning Hub
6 min read

There are many scenarios where a Server Event in Pricefx needs to trigger an action in an external system, for example:

  • A Quote or Price List gets exported to an external system immediately on approval.

  • The completion of an Analytics Data Load notifies the Integration Manager which can then continue with next integration tasks.

  • A scheduled task can send custom Event to Integration Manager to trigger certain action.

What’s a Pricefx Server Event

When certain actions occur in Pricefx, such as the creation of a Price List, Pricefx can fire/generate an event.

Examples of cases, when events are generated, are:

  • Approval of Price Lists

  • Approval of Live Price Grid items

  • Approval of Quotes

  • Calculated Field Set (CFS) calculation finishes

  • Update of Price Record

  • Analytics Data Load finishes

The server event is a small piece of information, stored as a record in the EventTask table.

Figure 1. Example of a page with Pricefx Events

The Event has the following fields:

  • Event Type - Displayed as Name. See the Event Types section below for a list of types.

  • Other detailed information (depends on the type of the Event)

    • ID of the document/process on which the action/situation happened.

How Events are Consumed

The Events can be consumed in many ways, for example:

  • By Integration Manager - either by Push or Pull method.

  • By a Logic (e.g., by a Calculation Flow) in Pricefx Core - by reading the records of the EventTask table.

  • By an external system - either by Push or Pull method.

Principle / Flow

Let’s explain the principle on an example of Price List export after its approval:

  1. Pricing Manager

    1. Creates a Pricelist and waits for its calculation.

    2. Reviews the Prices List and submits it for approval.

  2. Approver

    1. Approves the Price List.

  3. Pricefx Core

    1. Creates an Event (record) and stores it in a table EventTask (type code: EVT).

    2. If the Push Event is required, it pushes a message with the Event to the Integration Manager over an HTTP request.

  4. Integration Manager

    1. If Pull Event is required, it pulls the list of new Events from the EventTask table via the Pricefx Core REST API.

    2. Reads the records of the Price List from the PL/PLI tables (via the Pricefx REST API).

    3. Converts the PLI records to the shape required by an external system (CSV, XML, …​) depending on the project needs.

    4. Sends the converted records to the external system (the channel depends on project needs).

Pull Events from Pricefx to IM

  1. Pricefx Core

    1. Stores the Events to the EventTask table,

      • field Retries Left is set to 5,

      • field Response is set to 0.

    2. But it does not push them to the external endpoint (usually Integration Manager).

  2. The Integration Manager (or potentially some external service)

    1. Is reading the Events regularly (by default every 10 seconds) from the EventTask via the Pricefx REST API

      • The IM can filter which events to read.

    2. When it finds a new Event, it will proceed accordingly.

    3. If the processing of the Event is successful, it will update the Retries Left (set to 0) and Response field in the EventTask table (via Pricefx REST API call).

In comparison with the Push method, Pull has the advantage that the IM can download only the event types, that it wants to process at the moment.

For more details on IM configuration of the Pull Events, see IM Events docs.

Push Events from Pricefx to External Endpoint

The endpoint can be any external service that can accept an HTTP request with JSON data.

  1. Pricefx Core

    1. Stores the Events to the EventTask table,

      • field Retries Left is set to 5,

      • field Response is set to 0.

    2. Sends (over HTTP POST) also a message with the Event data to the external endpoint (usually Integration Manager).

      1. The unsent messages (with Retries Left > 0) are sent regularly (by default every 1 minute) to Integration Manager.

      2. The response status code of that call is stored in the field Response.

      3. When the IM replies with success (Status 200), Pricefx will set Retries Left to 0, so that it does not try to send it again.

      4. When the IM is down (or not responding), the Retries Left counter is decreased by one.

  2. The Integration Manager

    1. Is listening for the Event messages.

    2. Once it receives a new Event, it will proceed accordingly.

For more details on IM configuration of the Push Events, see IM Events docs.

Event Types

There are many types of Events, which are generated automatically by Pricefx Core. You can also see the list of all Event Types in the documentation.

  • Job Process finished

    • CALCULATION_COMPLETED_PL - Pricelist calculation finished

    • CALCULATION_COMPLETED_SIM - Pricelist Simulation calculation finished

    • CALCULATION_COMPLETED_CFS - Calculated Field Set process finished

    • CALCULATION_COMPLETED_PG - Price Grid (LPG) calculation finished

    • CALCULATION_COMPLETED_RC - Rebate Records (RR) calculation finished

    • CALCULATION_COMPLETED_CG - Calculation Grid (CG) calculation finished

    • PADATALOAD_COMPLETED - Analytics Data Load process finished

  • Job Process failed

    • JOB_FAILED - When any scheduled job failed (PL calc., DL, CFS, …​ ). I.e., whatever you can find in the JST table with the status Error.

  • Approval Workflow

    • ITEM_APPROVED_CT - Agreements&Promotions contract approved

    • ITEM_APPROVED_PGI - Price Grid (LPG) line Item approved

    • ITEM_DENIED_PGI - Price Grid (LPG) line Item denied

    • ITEM_APPROVED_PL - Pricelist approved

    • ITEM_APPROVED_Q - Quote approved

    • ITEM_APPROVED_RR - Rebate Record approved

    • ITEM_APPROVED_RBA - Rebate Agreement approved

    • ITEM_APPROVED_CL - Claim approved

    • ITEM_APPROVED_DCR - Data Change Request (DCR) approved

    • WORKFLOW_MESSAGE - Whenever an approver approves (or denies) the Approval Step.

    • WORKFLOW_SUBMIT - When an approvable document is submitted.

  • Data Updates

    • ITEM_UPDATE_PGI - Price Grid line Item updated (manual data change of the record)

    • ITEM_UPDATE_MPLI - Manual Pricelist Line Item updated (add/update/delete - detailed info about the operation - contains the MPLI record detail)

    • ITEM_UPDATE_Q - Quote updated (when the Status changes). The Event contains complete Quote Header information.

    • ITEM_UPDATE_CT - Agreements&Promotions contract updated

    • ITEM_UPDATE_CL - Claim Agreement updated

    • ITEM_UPDATE_CGI - Calculation Grid item updated manually

    • ITEM_UPDATE_RR - Rebate Record updated

    • ITEM_UPDATE_PR - Price Record updated (add/update/delete)

    • ITEM_UPDATE_PPV - Any kind or Price Parameter value update (LTV or MLTVx) - (Add / Update) - the Event contains the record itself.

    • CHANGE_NOTIFICATION_PP - Any kind or Price Parameter bulk update. (Delete / Update) Event has only information, that someone manipulated certain table.

    • CHANGE_NOTIFICATION_CA - Update of the Customer Assignment (when Customer Assignment for PL or MPL changes)

    • CHANGE_NOTIFICATION_MPL - Update of an Item of the Manual Price List (only tells, that there’s a change and in which MPL)

  • Custom Event

    • CUSTOM - Custom event created by Logic.

Custom Events

If you need to handle some events, which are not supported by the Pricefx Core out of the box, you can also generate your own Events from the Logic, and let Integration Manager do certain processing.

To create new custom Event, use the function api.customEvent().

Administration

Setup

Enable Events on Pricefx Server

The setup of Events is in the menu under Administration › Configuration › System Configuration › General Settings › Events.

Figure 2. Screen for configuration of Events
How to Switch Events On/Off:

  • To switch ON the generation of Events by Pricefx Core, you must set the value of the Event URL field and Save Changes of the setting.

    • If you plan to use PULL Events or you just want Pricefx to generate the Events without sending it anywhere, then simply use any dummy value here, e.g., "http://dummy_url".

    • If you want to use PUSH Events, then use the URL of a real Integration Manager end-point.

  • To switch OFF the generation of the Events, remove the value of the Event URL field and Save Changes of the settings.

How to Switch Push/Pull Events:

  • To set Push Events, ensure with the Integration team that the URL Event URL is correct and uncheck the checkbox Disable sending events thought HTTP (PUSH).

  • To set Pull Events, the URL Event URL must not be empty and ensure to check the checkbox Disable sending events thought HTTP (PUSH).

How to Switch Sending of Events by Email

  • Ensure to set a correct email to the Event Email field and Save Changes of the settings.

For more details, see the page Events in Documentation.

Filtering which Events Are Generated

By default, all event types are generated by Pricefx, when the Events are switched on. But, depending on the project, certain user actions can generate a lot of events (e.g., of type ITEM_APPROVED_PGI or ITEM_UPDATE_PPV), which you might not need to process but will be generated by Pricefx anyway (as a part of normal functionality). And if you’re pushing the Events to Integration Manager, Pricefx will push all of the generated Events, even if you might not need them.

To select, which types of Events are generated for the partition, you must set the Event BitMask in the System Admin → Partition Admin screen. This screen is available only to the superadmin, so you should ask Support to help you set it up.

The Event BitMask represents a list of Event Types, which you want Pricefx to generate for the given partition.

Monitoring

In Unity UI, to open and review the list of all generated Events, navigate to Administration › Logs › Events.

You will find here all the generated events, stored in the table EventTask. Remember, the generation of Events depends on if it’s allowed at all, and if there’s any filter in the BitMask.

In the screenshot, the partition is set up for Pull Events, but there’s no Integration Manager to read the Events, so they still have Retries Left set to 5.

You can notice that when you move your mouse over the Message, it shows the full content of the message in the tooltip.

For more details, see Server Events in Unity Documentation.

References

Pricefx Core Documentation

Groovy API

Integration Manager Documentation

Knowledge Base

Found an issue in documentation? Write to us.