Home / Integration / Integrations / Location master.html

Location Master Service Integration

Overview

Attribute Value
Context Location Master Service
Pattern Conformist
Direction Inbound (Location Master → Process Path)
Protocol REST API (cached)
Caching Redis, 15 min TTL

Integration Summary

Location Master Service provides warehouse topology and zone configuration. Process Path conforms to their location model and uses it for routing decisions, zone-based capacity planning, and conveyor topology understanding.

1
2
3
4
5
6
7
8

┌─────────────────────────┐         ┌─────────────────────────┐
│   LOCATION MASTER       │         │      PROCESS PATH       │
│                         │         │                         │
│  • Warehouse topology   │  ─────► │  • Zone routing         │
│  • Zone definitions     │   API   │  • Conveyor mapping     │
│  • Conveyor layout      │(cached) │  • Path planning        │
│  • Capacity constraints │         │  • Reroute decisions    │
└─────────────────────────┘         └─────────────────────────┘

API Endpoints

Get Warehouse Layout

Endpoint: GET /api/v1/locations/warehouses/{warehouseId}/layout

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

{
  "warehouseId": "WH-001",
  "name": "Seattle Fulfillment Center",
  "zones": [
    {
      "zoneId": "ZONE-A",
      "zoneName": "Fast Mover Zone",
      "zoneType": "PICKING",
      "capacity": {
        "aisles": 20,
        "bins": 5000,
        "skuCapacity": 3000
      },
      "conveyorConnections": ["CONV-MAIN-01", "CONV-AFE-INDUCT"],
      "supportedPaths": ["SINGLES", "AFE"]
    },
    {
      "zoneId": "ZONE-B",
      "zoneName": "Standard Zone",
      "zoneType": "PICKING",
      "capacity": {
        "aisles": 30,
        "bins": 8000,
        "skuCapacity": 6000
      },
      "conveyorConnections": ["CONV-MAIN-02"],
      "supportedPaths": ["SINGLES", "AFE", "BATCH_FLOW"]
    }
  ]
}

Get Zone Details

Endpoint: GET /api/v1/locations/zones/{zoneId}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

{
  "zoneId": "ZONE-A",
  "zoneName": "Fast Mover Zone",
  "zoneType": "PICKING",
  "location": {
    "building": "MAIN",
    "floor": 1,
    "quadrant": "NE"
  },
  "aisles": [
    {
      "aisleId": "A-01",
      "bays": 25,
      "levelsPerBay": 5,
      "binsPerLevel": 4,
      "pickFace": true
    }
  ],
  "conveyorAccess": [
    {
      "conveyorId": "CONV-MAIN-01",
      "accessPoint": "CONV-ACCESS-A-01",
      "direction": "OUTBOUND"
    }
  ],
  "restrictions": {
    "hazmatAllowed": false,
    "temperatureControlled": false,
    "maxItemWeight": 50
  }
}

Get Conveyor Topology

Endpoint: GET /api/v1/locations/conveyors/topology

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  "warehouseId": "WH-001",
  "conveyors": [
    {
      "conveyorId": "CONV-MAIN-01",
      "type": "BELT",
      "startPoint": "PICK-ZONE-A",
      "endPoint": "SORT-DIVERT-01",
      "length": 150,
      "speed": 2.5,
      "capacity": 600,
      "diverts": [
        {
          "divertId": "DIVERT-SINGLES",
          "position": 50,
          "destinations": ["SINGLES-PACK-01", "SINGLES-PACK-02"]
        },
        {
          "divertId": "DIVERT-AFE",
          "position": 100,
          "destinations": ["AFE-INDUCT-01", "AFE-INDUCT-02"]
        }
      ]
    }
  ]
}

Get AFE Configuration

Endpoint: GET /api/v1/locations/afe/{afeId}/configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

{
  "afeId": "AFE-01",
  "sorterType": "TRAY_SORTER",
  "capacity": {
    "traysPerHour": 2700,
    "activeLanes": 9
  },
  "inductStations": [
    {
      "stationId": "INDUCT-01",
      "zipperMerge": "MERGE-01",
      "emptyTrayBuffer": 15,
      "maxThroughput": 300
    }
  ],
  "rebinWalls": [
    {
      "wallId": "WALL-AFE-01",
      "wallType": "SORTABLE_AFE",
      "chuteCount": 166,
      "assignedLanes": ["LANE-01", "LANE-02", "LANE-03"]
    }
  ],
  "dischargeLanes": [
    {
      "laneId": "LANE-01",
      "maxTraysQueued": 6,
      "destinationWall": "WALL-AFE-01"
    }
  ]
}

Data Usage in Process Path

Zone-Based Routing

Process Path uses zone data for routing decisions:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

