Location and the travelled path

The travelled path is the trail of positions the xMatix mobile app records while a field user is checked in, and it lets managers and dispatchers see where the team is now and where they went during the day. It sits between attendance and the work itself: the user checks in, the app records positions until check-out, and you then read the path on the dispatch console map, on a visit plan's map, or in the mobile app. Treat the path as evidence to compare with visits and attendance. On its own it does not prove that someone was or was not somewhere.

Overview

Location tracking is switched off unless your administrator turns it on for a mobile app. When it is on, the app records a position at a set interval for every user who has to check in, from check-in to check-out, and uploads the positions in batches. Each position is stored against the user's resource record. The same data drives three things:

• the current position of each resource (the newest position uploaded so far),
• the travelled path for a day, a time range or a visit plan,
• the freshness counters on the dispatch console (live now, tracking, off grid).

This page covers the manager, dispatcher and administrator side. What the field user sees on the phone (the disclosure, the notification, the permission prompts) is on Location tracking on mobile.

When to use it

• Dispatching: check who is nearest to an unassigned job before you drag it onto someone's lane.
• Reviewing a field day: compare a visit plan's planned stops with the path the rep actually travelled.
• Following up on exceptions: when a visit was recorded with no check-in nearby, or a day looks short, the path is one of the things to look at, together with the attendance punches and the visit records.
• Self-review: a field user can open their own path for today from the mobile app.

How xMatix handles it

Recording is tied to the check-in session. The app records only while the user is checked in and not paused. It starts at check-in, stops when the user pauses, starts again on resume, and stops at check-out. Users who don't have to check in are never tracked, even when tracking is on for the app.

What a position holds. Latitude and longitude, accuracy, speed and heading where the phone supplies them, and the time the phone captured it. Nothing else from the phone is recorded.

How capture works on each phone platform.

So on iOS a path normally has gaps for the time the app was not on screen. That is how the app works on that platform, not a fault.

Uploading. Positions are queued on the phone and uploaded in batches: when the batch reaches the configured size, about once a minute while the app is open, when the app comes back to the foreground, when connectivity returns, and at pause or check-out. Offline positions wait on the phone and go up later, in the order they were captured.

What the server accepts. Each batch is recorded against the resource linked to the signed-in user. The server skips any position stamped more than 3 days in the past or more than 5 minutes in the future, and it refuses a batch of more than 500 positions. A batch that is uploaded twice (after a timeout, for example) is recorded only once. So a phone that stays offline for more than three days loses the oldest positions when it finally uploads.

Link to the check-in. A batch carries the check-in it belongs to when the phone still knows it at upload time. Batches uploaded after check-out (the final batch, or batches that waited offline) go up without that link. When you compare a path with attendance, match on the resource and the time, not on the check-in link.

Current position. After each upload the resource's current position becomes the newest position in the batch. An older batch that arrives late never replaces a newer position.

Long paths are thinned for display. A path request returns at most 2,000 positions. A longer range is split into equal time slices and the first position of each slice is kept, so long straight stretches still draw correctly but short detours can disappear.

Retention. Each position is stamped with a purge date 90 days after it was captured, but no scheduled job deletes positions on that date. Positions are kept until they are deleted another way. If your organization promises a retention period to its employees, agree with your administrator how that is carried out.

Prerequisites

• The field user signs in to the mobile app, has a linked resource record, and belongs to a security profile that has Check-in required on the mobile app's Profiles tab. Check-in itself is set up as described in Attendance.
• Enable location tracking is on for that mobile app.
• On Android, the user has granted location Allow all the time. On iOS, the user has granted location access.
• To read someone else's path or position, their resource must be linked to a user, and that user's role must sit below yours in the role hierarchy (see Permissions).

Procedure

Step 1 — Switch tracking on (administrator)

1. In Setup, open Design Studio → Apps → Mobile Apps and open the mobile app your field users sign in to.
2. On the Check-In tab, turn on Enable check-in / check-out. On the Profiles tab, turn on Check-in required for the profiles that should be tracked.
3. On the Location Tracking tab, turn on Enable location tracking and set Capture interval, Batch size and Minimum distance (see Configuration).
4. Optionally, on the Settings tab, turn on Allow pausing check-in so users can pause the session, which also pauses tracking.
5. Save. Phones pick up the change the next time they fetch the app configuration, for example at sign-in or when the app comes back to the foreground. A session that is already running keeps its current state: the change takes effect at the user's next check-in or resume.

Before the first tracked day, tell your field users what is recorded and when, and that Android phones need Allow all the time.

