ITAM Actions

Actions in ITAM are triggered automations that can send mail, change records, or call a webhook.

Found as a sub navigation item under Settings in the main left sidebar of the ITAM web interface.

Actions allow you to build various kinds of automations. These can be very powerful, and therefore possibly dangerous if you were to accidentally create an infinite loop of conditions between two actions, or flood someone's email with system changes. Be sure to test your Actions and consider their conditions carefully.

There are 3 basic Types of Actions, each of which will offer different conditions for creating them.

• Send Mail on Event - As indicated, this will send an email when something occurs. For example, if the amount of RAM changes in any computer, send an alert, provided it is not in a divison that contains "Thin Clients" and is not getting RAM data for the first time. Macros can be used to populate data in the email subject and message.

 

• Call a Webhook - Use this to make a call to an external system to make a change based on an event in the KeyServer. For example (purely hypothetical), when a computer is moved to Dormant, call on another web based system to remove the computer from your DNS system.
• Change Computer/Device on Event - Based on one property change, make another property change. For example if a computer is moved to the Disposed Life Stage, also move it to a Dormant Login status.     

Triggers

The Trigger is what kicks off the Action. Events can be the change of a computer property, or a certain type of Journal entry being created. These can also be Signals as set in Forms. A Signal uses the syntax sgnl.form.fill.signalname where the signal name is optional and set in the Form Properties. If you do not specify the signalname then the Action will triger on ANY form save event where Signal on Save is enabled.

Filters

You can create filter criteria on Actions. These differ based on the type of action:

• Change actions have a visual filter builder that is the same as what you see when building a Filter on the Computers or Devices pages. This allows for each field selection, logical operator choice, and variable editing.
• Email actions on the other hand are special. It is a purely manual method that goes back to making Filters in KeyConfigure. However, instead of using the field names from the Tables documentation, use the Macros as shown below (do NOT include the braces). Note you can also use a macro by itself to test for "truth" of that condition. For example, (event.from) tests to see if there is a from value on the event, so you could filter out all events where it's the initial population of the field by the client and only trigger on change.

RegEx and Advanced Lookups

It is possible to use regular expressions inside the macro syntax explained above, and also reference a json style lookup table. The Advanced Lookups field holds that lookup table information. This allows for at least one specific use case by design, which is parsing a computer name in a more advanced manner than simple Rules can handle. For example, if you need to look at the 4th and 5th characters of the computer name to determine what Division the computer should be in, these advanced features can do that.

Regex is simple only, not extended.  This means you can not use braces or carets in the expressions for example.  The syntax of using regex and lookups in a macro follow this general pattern:

Note that the lookup can in fact be an internal [table].[field] as well as a lookup specified in the action.  So for example:

says to take the name of the object (i.e. the computer that just got triggered), pass the 4th and 5th characters of the name to a variable, and look up that value in the locationlookup table.  We would put this in the field for the "Make these changes" portion of the Action for a Field like Building or Location.  That table in the Advanced Lookups would in turn look something like this:

So we create a simple way to get human readable strings for the field we want to populate, like Building, Location, etc based on the information we have encoded into our computer naming convention.

Other examples might include:

Look up the Last User in the User table and grab their Department.  You might have a use case to put this in the Department field of the Computer so that each record dynamically sets its department based on the last person to log in to the machine.  (likely not useful in most organizations but a good example of cross table lookup capability)

Simply take the 3 characters after the first dash in the computer name and return it.  Maybe this is the part of the computer name that is the Room it is assigned to so you put this in the Room field.

Consider with these examples you could therefore have one Action that when the Name changes on a Computer, sets the Department, Building, Room, Location, and Region all based on individual macros that may include lookup tables.  Each macro is slicing up a different portion of the name for the needed information to set the field value.

Macros

Actions can customize their results using macros that change depending on the details of the trigger event. Macros are enclosed in double braces and can be placed within most fields of the action. For example, to embed the current date, use {{now.date}}

There are five macro groups. The specific macros that are available depend on the type of action, as indicated below.

