A ready-to-use configuration template for building a Retailer Master Directory

Table of Contents

This guide is a configuration reference for building a field visit management system in Clappia. It covers two core apps, a Retailer Master Directory and a Field Visit Logger, and an optional third app for daily GPS route tracking. Each section provides the complete field list, block types, display conditions, formula references, and workflow actions needed to replicate the bundle from scratch.

The intended reader is someone building in Clappia who wants a concrete starting point rather than a conceptual overview. Use this as a checklist alongside your Clappia workspace. Adapt field labels, GPS boundaries, and workflow recipients to your organisation's structure as needed.

App Overview

App	Core Function	Workflows
Retailer Master Directory	Stores all retailer records. Acts as the data source for the visit logger's auto-fill. No workflows.	None
Field Visit Logger	Captures each store visit with OTP and GPS verification, standardised outcomes, and conditional follow-up fields. All automations trigger here.	On save, on review
Daily GPS Tracking (optional)	Records each rep's full day route and links individual visits to the route timeline.	On save, on review

Build order: Always build the Retailer Master Directory first and populate it with retailer records before configuring the visit logger. The visit logger's lookup blocks and GPS comparison depend on master data being present.

Retailer Master Directory

App Settings

Name: Retailer Master Directory
Template: Blank
Sections: One section labelled 'Details'
Drafts: Enabled (for data administrator use)
Authentication: Required

Field Configuration

Field Label	Block Type	Required?	Notes
Retailer ID	Single Line Text	No	Unique identifier per store. Used by visit workflow to link visits to tracking record.
Retailer Name	Single Line Text	No	Used as search key and in notification messages.
Retailer Contact Number	Single Line Text	No	Second search key in the visit logger.
GPS Coordinates	GPS Location block	No	Default to current location on record creation. This is the store's registered coordinates used for proximity check.
Postal Code	Single Line Text	No	Used for the postal code search path and embedded map filter in the visit logger. Adapt label to your region (PIN code, postcode, zip code).
Field Representative Name	Single Line Text	No	Contact assigned to this retailer.
Field Representative Email	Single Line Text	No	Used in visit workflow for owner assignment.
Field Representative Mobile	Single Line Text	No
Territory Manager Name	Single Line Text	No
Territory Manager Email	Single Line Text	No	Used in visit workflow for owner assignment.
Territory Manager Mobile	Single Line Text	No
Zone	Single Line Text	Yes	Required. Used by visit workflow to look up zonal manager contacts.
Region	Single Line Text	Yes	Required. Used by visit workflow to look up regional manager contacts.
Territory	Single Line Text	Yes	Required.

Validation: Block New Records

Add a Validation block with a condition that always evaluates to true on a new submission. Set the error message to: 'New retailer records cannot be created here. Please contact your data administrator.' This prevents field representatives from adding stores through the visit form's lookup and keeps master data under centralised control. Editing existing records remains allowed.

Access

Data administrators: Full access to create and edit retailer records
All other users: No direct access. They interact with this app only through the visit logger's lookup blocks.

Field Visit Logger

App Settings

Name: Field Visit Logger (or Unplanned Retail Visits Logger)
Template: Blank
Sections: One section labelled 'Visit Details'
Submit button label: 'Record Visit'
Authentication: Required
Drafts: Disabled
View submissions: Disabled for field representatives
Post-submission message: Include the Submission ID so reps have a reference number after each visit.

Lookup Block 1: Search by Name or Contact Number

Add a Get Data from Other Apps block. Point it at the Retailer Master Directory. Configure the search to filter by Retailer Name or Retailer Contact Number. When a match is selected, auto-populate the following as read-only pulled fields:

Field to Populate in Visit Form	Source Field in Master Directory
Retailer Name	Retailer Name
Retailer ID	Retailer ID
Retailer Contact Number	Retailer Contact Number
Store GPS Coordinates	GPS Coordinates
Postal Code	Postal Code
Field Representative Name	Field Representative Name
Field Representative Email (raw)	Field Representative Email
Territory Manager Name	Territory Manager Name
Territory Manager Email (raw)	Territory Manager Email
Zone	Zone
Region	Region
Territory	Territory

Lookup Block 2: Search by Postal Code

