What are we building?

This guide will describe how to capture route stop task completions by:

1. Configuring a document submission webhook notification
2. Retrieving the full document object using the Documents API

Configure a Document Submission Webhook Notification

See the Webhooks guide for details on how to create a webhook. Specifically, you'll want to configure a Document Submission alert to send to the webhook.

Once you've configured the webhook and the alert, you'll receive a JSON payload like the following whenever a document is submitted:

{
  "eventId": "73746344-4b76-4e2a-ba19-3fa04b2f7038",
  "eventMs": 1587567280773,
  "eventType": "Alert",
  "event": {
    "alertEventUrl": "https://cloud.samsara.com/o/53729/alerts/incidents/v2/159570/5/1654973/1587567275566",
    "alertConditionDescription": "Document Submission",
    "alertConditionId": "DriverDocumentSubmitted",
    "details": "A Stop Tasks document was submitted by Tyler Freckmann at Wed, 22 Apr 2020 7:54am PDT. Document: https://cloud.samsara.com/o/53729/groups/54868/fleet/reports/documents/1654973/1587567275566 (ID: 1654973_1587567275566)",
    "driver": {
      "id": 1654973,
      "name": "Tyler Freckmann"
    },
    "orgId": 53729,
    "resolved": false,
    "startMs": 1587567275566,
    "summary": "Stop Tasks Submitted"
  }
}

In order to retrieve details about the document, you'll need to extract the driver ID and document ID from the webhook payload.

The driver object in the webhook payload contains an id field, which is the driver ID you'll need to retrieve the full document object.

The document ID is located in the details field of the webhook payload, and always has the following structure:

A {documentTemplateName} document was submitted by {driverName} at {submissionTime}. Document: {documentUrl} (ID: {documentId})

You can use regex or other string operations to extract the document ID from this field.

Retrieve the Document

Once you've extracted the document ID from the webhook notification, you can use Fetches a document API to retrieve the full document object.

The GET /v1/fleet/drivers/{driver_id}/documents/{document_id} endpoint allows you to retrieve the document object using the driver ID and document ID collected from the webhook notification payload.

For example, using the payload above, you would perform the following GET request:

GET /v1/fleet/drivers/1654973/documents/1654973_1587567275566

and you would receive the following payload back:

{
  "driverDocument": {
    "orgId": 53729,
    "driverId": 1654973,
    "id": "1654973_1587567275566",
    "driverCreatedAtMs": 1587567275566,
    "serverCreatedAtMs": 1587567281000,
    "serverUpdatedAtMs": 1587567281000,
    "dispatchJobId": 4335797294,
    "notes": "Some notes",
    "state": "Submitted",
    "documentType": "Stop Tasks",
    "vehicleId": 212014918732717,
    "fields": [
      {
        "value": "1234",
        "stringValue": "1234",
        "label": "Load #",
        "valueType": "ValueType_String"
      },
      {
        "value": [
          {
            "value": "Yes",
            "selected": true
          },
          {
            "value": "No",
            "selected": false
          }
        ],
        "multipleChoiceValue": [
          {
            "value": "Yes",
            "selected": true
          },
          {
            "value": "No",
            "selected": false
          }
        ],
        "label": "Did you drop the trailer?",
        "valueType": "ValueType_MultipleChoice"
      },
      {
        "value": 1,
        "numberValue": 1,
        "label": "# of pieces",
        "valueType": "ValueType_Number"
      },
      {
        "value": {
          "dateTimeMs": 1587567264724
        },
        "dateTimeValue": {
          "dateTimeMs": 1587567264724
        },
        "label": "Time unloaded",
        "valueType": "ValueType_DateTime"
      }
    ]
  }
}

See Fetches a document API reference for full details.

Associating a Document with a Stop

The dispatchJobId field of the document will tell you which route stop this document was submitted at.

Alternative Strategies

In addition to capturing stop task completion via webhook handling, you can Track Route Progress and Fetch the route when a desired state change occurs (such as a stop moving into the departed state).

When you fetch the route, the each stop in the stops array will include a documents array, listing the documents (stop tasks) associated with that stop. You can then Fetch the document using its id.