Fetch Jobs Implementation Documentation

Fetch>>Jobs Implementation Documentation

Overview

The "Fetch>>Jobs" functionality allows users to search for and select transport jobs that can be consolidated into a Transport Consolidation document. The implementation provides a comprehensive dialog interface with filtering, sorting, and selection capabilities.

Architecture

1. Button Setup

The "Fetch>>Jobs" button is added to the Transport Consolidation form in the refresh event handler:

refresh(frm) {
    // Add custom button to fetch jobs (always show dialog for manual selection)
    frm.add_custom_button(__("Jobs"), function() {
        fetch_consolidatable_jobs(frm);
    }, __("Fetch"));
}

Location: Lines 6-9

Key Points:

• Button is always visible (no conditions)
• Clicking triggers fetch_consolidatable_jobs(frm)
• Button is placed in the "Fetch" button group

---

2. Fetching Consolidatable Jobs

The fetch_consolidatable_jobs() function makes a server call to retrieve jobs that can be consolidated:

function fetch_consolidatable_jobs(frm) {
    frappe.call({
        method: "logistics.transport.doctype.transport_consolidation.transport_consolidation.get_consolidatable_jobs",
        args: {
            consolidation_type: frm.doc.consolidation_type || null,
            company: frm.doc.company || null,
            date: frm.doc.consolidation_date || null,
            current_consolidation: frm.doc.name && !frm.doc.__islocal ? frm.doc.name : null
        },
        callback: function(r) {
            if (r.message && r.message.status === "success") {
                show_jobs_dialog(frm, r.message.jobs, r.message.consolidation_groups, r.message.debug);
            }
        }
    });
}

Location: Lines 132-158

Parameters Sent to Server:

• consolidation_type: Type of consolidation (Route, Pick, Drop, Both)
• company: Company filter
• date: Consolidation date filter
• current_consolidation: Current consolidation name (to exclude already added jobs)

Server Response:

• jobs: Array of consolidatable jobs
• consolidation_groups: Grouped jobs by common addresses
• debug: Debug information for diagnostics

---

3. Jobs Dialog Structure

The show_jobs_dialog() function creates a comprehensive dialog interface:

Location: Lines 518-1242

3.1 Dialog Fields

The dialog includes the following sections:

1. Summary Info (HTML Field)

   • Shows count of found jobs
   • Displays consolidation groups count
   • Includes collapsible diagnostics section

2. Filter Section (Collapsible)

   • filter_customer: Link field to filter by customer
   • filter_pick_address: Link field to filter by pick address
   • filter_drop_address: Link field to filter by drop address
   • filter_consolidation_type: Select field (Route/Pick/Drop/Both)
   • sort_by: Select field for sorting
   • sort_order: Ascending/Descending

3. View Toggle

   • Toggle between "Jobs" view and "Transport Legs" view
   • Buttons to switch views dynamically

4. Jobs Table (HTML Field)

   • Dynamic table showing jobs or legs
   • Includes checkboxes for selection
   • Responsive with tooltips for addresses

5. Select All Checkbox

   • Checkbox to select/deselect all items at once

3.2 Dialog Initialization

const dialog = new frappe.ui.Dialog({
    title: __("Consolidation Suggestions"),
    size: 'large',
    fields: [/* field definitions */],
    primary_action_label: has_jobs ? __("Add Selected Jobs") : __("Close"),
    primary_action: function(values) {
        // Handle job selection and addition
    }
});

Key Features:

• Large dialog size (90% width, max 1400px)
• Dynamic primary action label
• Stores dialog reference in frm._consolidation_dialog for synchronization

---

4. Data Management

4.1 Jobs Data Storage

The dialog maintains several data structures:

let all_jobs = jobs || [];              // Original jobs list from server
let filtered_jobs = jobs || [];         // Currently filtered list
let selected_jobs = [];                 // User-selected jobs
let current_view = "jobs";              // Current view: "jobs" or "legs"

Dialog-level storage:

• dialog._jobs_data.all_jobs: All consolidatable jobs
• dialog._jobs_data.filtered_jobs: Filtered jobs
• dialog._all_legs: All transport legs (when in legs view)
• dialog._filtered_legs: Filtered legs
• dialog._legs_job_names: Job names for which legs were fetched

4.2 View Switching

The dialog supports two views:

1. Jobs View (Default)

   • Shows transport jobs with consolidation information
   • Displays: Job name, Customer, Scheduled Date, Load Type, Pick/Drop Addresses, Type