Step 2 — Check in with tracking (field user)

1. Open the check-in screen. With tracking on, it shows: "While you are checked in, your location is recorded roughly …". The time in that sentence comes from the capture interval.
2. The first time location is needed, the app shows its own explanation, xMatix records your location while you are checked in. Tap Allow location and then answer the phone's permission prompt. Not now leaves the permission unchanged.
3. On Android, if location is not set to Allow all the time, the check-in screen explains why and shows where to change it: Settings → Apps → xMatix → Permissions → Location → Allow all the time. Check-in stays disabled until you change it. Come back to the app and it checks again.
4. Check in. Recording starts. On Android a notification reads "xMatix is tracking your visit path".

Step 3 — Pause, resume and check out (field user)

• Pause (when your administrator allows it) stops recording. Resume starts it again under the same check-in.
• Check-out stops recording, and any positions still queued are uploaded.
• To see your own path for today, open the session sheet and tap View path travelled. It shows the path since midnight on your phone, not since check-in. The row appears only when tracking is on and the app knows your resource.

Step 4 — Read positions and paths on the dispatch console (dispatcher)

1. Open the dispatch console page and switch to Map.
2. Read the summary strip first: live now means a position within the last 15 minutes, tracking within the last 60 minutes, and off grid no position for more than 24 hours (resources with no position at all count as off grid). The alerts ticker also calls out stale positions.
3. Select one or more resources in the left pane. Each one's path for the map's selected day (midnight to midnight in your browser's time zone) is drawn.
4. Use the path for context only. Selecting on the map does not assign work, so go back to Board or Gantt to make changes.

A resource you can't see is not in your hierarchy, has no linked user, or has never uploaded a position. Operating the console is covered in The dispatch console.

Step 5 — Compare a visit plan with the path travelled (manager)

1. Open the visit plan and go to the map on its agenda.
2. Turn on Path travelled. The map draws the path recorded for the plan.
3. The path belongs to the plan's Executed By resource, or to its Assigned To resource when no one has executed it. It covers the plan's actual start to actual end, or the planned start and end when the actual times are empty, or up to now when there is no end.
4. Compare the path with the planned stops and the visit records. Look for gaps first: iOS devices, pauses, offline stretches and days with no check-in all leave gaps that are not absences.

The same Path travelled layer is on the visit plan agenda map in the mobile app. Managers using a mobile allocation console page can open a resource from the current-positions list to see their path.

Business rules

• Tracking runs only when tracking is on for the mobile app, the user has to check in, and the user is checked in and not paused.
• Turning tracking on or off applies from the user's next check-in or resume, once the phone has fetched the new configuration. A session already recording keeps recording until pause or check-out. Positions already recorded are kept.
• Positions are always stored against the signed-in user's own resource. A user cannot upload positions for someone else.
• Positions older than 3 days, or more than 5 minutes in the future, are skipped when they reach the server. Up to 500 positions are accepted per batch.
• The current position only moves forward in time. A late batch never replaces a newer position.
• Path requests return at most 2,000 positions. Longer ranges are thinned by time slice.
• Minimum distance filters positions on the phone when it records in the background. In iOS foreground capture the app records one position per interval, at intervals of no less than 15 seconds.
• Positions get a purge date 90 days after capture, but nothing deletes them automatically on that date.

Example

A field service company switches tracking on for its technician app with a 60-second interval, batches of 20 and a 25-metre minimum distance. Technician A uses an Android phone and Technician B uses an iPhone. Both check in at 09:00.

At 11:30 the dispatcher opens the console map. Technician A shows live now, with a position updated two minutes ago, and the day's path runs through three customer sites. Technician B's last position is 40 minutes old, so B counts under tracking but not live now. B's path shows dots at the first site and then a gap: the phone went into a pocket with the app in the background, and the app records only in the foreground on iOS. The dispatcher calls Technician B rather than reading the gap as an absence, then assigns the urgent job to Technician A on the Board.

At the end of the week the service manager opens Technician A's visit plan for Tuesday and turns on Path travelled. The path matches the planned stops except for a 20-minute detour, which the visit notes explain.

Training

Practice exercise

In a sandbox, with a test mobile app and a test user whose profile has Check-in required:

1. Turn on Enable location tracking with a 30-second interval and a minimum distance of 0.
2. On a test Android phone, sign in, grant Allow all the time, check in, and walk around for ten minutes with the app minimised.
3. Check out. On the web, open the dispatch console map, select the test resource and today's date.

Expected result: the resource shows live now with a path of about 20 positions that follows your walk. The test user's own View path travelled shows the same path. If you repeat the exercise on an iOS phone with the app minimised, the path stops while the app is off screen.

Quick reference

• Tracking is off until an administrator turns it on, per mobile app.
• Only users who must check in are tracked, and only while checked in and not paused.
• Android: background capture, needs Allow all the time. iOS: foreground only.
• Live now is 15 minutes or less, tracking is 60 minutes or less, off grid is more than 24 hours.
• You see your own path and the paths of users below you in the role hierarchy.
• Match paths to attendance by resource and time, not by the check-in link.
• Positions more than 3 days old are dropped when they finally upload.
• Paths longer than 2,000 positions are thinned.
• Positions are kept until deleted. The 90-day purge date is not enforced by a job.

Permissions

Location access does not follow entity permissions or security profiles. It follows only the role hierarchy (Setup → Access Control → Users, role per user). A user with no role, or at the top of a branch of the hierarchy with nobody beneath them, sees only their own position. Being a system administrator does not show you every path. Resources with no linked user never appear for anyone. A user who requests a path they can't see gets no path; on the console that resource simply draws nothing. The role hierarchy is explained in The security model.

Configuration

All settings are per mobile app, under Setup → Design Studio → Apps → Mobile Apps → open the app.

The Location Tracking settings are stored only while tracking is on. When you turn it off and save, the interval, batch size and distance go back to their defaults the next time you turn it on.

The dispatch console's map needs a location configuration on its work entity, and a console can cap the points drawn per path. Both are covered in the field service configuration reference.

Common problems

"Check-in is disabled and asks for 'Allow all the time'"

Tracking is on and this Android phone doesn't allow background location. Change the permission at Settings → Apps → xMatix → Permissions → Location → Allow all the time, then return to the app. If the phone's policy (a managed work profile, for example) won't allow it, an administrator can turn tracking off for that mobile app. There is no per-user exception.

"My technician's position is hours old"

Check in this order: is the user checked in and not paused? Is the phone online? Has the app been opened recently? On iOS, recording stops whenever the app is not on screen. Positions upload in batches, so the current position is only as fresh as the last upload.

"A resource is missing from the map"

The resource has no linked user, the user isn't below you in the role hierarchy, the user isn't in a profile that requires check-in, or they have never uploaded a position. Being an administrator does not widen location access.

"The path has gaps or jumps"

Expected causes: an iOS phone with the app in the background, a pause, an offline stretch longer than three days, the minimum distance filter while standing still, or thinning on a long range. Narrow the time range (one day rather than a week) to see more detail.

"The path doesn't match the check-in"

The final batch and batches that waited offline are uploaded without the check-in link. Compare by resource and time instead.

"The visit plan's Path travelled is empty"

The plan has no Executed By or Assigned To resource, it has no start date, or nothing was recorded for that resource in the plan's window. Check whether that resource was checked in with tracking on during the planned or actual times.

Common questions

Does the app track people when they're not working?

No. The app records only between check-in and check-out, and not while the session is paused. Users who don't have to check in are never tracked. On Android a notification is visible for as long as recording runs, so a user can see at a glance whether it is on. On iOS the app records only while it is open on screen. Positions are stored against the user's own resource, so recording for someone else is not possible.

Can the path prove that a visit happened?

Not by itself. A path shows positions the phone reported, with the accuracy the phone gave, and it has expected gaps: iOS background time, pauses, offline days and thinning. Use it alongside the check-in punch, the visit record, photos and the customer's confirmation. A sparse path is a reason to ask, not proof that the visit didn't happen.

Who can see where I have been?

You, and users whose role sits above yours in your organization's role hierarchy, typically your manager and their managers. Location access does not follow entity permissions or security profiles, and administrators don't see every path automatically. Dispatchers see your position on the console only when you fall inside their hierarchy.

How long are positions kept?

Each position is stamped with a purge date 90 days after capture, but no scheduled job deletes positions on that date, so they are kept until they are deleted. If your organization commits to a retention period, your administrator needs to arrange how older positions are removed.

Why does an iPhone produce a thinner path than an Android phone?

On iOS the xMatix app does not record in the background. It records only while the app is open on screen, at no less than 15-second intervals. Android records in the background until check-out. Plan for this when you compare users or set expectations for path review.

Related topics

• Location tracking on mobile — the field user's view: disclosure, notification, permissions
• Attendance — the check-in session the path belongs to
• The dispatch console
• Visit plans
• Field service configuration reference
• The security model
• The technician's day