Guide: Service Level Agreement

SLA Monitoring Connected to Logistics Service Level — Design Document

This document designs how to connect Transport Plan / Job SLA monitoring to Logistics Service Level, and which fields to add on both sides for comprehensive monitoring. Target date is always based on a date from the job (e.g. for sea freight: job open date, recognition date, invoice date, booking date, ETD, ETA, others). Service level is applicable (selected) on Sales Quote, Orders, and Jobs; monitoring (sla_target_date, sla_status, scheduler) is on job level only.

1. Current State

Logistics Service Level (master)

Field	Type	Purpose
service_code	Data (unique)	Naming / code
service_name	Data (unique)	Display name
transport_mode	Select	Sea / Air / Land / Multimodal
est_transit_time	Int	Est. Transit Time (Days)
text_uufb	Text Editor	Description

• Transport Order has Link service_level → Logistics Service Level.
• Transport Job has no link to Logistics Service Level; SLA fields (sla_target_date, sla_status, sla_notes) are manual only.

Transport Job (transaction)

Field	Type	Purpose
transport_order	Link	Source order (which has service_level)
booking_date	Date	Job booking date
scheduled_date	Date	Requested/scheduled date
sla_target_date	Datetime	When job is due (manual today)
sla_status	Select	On Track / At Risk / Breached / Not Applicable
sla_notes	Text	Free-form notes

• No automatic derivation of sla_target_date from order or service level.
• No automatic update of sla_status from current time vs target.

Gap

• Service level (transit time, mode) is defined on Order but not used for job SLA.
• Job SLA is disconnected from Logistics Service Level; no aggregation or monitoring by service level.

---

2. Goals and principles

1. Connect Job SLA to Logistics Service Level (direct link on Job; copy from Order/Quote when job is created).
2. Target date from job date: SLA target date is always derived from a date on the job. On Logistics Service Level, user selects which job date to use (e.g. Job Open Date, Recognition Date, Invoice Date, Booking Date, ETD, ETA, others). Target = selected job date + transit days (from service level).
3. Applicable vs monitoring:
   • Applicable: Service level can be selected on Sales Quote, Orders (Transport Order, Sea Booking, Air Booking, etc.), and Jobs (Transport Job, Sea Shipment, Air Shipment, Warehouse Job). This defines which SLA applies.
   • Monitoring: SLA target date, SLA status, and scheduler updates exist only on Job doctypes. Quote and Order do not have SLA target/status; they only carry the service level for propagation to the Job.
4. Automate SLA status (On Track / At Risk / Breached) using thresholds defined on Logistics Service Level.
5. Monitor SLA by service level (reports, list views) at job level only.

2.1 Applicable vs monitoring

• Applicable: Service level can be selected on Sales Quote, Orders (Transport Order, Sea Booking, Air Booking, Warehousing orders, etc.), and Jobs (Transport Job, Sea Shipment, Air Shipment, Warehouse Job). This defines which SLA applies to the flow. Quote and Order carry the service level for propagation to the Job; the Job can also have the service level set or overridden directly.
• Monitoring: SLA target date, SLA status (On Track / At Risk / Breached), and scheduler updates exist only on Job doctypes. Quote and Order do not have sla_target_date, sla_status, or scheduler updates; they only store the service level link for applicability and propagation.

---

3. New Fields

3.1 Logistics Service Level

Add an SLA Monitoring section with the following fields.

Field	Type	Label	Description
sla_section	Section Break	SLA Monitoring	Collapsible section for SLA rules.
sla_target_base_date	Select	SLA Target Base Date	Which job date to use as the base. job’s SLA target is determined. Options: Job Open Date, Recognition Date, Invoice Date, Booking Date, ETD, ETA, ATD, ATA, Scheduled Date, Manual on Job. Filter by transport_mode.
sla_transit_days	Int	Days to Add	Number of days to add to the base date to get SLA target (default: same as est_transit_time or 0).
sla_at_risk_hours_before	Int	At Risk (hours before target)	Hours before sla_target_date at which status becomes At Risk (e.g. 24). Leave 0 to disable.
sla_breach_grace_minutes	Int	Breach Grace (minutes after target)	Minutes after sla_target_date before status becomes Breached (e.g. 0 or 60).
sla_business_day_end_hour	Int	Business Day End Hour	Treat target date as end of this hour (0–23, e.g. 17 = 5 PM). Used when converting date-only base to datetime.
sla_escalation_contact	Link (User) or Data	Escalation Contact	Optional; for alerts or reporting.
column_break_sla	Column Break
sla_notes	Small Text	SLA Notes	Optional notes (e.g. escalation process).

