Tasks

Tasks enable you to manage inventory validation workflows by tracking expected items against actual RFID tag reads. Each task is associated with a logical point and can contain one or more documents (such as ASNs, packing lists, or shipping manifests) that define what items are expected at that location.

Overview

Tasks provide a structured way to:

• Validate inventory by comparing expected items against tags read by the RFID reader

• Track progress in real-time as tags are detected

• Identify discrepancies such as unexpected tags or missing expected items

• Manage documents that define expected quantities for specific GTINs or EPCs

• Monitor completion through task states and progress metrics

Tasks are particularly useful for:

• Receiving operations: Validate incoming shipments against Advanced Shipping Notices (ASNs)

• Picking operations: Verify that the correct items are picked for orders

• Cycle counting: Track inventory counts against expected quantities

• Quality control: Ensure all expected items are present and identify unexpected items

Task Lifecycle

Tasks progress through several states during their lifecycle:

1. Pending - Task has been created but not yet started

2. Running - Task is active and processing tag reads

3. Completed - Task has finished successfully

4. Failed - Task encountered an error and cannot continue

5. Cancelled - Task was terminated before completion

Task Components

Logical Point Association

Every task must be associated with a logical point. The logical point defines which antennas (and potentially which readers) are involved in the task. When tags are read by antennas assigned to that logical point, they are automatically processed against active tasks.

Note: Before creating tasks, ensure you have configured logical points in the Logical Points feature.

Documents

Tasks contain one or more documents that define expected items. Each document can be:

• ASN (Advanced Shipping Notice): Defines what should be received

• Packing List: Lists items in a shipment

• Order: Specifies items to be picked or shipped

• Custom Document: Any structured list of expected items

Each document contains a list of expected items with:

• GTIN/EPC codes: The identifiers for expected items

• Expected quantities: How many of each item should be present

• Document ID: A unique identifier for the document (e.g., "ASN-1000456")

Progress Tracking

Tasks automatically track progress as tags are read:

• Total Expected: Sum of all expected quantities across all documents

• Total Read: Number of unique tags that match expected items

• Percentage Complete: Calculated progress percentage

• Matched EPCs: Set of EPCs that matched expected items

• Unexpected EPCs: Set of EPCs that were read but not in expected items

Creating Tasks

Tasks are created programmatically via the REST API or MQTT commands. A task definition includes:

• Task ID: Unique identifier (typically a UUID)

• Logical Point ID: The logical point this task is associated with

• State: Initial state (usually "pending")

• Documents: Array of document definitions

• Created At: Timestamp when the task was created

Example: Creating a Receiving Task

{
  "taskId": "fb2a0f4f-7eaa-4310-a925-3079630539c3",
  "logicalPointId": "DockDoor01",
  "state": "pending",
  "createdAt": "2024-11-01T19:22:11Z",
  "documents": [
    {
      "documentId": "ASN-1000456",
      "mode": "gs1",
      "gs1Items": [
        {
          "code": "00012345600012",
          "expectedQuantity": 24
        },
        {
          "code": "00098765432105",
          "expectedQuantity": 12
        }
      ]
    }
  ]
}

This task expects:

• 24 units of item with GTIN 00012345600012

• 12 units of item with GTIN 00098765432105

Task Processing

Once a task is created and set to "running" state, the system automatically:

1. Monitors tag reads from antennas assigned to the logical point

2. Matches EPCs against expected items in task documents

3. Updates progress as matches are found

4. Tracks unexpected tags that don't match any expected items

5. Publishes progress events via Server-Sent Events (SSE) streams

Tag Matching

The system uses the TDT (Tag Data Translation) engine to decode EPCs and match them against expected GTINs. When a tag is read:

• If the EPC matches an expected GTIN, it's added to matchedEpcs and the totalRead count increases

• If the EPC doesn't match any expected item, it's added to unexpectedEpcs

• Progress percentage is recalculated: (totalRead / totalExpected) × 100

