Datasets define the information used in an Auclio application.

What a dataset is #

A dataset is a collection of objects that all share the same structure. Each object represents one business item, and the dataset’s properties define what is stored about it.

For example, accounts, contacts, projects, requests, and incidents are each a dataset. One account, one contact, and one request are objects within them.

A dataset is created inside one application and belongs to that application. Widgets read from it, workflows move its objects through states, and permission rules decide who can see them.

Datasets, objects, and properties #

Three terms are used throughout this documentation.

Dataset #

A dataset represents one type of business information, such as accounts, projects, or requests. All objects in a dataset use the same set of properties.

Property #

A property defines one piece of information associated with an object, such as Account name, Country, or Annual revenue. A property has a data type, which decides what kind of value it can hold.

Object #

An object is one individual item in a dataset: one company in an Accounts dataset, or one project in a Projects dataset.

A simplified dataset could look like this:

Each row represents an object, and each column represents a property.

Dataset examples #

A customer management application might use four datasets:

• Accounts — the companies you do business with;
• Contacts — the people who work at those companies;
• Opportunities — potential sales;
• Activities — calls, meetings, and tasks.

An Accounts object might hold:

• Account name
• Account owner
• Country
• Industry
• Number of employees
• Annual revenue
• Customer status

Notice that each dataset covers exactly one kind of thing. Contacts are not stored as extra properties on an account, because a company can have many contacts and each contact has its own information.

How datasets are used in applications #

Datasets provide the data displayed and managed through widgets.

The Table widget, the Text Grid widget, and the Form widget can all be connected to a dataset. A dataset does not automatically appear on an application page. It must first be connected to one or more widgets.

The Text widget, the Card widget, and the Button widget are not connected to a dataset. They show values passed to the page as parameters, written as $(parameterName) inside a text or address field.

The same dataset can be used by any number of widgets on any number of pages. A list on one page, a details block on another, and a form for adding new objects can all read from a single Accounts dataset.

Internal and connected datasets #

Every dataset uses a connection, and the connection decides where the objects physically live.

An internal dataset uses the built-in connection that Auclio creates with every application. The objects live in Auclio and are managed only there. Nothing else needs to be installed, and you have complete control over the properties.

A connected dataset uses an external connection to another system. Today that means M-Files. The objects live in the M-Files vault, and Auclio reads them, displays them, and writes changes back. The vault remains the source of the information, so its object types, metadata properties, value lists, and workflows shape what the dataset can hold.

One application can use both kinds at the same time. A common pattern is to keep documents and their metadata in M-Files, and to hold supporting information that does not belong in the vault in internal datasets.

The connection is chosen when a dataset is created and cannot be changed afterwards.

See Understanding connections for detailed instructions on connection types, and Connect Auclio to M-Files for M-Files connectivity.

Relationships between datasets #

Applications often use several datasets, and objects in one dataset frequently refer to objects in another. A contact belongs to an account. A task belongs to a project. An opportunity belongs to both an account and a contact.

In Auclio, a relationship is a property with the Dropdown data type that points at another dataset. Selecting a value in that property does not copy the other object’s information; it records which object was chosen. The information stays in one place, and a change made there is reflected everywhere the object is referenced.

Relationships are what make it possible to build an account details page that lists that account’s contacts, or to filter opportunities by industry without storing the industry on every opportunity.

See Connect related datasets for detailed instructions on creating and using relationships.

Planning a dataset #

Before creating a dataset, define:

• what type of information the dataset should contain;
• what one object represents;
• which properties are required;
• which properties are optional;
• which property identifies an object to a person reading it;
• whether objects need to be related to another dataset;
• whether objects move through states, and therefore need a workflow;
• who should be able to view or edit the objects;
• whether the data will be managed in Auclio or retrieved through a connection.

Keep each dataset focused on one type of object. Avoid combining unrelated information in the same dataset.

The question about what one object represents is the one worth spending time on. If you cannot finish the sentence “one object in this dataset is one …” in a few words, the dataset is probably covering two things and should be split.

Naming recommendations #

Use clear and consistent names.

For datasets, use plural names that describe the objects they contain:

• Accounts
• Contacts
• Projects
• Requests
• Expenses

For properties, use specific names that describe the value:

• Account name
• Project owner
• Request status
• Annual revenue

Avoid vague names such as Information, Value, or Details unless their meaning is clear from the context. Avoid abbreviations that only your team would recognize, because these names appear as column headings and field labels to everyone who uses the application.

Property names are also the basis for the internal key Auclio generates, so it is worth getting them right at the start.

Before changing or deleting a dataset #

Before changing or deleting a dataset or property, check where it is used. Removing it may affect pages, widgets, workflows, or permission rules that depend on it. A property that is in use cannot have its data type changed or be removed. The dataset list shows a Used in count, and opening it lists every page, related dataset, and child dataset that depends on the dataset.

Other changes are allowed but still worth checking:

• renaming a property changes the label everywhere it appears;
• making a property required affects objects that were created without a value;
• changing the property marked as Name changes how objects are labelled throughout the application;
• narrowing a property’s allowed values may leave existing objects outside the new range.

Review the dataset’s usages before making any of these changes, and test with a few objects before applying them to a dataset in daily use.