When you create a topic in Atlas — one particular property, customer or piece of equipment — the form is short: a fixed Classification, a required Name, and two optional fields that are easy to skip and worth understanding: External ID and Properties.
External ID: the cross-reference
The External ID is for cross-referencing. If this property also exists in another system — an accounting package, a scheduling tool, an older database — put that system’s identifier here, and the two can always be matched.
Why it matters
Most businesses don’t replace every tool at once. For a while, and sometimes for good, Atlas sits alongside other systems. Without a shared identifier, matching records between them depends on names, which are rarely identical: “42 Juniper Ln” in one place, “42 Juniper Lane” in another.
An External ID removes the guesswork. Whether you’re reconciling by hand, importing, or building an integration on the Atlas API Client, the ID is a stable key that both sides agree on.
Good practices
- Use the other system’s identifier as-is. Don’t reformat it; the point is an exact match.
- Pick one system of reference per classification. If properties are also tracked in your scheduling tool, use its ID consistently.
- Fill it in at creation. It’s much easier to capture an ID when a topic is created than to backfill hundreds later.
- Don’t overload it. The External ID holds one identifier. If you need to track identifiers from several systems, record the others as properties.
Properties: details at a glance
Topic properties are free-form pairs of a label and a value, for anything you want to see at a glance. In the Atlas tutorial, the topic 42 Juniper Lane gets two: a zone and a visit day.
When to use a property vs. a record
The difference is structure:
| Use a property when… | Use a data record when… |
|---|---|
| It’s a quick label you want visible on the topic | It’s information with a defined shape and rules |
| One value is enough | It has several related fields |
| Validation isn’t important | It must be validated and consistent across topics |
| Examples: zone, visit day, account tier | Examples: address, site details, contact details |
Properties are handy precisely because they’re free-form. That’s also their limit: nothing enforces their spelling or format. If a property becomes important — you start filtering or reporting on it — that’s a sign it should move into a data schema, where it gets a type, a format and a required rule.
Putting them together
A well-formed topic might look like this:
- Name: 42 Juniper Lane
- External ID: the property’s identifier from your scheduling tool
- Properties: Zone = North, Visit day = Tuesday
- Records: a Property Profile holding the validated service address and site details
The name identifies it for people, the External ID identifies it for other systems, the properties summarize it at a glance, and the records hold the structured detail.
Choosing what goes in an External ID
The External ID works best when it holds one stable identifier from one system. A few rules of thumb:
- Prefer a system-generated ID over something people type, such as a name or code that changes.
- Keep it exact. Copy the value as the other system produces it, including any prefix or leading zeros.
- Document which system it refers to in the classification’s description, so nobody has to guess.
- Be consistent within a classification. If properties reference the scheduling system, all properties should.
Using External IDs in an integration
External IDs earn their keep when systems talk to each other. A typical pattern for a nightly sync:
- Read records from the other system.
- For each one, look for a matching Atlas topic by its External ID.
- If a match exists, update the Atlas record; if not, create the topic and store the identifier.
- Log anything that couldn’t be matched for a person to review.
Because the identifier is exact, matching doesn’t depend on names or addresses, which are the usual source of duplicates. See Atlas as the backend for your own applications.
Getting the most from topic properties
Properties are best used as a small, consistent set per classification — the two or three things you want to see at a glance. For properties in a landscaping business, Zone and Visit day are good examples; for equipment, Location and Status might be.
Agree the labels as a team and use them consistently. Because properties are free-form, nothing enforces spelling: “Visit day” and “Visit Day” are different labels, and inconsistency makes them less useful.
When a property should become a schema field
Move information out of properties and into a data schema when any of these become true:
- You want to validate it (a date, a number, a fixed set of choices).
- You want to report on it reliably.
- It’s required for every topic.
- People disagree about how to write it.
The migration is straightforward: add the field to the relevant data schema, publish a new version, and fill it in on each topic’s record.
Frequently asked questions
Is the External ID unique? Treat it as your link to another system’s identifier; keep it unique within the classification by convention so matches stay unambiguous.
Can a topic have more than one external identifier? The External ID field holds one. Record additional identifiers as properties, clearly labelled with the system they belong to.
Are properties visible on forms? Properties belong to the topic, not to a form. Information you collect from people belongs in data schemas.