Add a second Get Data from Other Apps block filtered by Postal Code. When used, this path populates the Postal Code field in the visit form and triggers the display of an embedded analytics view (see GPS Analytics Embed below). All other store detail fields remain empty through this path until confirmed; the postal code path is primarily for area-based discovery rather than full auto-fill.

Email Cleanup Formulas

Contact emails pulled from the master directory may carry stray whitespace from data entry. Add two hidden Formula blocks to produce clean values for the workflow:

Field Representative Email (clean):

TRIM({Field Representative Email (raw)})

Territory Manager Email (clean):

TRIM({Territory Manager Email (raw)})

Fields used: The two raw email fields pulled from the master directory.

What the formulas do: Strip leading and trailing whitespace from the email strings.

What the user sees: These are hidden from the form view. The workflow uses their output values for owner assignment.

OTP Verification

Field / Block	Type	Display Condition	Notes
Authenticator Code	Number block	Show only at initial form state (before first submission)	Rep enters the OTP obtained on-site
Verify OTP	Button block	Same as above	Calls external OTP validation API via REST action. Response stored in hidden 'OTP Response' field.
Valid OTP message	Validation block	Show when OTP Response = success value	Displays: 'Valid OTP'
Invalid OTP message	Validation block	Show when OTP Response = failure value	Displays: 'Invalid OTP'. Blocks submission.

‍

GPS Capture and Proximity Check

Field	Type	Display Condition	Notes
Store GPS Coordinates	GPS Location (read-only, pulled)	Always visible after retailer selected	Pulled from master directory. This is the reference point for the proximity check.
Your Current Location	GPS Location block	Visible after Retailer ID is populated (i.e. retailer has been selected)	Captures rep's live coordinates. Compared against store coordinates.
Distance diagnostic	Formula or read-only field	Visible to support users only	Shows haversine distance in metres between the two coordinate sets. Not shown to field reps.

‍

GPS proximity validation: Add a Validation block that checks the distance between Your Current Location and Store GPS Coordinates. Set the boundary to 200 metres (adjust for your territory type). Error message: 'Your current location is more than 200 metres from this store. Please confirm you are at the correct location.' This blocks submission until the check passes.

GPS Analytics Embed

Add an embedded analytics view (a filtered report) that shows registered retailer locations on a map. Set its display condition to show only when the Postal Code field (populated by the postal code lookup path) has a value. This gives reps who search by postal code a visual reference of stores in that area. It does not appear for reps who use the name or contact number search path.

Visit Outcome Fields

Field	Type	Required?	Display Condition
Shop Open	Single Selector (Yes / No)	Yes	Always visible
Order Placed	Single Selector (Yes / No)	Yes	Always visible
Additional Products Required	Long Text	No	Visible only when Order Placed = No
Next Visit Date	Date block	Yes (when visible)	Visible only when Order Placed = No

Remaining Fields

Submitter Name: Auto-populated from the logged-in user account. Always visible.
Submitter Email: Auto-populated. Display condition: visible only after the record has been saved (post-submission state). Used by the workflow to key the daily tracking record.
Guidance text: An HTML Text block explaining how to update a retailer's GPS coordinates via the dashboard if the stored location is inaccurate.

Field Visit Logger Workflows

Open Design App and then Workflows in the Field Visit Logger. Configure the New Submission Flow (on save) with the following actions in order:

Action 1: Assign Territory Manager as Owner

Add an Add Owner action. Set the owner email to the Territory Manager Email (clean) formula field. This gives the territory manager immediate visibility into the visit record.

Action 2: Look Up and Assign Regional and Zonal Contacts

Add a Get Data from Other Apps action in the workflow that queries a regional and zonal contacts mapping app using the visit form's Zone and Region values. Map the returned contact emails to variables. Add those emails as additional owners using separate Add Owner actions. If you do not have a contacts mapping app yet, use static email addresses per zone and region as a starting configuration and replace them with the dynamic lookup once the mapping app is built.

Action 3: Follow-Up Reminder (Conditional)

Add a Condition block: Order Placed = 'No'. Under the matching branch, add a Wait node configured to pause until the Next Visit Date at approximately 9 AM. After the wait, add a Mobile Notification action addressed to the submitter:

Reminder: Follow up with {Retailer Name} today. Products discussed: {Additional Products Required}

Action 4: Update Daily Tracking Record

Add an Edit Submission action that finds the submitter's current day tracking record (queried by Submitter Email and today's date in the Daily GPS Tracking app) and updates it with the Retailer ID of the current visit. If no tracking record exists, this action fails silently without affecting the visit submission.

