Schema editor
Path to function: Preferences > Schema editor
This function also allows you to include selected information about your users in reports which can be shared with others. You are responsible for ensuring you comply with all local rules and legislation relating to sharing this kind of data. For more information, see About reports and privacy.
The schema editor allows domain administrators to define additional attributes (data fields) to be stored on accounts and permission sets and whether they are releasable and reportable. There are three schemas, although other settings may mean some or all are unavailable (if you have a self-registration scheme, for example, the editor is unavailable):
- Personal account - for attributes that apply to an individual, such as name or status. Any attributes sent from local systems must be added here if they are to be released or reported on.
- Permission set - for attributes that should be applied to sets of users such as roles or departments
- Organisation - for attributes that should be applied to everyone, such as organisation names or identifiers
Any attributes you add will appear on the relevant account type or permission set's add and edit pages where you can give them values.
1. Adding custom attributes
Pick the schema first - personal accounts, permission set or organisation.
Add custom attributes by dragging the type of attribute you want from the list on the left to the custom attributes section on the right. You can click and drag custom attributes to change the order they appear in after the core attributes.
Which attribute type you choose depends on what you will be using the field for (see section 3 below) and the tabs at the top will let you assign these custom attributes to accounts, permission sets or organisations depending on whether you want them to apply to individuals, groups or everyone.
The common elements of each attribute type are:
- Target name
How the system will store the attribute. This is how it appears in upload and download files and, if released to service providers, this is the attribute name that is used. If the target name equates to a scoped attribute, OpenAthens will add your scope to it when it is released. It must be unique within your schema.
This name cannot be edited later, but can be transformed in release policies.
The target name is also what reports are linked to if you set the attribute as reportable.
Some target names are reserved for system use.
- Display name
How the field is presented in interfaces such as the account add or modify dialogues and in the reporting interface.
- Required
If this is checked the attribute becomes mandatory and appears alongside other mandatory attributes such as first / last name and email address rather than optional attributes such as fax number. If an account does not have data in a new schema field, it will require a value before you can save any other changes.
- Releasable
Whether or not this attribute can potentially be released to service providers via the release policy.
- Reportable
Whether or not this attribute will be recorded and aggregated for statistics reports (not available on all attribute types). Collection starts after saving, but only for accounts that have the attribute populated with data. Populate it on a test account, do some things with it, and check the next day. - Help text
This appears in the bulk template when you hover over the help flash on the headings.
Some attributes have additional elements
- Default value
Appears on yes/no attributes and date attributes to define the initial value when an account or permission set is created. On date attributes this will be in the form of a number of days ahead of the date when the field is first used - i.e. ahead of when the account or permission set is created.
- Choices
Appears only on the choice attribute and allows you to define the items that appear in a drop down list and their order. These lines represent the valid items. There are some considerations and constraints when it comes to editing these covered in the next section.
2. Editing custom attributes
When you hover over any of the custom attributes you will see buttons to edit or disable that attribute.
Edit
In general you can change any field apart from the target name. If you needed to change that you would have to create a new custom attribute and migrate any data.
In practice the choice attributes have more complicated considerations because the choices available do not represent enumerations in the back end but a list of valid values that are stored in the database. This means that you cannot change the name of any choice, only add or remove them.
When you remove a choice this does not remove or change any existing data - that value will still appear in the field if you bring up the details for an account however it will no longer be a valid value so the page will not let you save any changes without also selecting a new value for this attribute. You will not be able to search for the removed value.
Because of this you may want to migrate some data as part of your change.
Disable
Disabling an attribute prevents it appearing or being used in any interfaces but does not remove any data. Re-enabling it makes it and its data available again. Statistics are not recorded against it whilst disabled.
If you are using the API for anything such as an automated bulk upload function or running your own custom self registration portal, then disabling any attributes will cause problems if your processes are expecting them to be available.
Delete
Once a custom attribute is disabled, the delete option becomes available. Clicking it will mark the attribute for deletion, but it will not be deleted until you save changes.
Deletion removes the attribute from release policies and data from our systems, so migrate or download any data you need to keep before you do this.
3. Types of custom attribute
Text
Single or multi-line text fields for information such as identifiers or course codes. If set as multi-line it cannot be set as reportable.
Choice
Drop-down lists of options for things like job roles or other things to group users by. Reorder choices by dragging them up and down.
Yes/no
For either / or questions such as whether someone is full time, or allowed to access the restricted section. Setting one of these as required effectively only controls whether it appears with the mandatory or optional fields as both yes and no are valid values.
Email address
Similar to a single line text field but includes validation for email addresses.
Web URL
Similar to a single line text field but includes validation for a URL
IP address range
Similar to a multi line text field
Date
Dates can have a default value of a number of days later.
4. Setting core attributes as reportable
At the top of the personal schema is a section called core attributes that is usually collapsed. If you expand this section you will see all of the main account attributes that you can populate in the interface (or map to if you are using local accounts).
The only option here is the a reportable button that is available on hover. Click this and save to have that core attribute appear as a break down option in reporting. Multi-line attributes such as address or notes cannot be set as reportable and it may take a day for you to see results.
Marking fields that contain personal or identifiable data as reportable can have implications under data protection legislation. See About reports and privacy
Anything to watch out for?
The schema is a fundamental part of the system and some changes may take a few seconds longer to appear in other parts of the interface. It is also why this section is the longest one of any feature or function.
Modifications to your schema can have far-reaching consequences, especially if you use things such as self registration or the API to interact programatically. Planning is essential, especially if removing anything.
Deletion is permanent - there is no recovery option.
If you have unsaved changes on an open attribute release page (e.g. in another tab) and you delete an attribute that features in a policy, you will not be able to save any changes to that release policy - you will need to close that tab and make your changes again.
Pre-existing accounts will not have any data against a new attribute until data is added (e.g. by bulk upload or editing an OpenAthens account, or the next authentication by a local account). This could affect search results and reporting as accounts without data against the attribute will not appear in a search over that attribute. If the attribute is released to and expected by a resource, it will have no data so may affect access.
If you remove the reportable flag from an attribute, that data will stop being recorded and the option to break down by it will no longer appear in reports.