Administration Guide

Form Layouts

On this page

A form layout defines how an object class's form is arranged in the Web App. Each class that has form layouts can hold several stored layouts, and at most one of them at a time is the class's default. Every class's list also shows a System row for the class's built-in layout. Form layouts are edited in the Admin Center; the Settings App has no page for them. For the fields a layout can place, see Fields. For the separate View Forms page, see View Forms and Preview.

Examples in the Admin Center

Add a tab with a user-defined field

This example adds a tab containing an existing user-defined field (UDF). Before you begin, check the field's name in General > Fields > object class, or Workflow and Business Logic > object class > Fields. Use the field name, including its UDF_ prefix, as the element's key. See Fields if you need to create the field first.

  1. Open Form Layouts for the object class and create or open a custom layout. See Create a layout.
  2. In Layout, find the tabs element that holds the form's tabs.
  3. Add the tab definition below to that element's items array, separating it from neighboring elements with commas. Replace UDF_string with your field's name and Custom Field with the tab label you want.
  4. Click Save. To apply a new layout, use Set as default.
{
  "key": "udf",
  "caption": "Custom Field",
  "type": "tab",
  "component": "layout",
  "items": [
    {
      "key": "any",
      "type": "container",
      "items": [
        {
          "key": "UDF_string",
          "type": "field"
        }
      ]
    }
  ]
}

The tab displays the UDF inside a container. A field can appear only once in a layout. When you place a UDF explicitly, it disappears from the built-in Custom Data area. If you remove it from the custom location without placing it elsewhere, it appears in Custom Data again.

Add a tab with a filtered data view

This example adds a Closed tab to a Project form. It uses the same related-ticket list as the Tickets tab, with an additional filter that shows only closed tickets.

  1. Open a custom Project form layout, or create one.
  2. In Layout, locate the Tickets tab definition and copy it into the same tabs element's items array. Keep its key as Tickets; set its caption to Closed to change the displayed label.
  3. Add "filter": "[Status] = 'Closed'" to the copied ProjectTicketList grid. The complete added tab is shown below.
  4. Click Save. To apply a new layout, use Set as default.
{
  "key": "Tickets",
  "caption": "Closed",
  "type": "tab",
  "customMarking": true,
  "component": "layout",
  "items": [
    {
      "key": "ProjectTicketList",
      "type": "grid",
      "filter": "[Status] = 'Closed'"
    }
  ]
}

In the Web App, the Project form's Closed tab shows the filtered list. The layout filter is applied in addition to the system data view's filter, so the list still contains only tickets related to the current project. The layout editor does not suggest fields, operators, or values for the filter expression.

On save, Alloy Navigator adds a uniqueId to the filtered grid. Let the editor generate this value. The new grid then has its own view settings: you can change its columns and sorting without changing the original Tickets view. To change the fixed filter, edit filter in the layout; it cannot be changed through Customize View > Filter.

How the Web App uses a layout

When the Web App opens a form, it chooses the layout in this order, for every object class:

  1. The layout that the record's type is attached to. See Assign ticket types to a layout.
  2. When the record has no type, or its type is not attached to any layout, the class's default layout.
  3. When no stored layout is the class's default, the class's built-in layout, the one the System row stands for.

On a form opened from a create action, the record's type is taken from the types listed for that create action, and the same order follows. When those types are attached to different layouts, which of those layouts the form uses is not fixed. Two records of one class, or two create actions of one class, can therefore open with different layouts. The form header is not part of the layout: its lifecycle strip, calculated fields, and copy-link line are configured separately.

Columns and containers

  • A Layout element and a tab whose component is layout arrange their items the same way: in a single scrollable column when any item is a container or when every item is a field, and otherwise in a row.
  • Only a Column element applies the styles value. A width such as "500px" or "50%" fixes the column's width; a column without a width stretches. On any other element, styles has no effect.
  • A container's header is always the translation of its key; its caption is not used.
  • A container keyed Activity that holds one item adds the record's activity count to its header when the count is not zero.
  • A container with a header whose only item is a field hides that field's label when the field's key, without _HTML, is the container's key.
  • Every container is expanded each time the form opens, including a container the user collapsed before. A container that is not collapsible has no collapse control.

