Preference ItemType for Admins & Developers • PLM Forge

Introduction

The Preference ItemType can often go unnoticed by developers and admins, as it is mainly used to automatically store user preferences. However, it is a powerful feature that can be used to configure default Search Grid views that would otherwise be difficult to change.

Where to find the Preference ItemType?

You can find the Preference ItemType under the Administration dropdown in the Table of Contents (TOC):

What is the Preference ItemType?

The Preference ItemType is an administrative Item used by Aras to store user preferences and a few global preferences.

A preference Item will automatically be created for each user when they log in.

There is also a global World preference Item that is used to store unique global preferences, but I will not be covering that in this post.

Preference Form

Opening up a preference Item for a user will show the following form:

The Preference form contains multiple tabs, but this post will focus mainly on the Item Grid Layout tab, because understanding this tab will allow admins and developers to customize the default layout for user’s Item Grid views.

A quick overview of each tab:

General Settings - This tab contains the general preferences for the user.
PE_MainPreferences - Defines the default Change Management process selected when a user uses the “Add Item(s) to Change…” action.
Item Grid Layout - Stores default saved layout preferences for specific Item Search Grids.
Relationship Grid Layout - Stores default saved layout preferences for specific Relationship Grids.
Secure Social - Stores saved preferences for Secure Social related to messaging and notifications.
CMF Grid Layout - Stores saved preferences for items that use the Content Modeling Framework (CMF). Aras Blog for more info on CMF.

How Item Grid Layout Drives the Search Grid

The top half of the screenshot is the Item Grid Layout tab on a user’s Preference Item; the bottom half is the user-facing Search Grid. The colored callouts show how each Preference property drives a specific control/behavior in the grid.

ItemType Id — The GUID of the ItemType this layout applies to (e.g., CAD Documents). The preference is only used when the grid is for this ItemType.
Column Widths and Column Order — Semicolon-separated lists that define the visible columns and their sequence. Columns not listed are hidden. Widths map 1‑to‑1 to the ordered columns.
Page Size — Default rows per page in the grid (toolbar page-size control).
Max Records — Server-side cap for results returned by a search. 0 means no explicit cap.
Query Type — Default state of the Effectivity selector (e.g., Released vs Current), used when the grid first loads.
Show Preview — Default preview pane mode: Off, Properties, or Form (Monitor > Preview menu).
Frozen Columns — The count of leading columns that remain fixed during horizontal scroll. The thick gray divider marks the freeze boundary.

In the screenshot shown above: Page Size = 50, Max Records = 0, Query Type = Released, Show Preview = Off, and Frozen Columns = 1.

When a user updates their default grid layout for an ItemType, these values are written to their Preference Item under the Item Grid Layout tab. Updating them changes the default grid experience for that user for the specified ItemType.

How the Item Grid Layout can be Used by Admins & Developers

A common use case for the Item Grid Layout is to configure the default effective search mode for specific ItemTypes.

For example, say you want the CAD Document search grid to default to showing only released items for all users or specific users.

You can create or update user preferences for a given Item Grid Layout programatically using a server method with the Method ItemType.

Example C# Server Method to set the default effective search mode for CAD Documents to Released for all existingusers:

Innovator inn = this.getInnovator();
 
// Grab CAD ItemType for GUID and default item preferences
Item getCADItemType = inn.newItem("ItemType", "get");
getCADItemType.setAttribute("select", "id,maxrecords,default_page_size");
getCADItemType.setProperty("name", "CAD");
Item cadProperties = inn.newItem("Property", "get");
cadProperties.setAttribute("select", "name,is_hidden,sort_order,column_width");
cadProperties.setAttribute("orderBy", "sort_order");
cadProperties.setProperty("is_hidden", "0");
getCADItemType.addRelationship(cadProperties);
 
Item cadItemType = getCADItemType.apply();
string cadItemTypeID = cadItemType.getID();
 
// Setup default grid settings for for new preferences
StringBuilder sbDefaultColumnOrder = new StringBuilder("L;");
StringBuilder sbDefaultColumnWidths = new StringBuilder("32;");
 
