Service Actions and Field Mappings
On this page
- In the Settings App
- Where you create a service action
- The service action window
- The Template tab
- The Field Mapping tab
- The Field Mapping window
- Where the service attributes come from
- What a mapping cannot target, and what is added for you
- Default field mappings
- Mail Connector service attributes
- Portal service actions
- Scheduled Task
- Built-in UI actions of project tasks
- Related topics
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
thumbnailPhotoorjpegPhotoreceives the user's photograph, scaled to fit 300 x 300.memberOfreceives 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.