Tabs

  • A tab's label is its caption. A tab without a caption is labeled with the translation of its key. A Custom Data tab uses the configured user-defined field tab caption before either.
  • A top-level tab with customMarking set shows a count in its label when its items, or the items of its single Column, include a grid, an activity list, or a board, or when its component is one that carries a count. The count is shown only when it is not zero. A tab without customMarking shows no count.
  • A customMarking tab that has no count, such as a Notes or Resolution tab, shows a small dot when its rich-text field is not empty.
  • A tab whose component is notes shows the class's rich-text notes field. When the class has no rich-text notes field, the tab shows the plain notes field without a label. A tab whose component is resolution always shows the rich-text resolution field.
  • A tab whose component is personalCalendar or reservationCalendar shows the same calendar, chosen by the record's class: on a person, the person's personal calendar, and on a record of any other class, a reservation calendar. The calendar is read-only whenever the record is.
  • The Web App hides some tabs of a record because of the record's data, never because of the user's rights: the Approvals tab when the record has no approvals, the Virtual Machines tab when there are none, and the Technician and Work Calendar tabs on a person who is not a technician.
  • Each technician has a setting to show an object's activity on a separate tab, which is off by default. When it is on, the Web App takes every Activity element out of the layout, removes the elements that are left empty, and puts the first Activity element alone into a tab keyed Activity in the second position. It adds that tab if the layout has none. A layout without an Activity element stays as it is, and so does a layout whose only Activity element already sits alone on its Activity tab.

Fields and other elements

  • A user-defined field placed in a layout by its UDF_ field name shows once, where the layout puts it. It no longer appears in its default Custom Data place, the Custom Data tab or the Custom Data container of the General tab. A Custom Data place left with no user-defined field is not shown.
  • The Custom Data element shows the visible user-defined fields assigned to the Custom Data section of the General tab, in one collapsible container. Its header is the section caption configured for that section.
  • A field element whose key is not a field of the class shows only a loading placeholder on the form, and no error.
  • A calculated field named Rating shows as a read-only star rating. When the form computes a calculated field from other fields, it uses the values last loaded from the server, not changes that are not saved yet.
  • A Tags element and a field element keyed Tags show the same tags control.
  • A Label element shows the translation of its key. When that translation still has a value to fill in, the label shows the message as the server fills it in for the current record instead.
  • In the associated information panel, the Category column shows each listed object's category. For a location, a person, a software license, or a group, the Category column is always blank.
  • The asset categorization panel always shows the product class field. After it, the panel adds fields chosen by the product class, and it changes them as soon as the product class changes. Computer, Consumable, Hardware, and Software License each have their own pair of type and category fields, which follows the asset type and asset category fields. Any other product class gets a single general field.
  • On a purchase order, the vendor information panel shows the vendor's Name, FEIN, Phone, Fax, Contact, Email, and Address. The panel reloads them each time the vendor changes on the form, including on a purchase order that has not been saved yet, and replaces anything typed into them.
  • On a software product, the software license view panel shows a License block that names the tracked software record the product rolls up to, with Discovered and Used counts and an Options menu (Open, Open in new tab, View) for that record. The block is shown only when a tracked software record is linked.
  • The service information panel shows six read-only fields about the service selected on the form: its type, category, status, service manager, support group, and Availability Hours. The panel reloads them each time the selected service changes, and the fields are empty while no service is selected.
  • The license summary panel shows the license's compliance as an icon and a text, which is red when the license is out of compliance. Then come "Total License Qty", "Reconciled", "Unreconciled Allocations", "Upgraded", "Used", and either "Available" or, when there are not enough licenses, "Required". In a container narrower than 800 pixels, the panel arranges its items vertically.
  • The license restrictions panel shows the license's restrictions as a table in a collapsible container, with dialogs for restriction rules by location, organization, device, user, device owner, allowed installs per user, CPUs per license, and CPU cores per license. Which rules are available depends on the license's statistics, such as its tracking mode and the restrictions already set. The person and device pickers leave out the persons and devices that are already restricted.
  • The tracked software summary panel shows the same kind of compliance icon and text with "Total License Qty", "Discovered", "Reconciled", "Unreconciled Installations", "Upgraded", "Used", "Available", and "Required". It shows all of these whatever the tracking mode.
  • The associated fields element shows two fields of the asset record associated with the open record, "Asset Tag" and "Barcode", and the associated product element shows that asset's "Product" field. Their labels and values come from the Asset class's fields. These asset fields are available only on Computer, Hardware, and Software License forms, where they are always read-only, even when the record itself can be edited. On a form of any other class, the two elements show no fields.
  • The board element always shows a board of tasks, whatever the form's class. It shows the tasks that have the open record as their parent or as an ancestor at any level: on a project, every task of the project, and on a record with no tasks under it, no tasks. In the board's default view, its columns are the task statuses, the cards are sorted by Created Date with the newest first, and each card shows the task's flag status, OID, summary, assignee, priority, status, and planned end date. The board element has no button for adding a task.
  • A Button element is labeled with the translation of its key. Only a button keyed ShowAuditInformation, labeled "Show audit information", has an action: it opens the record's audit report in a new browser tab, and it is unavailable while the record has no audit date. A button with any other key is shown but does nothing when clicked.
  • The feedback panel is not shown when no feedback exists for the record's current assignee.
  • The created and modified information is not shown while a record is being created. When no user name is recorded for a record, such as a record the system created, the line leaves out "by" and the name.

