Using $$addMessage to Surface Validation and Guidance Messages

this feature will be available in relase 2601 this guide explains how to use the $$addmessage and $$removemessage helpers in nue ui plugins to surface and manage validation errors , warnings , and informational notices on quote/order headers and line items use $$addmessage when you want to indicate blocking errors provide helpful guidance or business context while users edit quotes/orders messages show up as bell icons in the ui, either next to the quote header or at the line level header level and line level messages displayed in the line editor are stored in the ruby messages c object messages created on quotes are automatically carried over to orders when the quote is finalized an order cannot be activated until all error level messages are resolved 💁‍♀️ any message added by a plugin should also be removed when its triggering condition is no longer met for example, when a user fixes an error or when an additional discount no longer applies message levels and behavior $$addmessage supports three message levels, each with a different bell icon color and intended usage level example behavior / typical use case general guidelines error critical validation failures users can save the quotes or orders with errors, but orders having errors cannot be activated use error when the issue must be fixed before the quote is finalized into an active order example use case configuration is not allowed and must be fixed tax manager requires at least one integration on the quote avalara integration, stripe tax integration, or sphere integration warning orange needs attention, but user can continue use warning when approval or extra consideration is required example use case discount is high but may still be allowed for review discount exceeds 40% this may require additional approval from the finance team info non blocking tips, context, or reminders user info when the system is simply explaining an automatic rule example use case system applies a rule and explains why a 15% discount has been automatically applied because the quote includes more than two integration products function signature $$addmessage function $$addmessage(params { level 'error' | 'warning' | 'info', message string, field? string, fieldmessage? string, lineid? string, customtitle? string }) { success boolean, messageid? string, error? string } parameters level (required) message severity 'error', 'warning', or 'info' message (required) the main message text to display field (optional) field name that has the issue (e g , 'quantity', 'discount') fieldmessage (optional) additional context for the field lineid (optional) line item id for line level messages omit for header level messages customtitle (optional) custom title for the message return value $$addmessage returns a simple status object { success boolean, // true if the message was added successfully error? string // error description when success is false } typical usage pattern check success to confirm the message was added log or handle error if success is false $$removemessage function function signature $$removemessage(params { lineid? string, field? string, level? 'error' | 'warning' | 'info' }) { success boolean, removedcount number, error? string } parameters at least one parameter must be provided parameters can be combined to narrow the removal criteria lineid (optional) remove messages from a specific line omit to remove from header field (optional) remove messages for a specific field (e g , 'quantity', 'discount') level (optional) remove messages of a specific level ('error', 'warning', or 'info') return value { success boolean, // true if removal was successful removedcount number, // number of messages removed error? string // error description if success is false } removal behavior with lineid removes messages from the specified line item without lineid removes messages from the header multiple criteria all criteria must match for a message to be removed available plugin events both $$addmessage and $$removemessage are available in these ui plugin events ui afteredit after a user edits a line item field ui afterloading after the line editor loads ui aftercalculation after price calculation completes ui beforecalculation before price calculation runs line level messages line level messages show a bell icon on the specific row include the lineid parameter to target a specific line example 1 validation error // plugin event ui afteredit // plugin type lineitem // error when quantity is invalid const line = $$changedlineinfo updatedlineitem; if (line quantity <= 0) { $$addmessage({ level 'error', message 'quantity must be greater than zero ', field 'quantity', fieldmessage 'invalid quantity', lineid line id }); } example 2 discount warning // plugin event ui afteredit // plugin type lineitem // warning when discount is too high if ($$changedlineinfo updatedlineitem discount > 20) { $$addmessage({ level 'warning', message 'discount exceeds the recommended maximum of 20% manager approval may be required ', field 'discount', fieldmessage 'max recommended 20%', lineid $$changedlineinfo updatedlineitem id }); } example 3 info message // plugin event ui aftercalculation // plugin type lineitem const line = $$changedlineinfo updatedlineitem; if (line quantity >= 100) { $$addmessage({ level 'info', message 'this product qualifies for volume pricing at 100+ units ', field 'quantity', lineid line id, customtitle 'volume discount available' }); } header level messages header level messages show a bell icon near the quote/order header omit the lineid parameter for header messages example 1 approval required // plugin event ui aftercalculation // plugin type headerobject const totalamount = $$headerobject totalamount || 0; if (totalamount > 100000) { $$addmessage({ level 'warning', message 'quote total exceeds $100,000 vp approval required before submission ', customtitle 'approval required' }); } example 2 informational notice // plugin event ui aftercalculation // plugin type headerobject const totalamount = $$headerobject totalamount || 0; if (totalamount < 1000) { $$addmessage({ level 'info', message 'orders under $1,000 qualify for expedited processing ' }); } full plugin example this example validates all line items after calculation and adds both line level and header level messages // plugin event ui aftercalculation // plugin type any // validate all line items for (const line of $$headerobject lineitems) { // check margin const margin = ((line listprice line netsalesprice) / line listprice) 100; if (margin < 10) { $$addmessage({ level 'error', message `margin is only ${margin tofixed(1)}% minimum margin is 10% `, field 'netsalesprice', fieldmessage 'below minimum margin', lineid line id }); } else if (margin < 20) { $$addmessage({ level 'warning', message `margin is ${margin tofixed(1)}% consider increasing price `, field 'netsalesprice', lineid line id }); } } // header level validation if ($$headerobject lineitems length === 0) { $$addmessage({ level 'error', message 'quote must have at least one line item before saving ' }); } checking return value // plugin event ui afteredit // plugin type lineitem const result = $$addmessage({ level 'warning', message 'test message', lineid $$changedlineinfo updatedlineitem id }); if (result success) { console log('message added successfully ', result messageid); } else { console error('failed to add message ', result error); } common use cases 1\ quantity validation block invalid quantities, such as orders below a minimum order quantity (moq) const line = $$changedlineinfo updatedlineitem; if (line quantity < line minimumorderquantity) { $$addmessage({ level 'error', message `minimum order quantity is ${line minimumorderquantity}`, field 'quantity', lineid line id }); } 2\ price validation (below cost) flag situations where the selling price is below cost const line = $$changedlineinfo updatedlineitem; if (line netsalesprice < line costprice) { $$addmessage({ level 'warning', message 'selling below cost price approval required ', field 'netsalesprice', lineid line id }); } 3\ discount limits enforce maximum allowed discounts const line = $$changedlineinfo updatedlineitem; const maxdiscount = 25; if (line discountpercentage > maxdiscount) { $$addmessage({ level 'error', message `discount cannot exceed ${maxdiscount}%`, field 'discountpercentage', fieldmessage `max ${maxdiscount}%`, lineid line id }); } 4\ product compatibility checks prevent incompatible products from being combined // check if incompatible products are on the same quote const hasproducta = $$headerobject lineitems some(l => l productsku === 'prod a'); const hasproductb = $$headerobject lineitems some(l => l productsku === 'prod b'); if (hasproducta && hasproductb) { $$addmessage({ level 'error', message 'products a and b cannot be on the same quote due to licensing restrictions ' }); } 5\ subscription term validation suggest or enforce minimum subscription terms const line = $$changedlineinfo updatedlineitem; if (line subscriptionterm && line subscriptionterm < 12) { $$addmessage({ level 'warning', message 'subscription terms less than 12 months may not qualify for standard pricing ', field 'subscriptionterm', lineid line id }); } 6\ bundle validation ensure required add ons are included with bundles // ensure required add ons are present const bundleline = $$headerobject lineitems find(l => l productsku === 'bundle 001'); const hasrequiredaddon = $$headerobject lineitems some(l => l productsku === 'addon required' && l parentlineid === bundleline? id ); if (bundleline && !hasrequiredaddon) { $$addmessage({ level 'error', message 'bundle requires the mandatory add on product ', lineid bundleline id }); } best practices 1\ choose the right level error blocks saving or submitting use for hard business rules (e g , “margin below minimum,” “missing required add on”) warning highlights risk or policy deviations, but still allows users to proceed info provides context or tips (e g , “qualifies for expedited processing,” “volume discount available”) 2\ make messages clear and actionable bad messages are vague and don’t tell users what to do next good messages state what is wrong state what the user should do // ❌ bad vague message $$addmessage({ level 'error', message 'invalid value', lineid line id }); // ✅ good clear and actionable $$addmessage({ level 'error', message 'quantity must be between 1 and 1000', field 'quantity', fieldmessage 'enter a value between 1–1000', lineid line id }); 3\ avoid duplicate messages the platform automatically prevents exact duplicate messages (same message, level, field, and lineid), but you should still design plugins to avoid unnecessary repeat calls // the second call will be ignored (duplicate) $$addmessage({ level 'error', message 'same message', lineid line id }); $$addmessage({ level 'error', message 'same message', lineid line id }); 4\ use custom titles for extra context custom titles help users quickly identify the category of the issue $$addmessage({ level 'warning', message 'this configuration requires legal review before activation ', customtitle 'legal review required' }); 5\ always include field when applicable if the message is about a specific field, set the field parameter this improves ux by tying the message to the exact field $$addmessage({ level 'error', message 'start date cannot be in the past', field 'startdate', fieldmessage 'select a future date', lineid line id }); troubleshooting message is not appearing check the following return value confirm result success === true from $$addmessage valid lineid for line level messages, ensure lineid refers to an existing line item in $$headerobject lineitems supported plugin event make sure the plugin is running in one of the supported ui events ui afteredit ui afterloading ui aftercalculation ui beforecalculation correct plugin type for line level messages, the plugin type should be lineitem or any message appears but does not update messages are added during plugin execution if you need to “update” a message change the message text (so it’s not treated as a duplicate), or remove the old message (if you have logic for that) before adding a new one multiple messages on the same line it is expected and supported for a line to have multiple messages with different levels or content (for example, one warning about discount and one info about volume pricing)