Administration Guide

Mobile App Configuration

On this page

The Alloy Navigator app and the Alloy Self-Service app read their configuration from a mobile application record on the server. A record holds an application id, a configuration document, and an optional URL mask. Each app asks for its record by an application id built into the app:

App Application id it asks for What the configuration defines
Alloy Navigator app (technician app) NavigatorMobile list views, detail forms, and hidden classes
Alloy Self-Service app SelfServiceMobile list views and the modules the app requests

You manage the records in the Settings App and in the Admin Center; see Admin Center and Settings App for how the two applications relate. To connect a device, a user needs the API URL, which you can hand out as a QR code. Devices that sign in are registered for the person, and you can remove a registration in the Web App.

Before you begin

  • Managing mobile application records requires the Mobile Applications administrative permission ("Allows managing Mobile Applications"), in the Services group of administrative permissions. Both the Settings App and the Admin Center check it. In the Admin Center, the server also checks the access policy for administering services. See Permissions Reference.
  • The Alloy Self-Service app needs the API module. It does not need a Self Service Portal web site.

How an app finds its record

An app asks for its record by application id. Among the records with that id:

  • A record with an empty URL mask always qualifies.
  • A record with a URL mask qualifies when the mask appears, compared without regard to case, inside the API URL the app connects with.
  • When the request carries no API URL, every record with that id qualifies.
  • The first qualifying record wins. When no record qualifies, the app's configuration request fails.

With URL masks, one database can serve several deployment addresses.

Technician app configuration

The NavigatorMobile configuration is one <Data> document with three sections:

  • <Views> - per object class, an <Object Name="…"> element with named <View Name="…"> list views. Each view has <Fields> of <Field Name="…"/> in display order, an optional <Sorting> of <SortBy FieldName="…"/> keys, and an optional <Filter> that holds a SQL condition without WHERE.
  • <Forms> - an <Objects> element with, per class, an <Object Name="…"> that lists the fields of the detail form, either as one <Fields> list or in named <Section Name="…"> groups. The app reads <Section> groups from build 2.4.90 on, and treats a <Fields> list as one unnamed section.
  • <DisabledObjects> - <Object Name="…"/> entries for the classes to hide.

The supplied configuration uses sectioned forms. Alloy Navigator app version 2.4.86 cannot read that configuration; version 2.4.91 can. If you use version 2.4.86, update the app before using the supplied configuration.

Views

  • To add a view, add a <View> element. There is no other place to define one.
  • The server keeps each view whose class is one the API serves to the technician app.
  • The <SortBy> keys apply in document order. A key sorts ascending unless it carries Reverse="1". An ascending sort on Due_Date puts empty dates last. When no key is Created_Date, Ticket, or OID, the list is also sorted by ID last.
  • The app offers each class's views exactly as configured, in a menu beside the list title; the title is the current view's name. Choosing a view reloads the list with it and applies the sort and filter the device holds for that view. A sort the user picks in the app's view settings replaces the configured sort. The app remembers on the device, per class, the last view used and that view's sort and filter.
  • For Announcement and Knowledge Base Article, the app does not use the configuration; it always offers one fixed view. When the configuration has no announcement view named MobileApp.Default, the server creates one that lists the currently active announcements.

Hidden classes

A class listed under <DisabledObjects> is dropped from the app's home screen. Tapping an entry for a record of that class in the app's notification center shows "This object cannot be accessed because objects of that class are either not supported or have been disabled in this app."

Leaving a class out of <Views> or <Forms> does not hide it. A class whose configuration has no view or no form stays on the home screen, grayed out, and tapping it shows "The Alloy Navigator server is not configured to support these objects. Contact your administrator to request a configuration update."

The classes on the app's home screen are a fixed set built into the app. A class outside that set cannot be reached in the app.

A configuration that cannot be read

When the server cannot read the view configuration, it reports "Error loading view configuration". A <Forms> block that cannot be read fails with the error that reading the XML itself raises. The server keeps no part of a configuration it cannot read. When the app cannot get or read its configuration, it falls back to a built-in behavior: Service Request, Change Request, and Approval Request disappear from the app.

When a change takes effect

Changes you save to views or forms take effect with the Alloy Navigator app's next list or form request. You do not need to restart the API. Changes to the Alloy Self-Service app's views require an API restart.