Forms that create a record

On a form opened from a create action, where saving creates the record, some elements show the message "This area is only available after you save the record" instead of their content: the Activity element, every grid, and the tabs whose component is a personal calendar, a reservation calendar, a Gantt chart, a Gantt tasks board, or related objects. The Notes, Resolution, and Custom Data tabs show their fields on that form.

In the Admin Center

Before you begin

The Form Layouts node, and the page it opens, are available to an account that holds the Form Layout Configuration permission or the Administrative Access permission. Without Administrative Access, the node is shown only in the tree of an object class whose business logic permission the account also holds. An account with neither Form Layout Configuration nor Administrative Access does not see the node, even with the Workflow Configuration permission and the class's business logic permission, and the page shows "Sorry, this page is not available" instead. In the role editor, Form Layout Configuration is under Business Logic Management. For permissions in general, see Permissions Reference.

Open the Form Layouts list

Form Layouts is a node in the tree of each object class that has form layouts. In the Workflow tree, open the object class, then Form Layouts.

The list always begins with a System row, described as "System Form Layout". This row stands for the class's built-in layout. It is marked default whenever no stored layout is the default. The System row cannot be deleted or exported.

Opening the System row shows the built-in layout read-only. Instead of the Name and Description fields, the pane shows an information banner with a Read more link to online help, and its only button is Close.

When you open a stored layout that is the class's current default, its name in the pane title carries a "default" badge. Other stored layouts and the System row show the plain name. The pane of a stored layout also shows when it was last saved and by whom, as "Created/modified: <date> by <name>".

Create a layout

  1. Click New. The New Form Layout pane opens with an empty Name and Description, and default turned off.
  2. Enter a Name and a Description. Both are required.
  3. Edit the Layout field. It starts with the class's current default layout: the stored default layout, or the built-in layout when no stored layout is the default. The name, description, and ticket types of that layout are not copied.
  4. Click Save. The layout is saved as a separate layout that is not the default.

To make the new layout the class's form, set it as the default. Records whose type is attached to another layout still open with that layout.

Set the default layout

Use Set as default on a layout. If another layout is already the default, you are asked "Are you sure you want to set "<new>" as the default instead of "<old>"?" with both layout names filled in. When a stored layout becomes the default, the class's other layouts stop being default.

IMPORTANT: Using Set as default on the System row clears one default layout, and that layout can belong to another object class. When several classes have a default layout, this class's stored default can stay in place, and the list still shows it as the default.

Delete a layout

Select a layout and click Delete. Delete is unavailable for the System row and for the layout that is currently the default. To delete the default layout, make a different layout the default first. The ticket types attached to a deleted layout are left without a layout.

Export and import a layout

Export is unavailable only for the System row, so you can export the current default layout.

When you import a layout file, it is checked in this order, and each failed check shows its own message:

  1. The file must be valid JSON.
  2. The file must be a form layout file exported by Alloy Navigator. Otherwise the message begins "The file you are trying to import is not a form layout for Alloy Navigator".
  3. The file must match the layout format.
  4. The file's version must have as many dot-separated parts as the product version, and no part of the product version may be smaller than the file's part in the same place.
  5. The file's class must match the current object class. Otherwise the message names both classes, or says the file's class is not recognized.

If the imported layout's name is already used, " (1)", " (2)", and so on is added to the name, and the import goes ahead.

Assign ticket types to a layout

The Form Layouts list has a Types column only for Incidents, Work Orders, Change Requests, Service Requests, and Problems. In this column you attach ticket types to a layout. In the Web App, a ticket of an attached type opens with this layout, whether or not the layout is the class's default.

  • Type in the picker's search field to filter the types.
  • Click a type, or press Enter, to select or clear it. This saves the whole selection and closes the picker.
  • Hold Ctrl (Cmd on a Mac) while you click to select or clear a type and keep the picker open.
  • Clicking outside the picker also saves the selection.

An added type is saved at once. A removed type is saved after a short delay. Each save replaces the layout's whole list of types.

A ticket type can be attached to one layout at a time, and the picker offers only types that are not attached to a layout. If a selected type has been attached to another layout in the meantime, nothing is saved. The save fails with one message for each such type: "Type with Id = <type id> already has layout Id = <layout id>".