Action 5: Push to External System

Add a REST API action that sends the visit payload to your external CRM or reporting system. Map the following fields in the request body:

Payload Field	Source
submissionId	Clappia Submission ID (system variable)
submitterEmail	Submitter Email
retailerId	Retailer ID
retailerName	Retailer Name
orderPlaced	Order Placed
nextVisitDate	Next Visit Date
additionalProducts	Additional Products Required
visitTimestamp	Submission created timestamp

‍

Configure error handling so a failed external push does not block the Clappia submission from saving. The on-review workflow can retry the push by applying a sync status to the record.

Daily GPS Tracking App (Optional)

App Settings

Name: Daily GPS Tracking
Template: Blank
Authentication: Required
Drafts: Disabled

Field Configuration

Field	Type	Notes
Date	Date block	Required. Default to today.
Role	Single Selector	Options: Field Representative, Territory Manager. Pre-set and not editable by end users.
Live Tracking	Live Tracking block	Starts GPS route recording on activation. Auto-stops after 12 hours if not manually stopped. Immediately creates the tracking record when activated.
Starting GPS Location	GPS Location (read-only)	Populated post-submission. Shows where the tracking session began.
End GPS Location	GPS Location (read-only)	Populated post-submission.
Travel Start Time	Time (read-only)	Populated post-submission.
Travel End Time	Time (read-only)	Populated post-submission.
Distance Travelled	Number (read-only)	Populated post-submission. Total distance in kilometres.
Submitter Email	Single Line Text (auto)	Stored for deduplication and workflow keying.
Submitter Name	Single Line Text (auto)	Stored for external payload.

‍

Validation: One Session Per User Per Day

Add a Get Data from Other Apps block that queries the Daily GPS Tracking app filtered by Submitter Email and today's date. Add a Validation block that fires when a matching record is found, showing: 'You have already started a tracking session today.' This prevents duplicate tracking records for the same user on the same date.

On-Save Workflow

Owner assignment: If Role = Field Representative, look up the correct territory manager email from a contacts mapping app using the submitter's email or phone. Add as owner. If Role = Territory Manager, apply equivalent logic.
External tracking summary: Add a REST API action (with a short Wait node to allow the tracking session to initialise) that sends the tracking payload: Submission ID, submitter name, role, date, starting and ending GPS, travel times, and distance.

Launch Checklist

Item	Done?
Retailer Master Directory built and all retailer records imported
GPS coordinates verified for at least a sample of retailer records
Visit logger lookup blocks pointed at the correct master directory app
OTP API endpoint configured and tested with a real device
GPS boundary set appropriately for your territory type
Email cleanup formulas verified: TRIM output matches expected email format
Workflow owner assignment tested: correct managers receive access on first visit
Follow-up reminder tested: mobile notification fires on Next Visit Date at 9 AM
External system push tested: visit payload arrives correctly formatted
Daily tracking linkage tested: visit record updates tracking session correctly
Field rep permissions configured: submit-only access, no view of other reps' records
Territory manager permissions configured: view access to their territory's visits
At least one end-to-end test completed using the Clappia mobile app on a real device
Offline submission tested: visit syncs and workflow fires on reconnect

‍

Adapting This Template for Other Contexts

The bundle described here is built around retail field visits, but the underlying pattern applies to any field operations scenario where teams visit multiple fixed locations and need to record outcomes with presence verification. The following adaptations require changes to field labels and workflow recipients only, with the core logic remaining the same:

Service technician visits: Replace 'Order Placed' with 'Service Completed' and 'Additional Products Required' with 'Parts Required'. Replace retailer classification fields with client or site type classifications.
Healthcare field visits: Replace store outcome fields with patient visit outcomes. OTP and GPS verification remain applicable for compliance purposes.
Facility inspections: Replace order and product fields with inspection result fields. The GPS proximity check confirms the inspector was at the correct facility.
Distribution or logistics stops: Replace 'Order Placed' with 'Delivery Confirmed'. The follow-up reminder branch handles exceptions where delivery could not be completed.

In each case, the Retailer Master Directory becomes a Location Master Directory, the visit form's lookup pulls location data instead of retailer data, and the workflow's owner assignment is adapted to the management hierarchy relevant to that industry.