IMPORTANT:

Before editing either mobile app's configuration, keep a copy so you can restore it if needed. Technician-app changes reach users with their next request; self-service view changes require an API restart. Copy the whole text of the Configuration field (Configuration: in the Settings App dialog) and save it. To roll back, paste the saved text into the same field and save the record. The Settings App shows action references differently from the stored text (see Edit a record), so paste the copy back in the application you copied it from.

A manual Import Settings… of an exported file does not roll back a record the database already holds: the import adds only the elements the stored configuration lacks and keeps your changes (see Export and import records).

Self-service app configuration

The SelfServiceMobile configuration has two blocks: <Views> and <Modules>.

Views

<Views> holds one element per view. The element's tag names the view family, and its Name attribute is the view's name. The tag encodes the kind of record and the viewer's relationship to it:

Element View family
TicketView tickets
TicketManagerView tickets, as manager
TicketCollaboratorView tickets, as collaborator
ApprovalsView approvals
ReservationsView reservations
ServiceView service requests
ServiceCollaboratorView service requests, as collaborator
LibraryView library
AssetsView assets
ArticlesView articles
ServiceCatalogView service catalog filter

Inside a view, <Fields> lists the <Field Name="…"/> columns, and an optional <Filter> holds a SQL condition. Sorting in this configuration is ignored.

For ServiceCatalogView, the first view's filter limits the items shown in the service catalog; the app does not offer it in a view selector. The supplied configuration has no service catalog filter.

The app asks the server for the views of each class it can list (the ticket class, Approval Request, Equipment Reservation, Library Item, Service Request, and Asset) and offers the returned names in a view selector. A view family whose module is not installed is never asked for. The server keeps the views it has read until the API process restarts, so a changed view reaches the app after that restart.

Licensed modules

<Modules> holds <Module Name="…"/> lines. The list is a request: the server keeps only the modules the license allows and reports those to the app as installed. A module you list but the license does not allow is silently absent. The server also filters the app's search results to the object classes of the installed modules.

License Modules allowed
ITSM and ITAM ServiceCatalog, Incidents, Tickets, Library, Approvals, KnowledgeBase, Announcements, Assets
ITSM only ServiceCatalog, Incidents, Tickets, KnowledgeBase, Approvals, Announcements
ITAM only Approvals, Announcements, Library, Assets
neither none

Removing a module from the configuration removes its entries from the app when the app next requests its configuration; the table below lists them. After a license change, restart the API for the app to receive the change.

The installed modules alone decide which portlets, drawer entries, bottom-bar buttons, and search scopes the app shows:

Module What it turns on in the app Search scope it adds
Incidents Submit a Ticket, the My Tickets portlet, Tickets and Requests in the drawer, the Tickets tab of My Items Tickets
ServiceCatalog Request a Service, the popular-items portlet, the catalog pages, the Service Requests tab Service Catalog, Service Request
Library Reserve Equipment, the reservation search, the Equipment Reservations tab Equipment, Equipment Reservation
Approvals the Approvals portlet and the Approval Requests tab Approval Request
KnowledgeBase Browse Solutions, the Popular Articles portlet, and the Knowledge Base pages Knowledge Base
Announcements the Announcements portlet and pages none
Assets My Assets in the drawer and the asset pages Assets

The All search scope is always offered and searches everything the user may see. With no module installed, search and the plus button are disabled and the home screen shows only the Last Updates portlet.

Mobile application records in the Settings App

Edit a record

  1. Go to Services > Mobile Applications. The list shows the columns Mobile Application ID and URL Mask; a Configuration column exists but is hidden by default.
  2. Double-click the record's row, or select the row and click Edit or press Enter. The Mobile Application [<application id>] dialog opens. It shows the application id as a read-only line, "Mobile Application ID:" followed by the id, rather than as an editable field.
  3. Edit the Configuration: field, the URL Mask: field, or both.
  4. Click OK.

OK parses the configuration as XML before anything is saved. If the text does not parse, the parser's error is shown and the dialog stays open. A document that parses is saved as the parser writes it back.

The Settings App displays action references as action numbers and converts these references when saving. If a referenced action does not exist in this database, opening or saving the configuration fails with "Action not found". Restore a configuration copy through the same application you copied it from.

