Capture data in the field

Capturing data on the mobile app means filling in a form, attaching a photo or document, stamping a location, collecting a signature or scanning a barcode, and saving it so it reaches xMatix even when you have no signal. These tools do not appear on every screen. Each one appears only where your organization's mobile layouts put it, so two record types, or two colleagues on different apps, can see different tools. This page covers each tool, what happens when you save, and which tools need a connection.

Overview

When to use it

• Use a form for any record your app lets you create or change: an outlet, an order, a service report.
• Use Attachments for supporting documents such as an ID proof, a shop photo or a signed delivery note.
• Use the visit's own tasks for photos and signatures during a visit. They queue offline, so they are the safest choice where the signal is poor.
• Use scanning whenever a product or a code is printed on the item. Scanning avoids typing errors.

How xMatix handles it

• One save, then a queue. When you save, the app tries the server first. If the server is out of reach, the change goes into a queue on the phone and is sent later. You can see that queue under Preferences → Sync status (see Working offline).
• Offline saving is per record type. A record type can be saved offline only if it is in your mobile app's offline list and is allowed to be edited offline. On any other type, the form tells you that you're offline and refuses to save.
• Files follow their record. Files picked on a new record are held with the form. They upload as soon as the record is saved, and when you are offline they queue behind the record itself.
• Photos are compressed, not resized. Camera and gallery photos are re-encoded at a lower quality to keep uploads small. Their dimensions are kept.
• Location is stored as a field, never hidden in the photo. The app does not read location data from photos. Where a form records where a photo was taken, it writes the location into a location field on the record that you can see.

Prerequisites

• The xMatix mobile app, signed in, with the first download complete (see Get started with the mobile app).
• Create or edit rights on the record type. Without them, the New button and the Edit menu item do not appear.
• Camera, photo library and location permissions on the phone. The app asks the first time a tool needs one.

Procedure

Step 1 — Start a new record or open one for editing

To create a record, open its list and tap the round + button at the bottom. Its label names the record type, for example New order, and it shrinks to just the icon while you scroll. The button appears only when you have create rights and the list has a New action available on mobile.

To change a record, open it, tap ⋮ in the header and choose Edit. Edit is hidden while a background job is still processing the record.

The form opens with any default values your administrator set. The button at the bottom reads Create <record type> or Update <record type>, unless the layout gives it its own label.

Step 2 — Fill in the form

Work through the form from top to bottom. While a required field is empty, the main button is greyed out. If you tap it anyway, the app scrolls to the first problem. It shows a toast such as 2 fields need attention: Account, and the field itself reads <Field> is required.

Lookup fields such as Account or Item search the records on your phone first. When a lookup finds nothing while you are offline, it says Not available offline.

Forms that open as a sheet protect your work. If you close the sheet with unsaved changes (×, Cancel, swiping down, tapping outside it or pressing the Android back button), the app asks Discard changes? with Keep editing and Discard. A form that fills the whole screen has no such prompt, so save before you leave it.

Step 3 — Save, online or offline

Tap the main button once. While it works, it reads Saving…. Then read the message:

Queued changes appear under Preferences → Sync status → Changes. If the server later rejects a queued change, it moves to Needs attention with the reason. Tap Fix, and the form opens pre-filled with your values. Correct the field and save. This resends the same queued change, so no duplicate record is created. See Fix a rejected change.

Step 4 — Attach photos and files

The Attachments section (its title may differ) offers up to three buttons: Camera, Gallery and File. Your administrator can limit it to fewer. A camera-only section means a fresh photo is required.

• On a new record, pick or take the file before you save. The section reads Attached to the record the moment it is saved., and each file waiting to go shows Uploads when the record is saved. Save the record, and the files upload with it, or queue with it if you are offline. If a file cannot be queued, you see Saved, but <file> could not be attached. Add it from the record.
• On a saved record or an edit form, each file uploads immediately and needs a connection. Offline, the list shows Not available offline, and an upload you try anyway fails with Upload failed. Add the file again once you are online.

Tap a file in the list to preview it: images can be zoomed and PDFs open in the app. The bin icon removes a file. On a saved record it asks Delete attachment first. A file that is still waiting on a new form is removed straight away.

Some sections need a set number of files. Attach a document before saving. or Attach at least 2 documents before saving. means the record cannot be saved until you add them. Too many files means the section is full. To replace a photo, remove the old one and take the new one.

If the section records the photo's location, the app asks for location access the first time (To record where this photo was taken.). Only photos taken with Camera are stamped, not gallery or file picks. If location is denied, the photo is kept without a location.

Step 5 — Capture a location

A location box reads Capture location. Tap it, and the box shows Finding your location… and then the captured point. Recapture takes it again, and Retry appears after a failed attempt. Some forms capture the location as soon as a new record opens, and some do not allow a recapture once a location is set. Both are layout settings.

