Administration Guide

Service Actions and Field Mappings

On this page

A service action is how a background component, such as the Mail Connector or the Active Directory import, creates or updates a record. Service actions come in create/update pairs, because the connector must decide, for each incoming record, whether it is making something new or changing something it made before. Five connectors work this way: the Mail Connector, the Active Directory import, the Alloy Discovery connector, the Alloy Discovery connector for Chromebooks, and AlloyScan. The Self Service Portal's create and update actions are authored in the same window but are not service actions; see Portal service actions.

A service action's distinguishing part is its field mapping: the rows that bind an incoming attribute to a target field. A create action also carries a data template. When a service action runs, its template is applied first, if it has one, then its mapping, field by field, and then its program.

In the Settings App

Where you create a service action

A class's service actions are listed on the Service Actions node, in the Actions folder of the class's Workflow node. See Workflow Overview for the layout of the workflow tree. On Service Actions, New is a submenu with a create entry and an update entry for each connector that serves the class. The Mail Connector pair is offered on every class; each other pair is offered only on the classes in the table. Service Actions have no ordering command.

Connector New-menu entries Create offered on Update offered on
Mail Connector Create Action for Mail Connector, Update Action for Mail Connector every class every class
Active Directory import Create Action for Active Directory Import, Update Action for Active Directory Import Persons Persons
Alloy Discovery connector Create Action for Alloy Discovery Connector, Update Action for Alloy Discovery Connector Computers, Hardware, Persons Computers, Hardware
Alloy Discovery connector, Chromebooks Create Chromebook Action for Alloy Discovery Connector, Update Chromebook Action for Alloy Discovery Connector Computers Computers
AlloyScan Create Action for AlloyScan, Update Action for AlloyScan Computers, Hardware, Persons Computers, Hardware
Self Service Portal Create Action for SSP (on Persons, the entry ends in (Self-Registration)), Update Action for SSP Incidents, Persons, Reservations Incidents, Approval Requests, Reservations, Service Requests

Which service action a connector runs is set on the connector's job, per target class; a class with no service action configured there is not imported. The Mail Connector's job names its Persons create action directly and, for everything else, holds an ordered, conditional list, each entry naming one Mail Connector create or update action, which is why one mailbox can create several ticket classes. See Incoming E-mail Processing Rules and Active Directory Synchronization for how those jobs are set up.

Copy Item on the workflow tree's toolbar copies the selected item into a new one and opens the copy at once, so you name and save the copy in one step. The one item it refuses is the Service Catalog's "Make Request" action; for it, Copy Item shows "This is a system record and it cannot be copied."

The service action window

The tabs available in the service action window depend on the kind of action.

  • General holds Name, Description, and Enabled. On the two Self Service Portal kinds it also holds Caption, which is mandatory and copies the Name into itself when you first enter it or leave it empty. The Persons self-registration create action has no Caption box; its caption is always its name.
  • A connector kind shows Field Mapping and neither Condition nor Form. A Self Service Portal kind shows Form in place of Field Mapping, because a portal action is started by a customer filling in a form rather than by a connector supplying attributes. It also shows Condition, except on Persons.
  • Template appears only on the create kinds.
  • Every kind ends with the Programming and Processes tabs.

The Template tab

The Template tab carries the note "The Template tab allows you to choose an existing template or define a custom template to be used only for this Action. This template's values will be applied when the object is created." Its list shows the class's reusable templates by name, or <Custom> when the action has its own private template.

  • While a reusable template is selected, its grid is read-only.
  • Make Custom copies the rows of the selected template into a new private template for this action and unlocks the grid. You edit the Field Name and Value columns in place.
  • Make Reusable asks for a Template Name: of up to 50 characters in the Reuse Template box, saves the template under that name, and switches the action onto it. A name the class already uses is refused with "Another template with this name already exists. Enter a different name."
  • Picking a different template after the custom template has rows warns "The Custom Template definition will be lost. Do you really want to change the current template?" If you answer No, the action stays on <Custom>.

The Form tab of a Self Service Portal action uses the same controls and lists the class's forms; there the button reads Use Custom while the full form is selected.

The Field Mapping tab

The Field Mapping tab shows a grid whose columns include Field Name, Service Attribute, and Is Virtual. The grid is sorted by Is Virtual and then Field Name; a mapping has no order of its own.

  • To add a row, click New. To change a row, double-click it. Both open the Field Mapping window.
  • On an update action, the grid's Replacement Mode column shows each row's replacement mode, and you can change the mode of a row that targets an object field directly in the grid.
  • Delete asks "Are you sure you want to delete the selected item?"

The Field Mapping window