function evaluateZoneAffinity(shipment, zone) {
  // Check if shipment's pick locations are in this zone
  const pickLocations = shipment.allocations.map(a => a.warehouseLocation.zone);
  const zoneMatch = pickLocations.filter(z => z === zone.zoneId).length;
  const affinityScore = (zoneMatch / pickLocations.length) * 100;

  // Check zone's supported paths
  const pathCompatible = zone.supportedPaths.includes(shipment.assignedPath);

  return {
    affinityScore,
    pathCompatible,
    recommendations: pathCompatible ? [] : ['CONSIDER_ALTERNATE_PATH']
  };
}

Conveyor Path Calculation

Process Path uses conveyor topology for routing:

1
2
3
4
5
6
7
8
9
10
11
12
13

function calculateConveyorPath(origin, destination) {
  const topology = getCachedTopology();

  // Find path through conveyor network
  const path = findShortestPath(topology, origin, destination);

  return {
    segments: path.segments,
    totalDistance: path.distance,
    estimatedTransitTime: path.distance / avgSpeed,
    divertPoints: path.diverts
  };
}

AFE Wall Assignment

Process Path uses AFE config for wall/chute assignment:

1
2
3
4
5
6
7
8
9
10
11

function selectRebinWall(shipment, afeConfig) {
  const availableWalls = afeConfig.rebinWalls.filter(wall => {
    const utilization = getWallUtilization(wall.wallId);
    return utilization < 90; // Not critical
  });

  // Select wall with best availability
  return availableWalls.sort((a, b) =>
    getWallUtilization(a.wallId) - getWallUtilization(b.wallId)
  )[0];
}

Caching Strategy

Data Type Cache Key TTL Invalidation
Warehouse layout location:warehouse:{id} 1 hour On LayoutChangedEvent
Zone details location:zone:{id} 15 min On ZoneUpdatedEvent
Conveyor topology location:conveyors:{warehouseId} 15 min On TopologyChangedEvent
AFE configuration location:afe:{id} 15 min On AFEConfigChangedEvent

Cache Implementation

1
2
3
4
5
6
7
8
9
10

@Cacheable(value = "location-zones", key = "#zoneId", ttl = 900)
public ZoneDetails getZoneDetails(String zoneId) {
    return locationMasterClient.getZone(zoneId);
}

@CacheEvict(value = "location-zones", key = "#event.zoneId")
@EventListener
public void handleZoneUpdated(ZoneUpdatedEvent event) {
    log.info("Zone cache evicted for: {}", event.getZoneId());
}

Events Consumed (for Cache Invalidation)

LayoutChangedEvent

Topic: location-master.layout.changed

1
2
3
4
5
6
7
8
9

{
  "type": "com.paklog.location.layout.changed.v1",
  "data": {
    "warehouseId": "WH-001",
    "changeType": "ZONE_ADDED",
    "affectedZones": ["ZONE-C"],
    "effectiveAt": "2025-01-20T10:00:00Z"
  }
}

ConveyorStatusChangedEvent

Topic: location-master.conveyor.status

1
2
3
4
5
6
7
8
9
10

{
  "type": "com.paklog.location.conveyor.status.v1",
  "data": {
    "conveyorId": "CONV-MAIN-01",
    "previousStatus": "RUNNING",
    "currentStatus": "STOPPED",
    "reason": "MAINTENANCE",
    "estimatedRestoreTime": "2025-01-20T11:00:00Z"
  }
}

On conveyor status change:

1
2
3
4

1. Invalidate conveyor topology cache
2. Recalculate affected routes
3. Adjust routing to avoid stopped conveyors
4. Notify WES of capacity impact

Zone Restriction Handling

Process Path enforces zone restrictions from Location Master:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{
  "routingDecision": {
    "shipmentId": "SHP-123456",
    "hasHazmat": true,
    "evaluatedZones": [
      {
        "zoneId": "ZONE-A",
        "hazmatAllowed": false,
        "eligible": false,
        "reason": "HAZMAT_RESTRICTED"
      },
      {
        "zoneId": "ZONE-B",
        "hazmatAllowed": true,
        "eligible": true
      }
    ],
    "selectedZone": "ZONE-B"
  }
}

Divert Point Configuration

Process Path uses divert configuration for physical routing:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "divertDecision": {
    "shipmentId": "SHP-123456",
    "assignedPath": "AFE",
    "toteId": "TOTE-789",
    "divertPoint": "DIVERT-AFE",
    "divertPosition": 100,
    "destinationStation": "AFE-INDUCT-01",
    "divertCommand": {
      "conveyorId": "CONV-MAIN-01",
      "divertId": "DIVERT-AFE",
      "direction": "LEFT",
      "toteBarcode": "TOTE-789"
    }
  }
}

Error Handling

Error Action
Location Master unavailable Use cached data
Cache miss + API failure Use default zone config
Invalid zone reference Log error, route to default
Conveyor topology stale Refresh on next request

Performance Metrics

Metric Target Description
Cache hit ratio > 95% Reduce API calls
API response time < 50ms When cache miss
Topology refresh time < 5s Full refresh
Zone lookup time < 10ms From cache

Monitoring

Key Metrics

Alerts