Monitoring Task Progress

You can monitor task progress in several ways:

Real-time Progress Stream

Subscribe to Server-Sent Events (SSE) to receive real-time progress updates:

curl -N \
  -H "Authorization: Basic YWRtaW46YWRtaW4=" \
  -H "Accept: text/event-stream" \
  https://<reader-ip>:8443/api/v1/tasks/task/{taskId}/events

The stream emits progress events whenever the task state or progress changes.

Progress Snapshot

Get the current progress at any time:

curl -H "Authorization: Basic YWRtaW46YWRtaW4=" \
  https://<reader-ip>:8443/api/v1/tasks/task/{taskId}/progress

Response example:

{
  "state": "running",
  "percentage": 75.5,
  "totalExpected": 120,
  "totalRead": 91,
  "matchedEpcs": [
    "30395DFA82CFF54000000444",
    "E2801191A503006075A97238"
  ],
  "unexpectedEpcs": [
    "E2801191A503006075A99999"
  ],
  "message": "Processing..."
}

Managing Documents

You can add, update, or remove documents from an active task:

Add Document

curl -X POST \
  -H "Authorization: Basic YWRtaW46YWRtaW4=" \
  -H "Content-Type: application/json" \
  https://<reader-ip>:8443/api/v1/tasks/task/{taskId}/documents \
  -d '{
    "documentId": "PACKLIST-42",
    "mode": "gs1",
    "gs1Items": [
      { "code": "00098765432105", "expectedQuantity": 6 }
    ]
  }'

Update Document

curl -X PUT \
  -H "Authorization: Basic YWRtaW46YWRtaW4=" \
  -H "Content-Type: application/json" \
  https://<reader-ip>:8443/api/v1/tasks/task/{taskId}/documents/{documentId} \
  -d '{
    "documentId": "PACKLIST-42",
    "mode": "gs1",
    "gs1Items": [
      { "code": "00098765432105", "expectedQuantity": 10 }
    ]
  }'

Remove Document

curl -X DELETE \
  -H "Authorization: Basic YWRtaW46YWRtaW4=" \
  https://<reader-ip>:8443/api/v1/tasks/task/{taskId}/documents/{documentId}

Task Completion

Tasks can be completed in several ways:

1. Automatic completion: When all expected items are matched, the task state can be updated to "completed"

2. Manual completion: Update the task state to "completed" via the API

3. Cancellation: Set the task state to "cancelled" to stop processing

When a task is completed, failed, or cancelled:

• Progress events stop being published

• The task remains in the system for reference

• Tasks are automatically cleaned up after a retention period (default: 1 day)

Integration with MQTT

Tasks can also be managed via MQTT commands. The reader subscribes to task management topics and processes commands:

• Create task: POST command to /api/v1/tasks

• Update task: PUT command to /api/v1/tasks/task/{taskId}

• Get task: GET command to /api/v1/tasks/task/{taskId}

• Delete task: DELETE command to /api/v1/tasks/task/{taskId}

See the MQTT documentation for details on MQTT command format.

Best Practices

1. Use meaningful task IDs: Use UUIDs or structured identifiers that help you track tasks in your system

2. Set logical point before creating tasks: Ensure logical points are configured and antennas are assigned

3. Monitor progress streams: Use SSE streams for real-time updates rather than polling

4. Handle unexpected EPCs: Check unexpectedEpcs to identify items that shouldn't be present

5. Clean up completed tasks: Remove tasks when no longer needed to free system resources

6. Validate document structure: Ensure GTIN codes match the format expected by your tags

7. Use document IDs consistently: Use the same document ID format across your system (e.g., "ASN-{number}")

API Reference

For complete API documentation, including all endpoints, request/response formats, and error codes, see the REST API documentation.

Related Features

• Logical Points - Configure logical points that tasks are associated with

• Validation - Tag validation rules and filtering

• REST API - Complete API reference for task management

• MQTT - MQTT command interface for tasks