If the box reads Location access is off or Allow location access to capture, allow location for the app in the phone's settings, or tap the box to be asked. Location sharing is paused means you paused location sharing for your check-in session. Resume it and capture again.

Step 6 — Capture photos and signatures during a visit

On a visit, photos and signatures belong to the visit's tasks (see Complete a visit). These are the safest captures when the signal is poor. The photo or signature is copied into the app's own storage and queued, so it survives losing the connection.

• Photo tasks. Tap Take photo or Choose from library, check the picture (Retake photo if needed), then tap Submit photo. The toast says Photo uploaded online or Photo stored · uploads later offline.
• Digital Signature. Explain what the customer is signing, let them sign in the box, use Clear to start again, then tap Submit. The task shows ✓ Signature captured, with Re-sign if it needs redoing. The toast Signature submitted appears whether you are online or not; offline, the signature is queued.
• Combined captures such as Customer KYC, Proof of Delivery and Service Order Execution collect photos, signatures and other values on one screen. On submit you see <task> submitted online, or <task> saved · syncs later offline. In Delivery Fulfillment, the signature is opened from the task's menu rather than shown inline, so the customer signs last.

Step 7 — Scan a code into a line field

In line-item editors, fields whose name marks them as a code (serial, batch, lot, IMEI, part, component or barcode) carry a scan icon. Tap it to open a full-screen scanner (Point at the <field> barcode), hold one code in the frame, and the code is typed into the field. Check the value before you save. The scanner reads QR, EAN-13, EAN-8, UPC-A, UPC-E, Code 128, Code 39, Code 93, ITF-14, Codabar, Data Matrix and PDF417 codes, and it works offline because it only fills in the field.

Step 8 — Build a document by scanning

Where your organization added Barcode quick add to a document, the scan screen opens with the camera live. A search box (Search by item name or code) covers labels that will not read.

1. Scan each product. The strip above the list confirms Added <item>. A label that carries its own quantity adds that quantity, for example Added 6 × <item>.
2. Scanning the same product again adds to its quantity. The scanner ignores a code that stays in view, so you have to move the label away and back to count it again.
3. Adjust quantities with the stepper, or remove a line.
4. Read the summary (Total Item, Total Amt) and tap Submit. The toast says N line(s) added successfully, or N line(s) added — will sync when online when you are offline.

If a product is already on the document, the app asks you to choose Skip or Add for it before you can submit. Strip messages tell you when a scan was not added:

• <item> can't be added: the item is not active, not for sale, orders are not allowed for it, or it is no longer stocked.
• This barcode isn’t in the product list: no item matches the code.
• No connection — try this one again: the lookup needed the server and could not reach it. Scan again when you have signal.

Step 9 — Find products in Take Order and the catalogues

In Take Order, tap the Scan a barcode card (Point at the product to jump to it) and scan. The app opens that product and shows Found <item>. Messages such as No product for code <code> or <item> can't be ordered — it is <reason> explain a miss, and Couldn't look up <code> — no connection means you need signal for that code. If the camera cannot start, search by code instead.

Catalogue tiles show the price worked out from the price lists on your phone. Price on sync means no price could be worked out from that data. Don't quote a price until you have synced or checked online. Frequently ordered suggestions in Take Order come from the outlet's order history on your phone and work offline. The separate Frequent Items panel some layouts carry asks the server, so offline it reads Not available offline.

Business rules

• Offline saving needs the record type to be in the mobile app's offline list with offline editing allowed. A type that is not listed can only be saved online.
• Required fields treat an empty value, a blank space or zero in a required number field as missing.
• Fix is offered for queued creates and edits only. A rejected delete or action can be retried or discarded.
• Attachments on a saved record upload directly and are never queued. Files on a new record are queued with the record.
• File size. The server refuses a file above its size limit (50 MB unless your deployment sets another) with File exceeds the maximum allowed size of 50 MB. The app itself checks neither file size nor file type.
• Photo quality. Attachment and visit task photos are re-encoded at 80% quality, and check-in selfies and display-audit photos at 60%. Signatures are saved as PNG images.
• Photo location is stamped only for camera photos, only on create and edit forms, and only where the layout names a location field.
• Scanning adds one of the item's smallest unit per scan unless the layout counts cases. A multi-part label can also fill the quantity and price.
• The Take Order cart is kept on the phone for each outlet and visit until you place the order, so leaving Take Order does not lose it.

Example

A field representative visits a new outlet with poor signal.

1. On the outlet list, they tap the + button. Outlets are editable offline in their app, so the form shows no offline warning.
2. They fill in the name and owner, tap Capture location, and in Attachments tap Camera to photograph the shop front. The photo shows Uploads when the record is saved.
3. They tap the Create … button at the bottom. The toast reads Saved offline — will sync when online.
4. They start the visit and run Barcode quick add on the opening order. They scan six products, scan one of them twice so its quantity becomes 2, and tap Submit. The toast reads 6 line(s) added — will sync when online.
5. Back in coverage, Preferences → Sync status shows the outlet, its photo and the order lines going up in order. The photo waits until the outlet has been created on the server.