2. Legs View

   • Shows individual transport legs
   • Displays: Leg name, Job, Customer, Date, Load Type, Pick/Drop Addresses, Status
   • Legs are fetched on-demand when switching to this view

Switch Function: switch_view(view_type) - Lines 1044-1137

---

5. Filtering and Sorting

5.1 Filter Function

The filter_jobs() function handles filtering for both views:

Location: Lines 848-1038

Filter Logic:

For Jobs View:

• Filters by customer (exact match)
• Filters by pick address (checks if job has matching pick address in array)
• Filters by drop address (checks if job has matching drop address in array)
• Consolidation type filtering is done server-side

For Legs View:

• Filters legs directly by customer, pick address, drop address
• Fetches legs if not already cached
• Applies filters to the legs array

Sorting:

• Uses sort_jobs() for jobs view (Lines 1324-1394)
• Uses sort_legs() for legs view (Lines 1244-1322)
• Supports multiple sort fields: Job, Customer, Date, Load Type, Addresses, Type/Status

5.2 Filter Event Handlers

Location: Lines 1142-1241

Event handlers are set up for:

• Link fields (customer, pick/drop addresses): Multiple event listeners to catch all changes
• Select fields (consolidation_type, sort_by, sort_order): Standard change events
• Consolidation type changes trigger server-side re-fetch via reload_jobs_with_filter()

Special Handling:

• Consolidation type filter changes update the form field and trigger server re-fetch
• Prevents recursive updates with _updating_from_dialog flag

---

6. Table Rendering

6.1 Jobs Table

Function: build_jobs_table_html(jobs, consolidation_groups) - Lines 1514-1744

Features:

• Responsive table with fixed layout
• Tooltips for Route consolidation type showing all addresses
• Consolidation type badges (Pick/Drop/Both/Route)
• Partial consolidation status indicator
• Checkboxes for selection with data-job-name attribute
• Links to job documents

Address Tooltips:

• For Route consolidation or multiple addresses
• Shows numbered list of all pick/drop addresses
• Positioned dynamically on hover

6.2 Legs Table

Function: build_legs_table_html(legs) - Lines 1396-1512

Features:

• Similar structure to jobs table
• Shows leg name, job name, customer, date, load type, addresses, status
• Status badges with color coding
• Checkboxes with both data-job-name and data-leg-name attributes

---

7. Selection Management

7.1 Checkbox Handling

Select All Functionality:

• Header checkbox in table: .select-all-checkbox
• Dialog field checkbox: select_all field
• Both are synchronized

Individual Checkboxes:

• Class: .job-checkbox
• Data attributes: data-job-name (and data-leg-name for legs)
• Change events update select-all state

Update Function: update_select_all_state() - Lines 1231-1240

7.2 Selection Collection

When "Add Selected Jobs" is clicked:

const checkboxes = dialog.$wrapper.find('.job-checkbox:checked');
selected_jobs = [];
const selected_job_names = new Set();

checkboxes.each(function() {
    const job_name = $(this).data('job-name');
    if (job_name) {
        selected_job_names.add(job_name);
    }
});

selected_jobs = Array.from(selected_job_names);

Location: Lines 757-769

Key Points:

• Collects unique job names from checked checkboxes
• Works for both jobs and legs views (legs have data-job-name)
• Validates that at least one job is selected

---

8. Adding Jobs to Consolidation

Function: add_jobs_to_consolidation(frm, job_names, dialog) - Lines 1746-1775

Process:

1. Validates document is saved (not local)
2. Makes server call to add jobs
3. Shows success/error alerts
4. Closes dialog and reloads form

Server Method:

method: "logistics.transport.doctype.transport_consolidation.transport_consolidation.add_jobs_to_consolidation"
args: {
    consolidation_name: frm.doc.name,
    job_names: job_names
}

---

9. Transport Legs Integration

9.1 Fetching Legs

Function: fetch_legs_for_jobs(job_names, callback) - Lines 160-202

Process:

1. Validates and cleans job names
2. Makes server call to get consolidatable legs
3. Returns legs array via callback

Server Method:

method: "logistics.transport.doctype.transport_consolidation.transport_consolidation.get_consolidatable_legs"

9.2 Legs View Logic

When switching to legs view:

1. Checks if legs are already cached
2. If not, fetches legs for all consolidatable jobs
3. Applies current filters to legs
4. Renders legs table

Caching Strategy:

• Legs are cached in dialog._all_legs
• Cache is cleared when jobs are reloaded
• Legs are re-fetched if job list changes

