Custom fields and formulas

Configuration

Custom fields and formulas

Entity fields let users pick a record you already keep in SmartLIMS, such as a customer, instead of typing it. Value formulas then fill in other fields from that choice, so the same address or date is never typed twice.

Who this is for: Laboratory owners and administrators · You need: the "Manage forms" permission (and "Manage predefined fields" to set up entity fields in the library)

The idea in short

A field of type Entity shows a searchable list instead of a text box. Users pick a laboratory, a user, a customer, an inspector, a country or a price-list item, and the request stores that choice.

A value formula is a short rule on a field that fills it in automatically. For example, a "Customer address" field can fill itself from the customer the user just picked. Formulas recalculate while the user fills in the request. They stop as soon as the user types into the field by hand, so a manual correction is never overwritten.

You set up both on the form edit page. See Forms and report templates for the rest of the form.

How to add an entity field

  1. Open Settings, then Forms, and open a form.
  2. Click Add general field or Add item field.
  3. Fill in Field name and Label, and set Type to Entity.
  4. Choose the Entity type (see the table below).
  5. Tick Multiple if users may pick more than one record.
  6. Set the Display template: how each picked record is shown. Left empty, a user or an inspector shows as their name (an inspector with their title, as reports print it) and every other record by its name. Click Insert attribute to add another attribute, for example a customer's city.
  7. Optionally choose a Default value. For an entity field this is a picker, not a text box.
  8. Click Save changes.

📷 Screenshot: a field card with Type set to Entity, the Entity type list open and the Display template below it

Entity type Where the records come from Attributes you can use
Laboratory your laboratories, see Lab setup Name, Type, Location, Examination type
User the people who can sign in, see Users and roles First name, Last name, Email
Customer your customers, see Contacts Name, City, Address, Official email, Contact person, Contact email, Contact phone
Inspector your inspectors, see Contacts Title, First name, Last name, Work position, Ministry, Email, Phone
Country every country in the world, named in the page's language; the request keeps the two-letter ISO code Name, ISO code
Price list item (Financial) the price list in SmartLabSys Financial, see Financial Code, Name, Unit, Category

If an entity type has no list to pick from, the card shows "No data source configured for this entity type."

How to add a price-list field

A price-list field lets users choose what to charge from the price list kept in Financial. The codes they pick are passed on to Financial with the request.

  1. Add an entity field and set Entity type to Price list item (Financial).
  2. To offer only part of the price list on this form, fill in Price-list categories or Price-list items (codes), separated by commas. "This form offers only the price-list items in these categories or with these codes. Leave both empty to offer the whole price list."
  3. Click Save changes.

If your company is not connected to Financial, the list on the request page is empty and a message under the field explains why.

How to write a value formula

  1. On a field card, click into Value formula.
  2. Click Insert field and choose the field and value you want. SmartLIMS inserts the right reference for you.
  3. Add any text you want between references, such as a comma or a space.
  4. Click Save changes.

A formula starts with exp- (fill in text) or date- (calculate a date).

You want Formula
The customer's address exp-{customer}.record.address
The customer's name and city exp-{customer}.record.name, {customer}.record.city
The inspector's full name exp-{inspector}.record.firstName {inspector}.record.lastName
Exactly what another field holds exp-{batch}.value
Today's date date-now
Tomorrow date-now+1day
Three days ago date-now-3days
Five days after the sampling date date-{sampling_date}+5days
Two days before another date date-{sampling_date}-2days

Here customer, inspector, batch and sampling_date are the Field name values of fields on your form.

Date offsets are counted in days and forgiving about how they are typed: date-now+7days, date-now + 7 days, date-now+7d and date-{received}-3 Days all work. A date formula fills a date field on the request like any other field.

  • .value gives what the other field holds.
  • .record. followed by an attribute gives an attribute of the record picked in an entity field. Use the attribute names that Insert field offers.
  • When an entity field allows Multiple, the attributes of all picked records are joined with commas. To join them with something else, put it in square brackets at the end, for example exp-{laboratories}.record.name[; ].

Rules

Rule What it means
Which fields a formula can use A general field can use other general fields. A sample field can use the fields of the same sample and the general fields.
When it recalculates Every time a field it depends on changes, while the request is being filled in. date-now is set once, when the page opens.
Manual edits win Once a user types into the field, or once the field already has a saved value, the formula no longer changes it.
Mistakes don't break the page A formula that can't be read, refers to a missing field, or depends on itself in a loop is skipped. The rest of the page works normally.
Where formulas live Only on form fields. Predefined fields don't have formulas; add the formula after you pick the field into a form.

Tips

  • Give fields short, stable Field name values. A formula breaks quietly if you rename the field it refers to.
  • After you add a formula, open a new request with the form and check that the field fills in as you expect.
  • Use a formula for values users usually accept but sometimes change, like a due date. They can overwrite the suggestion.
↑↓ to move ↵ to open esc to close