> For the complete documentation index, see [llms.txt](https://synap.ac/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://synap.ac/docs/platform/advanced-features/attributes.md).

# Attributes

Attributes are extra structured fields that you can add to users, content and other records in Synap. For example, you could record a student's school year, an exam's awarding body or the internal owner of a collection. Once created, the field travels with that type of record and can be used consistently in forms, filters, imports, exports and integrations where supported.

{% hint style="info" %}
**Location:** Settings → Data management → Attributes

Select **Save** in the Settings header to apply your changes.
{% endhint %}

```mermaid
flowchart LR
  A["Define the field<br/>Target, label, ID and value type"] --> B["Store a value<br/>Each relevant record has its own value"]
  B --> C["Use the value<br/>Forms, filters, exports, integrations and dynamic content"]
```

*Define the field once, store a value on each relevant record, then use that value throughout supported Synap features.*

### Where attributes can be used

The **target** determines which kind of record receives the field. Choose the relevant tab before creating an attribute. Available targets include:

* Users and User Groups;
* Exams, Tests, Attempts, Responses and Questions;
* Collections and Collection Items;
* Notes and Content;
* Assignment Groups and Sub Portals; and
* Records of learning.

An attribute created for Users appears on user records. An attribute created for Collections appears on collection records. It does not automatically appear on every type of content, and values are not copied between targets merely because the fields have similar labels.

{% hint style="info" %}
Choose the narrowest useful target. If “Qualification” describes a learner, create a User attribute. If it describes an assessment, create an Exam or Test attribute instead.
{% endhint %}

### Attribute settings

Each attribute has:

* a **Label**, which is the name administrators and students may see;
* an optional **Description**, which can explain what should be entered;
* a stable **ID**, which imports and integrations use to identify the field;
* a **Value type**, which controls the kind of information it accepts;
* an optional prompt or sublabel to help somebody complete it; and
* controls for who can view or edit the value.

For user attributes, **Collect on registration** adds the field to the registration form.

### Value types

Choose the type that best matches the information you want to collect.

| Type                | Use it for                                                                   | Example                                       |
| ------------------- | ---------------------------------------------------------------------------- | --------------------------------------------- |
| **Text**            | Free-form text. Keep values concise where they will be filtered or exported. | Student ID or department name                 |
| **Number**          | A value that should be treated as a number.                                  | Year group or target score                    |
| **Date**            | A calendar date.                                                             | Start date or renewal date                    |
| **Boolean**         | A single yes or no value.                                                    | Access arrangement approved                   |
| **Single choice**   | One value from a list you define.                                            | Qualification level                           |
| **Multiple choice** | One or more values from a list.                                              | Subjects studied                              |
| **Multiple text**   | More than one free-text value.                                               | External identifiers or previous institutions |
| **Likert scale**    | A response on an ordered scale.                                              | Confidence or satisfaction rating             |
| **Link**            | A web address associated with the record.                                    | External learner profile                      |
| **File**            | A file stored against the record.                                            | Evidence or supporting documentation          |

Select **Add attribute** to create a field. Use the edit action beside an existing attribute to change its configuration.

Choice types require a defined list of options. Use labels that will remain meaningful in reports, and avoid changing an established option to mean something different. For links, available settings can control whether the link appears as a button, how it opens and whether authenticated access is expected.

### Required fields and registration

Making an attribute **required** means a valid value is expected when the relevant record is created or updated through a supported workflow. Test every creation route you use, including bulk import and integrations, before making an established field required.

For User attributes, **Collect on registration** places the field in supported registration flows. The field label and description become student-facing copy, so write them as a clear question and explain why the information is needed. A required field that is not collected during registration may need to be completed by staff through another process.

{% hint style="warning" %}
Do not collect sensitive information simply because a field can be added. Confirm the purpose, access level, retention period and lawful handling of the data first.
{% endhint %}

### Who can view and edit a value

Each attribute can set a minimum level for viewing and editing its value.

| Level             | Typical audience                                         | Example use                                                   |
| ----------------- | -------------------------------------------------------- | ------------------------------------------------------------- |
| **User**          | The person the record belongs to, plus staff with access | Let students view or maintain an appropriate profile field    |
| **Moderator**     | Educator-level staff and above                           | Keep an operational value available to staff but not students |
| **Administrator** | Administrators only                                      | Restrict a sensitive or system-governed field                 |

View and edit are separate. A person may be allowed to see a value without being allowed to change it. Set **Edit** at least as restrictively as **View**, then verify the result with representative roles; labels can vary by area and the effective access also depends on the person's wider portal permissions.

These controls apply to the attribute value. They are not a substitute for the broader permissions that govern whether a staff member can open or edit the underlying user, quiz, exam or other record.

### Labels and IDs

The label is written for people. You can make it clear and descriptive, and it may be changed later when wording needs to improve.

The ID is written for Synap, imports and integrations. Treat it as the field's permanent name. Changing an ID that is already in use can break data imports, exports, dynamic content or integrations that still send the old value.

{% hint style="warning" %}
Before changing or removing an established attribute, check where its ID is used and what existing data has been stored against it.
{% endhint %}

Changing the value type is particularly significant. A text value does not necessarily convert cleanly into a date, number or choice. If an attribute is already in use, create a new field and migrate or re-enter the data unless you have confirmed that the existing values are compatible.

### Plan an attribute before creating it

For each field, decide:

1. which record type owns the value;
2. whether it needs a controlled choice list or free input;
3. who supplies, views and edits it;
4. whether it should appear during registration;
5. which imports, reports, text variables or integrations will use its ID; and
6. how it will be retired if the organisation stops using it.

Use a consistent naming convention and reuse an existing field where it genuinely represents the same concept. Too many near-duplicate attributes make forms and reporting difficult to understand.

### Attributes and tags

Use attributes when a value belongs to a particular record and has a defined format—for example a user's student number or a collection's qualification level.

Use tags when you want to classify and filter questions or other supported content across a shared taxonomy—for example Subject, Topic and Difficulty.

### Check the result

After creating an attribute, add a test value to the relevant record and check every intended workflow. Confirm how the label, empty value, choice options and permissions appear to administrators and students, and verify the value in any import, export or integration that will rely on it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://synap.ac/docs/platform/advanced-features/attributes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.