Item propertyList = cadItemType.getRelationships();
for (int i = 0; i < propertyList.getItemCount(); i++) {
  Item propertyItem = propertyList.getItemByIndex(i);
  sbDefaultColumnOrder.Append(propertyItem.getProperty("name"));
  sbDefaultColumnOrder.Append("_D");
  if (i != propertyList.getItemCount() - 1) sbDefaultColumnOrder.Append(";");
  sbDefaultColumnWidths.Append(propertyItem.getProperty("column_width", "60"));
  if (i != propertyList.getItemCount() - 1) sbDefaultColumnWidths.Append(";");
}
 
string defaultColumnOrder = sbDefaultColumnOrder.ToString();
string defaultColumnWidths = sbDefaultColumnWidths.ToString();
string defaultPageSize = cadItemType.getProperty("default_page_size", "0");
string defaultMaxRecord = cadItemType.getProperty("maxrecords", "0");
 
// Grab World identity to exclude from preference search
Item getWorldIdent = inn.newItem("Identity", "get");
getWorldIdent.setAttribute("select", "id");
getWorldIdent.setProperty("name", "World");
Item worldIdentity = getWorldIdent.apply();
 
// Grab all Preference Items and CAD Document Item Grid Layout relationship info (except World)
Item getPreferences = inn.newItem("Preference", "get");
getPreferences.setAttribute("select", "id,identity_id");
getPreferences.setPropertyCondition("identity_id", "ne");
getPreferences.setProperty("identity_id", worldIdentity.getID());
 
Item getItemGridLayout = inn.newItem("Core_ItemGridLayout", "get");
getPreferences.addRelationship(getItemGridLayout);
 
Item preferenceList = getPreferences.apply();
 
// Loop through all user preferences and either 
// create CAD Document search grid preference if one doesnt exist
// or update only the Query Type value if a preference already exists
 
Item updateGridLayouts = inn.newItem();
 
for (int j = 0; j < preferenceList.getItemCount(); j++) {
  Item preferenceItem = preferenceList.getItemByIndex(j);
  Item gridLayouts = preferenceItem.getRelationships();
  bool cadLayoutFound = false;
 
  for (int k = 0; k < gridLayouts.getItemCount(); k++) {
      Item gridLayoutItem = gridLayouts.getItemByIndex(k);
      if (gridLayoutItem.getProperty("item_type_id","") != cadItemTypeID) continue;
 
      Item editGridLayoutPref = inn.newItem("Core_ItemGridLayout", "edit");
      editGridLayoutPref.setID(gridLayoutItem.getID());
      editGridLayoutPref.setProperty("query_type", "Released");
 
      updateGridLayouts.appendItem(editGridLayoutPref);
      cadLayoutFound = true;
      break;
    }
 
  // No existing layout preference found, so create a default layout preference
  if (cadLayoutFound == false) {
    Item createGridLayoutPref = inn.newItem("Core_ItemGridLayout", "add");
    createGridLayoutPref.setProperty("source_id", preferenceItem.getID());
    createGridLayoutPref.setProperty("item_type_id", cadItemTypeID);
    createGridLayoutPref.setProperty("query_type", "Released");
    createGridLayoutPref.setProperty("col_order", defaultColumnOrder);
    createGridLayoutPref.setProperty("col_widths", defaultColumnWidths);
    createGridLayoutPref.setProperty("page_size", defaultPageSize);
    createGridLayoutPref.setProperty("max_records", defaultMaxRecord);
    createGridLayoutPref.setProperty("preview_state", "Off");
    createGridLayoutPref.setProperty("frozen_columns", "1");
 
    updateGridLayouts.appendItem(createGridLayoutPref);
  }
}
// Remove empty item created at the start
updateGridLayouts.removeItem(updateGridLayouts.getItemByIndex(0));
 
if (updateGridLayouts.getItemCount() > 0) {
  Item result = inn.applyAML(updateGridLayouts.ToString());
  return result;
}
 
return this;

Example method to set the default effective search mode for CAD Documents to Released for all users

This method has been tested to work in Aras Innovator v14 by using the manual Run Server Method action.

You would need to modify this method to some extent if you wanted a server method that worked as a Server Event to create this default preference for new users going forward as well.

Conclusion

The Preference ItemType is a powerful feature that can be used to configure default Search Grid views that would otherwise be difficult to change.