Principle: Target date is always based on a date from the job. The service level defines which job date to use and how many days to add. Target = [value of selected base date on the job] + sla_transit_days (days), then set time to sla_business_day_end_hour:00 if base is date-only.

SLA Target Base Date: User selects which job date to use as the base (field sla_target_base_date):

Option	Meaning	Typical job fields (by module)
Job Open Date	When the job was opened	Warehouse Job: job_open_date; others: equivalent.
Recognition Date	Revenue / recognition date	Sea Shipment, Warehouse Job: recognition_date.
Invoice Date	Billing / invoice date	From linked Sales Invoice or job-level invoice date.
Booking Date	Booking / order date	Transport Job, Sea/Air Shipment: booking_date.
ETD / ETA / ATD / ATA	Estimated/actual departure/arrival	Sea/Air Shipment: etd, eta, atd, ata.
Scheduled Date	Scheduled execution date	Transport Job: scheduled_date.
Manual on Job	No auto-calculation	User sets sla_target_date on the job only.

Options can be filtered by transport_mode (Sea / Air / Land / Multimodal) so only dates relevant to that mode appear (e.g. for Sea: Booking Date, ETD, ETA, ATD, ATA, Recognition Date, Invoice Date, Job Open Date, Manual on Job).

Defaults (application level):
If a job has no Logistics Service Level or missing values: e.g. at_risk_hours_before = 24, breach_grace_minutes = 0.

---

3.2 Transport Job

Add/keep the following in the Service Level tab.

Field	Type	Label	Description
logistics_service_level	Link	Logistics Service Level	Optional. Set from Transport Order when job is created from order; can be set/overridden manually.
sla_target_source	Select (read-only or editable)	SLA Target Source	From Service Level | Manual. Indicates how sla_target_date was set.
sla_target_date	Datetime	SLA Target Date	Kept; can be derived from service level or set manually.
sla_status	Select	SLA Status	Kept; On Track / At Risk / Breached / Not Applicable. Updated by scheduled task when target is set.
sla_notes	Text	SLA Notes	Kept.

Field order (suggestion):
After sla_section: logistics_service_level, sla_target_source, then existing sla_target_date, sla_status, column_break_sla, sla_notes.

Derivation rules:

• When transport_order is set and Order has service_level: set logistics_service_level from Order (on create or on change of transport_order if product allows).
• When logistics_service_level is set and sla_target_base_date is not "Manual on Job": read the job's date field corresponding to sla_target_base_date (e.g. Job Open Date → job_open_date, Recognition Date → recognition_date, Booking Date → booking_date, etc.); add sla_transit_days days; set time to sla_business_day_end_hour → store in sla_target_date; set sla_target_source = "From Service Level". If the job does not have that date field or value is null, leave sla_target_date empty until the date is set.
• When user edits sla_target_date manually (or base date = "Manual on Job"): allow override; set sla_target_source = "Manual".

---

4. Data Flow

4.1 Job creation / update

1. From Transport Order

   • On creating a Transport Job from an Order (or when transport_order is set and order has service_level):
     • Set job.logistics_service_level = order.service_level.
   • If logistics_service_level has sla_target_base_date not "Manual on Job":
     • Read the job's date field for that base (e.g. booking_date, job_open_date, recognition_date, scheduled_date, etc.); add sla_transit_days days; set time to sla_business_day_end_hour:00 → store in sla_target_date; set sla_target_source = "From Service Level".
     • If the job does not have that date field or value is null, leave sla_target_date empty.

2. Manual job

   • User can set logistics_service_level and trigger the same derivation, or leave sla_target_date / sla_target_source manual.

3. Override

   • User can change sla_target_date after derivation; application can set sla_target_source = "Manual" on save if value differs from last derived value (optional).

4.2 SLA status update (scheduled task)

• Input: Transport Jobs where docstatus = 1, status not in (Completed, Cancelled), and sla_target_date is set.
• Parameters per job:
  • From job.logistics_service_level: sla_at_risk_hours_before, sla_breach_grace_minutes.
  • If no service level or values missing: use app defaults (e.g. 24 hours, 0 minutes).