---

10. Form-Dialog Synchronization

10.1 Consolidation Type Sync

The form and dialog stay synchronized for consolidation type:

Form → Dialog:

• When form field changes, dialog field updates (Lines 40-61)
• Triggers filter update if dialog is open

Dialog → Form:

• When dialog filter changes, form field updates (Lines 1179-1195)
• Triggers server re-fetch of jobs

Prevention of Recursion:

• Uses _updating_from_dialog flag
• Checks current values before updating

10.2 Dialog Reference Management

// Store reference
frm._consolidation_dialog = dialog;

// Clean up on close
const original_hide = dialog.hide;
dialog.hide = function() {
    if (frm._consolidation_dialog === dialog) {
        frm._consolidation_dialog = null;
    }
    original_hide.call(this);
};

Location: Lines 823, 839-845

---

11. Helper Functions

11.1 Sorting Functions

sort_jobs(jobs, sort_by, sort_order) - Lines 1324-1394

• Sorts jobs by various fields
• Handles date comparison
• Case-insensitive string comparison

sort_legs(legs, sort_by, sort_order) - Lines 1244-1322

• Maps job sort options to leg fields
• Handles date comparison
• Status-based sorting for "Type" option

11.2 UI Setup Functions

setup_address_tooltips(dialog) - Lines 337-382

• Sets up tooltip positioning for addresses
• Handles scroll events
• Fixed positioning for tooltips

setup_filter_toggle(dialog) - Lines 274-335

• Sets up collapsible filter section
• Moves filter fields into collapsible container
• Handles toggle animation

setup_diagnostics_toggle(dialog) - Lines 254-272

• Sets up collapsible diagnostics section
• Handles toggle animation

11.3 Update Functions

update_dialog_jobs(dialog, jobs, consolidation_groups, debug_info) - Lines 384-516

• Updates jobs data in dialog
• Rebuilds table HTML
• Re-applies filters
• Updates summary and diagnostics
• Clears legs cache

reload_jobs_with_filter(frm, dialog, consolidation_type) - Lines 204-252

• Re-fetches jobs from server with new filter
• Updates dialog with new data
• Clears legs cache
• Switches back to jobs view if in legs view

---

12. Error Handling

Validation:

• Checks if document is saved before adding jobs
• Validates at least one job is selected
• Handles empty job/leg lists gracefully

Error Messages:

• Server errors shown via frappe.show_alert()
• User-friendly error messages
• Loading indicators during async operations

---

13. User Experience Features

1. Loading Indicators:

   • Spinner shown when fetching jobs/legs
   • "Loading..." messages

2. Empty States:

   • Friendly messages when no jobs/legs found
   • Clear indication of filter results

3. Tooltips:

   • Address tooltips for Route consolidation
   • Status tooltips
   • Field descriptions

4. Responsive Design:

   • Wide dialog (90% width, max 1400px)
   • Scrollable tables
   • Fixed table layout for consistent columns

5. Diagnostics:

   • Collapsible diagnostics section
   • Shows filtering statistics
   • Debug information for troubleshooting

---

14. Data Flow Summary

User clicks "Fetch>>Jobs"
    ↓
fetch_consolidatable_jobs()
    ↓
Server: get_consolidatable_jobs()
    ↓
show_jobs_dialog() with jobs data
    ↓
Dialog renders with filters and table
    ↓
User applies filters/sorting
    ↓
filter_jobs() updates table
    ↓
User selects jobs and clicks "Add Selected Jobs"
    ↓
add_jobs_to_consolidation()
    ↓
Server: add_jobs_to_consolidation()
    ↓
Form reloads with new jobs

---

15. Key Design Decisions

1. Always Show Dialog:

   • Even when no jobs found, dialog shows for transparency
   • Allows users to see why no jobs match

2. Two-View System:

   • Jobs view for high-level overview
   • Legs view for detailed leg-level selection

3. Client-Side Filtering:

   • Fast filtering without server calls
   • Server-side filtering for consolidation_type (affects which jobs are consolidatable)

4. Caching Strategy:

   • Jobs cached in dialog
   • Legs cached but cleared on job reload
   • Prevents unnecessary server calls

5. Bidirectional Sync:

   • Form and dialog stay in sync
   • Prevents user confusion

---

Conclusion

The Fetch>>Jobs implementation provides a comprehensive, user-friendly interface for finding and selecting transport jobs for consolidation. It balances functionality with performance through client-side filtering, intelligent caching, and a responsive UI design.