The page's toolbar also carries Copy Item and Delete.

Export and import records

Mobile application records travel as the Mobile Applications Configurations settings section, which exports the selected records or all of them. To export records, select them on the Mobile Applications page and click Export Selected Settings…. You bring records into another database with Import Settings… on the main menu. The Admin Center's Mobile Applications page does not export records.

A manual Import Settings… adds a record that the database does not hold yet as it is in the file. A record that the database already holds is merged: the import adds only the elements that the stored configuration does not have yet, so your changes to that record are kept. The one exception is the Teams bot record, TeamsBot, whose configuration the import replaces with the one in the file; see Microsoft Teams: Self-Service Assistant Bot. If a stored configuration is not well-formed XML, a manual import stops with "The XML file 'Navigator Mobile Configuration' has invalid structure." For other import and restore options, see Export and Import Configuration.

A database upgraded from a version before 2022.1 has no SelfServiceMobile record until you import one.

Mobile application records in the Admin Center

The Mobile Applications page is under Services and Integrations in the Admin Center. It lists the records and lets you edit, copy, and delete them. The page has no New button: to add a record, copy an existing one.

Edit a record

  1. Go to Services and Integrations > Mobile Applications and open the record.
  2. The drawer is titled with the application id, and its section reads "Mobile Application ID:" followed by the id. Edit Configuration, URL Mask, or both.
  3. Save your changes.

Configuration is required: left empty, it fails with "The "Configuration" field is mandatory, it can't be left blank." The page makes no other check on the configuration text. URL Mask is optional. The page has no field for the application id.

Add a record by copying

  1. On the Mobile Applications page, select exactly one record.
  2. Click Copy Item.

Copy Item is available only while exactly one record is selected and no copy is still in progress.

Onboard devices

A device's first sign-in needs the API URL, the address of the API module (for example https://navigator.example.com/api), plus the user's credentials or SSO. The server generates no QR code, enrollment code, or onboarding token.

The Web Configuration tool shows the API URL. The same value is stored in the API Link system macro, which the Settings App lists under Workflow and Business Logic > Advanced > System Macros > Links; see Macros Reference.

Create a QR code

You produce the QR code outside Alloy Navigator, and nothing in the database or the API records that a code was issued. The QR reader of the Alloy Navigator app and the Alloy Self-Service app accepts two payloads:

  • The API URL itself: a payload that begins with http:// or https://.
  • A JSON object with API_URL and, optionally, API_USER, the user name to prefill.

A code that carries only the URL leaves the user to enter a user name and password or to use SSO; a code that carries the user name prefills it. A code that yields no URL is rejected with "Invalid QR Code".

Both apps offer Scan QR code beside the URL field of the sign-in page, and both read a code the same way. Users scan the code there; see Alloy Navigator Mobile App and Alloy Self-Service Mobile App.

Registered devices

A device is registered for a person when the person signs in from it with the Alloy Navigator app or the Alloy Self-Service app. A push notification goes to each of the recipient's devices registered for the app it targets; see Push Notifications.

  • Each sign-in registers the device again. A device that is already registered for the same app is updated, not added a second time.
  • When another person signs in from the device with the same app, the registration moves to that person. The previous person no longer has that device registered.
  • Neither app offers a way to unregister a device.

A registration is also removed automatically:

  • When the push relay answers that the device's notification token is not found, the registration is deleted at once.
  • When a Person record is deleted, all of that person's devices go with it.
  • When a sign-in registers a notification token that another registration for the same app already holds, that other registration is deleted, so a token belongs to at most one device per app.

In a new database created with the Default Workflow, the Remove Personal Information workflow function also removes every device registered to the person it runs for. An upgraded database need not have this function, and an administrator may have changed it.

Delete a registered device in the Web App

The Person record in the Web App lists the devices registered for the person. For each device the list shows the device name, the operating system, and the app, as Alloy Navigator or Alloy Self Service. The device identifier and the notification token are not shown. The list offers only deletion: a device cannot be opened, edited, or registered again from it.

  1. In the Web App, open the person's record.
  2. In the list of registered devices, delete the device.

The deleted device stops receiving push notifications. It is registered again the next time someone signs in from it with the app.