• Logic:
  • now = current datetime.
  • If now > sla_target_date + breach_grace_minutes → set sla_status = Breached.
  • Else if now >= sla_target_date - at_risk_hours_before → set sla_status = At Risk.
  • Else → set sla_status = On Track.
• Frequency: e.g. every 15–30 minutes (same or similar to existing job status task).
• Skip: Jobs with sla_status = "Not Applicable" (optional; or treat as no target and leave unchanged).

---

5. Monitoring and Reporting

5.1 List views

• Transport Job: Add columns logistics_service_level, sla_target_source, sla_target_date, sla_status.
• Filters: By logistics_service_level, sla_status, plan date (via run sheet/legs), customer.

5.2 Reports

• SLA compliance by Logistics Service Level

  • Group by logistics_service_level.
  • Count (or %) of jobs by sla_status (On Track, At Risk, Breached) and optionally by time period.
  • Optional: same for jobs linked to a given Transport Plan (via Run Sheet → Legs → Job).

• Existing On Time Delivery Report

  • Optional: add filter or column for logistics_service_level so delivery performance can be analysed by service level.

5.3 Transport Plan context

• SLA_MONITORING.md (existing) can be updated to state:
  • Jobs in a plan can have logistics_service_level and derived sla_target_date / sla_status.
  • Monitoring by plan = list jobs linked to the plan’s run sheets (Plan → Run Sheets → Legs → Transport Job), then filter/group by logistics_service_level and sla_status as above.

5.4 Escalation (optional)

• If sla_escalation_contact is set on Logistics Service Level, a future enhancement could send notifications when status becomes At Risk or Breached (e.g. from the same scheduled task that updates sla_status).

---

6. Implementation Outline

#	Task	Doctype / Layer
1	Add SLA Monitoring section and new fields to Logistics Service Level	DocType JSON (+ optional client script for defaults)
2	Add logistics_service_level and sla_target_source to Transport Job	DocType JSON
3	Copy service_level from Order to logistics_service_level when job has transport_order	Transport Job server script (on load/validate or on set of transport_order)
4	Derive sla_target_date and sla_target_source from Logistics Service Level when applicable	Transport Job server script (validate or before_save)
5	Scheduled task: update sla_status (On Track / At Risk / Breached) using service level thresholds	New function in logistics.transport.tasks (or equivalent), register in scheduler_events
6	Report: SLA compliance by Logistics Service Level	New report (Script Report or Query Report)
7	Update SLA_MONITORING.md to describe Logistics Service Level link and monitoring	Doc

---

7. Summary Table

Aspect	Logistics Service Level	Transport Job
New / changed	sla_target_base_date, sla_transit_days, sla_at_risk_hours_before, sla_breach_grace_minutes, sla_business_day_end_hour, sla_escalation_contact, sla_notes	logistics_service_level, sla_target_source; keep sla_target_date, sla_status, sla_notes
Connection	Master defining how SLA target and thresholds are applied	Link to master; target date derived from master when sla_target_base_date not "Manual on Job"
Monitoring	Aggregation by service level; escalation contact for future use	Per-job SLA target and status; status updated by scheduler using service level thresholds

This design links SLA monitoring to Logistics Service Level, adds the necessary fields on both sides, and keeps Transport Plan monitoring as "all jobs attached to the plan's run sheets," with the ability to filter and report by Logistics Service Level and SLA status.

---

8. Connections to Other Modules

SLA monitoring and Logistics Service Level are extended to Sea Freight, Air Freight, Warehousing, Customs, and Pricing Center so that one master (Logistics Service Level) and one monitoring approach apply across modules.

8.1 Module overview

Monitoring is job-level only. Service level is applicable (selected) on Sales Quote, Orders, and Jobs; monitoring (sla_target_date, sla_status, scheduler) is only on Jobs.

Module	Applicable (service_level selected)	Monitoring (SLA target, status, scheduler)
Transport	Transport Order, Transport Job	Transport Job only
Sea Freight	Sea Booking, Sea Shipment (job)	Sea Shipment only (job)
Air Freight	Air Booking, Air Shipment (job)	Air Shipment only (job)
Warehousing	Orders (optional), Warehouse Job	Warehouse Job only
Customs	—	Optional link on Declaration for reporting only
Pricing Center	Sales Quote	— (source only; flows to Order/Booking → Job)