IMPORTANT: Deleting a ticket type also deletes the layout attached to it, even when other ticket types are attached to the same layout.

Edit the layout definition

The Layout field holds the layout as a JSON list of elements. Each element needs a type; no element type requires a key. A field element names a field in its key, for example {"key": "<field name>", "type": "field"}. The key is a field name of the class; a user-defined field's name always starts with UDF_. The built-in Computers, Hardware, and Software License layouts also place fields of the linked asset, with names that start with Asset.. Such fields are available only on the forms of these three classes, where they are always read-only. To add or move a field on the form, you add or move its field element.

The 27 element types are of three kinds. Each type's type value is shown in parentheses. Write it exactly as shown, including the letter case.

  • Layout elements: tabs (tabs), tab (tab), layout (layout), row (row), column (column), container (container), label (label), and button (button).
  • Data elements: field (field), calculated field (calculatedField), tags (tags), activity (activity), modification information (modificationInfo), and custom data (customData).
  • Composite panels: service information (serviceInfo), associated information (assosiatedInfo), asset categorization (assetCategorization), vendor information (vendorInfo), license summary (licenseSummary), software license view (SoftwareLicenseView), license restrictions (licenseRestrictions), tracked software summary (trackedSoftwareSummary), associated fields (associatedFields), associated product (associatedProduct), feedback (ticketFeedback), grid (grid), and board (board).

An element can carry only these properties: key, type, caption, mandatory, readonly, customMarking, styles, component, container, keyWithHash, filter, uniqueId, and items.

A Tabs element holds Tab elements only. A tab's component is one of a fixed set of values: layout, whose tab holds its own items, and others that include notes, resolution, ganttChart, ganttTasksBoardTab, customData, relatedObjects, history, attachments, approvals, personalCalendar, and reservationCalendar.

A container can carry only the settings showHeader and collapsible.

A styles value is a list of key: "value" pairs separated by semicolons.

Save checks the Layout field, and the field shows the first error found. While an error is shown, the field is checked again after each change. The layout is refused when:

  • It is empty or is not valid JSON.
  • An element has no type or a type the editor does not recognize, or a component it does not recognize.
  • An element whose component is layout has no items.
  • An element carries a property the editor does not recognize ("Unknown property in layout item"), or a container carries a setting other than showHeader and collapsible ("Unknown property in container").
  • A Tabs element holds an element that is not a Tab.

After these checks, Save runs two more:

  • Two or more field elements have the same key. Saving is blocked, and the error dialog names one duplicate field and lists any others in its details. Only field elements are counted, and a field element without a key counts as an empty key, so two such elements also block saving.
  • A tab's key is empty or is not one of the standard tab names, the tab has no caption, and its customMarking is set. A confirmation describes the custom tab: Save Anyway saves the layout, and Cancel leaves it unsaved. The standard tab names are among the key suggestions the Layout field offers.

When the layout is saved, a grid element that has a filter but no valid uniqueId is given a new uniqueId. A grid element without a filter, or with a valid uniqueId, is saved as it is.

Reset to System replaces the layout definition with the class's built-in layout. When the Layout field is empty or shorter than three characters, it does so at once. Otherwise it asks "Resetting this layout will replace the layout definition with the system predefined one." with the buttons Reset and Cancel.

Preview a layout

Preview Layout opens a full-width mockup of the form. It is unavailable while the Layout field shows a validation error. That error appears after Save or after a failed preview attempt, so a layout that has not been checked yet can still be previewed.

In the preview:

  • The panel on the right captioned "ACTIONS" and the blank areas standing in for the page header and tab strip are not part of your layout.
  • Only the selected tab's content is shown. A tab whose component is not layout shows one centered caption made from the component's name instead of its items, and a tab with no component shows nothing.
  • An element's items are shown side by side only when its first item is a Column. A Column with a width in its styles keeps that width; otherwise it stretches.
  • A container shows its header unless it carries container settings that do not set showHeader to true. It shows a collapse control only when it is set collapsible. Collapsing a container hides its elements.
  • A styles entry without a colon, or with an empty key or value, is ignored without a warning. A value that itself contains a colon loses everything after that colon.
  • Most captions, such as container headers and tab labels, are made from the element's key, not from the field's configured display name. An Activity placeholder shows the key itself, and a Field placeholder shows the key with _HTML removed from it.
  • The preview uses only an element's type, key, items, component, styles, and container. The other properties do not change it.
  • The editor accepts 27 element types, and the preview draws 18 of them. Elements of type board, SoftwareLicenseView, licenseRestrictions, associatedFields, associatedProduct, button, tags, and layout are left out of the preview without an error. A tab element is drawn only as a tab of a Tabs element.