• now (all action types)
• connection (Mail, Webhook)
• mail (Mail)
• event (all action types)
• object (all action types, when event has a subjectid/subjecttype)

Now Group

Return the current date information in a given format.

now.datetime (2022-09-25 20:01:52)
now.date (2022-09-25)
now.time (20:01:52)
now.iso (2022-09-25T20:01:52-0400)
now.rfc (Sun, 25 Sep 2022 20:01:52 -0400)
now.day (Sunday)
now.month (September)
now.unix (1664150512)

Connection Group

connection.host
connection.server
connection.version
connection.admin
connection.section
connection.weburl

Mail Group

mail.from
mail.recipients
mail.date
mail.uuid

Event Group

Information related to the event that is triggering the action.

Computer / Device History (event.class = trail)

event.class
event.instance
event.when
event.subjecttype
event.subjectid
event.subjectname
event.hexid
event.txtid
event.what
event.from
event.into

Admin Journal (event.class = journal)

event.class
event.instance
event.latest
event.when
event.what
event.code
event.subjecttype
event.subjectid
event.subjectname
event.hexid
event.txtid
event.topicid
event.count
event.admin
event.comment
event.notes
event.level
event.committed
event.repealed
event.multiple
event.failure
event.agentless
event.resolvable
event.dateonly
event.deadline
event.sectionid
event.resolved.when
event.resolved.result
event.resolved.admin

Usage Log (event.class = usage)

event.class
event.instance
event.when
event.what
event.reason
event.duration
event.othertime
event.foreground
event.count
event.gmtoffset
event.flags
event.closed
event.tunnel
event.authed
event.remote
event.mobile
event.address
event.expansion
event.user
event.client
event.program
event.product
event.family
event.policy
event.computer
event.division

Signals (event.class = signal)

Used when triggering an action from a Signal in a Form.

event.class
event.instance
event.when
event.what
event.code
event.label
event.subjecttype
event.subjectid
event.subjectname
event.hexid
event.txtid
event.admin
event.description (Signal Message in Form)

Object Group

object.fieldname
(full object per subjecttype/subjectid of event)

For a list of fields see the Tables Documentation. Note the special case of object.division which will operation the division Name rather than the ID. Note you must use the full field name that appears after 'computer' for example, not a short name from the database. That is, to get the last session time for example you'd use object.lastlogin.

You can also reference linked tables. This takes the example syntax of {{object.owner:user.email}} (i.e. object.fieldname:linkedtable.fieldname) which in this case would return the email address of the User that is in the Owner field of the Computer record that is the Object of the triggered Action.

Examples

An example of using these might be an email for alerting you when a Division is deleted from the system:

{{event.subjecttype}} {{event.subjectname}} deleted by {{event.admin}} at {{event.when}}

This would yield: "division a-test.layer2 deleted by Yadin at 2022-10-11 12:44:23" for example.

For a Change Action you can apply all of the above and create some extremely advanced entries.  For example, if you had a Division structure that mirrored the various information encoded in your computer naming convention, you could string the macros you use per the above to set Building, Room etc to make the Division as well.  The follow is a real customer use case:

We have a series of macros here separated by periods (the division name delimiter for "subdivisions") that take parts of the computer name and either directly return them or perform a lookup.  In English, the first macro outputs the first character of the name, a period, and the next two characters of the name, then we put a period, then the second macro performs a lookup of the 4th character of the name on a table and returns that result, and then we append the 5th character of the name.  So 1.23.stuff5 is the effective result.  Highly specific but very well illustrates the flexibility of what these features can do in a standardized environment.

For those that enjoy the full power of regex, you can do things like this:

which will take the serial of the object, remove the dash between a letter and number group (if this was your expected pattern) and return the string without it (so ABC-123 becomes ABC123).

 Or another esoteric customer example:

Which takes the value of the first Custom field on the object, delimits it on the first period, passes the first segment through a lookup table, and you wind up with the rest of the string exactly as it was.

And in a similar situation:

Which takes a 3 part colon delimited department string we've pulled in from somewhere else, and spits back part 2 and 3 period delimited for use as a Division string.