Training

Practice exercise

In a sandbox app with an attachment section on a create form:

1. Turn on flight mode and create a record with one camera photo.
2. Confirm the toast Saved offline — will sync when online and the photo row Uploads when the record is saved.
3. Open the saved record and try to add a second photo. Expect Not available offline and Upload failed.
4. Turn flight mode off and open Preferences → Sync status.

Expected result: the record syncs first, then the first photo. The second photo has to be added again online.

Quick reference

• Look for a scan icon, an Attachments section or a location box. If they are missing, the layout doesn't include them; there is no setting on the phone.
• Saved offline — will sync when online means the change is queued, not lost.
• This record can't be saved offline means this record type can only be saved online.
• On a new record, files wait for the record. On a saved record, they need a signal.
• Visit photos and signatures always queue offline.
• Rescanning in Barcode quick add adds 1 each time.
• Price on sync means don't quote a price yet.
• Rejected changes are fixed with Fix in Sync status, not by re-creating the record.

Permissions

The app applies the same record security as the web. New appears only for users with create rights on the record type, and Edit and Delete only with update and delete rights. Your administrator manages these in security profiles (see Security profiles). Deleting an attachment needs the section's delete option to be switched on. Phone permissions (camera, photos, location) are separate, and you can withdraw them in the phone's settings at any time.

Configuration

Administrators shape capture in two places. Changes reach phones without an app update.

Mobile layouts. Open the record type's mobile layout in the mobile designer (Mobile Design, see Design the mobile form) and add or adjust:

The create layout's button label and default values are also layout settings. Scan icons on line fields come from the field's name, not from a setting, so name code fields accordingly (for example Serial Number).

The Mobile App record (Setup → Design Studio → Apps → Mobile Apps → Offline & Sync). Add a record type to the offline list and grant Editable offline so users can save it without a connection. Leave it out to keep it online only. See Configuring the mobile app.

Visit tasks, including photo and signature tasks, are set up in the visit task templates (see Checklists and tasks).

Common problems

"This record can't be saved offline. Reconnect to save."

This record type is not editable offline in your mobile app. Save it when you have a connection, or ask your administrator to add it to the offline list with offline editing allowed.

"Upload failed" when adding a photo

You are adding a file to a record that is already saved, and those uploads need a connection. Add the file again once you are online. If you are on a visit, use the visit's photo task instead, because that queues.

"File exceeds the maximum allowed size"

The file is larger than the server accepts. Pick a smaller file or export the document at a lower resolution.

A barcode scans but nothing is added

Read the strip. This barcode isn’t in the product list means no item has that GTIN or item code, or the item is not on your phone yet; sync and try again. <item> can't be added gives the reason, such as not active or not for sale. No connection — try this one again needs signal.

The scan icon, attachment section or location box is missing

These appear only where your app's mobile layout places them. A colleague on a different app or record type can see a different layout. Ask your administrator.

The record I need says "Not available offline"

The record was never downloaded to your phone. Tap Retry once you have a connection. A record you created offline instead shows Saved on this device — waiting to sync.

Common questions

Are my photos compressed or resized?

They are compressed but not resized. Photos from the camera or gallery are re-encoded at a lower quality so they upload faster, and the picture keeps its original dimensions. Check-in selfies are compressed a little more, and signatures are saved as sharp PNG images. The app does not check file size before upload. The server refuses anything above its limit, so a very large document is refused at upload, not shrunk.

Do photos I take carry my location?

The app does not read location data from photos. When a location matters, it is stored as a visible field on the record. An attachment section can be set to stamp a location field each time you take a photo with the camera; gallery and file picks are never stamped. Check-in and tracking locations are recorded separately, as described in Location tracking.

Can I capture data for a record I have not synced?

You can create new records offline for any record type that is editable offline, and edit records already on your phone. You cannot open or edit a record that was never downloaded, because there is nothing on the phone to change. The record screen then says Not available offline. If a record type you need is routinely missing, ask your administrator about its offline scope.

Does the form keep a draft if I leave it?

Forms do not save drafts. A form opened as a sheet warns you before discarding unsaved changes, but a full-screen form does not. The exception is Take Order: the cart is kept on your phone for each outlet and visit, even if the app is closed, until you place or clear the order.

Why does rescanning add another unit?

Barcode quick add counts physical items, so scanning the same product twice means two units. To prevent accidental double counts, the scanner ignores a code that stays in front of the camera. Move the label out of view and back to count it again. If you over-count, lower the quantity with the stepper before you submit.

Related topics

• Working offline: sync status and recovery
• How offline-first mobile works
• Complete a visit on mobile
• Create an order
• Configuring the mobile app
• Design a form layout
• Location tracking on mobile