> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cedarai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stale Inventory Cleanup

> Automated cleanup system for ghost railcar records

## What This System Does

When railcars arrive at your facility, they're marked as "INBOUND" in the system.⁠‌‌‌‌‌‌‌​‌‌​‌​‌​​​‌‌‌​‌‌​⁠ Sometimes these inbound records are created but the physical railcar never actually arrives - maybe the shipment was cancelled, rerouted, or there was a data entry error.

> [!WARNING]
>
> Without cleanup, these "ghost" railcars would stay in your system forever, cluttering reports and making it harder to see your actual inventory.

This automated cleanup system identifies and removes these ghost records based on how long they've been inactive.

***

## How We Determine What's "Stale"

A piece of equipment is considered **stale** when it has been sitting in an INBOUND state with no recent activity. Activity includes:

> [card] Waybill Updates
>
> When billing paperwork is updated

> [card] Consist Assignments
>
> When the equipment is added to a train or consist

> [!NOTE]
>
> If a railcar hasn't had either of these activities for a certain number of days, it's probably not actually at your facility.

## Configurable Settings

> [!NOTE]
>
> These settings can be adjusted in **Settings > Profile > Rail** to control how the cleanup works.

### System Control

> [accordion] Enable/Disable Cleanup
>
> **Setting name:** `Enable Stale Inventory Cleanup`
>
> **What it controls:** Turns the entire stale inventory cleanup system on or off.
>
> > [!WARNING]
> >
> > When disabled, stale equipment will remain in the system indefinitely. This may clutter your inventory reports.
>
> **Options:**
>
> * ✅ **Enabled** - System runs on schedule
> * 🛑 **Disabled** - System is paused

### Default Settings

> [!NOTE]
>
> These defaults apply to all carriers unless you set up carrier-specific overrides below.

> [accordion] Default Stale Threshold (in days)
>
> **Setting name:** `default_stale_days`
>
> **What it controls:** How many days of inactivity before equipment is considered stale.
>
> > [!TIP]
> >
> > If set to 30 days, any equipment that hasn't been updated or added to a train in the last 30 days will be flagged for deletion.
>
> **Business consideration:**
>
> * ⬆️ **Higher number** = More conservative, fewer deletions, but more clutter
> * ⬇️ **Lower number** = More aggressive cleanup, but risk of deleting legitimate equipment

> [accordion] Default Daily Deletion Limit
>
> **Setting name:** `default_daily_velocity`
>
> **What it controls:** The maximum number of stale equipment that can be automatically deleted per carrier in a single day.
>
> > [!TIP]
> >
> > If set to 50, and 200 pieces of equipment are flagged as stale for Union Pacific, only 50 will be deleted today.⁠‌‌‌‌‌‌‌​‌‌​‌​‌​​​‌‌‌​‌‌​⁠ The remaining 150 will trigger alerts for manual review.
>
> > [!WARNING]
> >
> > This is a **safety mechanism**. If there's a system error or data issue that incorrectly flags many items as stale, this limit prevents mass deletion disasters.
>
> **Business consideration:**
>
> * ⬆️ **Higher number** = Faster cleanup, but higher risk if something goes wrong
> * ⬇️ **Lower number** = Safer, but cleanup takes longer for large volumes

### Carrier-Specific Overrides

> [!NOTE]
>
> Override default settings for individual carriers. Only configure carriers that need different settings.

> [accordion] How to Set Up Carrier Overrides
>
> **Setting name:** `Stale Inventory Cleanup Overrides`
>
> **What it controls:** Custom settings for your carrier that override the defaults.
>
> **How it works:** When you configure these settings, they apply to your current carrier (identified by your carrier code). Each carrier can have their own custom thresholds and limits that override the system defaults.
>
> **You can optionally set:**
>
> * Custom stale threshold (in days) - overrides `default_stale_days`
> * Custom daily deletion limit - overrides `default_daily_velocity`
>
> **Why this exists:** Different carriers have different operating patterns:
>
> * 🚂 **Short-line railroads** might need longer grace periods (45+ days)
>
> * 🏭 **High-volume Class II carriers** might want faster cleanup (15 days)
>
> * 🔒 **Carriers with complex operations** might need lower velocity limits for safety
>
> > [!TIP]
> >
> > If you don't set carrier-specific overrides, the default settings will be used for your carrier.

## Safety Mechanisms

> [!NOTE]
>
> The system has multiple safeguards to prevent accidental data loss.

> [accordion] Daily Velocity Limits
>
> Only a limited number of deletions happen per day, per carrier.
>
> Any deletions beyond this threshold are:
>
> * ✋ **Not performed** - equipment stays in system
> * 📝 **Logged** - warnings written to system logs
> * 📊 **Tracked** - metrics recorded for investigation

> [accordion] Transload Protection
>
> Equipment in **active transload operations** will **NEVER** be deleted, regardless of age.
>
> > [!TIP]
> >
> > **What's a transload?** Transferring cargo from one railcar to another (or to a truck). These operations can take time, so equipment must remain in the system even if it looks inactive.

> [accordion] State Protection
>
> Only **INBOUND** equipment is eligible for cleanup.
>
> **Protected states:**
>
> * 🚂 OUTBOUND - leaving your facility
> * 🟢 ONLINE - in active use
> * 🗑️ Already deleted

## What Actually Gets Deleted

> [!WARNING]
>
> For a piece of equipment to be deleted, **ALL** of these conditions must be true:

**1. Status is INBOUND**

Equipment must be in an inbound state

**2. No Recent Activity**

No activity (waybill updates or consist assignments) for longer than the stale threshold

**3. Not Deleted**

Equipment is not already marked as deleted

**4. No Active Transload**