A mapping row binds one incoming attribute to one target: either a field of the object or a virtual field that the mapping defines. A virtual field can be used from the action's program as a parameter.

  • In the Field group, choose Object Field, which is selected by default and whose Name: lists the class's mappable fields, or Virtual Field, for which you type a Name: and pick a Type: (Integer, Logical, Currency, String, Memo, Date, Date/Time, Float, Reference, HTML, or Script Object). A target field or virtual field name that another row of the same mapping already uses cannot be used again in that mapping.
  • On an update action, Replacement Mode: decides when the row writes its target; the modes are listed below. It applies to object fields only: choosing Virtual Field disables it and shows N/A. When the selected object field is logical, Always is the only mode offered, and a row that stored another mode falls back to Always.
  • In the Service attribute group, choose the Name: of the incoming attribute. On the Mail Connector and Active Directory kinds you can also type a name the list does not hold; it is stored as typed. On the Alloy Discovery, Chromebook, and AlloyScan kinds, and on every kind when the target is a reference field, you can only pick from the list.
  • With Object Field chosen, OK is available when a field is selected, the service attribute is not blank, and a replacement mode is selected. With Virtual Field chosen, only a Name: and a Type: are needed, so a virtual field can be saved without a service attribute.
Replacement mode Writes the target when
Always always
When Target is empty the existing field value is empty
When Source has value the incoming attribute is not empty

The Service attribute list offers only attributes that fit the target chosen in the Field group, sorted by the caption they display:

  • When the target is a character type (String, Memo, Lookup, Multi-select, Encrypted, or HTML), or when nothing is chosen yet, the type narrows nothing. Otherwise an attribute stays only when its type matches: the same type, numeric for a numeric target, date or time for a date or time target, logical for a logical target. A reference target keeps only reference attributes.
  • When the target has a lookup table, every attribute with a different lookup table is dropped, whatever the type. A virtual field has no lookup table, so only its Type: filters the list.
  • A logical attribute named Disabled is offered only on the Active Directory update action.
  • Changing the target empties the list; it is rebuilt against the new target the next time you open it. Reopening a row whose stored attribute the narrowed list no longer holds shows the stored name.

Where the service attributes come from

The list of attributes you can map comes from a different place for each connector, and four of the five connectors reach outside Alloy Navigator to build it. That is why the Field Mapping window can fail to open on a computer that reaches Alloy Navigator without problems.

Connector Where the attribute list comes from Needs an outside connection while you author
Mail Connector a fixed list of message attributes (From, To, CC, BCC, Subject, Content, Sender, Sender Name, Sender E-mail, Priority, Auto-Generated, Auto-Replied), plus the Mail Connector service attributes (see Mail Connector service attributes) No
Active Directory import the directory's user schema, read live, plus four added entries: Manager (Link to Person), Full Login, memberOf (raw), and Disabled Yes, a reachable directory
Alloy Discovery connector the columns of the Alloy Discovery database's computer or hardware import table Yes, a Discovery database sign-in
Alloy Discovery connector, Chromebooks the columns of a Chromebook import table in the same Discovery database Yes, a Discovery database sign-in
AlloyScan the AlloyScan service's computer or hardware field list Yes, an AlloyScan site URL, client ID, and secret
  • The Alloy Discovery, Chromebook, and AlloyScan actions prompt you for their credentials while you author the mapping. The Active Directory actions prompt for nothing: the schema is read in your own security context, so the directory must be reachable, but no separate sign-in is needed.
  • The AlloyScan mapping editor connects to the site to list its live attribute names. Review the site URL and credentials before connecting.
  • The Alloy Discovery and Chromebook mapping editors open the Log in to Alloy Discovery dialog to connect to the inventory database and list its columns.
  • The Alloy Discovery and Chromebook lists never offer internal keys, node references, or credential references.
  • Sender is offered only when the target class is not Persons. Priority is Low, Normal, or High, taken from the message's priority.
  • Auto-Generated and Auto-Replied identify automatic messages and replies. A message that is auto-replied is also auto-generated. A notification this installation sent that bounces back is recognized as automatic.
  • An Active Directory attribute named thumbnailPhoto or jpegPhoto receives the user's photograph, scaled to fit 300 x 300. memberOf receives the name of each group the user belongs to, one per line; memberOf (raw) receives the same attribute unresolved. An attribute that is empty after trimming is passed as no value rather than as empty text.

What a mapping cannot target, and what is added for you

Some fields are never offered as a mapping target. On every connector these include the ticket fields status, type, priority, impact, urgency, category, closure code, and medium, a few references to other classes, the audit date, and, on the ticket classes, the organization. Each connector excludes a short list of its own on top of that:

  • Mail Connector: the location and the organization of a person.
  • Active Directory import: the same two fields, and the manager of an organizational unit or a location.
  • Alloy Discovery connector, Chromebooks, and AlloyScan: the manager and the parent of an organizational unit or a location, and the organization and the location of a computer.

Such fields are left to the action's program.

Alloy Navigator also adds mapping rows that the grid does not show:

  • An Alloy Discovery or Chromebook action on Computers, or an Alloy Discovery action on Hardware, also writes the import ID and the audit date.
  • An AlloyScan action on Computers or Hardware also writes the audit date. Before the AlloyScan connector runs an action, it always adds one attribute of its own, the audit date, to the attributes the action maps.
  • On an Alloy Discovery action, a mapping of the audit user set to Always runs as When Source has value, so an audit with no logged-on user cannot clear an owner who is already assigned.

