Customer documentation and records

Customer documentation is everything you know about one customer: articles written for them, and records filled in from templates. Records are the facts you would otherwise keep in a spreadsheet per customer, such as VLANs, Wi-Fi networks, the Microsoft 365 tenant, suppliers and alarm codes.

The customer documentation list#

Open Docs and choose Customer documentation to see every customer's articles and records in one list, newest first.

Each row shows the Title, its Type (Article, or the template a record was made from), the Customer, the Site it belongs to (or All sites) and when it was last updated. Articles published to the portal carry an In the portal badge. Filter by Type or Customer to narrow it down.

The customer's Docs tab#

On a customer, open the Docs tab. It has two parts: Documentation, described here, and Accounts, the customer's sign-up addresses and the mail vendors send to them (see Sign-up addresses for customers and Sign-up mail: codes, links and renewals).

On Documentation, on the left are the customer's Folders (see Folders, sharing and history); choosing one narrows everything to it. List and Map switch between the lists and the relationship map (below), and Documentation pack (PDF) makes one PDF of the customer's articles and records. The tab shows:

• Records: one card per template. Each card lists the customer's records of that kind with their site. An empty card shows what is still to document, and its + adds a record of that kind.
• Suggested records: applications on several of the customer's devices that are not documented yet, with Create record. See Records kept up to date and Active Directory snapshots.
• IP addresses, Diagrams and Files and photos. Docs > Diagrams lists every customer's diagrams in one place. See Diagrams, IP addresses and racks.
• Shared with the customer portal: files the customer's people see in the portal's Documents.
• Articles: the customer's own articles, with their status, review and whether they are in the portal. New article writes one for this customer.
• Credentials: the customer's credentials, with any whose password change is overdue called out. New credential adds one. See The credentials vault.

The customer's Overview also shows a short documentation summary.

Adding documentation#

The New button on Customer documentation (and on a customer's Docs tab) offers everything you can add:

• Article: a customer article. It works like a knowledge base article (see Knowledge base articles), except Where it lives is set to A customer.
• Record from a template: pick the template straight from the menu, the built-in ones and your own.

Adding a record#

1. Choose New, then the kind of record under Record from a template. Where you start a record without choosing a kind, Tenvara asks What are you documenting? and shows the templates to choose from.
2. Choose the Customer first: links and secrets belong to the customer, so the rest of the form follows from it.
3. Choose the Site if the record covers one site. Leave it empty when it covers every site.
4. Fill in the fields. Long templates are split into headed sections. Fields marked as required must be filled in.
5. Press Save record, or Cmd+S.

Values are checked against the template when you save: an IP address or range field only accepts an address or a CIDR range, a Web address only a URL, and so on.

Field types you will meet#

Reading a record#

Open a record to see its values grouped by section. Tables of rows show as tables, web addresses and phone numbers as links, and link fields as links to what they point at.

The Linked to panel shows everything the record links to. Press Link to add a link by hand. Press Edit (or E) to change the record.

A record made from a built-in template can be kept up to date from Tenvara's own data (the Microsoft 365 tenant, backups, the network, installed software, Active Directory): switch it on in the Kept up to date from Tenvara card. Filled fields are marked with their source and the rest stay yours. See Records kept up to date and Active Directory snapshots.

The record's ... menu also has Version history (every change kept, with restore), Duplicate..., Share a read-only link..., Print and Download PDF, and its Customer portal card shows chosen fields on the customer's portal. See Folders, sharing and history.

How link fields work#

A Link field creates a real link, so it shows up on both sides:

• A record that links to a credential appears on the credential under Used by.
• A record that links to a device appears on the device page.

If the thing a link field points at is deleted, the field is emptied the next time the record is saved.

Note: People without the credentials permission do not see credential links, in link fields or anywhere else. If they edit and save the record, the links they cannot see are kept.

Relationships and the map#

Records, articles and credentials can be related to each other, for example a line-of-business application to the server it runs on and to its vendor.

1. Open the record, article or credential and press Relate on its Related card.
2. Find the item (a customer's documentation relates to that customer's documentation and the knowledge base).
3. Add a label if it helps: "runs on", "vendor of" and "backs up" are offered, or type your own.

The Related card shows both directions, plus records that point here through a link field and articles that link here in their text.

The Map view on the customer's Docs tab draws it all: the customer's sites, records, credentials and articles, and the devices and contacts the documentation points at, in columns with the connections between them (related by hand, from a record field, linked in an article, and at the site). Point at an item to light up its connections, click to open it, hide kinds with the buttons along the top, or search with Find on the map. You only see what you are allowed to.

Documentation on devices, sites and contacts#

Device, site and contact pages have a Documentation section. It lists the articles, records and credentials linked to them, with credentials shown inline so a technician working on the device has the login in front of them.

From there you can:

• Reveal or copy a username, password or licence key with the buttons beside it (each reveal and copy is logged).
• Press Add credential to add one already linked to this device.
• Press New to add an article or a record.

These pages only ever list documentation of their own customer. Site pages also show the site's Racks and Files and photos, and a device shows the photos and diagrams it is linked to.

When a device moves to another customer#

If a device is moved to a different customer, its links from the old customer's articles, records and credentials are removed, and record link fields that pointed at it are emptied. Each change is noted on that item's timeline, so nothing about the old customer follows the device.