iTop-br-orderrequest

License Contributions welcome

An iTop extension to manage Order Requests (German: BANF – Bedarfsanforderung) directly in iTop. Submit purchase requests, route them through approval, and hand over to procurement - all as a specialized ticket with line items.

Features

Data Model

  1. OrderRequest (extends Ticket)
    • request_type_id → OrderRequestType (filtered to same org_id, status='active')
    • Technical approval fields: technical_approver_id, approval_request_date, approved_by_id, approval_date, approval_comment
    • Budget approval fields: budget_approver_id, budget_approval_request_date, budget_approved_by_id, budget_approval_date, budget_approval_comment
    • Procurement: procurement_reference
    • Roll-ups: estimated_total_cost (decimal, computed)
    • Relations: optional links to Incident / UserRequest / Problem / Change
    • Linked set: line_items (OrderRequestLineItem)
  2. OrderRequestLineItem
    • order_request_id (FK to OrderRequest)
    • line_number (auto 1..n per order), name, vendor_sku, description
    • quantity (integer, >0), uom (enum: EA, PT, HUR, LIC, SET, MON, ANN)
    • unit_price_estimated, total_price_estimated (RO, computed)
    • Linked set: functionalcis_list via link class
  3. lnkOrderRequestLineItemToFunctionalCI
    • Link table between OrderRequestLineItem and FunctionalCI
    • Uniqueness on (order_request_line_item_id, functionalci_id)
  4. OrderRequestType (typology per org)
    • org_id, code, name, status (active/inactive)
    • default_approver_id
    • requires_budget_owner_approval (boolean)
    • budget_approver_id (optional in general; required if requires_budget_owner_approval = yes)
    • description

Lifecycle

OrderRequest.status values (with UI styling and icons):

Transitions (user stimuli): submit → review → request approval → approve/reject → procure → close. On approve the approver and date are recorded; request approval sets approval_request_date.

Stimuli / Transitions

Mutability note

State diagram

stateDiagram-v2
    [*] --> draft

    draft --> submitted : ev_submit
    draft --> rejected  : ev_reject

    submitted --> in_review : ev_review
    in_review --> waiting_approval : ev_request_approval

    waiting_approval --> approved : ev_approve\n(no budget required)
    waiting_approval --> waiting_budget_approval : ev_request_budget_approval\n(budget required)
    waiting_approval --> rejected : ev_reject

    waiting_budget_approval --> approved : ev_budget_approve
    waiting_budget_approval --> rejected : ev_budget_reject

    approved --> procurement : ev_procure
    procurement --> closed   : ev_close

    rejected --> [*]
    closed   --> [*]

    note right of waiting_approval
      Path selection:
      - If OrderRequestType.requires_budget_owner_approval = no → ev_approve
      - If yes → ev_request_budget_approval → waiting_budget_approval
    end note

Usage

  1. Create types (OrderRequestType)
    • Per organization, define code, name, set status=active
    • Optionally set a default_approver_id (auto-filled on requests)
    • If budget approval is required, set requires_budget_owner_approval = yes and assign budget_approver_id
  2. Create an order request (OrderRequest)
    • Select Organization and Type (list is constrained)
    • Add line items (quantity, UoM, prices)
    • estimated_total_cost is computed automatically
  3. Approval workflow
    • Move to in_review → waiting_approval
    • On approve, approver & date are set; comments required
    • On reject, requester and date are recorded
    • Depending on the type:
      • Direct technical approval (ev_approve) or
      • Budget approval path (ev_request_budget_approval → waiting_budget_approval → ev_budget_approve / ev_budget_reject)
  4. Procurement
    • Provide procurement_reference and move to procurement
    • Close when complete
  5. Functional CIs
    • Link FunctionalCIs to line items at any time via functionalcis_list

Once the request leaves draft, line items become read-only and not deletable. Once the request is in closed or rejected, line items become deletable.

Configuration

This extension exposes lightweight workflow policies via module settings. Defaults are installed from the XML, but any value in config-itop.php takes precedence.

Module settings

Key Type Default Description
policy_mode string (off, warn, enforce) warn Controls whether policies are disabled, only warn, or block actions.
approval_restrict_to_assigned_approver bool true If enabled, only the assigned approver may trigger Approve actions.
approval_forbid_self_approval bool true If enabled, the requester/caller cannot approve their own request.
budget_auto_threshold int (≥ 0) 0 If > 0, forces the budget approval flow when estimated_total_cost ≥ threshold. 0 disables auto-budget.

Example in config-itop.php:

// config-itop.php
// ...
'module_settings' => array(
  // ...
  'br-orderrequest' => array(
    'policy_mode' => 'warn', // off | warn | enforce
    'approval_restrict_to_assigned_approver' => true,
    'approval_forbid_self_approval' => true,
    'budget_auto_threshold' => 0,
  ),
),

Policy modes

What the policies do

iTop Compatibility

The extension was tested on iTop 3.2.2

Testing

See Manual Test Plan for end-to-end test steps.

Contributing

Issues and PRs are welcome.

Please keep close to iTop conventions and include:

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file or https://www.gnu.org/licenses/agpl-3.0.en.html.

© 2025 Björn Rudner

This site is open source. Improve this page.