In the Select Placeholder window, the virtual fields of a connector action's mapping appear in the Service Fields category, sorted by name; for a Self Service Portal action the category is Form Fields. Choosing a virtual field inserts a placeholder such as %[VIR Comment]%. For the other placeholder categories, see Macros Reference.

Default field mappings

A new service action opens with the default mapping of its kind and class already in the grid. Default mappings exist only for the connector, action, and class combinations in the table below, all on Persons, Computers, Hardware, or the ticket classes. For any other combination, and on both Self Service Portal kinds, a new action opens with an empty mapping and the Default command is not shown.

Default asks "Are you sure you want to replace current mappings with default ones?" and then replaces every row, including rows you added, with the default mapping.

Connector and action Class Default mapping
Mail Connector create any ticket class requester, description, and summary, plus the virtual fields AutoGenerated, AutoReplied, and InactiveObjectRef
Mail Connector create Persons full name from the sender name, e-mail from the sender e-mail
Mail Connector update any ticket class the virtual fields AutoGenerated, AutoReplied, and Comment, the comment taken from the message content
Active Directory create / update Persons The update includes the virtual field Disabled
Alloy Discovery create / update Computers Available
Alloy Discovery create / update Hardware Available
Alloy Discovery create Persons Available
Chromebook create / update Computers Available
AlloyScan create / update Computers Available
AlloyScan create / update Hardware Available

Almost every default row writes Always. Two write When Target is empty: the Active Directory row that fills the notes from the directory's info attribute, and the Alloy Discovery row that fills the owner from the audit user, so an import does not overwrite notes or reassign an owner. The Alloy Discovery, Chromebook, and AlloyScan default rows show a display name for the attribute, such as "Audit ID", "CPU speed, GHz", or "AD.Department", instead of the raw column or path.

Mail Connector service attributes

Service attributes are named parsing rules that the Field Mapping window adds to the Mail Connector's attribute list. A rule is edited in the Edit Field window:

  • The Field group has Name:, Type:, and Description:. Type: offers the same eleven types as the Field Mapping window, with the reference type labeled Reference to object; String is preselected.
  • The Parsing Rule group has Extract value from:, Starting after:, continues until:, Case sensitive, and Remove leading and trailing spaces. When the type is Logical, a Check For: box appears and the extraction line is labeled In:.
  • A name that another attribute already uses is refused, and so is any of the Mail Connector's built-in attribute names.

Portal service actions

A Self Service Portal create action or update action is authored in the service action window, but it runs as an ordinary action: a portal customer starts it by filling in its form. Portal customers hold no security role, so a portal action is not restricted by role unless role grants exist for it; when they exist, they apply.

The Self Service Portal > Workflow page lists the same portal actions a second time, under these classes: Incidents, Approval Requests, Reservations, Service Requests, Library Items, Service Catalog Items, Computers, and Hardware. A class your license does not cover is left out.

  • Every class has a View Form group with one row: the class's view form, or "<Double-click to add a new View Form>" when it has none.
  • A Create Actions group appears only for Incidents and Reservations and ends with "<Double-click to add a new Create Action>".
  • An Actions group, holding the update actions, appears only for Incidents, Approval Requests, Reservations, and Service Requests and ends with "<Double-click to add a new Action>".
  • Each item row shows the item's ID and name beside an Enabled column. A double-click or Enter opens the same window that the class's Workflow node opens.

For which of these actions the portal offers a customer, and for the page's other commands, see Portal Actions and Forms.

Persons has no node on this page. The action that creates a person at self-registration is chosen in the Settings App's Self Service Portal settings, under Create new Person using Action:. The setting is mandatory while web registration is allowed, and it is disabled together with the rest of its group when web registration is not allowed. The self-registration action has no Condition tab, and its caption is always its name. For how a registration uses the action and its form, see Self-Registration.

Scheduled Task

A Scheduled Task is a workflow item that you author among the Automation Server's jobs, not in a class's workflow. To create one, go to Services > Scheduled Tasks > Tasks, which requires the permission of the Scheduled Tasks branch, and click New. A Scheduled Task has a program and no condition, form, template, or roles, and its group name defaults to "Integrations". The Automation Server runs it in a separate process, which executes its program against no object. For the Scheduled Task window, scheduling, and the task's log, see Scheduled Tasks.

Built-in UI actions of project tasks

Only on Project Tasks, the Actions folder of the workflow tree has a Built-in UI Actions node, which holds the class's embedded step actions. An embedded action is left out of the ordinary action list and is reached from elsewhere. Its Step Action window hides Allow to run:, Display in:, and the Additional criteria box. Stock rooms also use embedded step actions, which they bind to a stock-room toolbar and group.

A new database created with the Default Workflow holds one built-in UI action on Project Tasks, Schedule. An upgraded database need not have it, and an administrator may have changed it; see Default Workflow Configuration.