Skip to content

Editing deal content

This page covers the body of a deal: its sections and elements — creating, editing, re-ordering, deleting and cloning them — the available element types, and rebate element details, participation, and security. Deals are called agreements or PSAs internally. Core deal fields (name, term, supplier contacts, turnover streams, deal participation) are a separate page: Editing deal core details.

Requires: an authenticated login with view access to the deal. Content edits save through the same autosave described in Editing deal core details: the whole deal document is persisted every few seconds, and no edit below has its own save step unless noted.

How deal content is structured

A deal's body is a document of sections, each containing an ordered list of elements (called components internally). Each element has a hierarchical dotted ID (for example 2.3), a title, details/content, a type, show-on-dashboard and show-on-PDF flags, and optional element-level permissions.

The document is stored twice on the deal record: as XML (dealData, the canonical form used by the PDF renderer and rebate calculation) and as JSON (jsonData, kept in sync by the edit screen). Section and element text is also flattened into the search index so element content is searchable.

Element types

Type Purpose
meta (created by the General button) Plain text term
rich Rich-text (HTML) term
yesyno Yes/no term (yesno is a legacy alias rendered the same way)
rebate A rebate term with calculation fields — see below
priceChange Price-change term (render-only; no edit template)
reminder Reminder term (render-only; no edit template)
question Question term (render-only; no edit template)

Only meta/general, rich, yesyno, and rebate can be created and edited from the deal edit screen; the other three render on the deal and PDF but have no edit template in the current front end.

Creating, editing, re-ordering, deleting, and cloning elements

  • Create: add an element of a chosen type to a section; the screen assigns the next free dotted ID within that section.
  • Edit: opens the type-specific edit dialog for the element.
  • Re-order: drag elements by their handle within a section (and entries within participation lists). Ordering is simply the array order in the saved document — there is no separate reorder action.
  • Delete: removes the element (or a whole section) from the document after a confirmation prompt. There is no server-side recycle bin, but every save records a revision, so prior versions remain in deal history.
  • Clone element: deep-copies the element, assigns the next sibling dotted ID, and inserts the copy after the original. Saving is blocked while any two elements share an ID.

Cloning a whole deal

The Clone action copies the deal and returns the new deal's ID. What happens, in order:

  1. A new deal row is created copying the content (XML and JSON), name, keywords, supplier, contacts, term, deal type, price/promotion settings, rating, sign-off method, and calculation flag. The new deal gets the site's next internal reference, records the source deal as its origin, and is stamped as created by the current user.
  2. Security is not copied wholesale: the new deal is granted view for the admin role, plus only the "not" (deny) view rules from the source deal. Other source permissions (edit/delete/admin rules, view allow-rules) are not carried over.
  3. Seasonality rows and deal categories are copied.
  4. Turnover streams are duplicated as new records, and references to the old stream IDs inside the cloned content are rewritten to the new IDs. Element dotted IDs are not regenerated — they stay as in the source.
  5. The new deal is indexed for search.

A related action, Apply template, merges the site's default deal template into the current deal's content.

Rebate element details

A rebate element carries the calculation definition:

Field Meaning
Rebate type standard (Guaranteed), stepped (Stepped/Targeted), individual (Individual Target), groupgrowth (Group Growth), individualgrowth (Individual Growth)
Value The rate/amount for guaranteed rebates
Steps For non-standard types: bands of from / to / value
Target For growth types: the source deal, date range, and figures the growth is measured against
Calculate Whether this element participates in automated rebate calculation (the deal-level Calculation setting must also allow it)
Period Accrual frequency: monthly, bimonthly, quarterly, sixmonth, annual, biannual, fiveyear
Input / output sources The turnover stream IDs feeding the rebate (streams from chained deals are selectable)
Compound / strung / self-target Compounding against another element, stringing, or inheriting targets
Payable to Rebate payee; defaults to member
Non-retrospective Restricts calculation to non-retrospective treatment

Rebate participation (per element)

Each rebate element can restrict which member companies participate in that rebate, independently of the deal-level participation:

  • Basic mode: a simple list of participating member IDs.
  • Advanced mode: include/exclude lists of companies.

This is stored on the element (memberRestrictions) and used when a rebate is distributed across members.

Element security

Any element can carry its own permissions, per action (view, edit, delete, admin), each with three role lists: any (grant if the user holds any listed role), must (all required), mustnot (deny if held). Roles here are the same role tokens described in the permissions matrix (group names, member, admin, company names, and so on).

How it is evaluated (server side, hasPermissionXML):

  • superusers always pass.
  • If the element has permission rules: all must roles are required, any mustnot role denies, any any role grants; if rules exist but none grant, access is denied; with no effective rules it falls back to a caller-supplied default role list.
  • Legacy elements without a permissions tree fall back to a single PERMISSIONS attribute; rebate elements with no permissions default to requiring the rebates role.

Element security is enforced where elements are rendered or searched: the deal PDF omits elements the user cannot view (rebate sections also require the rebates role), and the deal browser's element search returns "No permissions" instead of the element value. The deal edit screen edits the permission lists themselves.