Samsara Ground Intelligence

The Samsara Ground Intelligence output in ArcGIS Velocity updates Ground Intelligence issues and creates or updates watchpoints in Samsara. The output pairs with the Samsara Ground Intelligence feed to close the loop between Samsara and external systems.

Learn more about the Samsara API

Examples

The following are example use cases for the output:

A city public works agency tracks pothole repairs in its work order system. A real-time analytic receives each work order as it is closed and uses the Resolve issue operation to set the matching Samsara road issue to resolved, using the issue ID stored on the work order. This keeps the Samsara issue list current without crews updating each issue manually.
A county road maintenance department collects repair reports from crews in a field app. When a crew reports that a pothole has been temporarily patched, a real-time analytic uses the Update issue type operation to change the Samsara issue type to patchedPothole. The issue stays open for follow-up while the repair status is reflected in Samsara.

Usage notes

Note the following when working with the output:

This output is available for real-time analytics and big data analytics. Ground Intelligence uses the US Samsara API endpoint (api.samsara.com). Velocity does not expose region as a configurable setting.
Both a Samsara subscription that includes Ground Intelligence and an API key are required. Testing the connection requires the Read Ground Intelligence Issues scope and does not verify write access. The required write scope depends on the operation:
- Issue operations require the Write Ground Intelligence Issues scope.
- Watchpoint operations require the Write Watchpoints scope.
A Dismiss issue operation requires a dismissal reason. The Update issue status operation cannot set an issue to dismissed.
An Update watchpoint operation requires a Watchpoint ID. At least one of the Observation type, Name, or Note expressions must be configured and return a nonnull value. You cannot update the latitude, longitude, or recurrence mode.

Parameters

The following table describes the parameters for the output:

Parameter	Description	Data type
API key (Required)	The Samsara API token used to authenticate requests. The token must have the Write Ground Intelligence Issues scope for issue operations, or the Write Watchpoints scope for watchpoint operations.	String
Operation	The action to perform for each feature: Resolve issue, Dismiss issue, Update issue status, Update issue type, Create watchpoint, or Update watchpoint. The default is Resolve issue.	String
Additional logging (Optional)	Turn on Enable Request Logging to include HTTP request and response details in the analytic logs. Velocity redacts the API key from these details, but field values may be sensitive. This option is off by default. The Enable Request Logging option is in the Advanced options section. Note: Turn this parameter on for troubleshooting purposes and turn it off when troubleshooting is complete. Once turned on, run the analytic; the additional request details are available at the INFO level on the analytic logs page. Contact Esri Technical Support for help with troubleshooting, if necessary.	Boolean

Parameter

Description

Data type

API key

(Required)

The Samsara API token used to authenticate requests. The token must have the Write Ground Intelligence Issues scope for issue operations, or the Write Watchpoints scope for watchpoint operations.

String

Operation

The action to perform for each feature: Resolve issue, Dismiss issue, Update issue status, Update issue type, Create watchpoint, or Update watchpoint.

The default is Resolve issue.

String

Additional logging

(Optional)

Turn on Enable Request Logging to include HTTP request and response details in the analytic logs. Velocity redacts the API key from these details, but field values may be sensitive. This option is off by default.

The Enable Request Logging option is in the Advanced options section.

Note:

Turn this parameter on for troubleshooting purposes and turn it off when troubleshooting is complete. Once turned on, run the analytic; the additional request details are available at the INFO level on the analytic logs page. Contact Esri Technical Support for help with troubleshooting, if necessary.

Boolean

Operation expressions

Each of the following is an ArcGIS Arcade expression that Velocity evaluates for every feature. Return text values as strings, for example "resolved" or $feature.id, and coordinates as numbers. Use the listed values with the capitalization shown.

Leave optional expressions unconfigured or return null to omit them. For Dismissal note, Name, and Note, return "" to send an empty string.

Parameter	Description	Used by	Returns
Issue ID	An Arcade expression returning a nonempty Samsara issue ID, such as `$feature.id`. Required only for issue operations; do not use the feature layer `ObjectID`. A constant ID targets the same issue for every feature.	Resolve issue, Dismiss issue, Update issue status, Update issue type	Text
Watchpoint ID	An Arcade expression returning the nonempty Samsara watchpoint ID to update.	Update watchpoint	Text
Status	The new status of the issue: needsReview, reviewed, or resolved.	Update issue status	Text
Issue type	The new type of the issue: pothole, roadCracking, or patchedPothole.	Update issue type	Text
Dismissal reason	An Arcade expression returning notMyJurisdiction, knownIssue, duplicate, inaccurateDetection, or other.	Dismiss issue	Text
Dismissal note (Optional)	An optional Arcade expression returning a dismissal note of at most 280 characters after evaluation.	Dismiss issue	Text
Observation type	The type of observation for the watchpoint: roadDefect, utilityCut, guardrail, streetlight, signage, stormDrain, graffiti, vegetation, blight, illegalDumping, littering, highVegetationWeeds, fire, or other. Required to create a watchpoint and optional to update one.	Create watchpoint, Update watchpoint	Text
Latitude	An Arcade expression returning a WGS 84 latitude as a decimal number from –90 to 90. If the geometry uses another spatial reference, project it to WGS 84 before using its y-coordinate.	Create watchpoint	Number
Longitude	An Arcade expression returning a WGS 84 longitude as a decimal number from –180 to 180. If the geometry uses another spatial reference, project it to WGS 84 before using its x-coordinate.	Create watchpoint	Number
Recurrence mode	An Arcade expression returning justOnce, daily, weekly, or monthly for a new watchpoint.	Create watchpoint	Text
Name (optional)	An optional Arcade expression returning a watchpoint name of at most 80 characters after evaluation.	Create watchpoint, Update watchpoint	Text
Note (optional)	An optional Arcade expression returning a watchpoint note of at most 280 characters after evaluation.	Create watchpoint, Update watchpoint	Text

Considerations and limitations

Consider the following when using the output:

If the API key is invalid or does not have the required scope, an error appears in the logs for each feature that Velocity sends.
Each valid feature sent to the output generates one request. Repeated input or upstream replay can repeat an operation, including creating duplicate watchpoints. Filter or aggregate the input to control request volume.
Velocity logs and skips features with invalid expression results. Velocity does not retry failed requests, including rate-limited requests (HTTP 429), and logs each failure, but it continues to process other features.
To obtain the ID returned by the Create watchpoint operation, temporarily turn on the Additional logging parameter and inspect the response. Keep this ID for the Update watchpoint operation; Velocity does not store it as a feature attribute or output parameter.
The output does not retrieve issues for use in the analytic or emit Samsara responses as downstream features. Testing the connection makes a read-only request; it does not evaluate operation expressions or verify write permissions.