8.2 Sea Freight

Doctypes: Sea Booking, Sea Shipment.

Current: Both have service_level (Link → Logistics Service Level); Shipment has eta, ata, booking_date.

Add (same semantics as Transport Job):

Doctype	New/updated fields	Derivation / monitoring
Sea Booking	Optional: sla_target_date, sla_status, sla_notes, sla_target_source	When service_level set: derive sla_target_date from Logistics Service Level (e.g. booking_date + sla_transit_days). Set sla_target_source = "From Service Level" or "Manual".
Sea Shipment	Optional: sla_target_date, sla_status, sla_notes, sla_target_source	Same derivation from Shipment's service_level (or from Booking). ETA can be used as alternative/override for target. Scheduler updates sla_status using service level thresholds.

Rename for consistency (optional): Keep field name service_level on Sea Booking/Shipment; in code and docs treat it as logistics_service_level (same doctype link). No schema rename required if not desired.

Reports: Include Sea Shipment/Booking in "SLA compliance by Logistics Service Level" (group by service_level, count by sla_status).

8.3 Air Freight

Applicable: Air Booking and Air Shipment (job) can have service_level. Monitoring is on job only: only Air Shipment (the job) gets SLA monitoring fields.

Add on Air Shipment (job) only: Same as Sea Shipment. Target = job date from sla_target_base_date (e.g. Booking Date, ETD, ETA, ATD, ATA, Recognition Date, Invoice Date, Job Open Date) + sla_transit_days. Scheduler updates sla_status. Air Booking keeps service_level only; no sla_target_date / sla_status.

Reports: Include Air Shipment in SLA-by–service-level report.

8.4 Warehousing

Applicable: Orders (Inbound, Release, Transfer, VAS, Stocktake) can have optional logistics_service_level; Warehouse Job (job) can have logistics_service_level. Monitoring is on job only: only Warehouse Job gets SLA monitoring fields.

Current: Orders have due_date; Warehouse Job has job_open_date, recognition_date; no service level link.

Add:

Doctype	New/updated fields	Derivation / monitoring
Warehouse Job (job)	logistics_service_level (Link), sla_target_date, sla_status, sla_notes, sla_target_source	Target = job date from sla_target_base_date (e.g. Job Open Date, Recognition Date; or from reference order's due_date if base = "Due Date"). Add sla_transit_days. Scheduler updates sla_status.
Orders (Inbound, Release, etc.)	Optional: logistics_service_level (Link)	Applicable only; propagates to Warehouse Job. No sla_target_date / sla_status on order.

Reports: Include Warehouse Job in SLA-by–service-level report; filter by warehouse / order type.

8.5 Customs

Doctypes: Customs Authority (has SLA); Declaration, Permit Application (have status / overdue concepts).

Current: Customs Authority has sla_standard_days, sla_express_days, sla_urgent_days, enable_sla_tracking, sla_alert_threshold_percent. Declaration has status (e.g. Pending, Overdue).

Connection (for cross-module SLA monitoring):

Approach	Description
A. Link to Logistics Service Level	Add optional logistics_service_level (Link) on Declaration (and optionally Permit Application). Used for reporting only: group declarations by Logistics Service Level in cross-module SLA report. Authority's own SLA (days) remains the source for customs-specific deadlines.
B. SLA tier mapping	Add on Logistics Service Level optional "Customs SLA tier" (Standard / Express / Urgent). When a Declaration is linked to a shipment/order that has a Logistics Service Level, map to authority's sla_standard_days / sla_express_days / sla_urgent_days for due-date calculation.
C. No schema change	Keep Customs Authority SLA and Declaration status as-is. Only document in design that "SLA by service level" report can later include Customs (e.g. by linking Declaration to Shipment/Order that has service_level).

Recommendation: Implement A (optional logistics_service_level on Declaration) for reporting; keep Customs Authority SLA as master for customs deadlines. Option B can be a later enhancement.

Reports: "SLA compliance by Logistics Service Level" can include Declaration count (or overdue count) where Declaration has logistics_service_level set (e.g. from linked Sea/Air Shipment).

8.6 Pricing Center (Sales Quote)

Current: Sales Quote has service_level (Link → Logistics Service Level). Quote flows to Transport Order, Sea Booking, Air Booking, etc.

Ensure:

• When creating Transport Order from Quote: copy service_level to Order (already present).
• When creating Sea Booking / Air Booking from Quote: copy service_level to Booking (already done in code).
• Downstream doctypes (Transport Job, Sea/Air Shipment, etc.) get logistics_service_level from Order/Booking or directly from Quote so SLA derivation and monitoring are consistent.

No new fields required on Sales Quote; only verify data flow in existing create/map logic.

8.7 Cross-module SLA report and defaults

Logistics Service Level already has transport_mode (Sea / Air / Land / Multimodal). Use it to:

• Filter which doctypes a given service level applies to (e.g. Sea → Sea Booking/Shipment; Land → Transport Order/Job; Multimodal → multiple).
• In "SLA compliance by Logistics Service Level" report: one table (or tabs) grouping by service level, then by module (Transport, Sea, Air, Warehousing, Customs) and counting by sla_status (On Track, At Risk, Breached).

Default service level per module:

• Air Freight Settings / Sea Freight Settings already have default_service_level. Use when creating Booking/Shipment without an explicit service level (e.g. from Quote).
• Warehouse Settings: add optional default_logistics_service_level (Link) so new orders/jobs can get a default for SLA derivation.
• Transport: default can come from Order's service_level or Transport Settings if desired (optional).

---

9. Implementation Outline (All Modules)

#	Task	Module / Doctype
1	Add SLA Monitoring section and new fields to Logistics Service Level (§3.1)	Logistics
2	Add logistics_service_level, sla_target_source and keep SLA fields on Transport Job (§3.2); copy from Order; derive target; scheduler	Transport
3	Add sla_target_date, sla_status, sla_notes, sla_target_source to Sea Booking and Sea Shipment; derive from service_level; extend scheduler	Sea Freight
4	Same as #3 for Air Booking and Air Shipment	Air Freight
5	Add logistics_service_level, sla_target_date, sla_status, sla_notes, sla_target_source to Warehouse Job; optional same on key orders; derive from due_date / service level; extend scheduler	Warehousing
6	Add optional logistics_service_level on Declaration (and optionally Permit Application) for reporting (§8.5)	Customs
7	Optional: Warehouse Settings – default_logistics_service_level	Warehousing
8	Optional: Logistics Service Level – customs_sla_tier (Standard/Express/Urgent) for future mapping to Customs Authority days	Logistics
9	SLA compliance by Logistics Service Level report: include Transport Job, Sea Shipment/Booking, Air Shipment/Booking, Warehouse Job, Declaration (where linked)	Cross-module report
10	Verify Sales Quote → Order/Booking service_level copy	Pricing Center
11	Update SLA_MONITORING.md with Logistics Service Level and cross-module links	Doc

---

10. Summary Table (All Modules)

Module	Applicable (service_level selected)	Monitoring (job only)	New SLA fields on Job	Scheduler updates sla_status
Transport	Transport Order, Transport Job	Transport Job	logistics_service_level, sla_target_source; keep sla_target_date, sla_status, sla_notes. Target from job date (sla_target_base_date) + days	Yes
Sea Freight	Sea Booking, Sea Shipment (job)	Sea Shipment (job)	sla_target_date, sla_status, sla_notes, sla_target_source. Target from job date (e.g. recognition date, booking date, eta) + days	Yes
Air Freight	Air Booking, Air Shipment (job)	Air Shipment (job)	Same as Sea. Target from job date + days	Yes
Warehousing	Optional orders, Warehouse Job	Warehouse Job	logistics_service_level, sla_target_date, sla_status, sla_notes, sla_target_source. Target from job date (e.g. job_open_date, recognition_date) or order due_date + days	Yes
Customs	—	Declaration (optional link for reporting)	Reporting only; authority SLA unchanged	No
Pricing Center	Sales Quote	—	None (source only)	N/A

This extends SLA monitoring and Logistics Service Level to Sea, Air, Warehousing, Customs, and Pricing Center so one design covers transport, sea, air, warehousing, customs, and quote-to-order flow. SLA monitoring to Logistics Service Level, adds the necessary fields on both sides, and keeps Transport Plan monitoring as “all jobs attached to the plan’s run sheets,” with the ability to filter and report by Logistics Service Level and SLA status.