Not part of an active transload operation

**5. Within Velocity Limit**

Carrier hasn't exceeded its daily deletion limit

> [!NOTE]
>
> If any of these conditions is false, the equipment stays in the system.

## Monitoring & Alerts

The system tracks key metrics for monitoring:

> [card] Deletions
>
> Tracks how many items were successfully deleted per carrier per run.

> [card] Over-Velocity Items
>
> Tracks how many items were flagged as stale but NOT deleted because they exceeded the daily velocity limit.

> [!WARNING]
>
> **If you see high over-velocity numbers:** This could indicate:
>
> * 📋 A legitimate backlog that needs attention
> * ⚠️ A data quality issue causing false positives
> * 🔧 System problems incorrectly flagging equipment

## Example Scenario

> [tab] Scenario
>
> **Settings:**
>
> * 📅 Default stale threshold: 30 days
> * 🎯 Default daily velocity: 50 deletions
>
> **Situation:**
> Union Pacific has 200 railcars that haven't been updated in 35 days.

> [tab] What Happens
>
> **1. Flagged as Stale**
>
> All 200 are flagged as stale (35 days > 30 day threshold)
>
> **2. Velocity Limit Applied**
>
> Only 50 are actually deleted (velocity limit)
>
> **3. Remaining Stay**
>
> The remaining 150 stay in the system
>
> **4. Warning Logged**
>
> A warning is logged about the 150 over-velocity items
>
> **5. Metrics Recorded**
>
> System metrics are recorded:
>
> * ✅ deletions = 50
> * ⚠️ overVelocity = 150

> [tab] Next Steps
>
> > [!WARNING]
> >
> > Operations team should investigate why 150+ railcars are stale.
>
> **Possible causes:**
>
> * 📊 Data quality issue?
> * 🔧 Process problem?
> * 📦 Real backlog?

## Recommendations for Configuration

> [tab] Conservative (Safer)
>
> **Configuration:**
>
> ```yaml theme={null}
> default_stale_days: 45
> default_daily_velocity: 25
> ```
>
> **Best for:**
>
> * Getting started with the system
> * Organizations with less confidence in data quality
> * Risk-averse environments
>
> **Pros:**
>
> * ✅ Minimizes risk of accidental deletions
> * ✅ More time to catch data entry errors
>
> **Cons:**
>
> * ⚠️ Slower cleanup of stale records
> * ⚠️ More clutter in reports

> [tab] Balanced (Recommended)
>
> **Configuration:**
>
> ```yaml theme={null}
> default_stale_days: 30
> default_daily_velocity: 50
> ```
>
> ⭐ **This is our recommended starting point**
>
> **Best for:**
>
> * Most operations
> * Organizations with good data quality
> * Standard processing times
>
> **Pros:**
>
> * ✅ Good balance of safety and efficiency
> * ✅ Reasonable cleanup speed
> * ✅ Adequate protection against errors

> [tab] Aggressive (Advanced)
>
> **Configuration:**
>
> ```yaml theme={null}
> default_stale_days: 15
> default_daily_velocity: 150
> ```
>
> ⚠️ **Advanced users only**
>
> **Best for:**
>
> * High-volume operations
> * Organizations with excellent data quality
> * Fast processing environments
>
> **Pros:**
>
> * ⚡ Fast cleanup of stale records
> * ⚡ Minimal clutter
>
> **Cons:**
>
> * ⚠️ Higher risk if data issues occur
> * ⚠️ Requires close monitoring initially
> * ⚠️ Less time to catch mistakes

## Questions to Consider When Configuring

> [accordion] How quickly do your inbound shipments typically get processed?
>
> * ⚡ **Fast (1-5 days)** → Lower stale\_days acceptable
> * 🐌 **Slow (2-4 weeks)** → Higher stale\_days needed

> [accordion] How accurate is your inbound data entry?
>
> * ✅ **Very accurate** → Can use higher velocity
> * ⚠️ **Occasional errors** → Keep velocity conservative

> [accordion] What's your tolerance for clutter vs. risk of deletion?
>
> * 🧹 **Prefer clean reports** → Lower stale\_days, higher velocity
> * 🛡️ **Very risk-averse** → Higher stale\_days, lower velocity

> [accordion] Do different carriers have different processing patterns?
>
> * ✅ **Yes** → Set up carrier-specific overrides
> * ❌ **No** → Use defaults for everyone

## Getting Help

> [!NOTE]
>
> If you notice unexpected behavior, follow these steps:

**1. Check Metrics**

Review system metrics for unusual patterns

**2. Review Logs**

Check system logs for warnings about over-velocity

**3. Verify Settings**

Confirm your configuration values in **Settings > Profile > Rail**

**4. Contact Support**

Reach out to the development team with specific carrier codes and date ranges

***

> [!TIP]
>
> **Quick Summary:** The Stale Inventory Cleanup system automatically removes "ghost" railcar records that have been inactive for too long, with built-in safety mechanisms to prevent accidental data loss.⁠‌‌‌‌‌‌‌​‌‌​‌​‌​​​‌‌‌​‌‌​⁠ Configure it in **Settings > Profile > Rail** based on your operation's needs.


## Related topics

- [Inventory](https://docs.cedarai.com/user-docs/mobile/inventory.md)
- [Sandbox](https://docs.cedarai.com/user-docs/arms/ops/sandbox.md)
- [List railcar inventory](https://docs.cedarai.com/api-reference/list-railcar-inventory.md)
- [Update railcar inventory (move equipment)](https://docs.cedarai.com/api-reference/update-railcar-inventory-move-equipment.md)
- [Asset Lifecycle Transitions](https://docs.cedarai.com/user-docs/arms/ops/asset-lifecycle.md)
