ESM Listener Implemented Actions
ESM Listener Implemented Actions
AlwaysFailDataCardAction
Class: com.efecte.datamodel.entity.action.implementations.AlwaysFailDataCardAction
Trigger: pre save
Description: Prevents saving the data card.
Configuration Items
| Name | Required | Description |
|---|---|---|
| Error Message | No | An optional error message which is displayed for the user / in the log files. Value can be a presentation text for localization purposes. Default value is Validation error (text_validator_error) (Since TODO: add build number (UNDER IMPLEMENTATION) |
Example
<action>
<name>Prevent saving of data card</name>
<class>com.efecte.datamodel.entity.action.implementations.AlwaysFailDataCardAction</class>
</action>ChangeDataCardValuesAction
Class: com.efecte.datamodel.entity.action.implementations.ChangeDataCardValuesAction
Trigger: pre save or post save
Description: Sets an attribute's value.
Configuration Items
| Name | Required | Description |
|---|---|---|
| Code | Yes | Attribute's code. |
| Value | Yes | New value for the attribute. Because the value is given as text, it will limit the possible datatypes, e.g. references doesn't work. Empty value (expressed as <value></value>) means emptying the attribute's value [since 4.2/4.1 4110; before this didn't work and caused error with most datatypes]. |
Example
<action>
<name>Set value to Closed</name>
<class>com.efecte.datamodel.entity.action.implementations.ChangeDataCardValuesAction</class>
<configuration_item>
<name>Code</name>
<value>jobstate</value>
</configuration_item>
<configuration_item>
<name>Value</name>
<value>Closed</value>
</configuration_item>
</action>CopyDataCardValuesAction
Class: com.efecte.datamodel.entity.action.implementations.CopyDataCardValuesAction
Trigger: pre save or post save
Description: Copies a value from source data card to another attribute's value or to a value of an attribute in the target data card. Can also copy values behind references.
4.2 (>=4209) if the copied attribute is multivalue, existing values will be REPLACED. This is not configurable. Multivalues work only on host data card, not behind references.
Configuration Items
| Name | Required | Description |
|---|---|---|
| Code | Yes | Code of the attribute to be changed. |
| Value | Yes | Code of the source data card attribute where the value is copied from. Or, if copying from a reference: $source_data_card_reference_attribute_code:referred_data_card_attribute_code$ |
Example
<action>
<name>Copy parent incident's status to child indicents</name>
<class>com.efecte.datamodel.entity.action.implementations.CopyDataCardValuesAction</class>
<configuration_item>
<name>Code</name>
<value>jobstate</value>
</configuration_item>
<configuration_item>
<name>Value</name>
<value>jobstate</value>
</configuration_item>
</action>CopySourceReferenceAction
Class: com.efecte.datamodel.entity.action.implementations.CopySourceReferenceAction
Trigger: post save
Description: Copies a reference to source data card to target data cards. (Since: Efecte 4.1 4111).
| Name | Required | Description |
|---|---|---|
| Code | Yes | A code of reference attribute in target data card. This attribute will get a reference to source data card. |
Example
<action>
<name></name>
<class>com.efecte.datamodel.entity.action.implementations.CopySourceReferenceAction</class>
<configuration_item>
<name>Code</name>
<value></value>
</configuration_item>
</action>CreateDataCardAction
Class: com.efecte.datamodel.entity.action.implementations.CreateDataCardAction
Trigger: post save
Description: Creates a new Data card, based on configured template and in configured folder. Optionally adds references between the creator and the created data cards, and sets any attribute values in the created card. As a special case, can add the time when editing in the Efecte GUI was started (see SC-604).
Configuration Items
| Name | Required | Description |
|---|---|---|
| Template | Yes | Template code of the template on which the new data card that will be based. |
| Folder | Yes | Folder code of the folder where the created data card will be stored. :SOURCE: will use the folder of the creator. |
| Reference from source | No | Attribute code for reference or back reference attribute in creator data card that will get a reference to the newly created data card. |
| attribute_code_in_created | No | Datatype specific value to be set to the indicated attribute. Note that the value is subject to datatype specific macros, such as date macros. |
| attribute_code_in_created | No | :EDITING_START_TIME: will place the editing start time in a date or string attribute of the created data card. Note that the edit start time is only available when the edit that triggered this action was done through the GUI edit view; thus this configuration item should be used in together with the GuiEdit source condition. |
| attribute_code_in_created | No | :SOURCE: will create a reference to the creator in a reference attribute, or copy the creator name to a string attribute. |
| attribute_code_in_created | No | $refence_path_to_creator_attribute$ copies the value of the indicated attribute of the creator to the indicated attribute of the created. |
Example
<action>
<name>Create new editing report</name>
<class>com.efecte.datamodel.entity.action.implementations.CreateDataCardAction</class>
<configuration_item>
<name>Template</name>
<value>editing_report</value>
</configuration_item>
<configuration_item>
<name>Folder</name>
<value>editing_reports/value>
</configuration_item>
<configuration_item>
<name>Reference from source</name>
<value>ref_to_editing_reports</value>
</configuration_item>
<configuration_item>
<name>start_time</name>
<value>:EDITING_START_TIME:</value>
</configuration_item>
<configuration_item>
<name>end_time</name>
<value>now</value>
</configuration_item>
<configuration_item>
<name>incident_subject</name>
<value>$subject$</value>
</configuration_item>
<configuration_item>
<name>ref_to_incident</name>
<value>:SOURCE:</value>
</configuration_item>
</action>EntityDataCardAction
Class: com.efecte.datamodel.entity.action.implementations.EntityDataCardAction
Trigger: pre save
Description: Moves a data card to trashcan, restores it from the trashcan, permanently deletes,hides or makes a data card visible. Notice that for example DatacardHiddenState-handler may conflict with a listener containing this action. If the template has a DatacardHiddenState-handler the implementation of the listener must take this into account.
Note:
"delete permanently" action currently does not work with non-root permission --> BUG-003907
Configuration Items
| Name | Required | Description |
|---|---|---|
| Entity Action | Yes | Action: "trashcan", "restore", "delete permanently", "hide", "set visible" |
Examples
<action>
<name>Move data card to trashcan</name>
<class>com.efecte.datamodel.entity.action.implementations.EntityDataCardAction</class>
<configuration_item>
<name>Entity action</name>
<value>trashcan</value>
</configuration_item>
</action>
<action>
<name>Restore data card from trashcan</name>
<class>com.efecte.datamodel.entity.action.implementations.EntityDataCardAction</class>
<configuration_item>
<name>Entity action</name>
<value>restore</value>
</configuration_item>
</action>
<action>
<name>Permanently delete data card</name>
<class>com.efecte.datamodel.entity.action.implementations.EntityDataCardAction</class>
<configuration_item>
<name>Entity action</name>
<value>delete permanently</value>
</configuration_item>
</action>
<action>
<name>Hide data card</name>
<class>com.efecte.datamodel.entity.action.implementations.EntityDataCardAction</class>
<configuration_item>
<name>Entity action</name>
<value>hide</value>
</configuration_item>
</action>
<action>
<name>Set data card visible</name>
<class>com.efecte.datamodel.entity.action.implementations.EntityDataCardAction</class>
<configuration_item>
<name>Entity action</name>
<value>set visible</value>
</configuration_item>
</action>ExpressionAction
Class: com.efecte.datamodel.entity.action.implementations.ExpressionAction
Trigger: pre save or post save
Description: Will execute a defined Python script on target data cards. (Since: Efecte 4.1 4111).
Note:
The name of the action is a bit misleading, because this runs scripts, not expressions (as the terms are used in the context of Validator and Expression handlers).
Configuration Items
| Name | Required | Description |
|---|---|---|
| Code | Yes | Code of an attribute of target data card. The result of the expression will be set to this attribute. |
| Expression | Yes | The Python script to be executed. |
FolderDataCardAction
Class: com.efecte.datamodel.entity.action.implementations.FolderDataCardAction
Trigger: pre save or post save
Description: Moves a data card to a specific folder.
Configuration items
| Name | Required | Description |
|---|---|---|
| Folder | No | Code of the folder where the data card is moved, or ":SOURCE:" if the data card is moved to the same folder where the source data is. |
| Folder attribute | No | Attribute's code which has a value which is a folder code where the data card is moved. If folder is configured, it will be used instead of this. |
| Fallback folder | No | Code of the folder where the data card is moved if there's no folder available which was configured with either folder or Folder attribute. |
If the action has no configuration, data card is moved to the same folder where the source data card is. Though, it is recommended to specify folder configuration. Source data card's folder is the default, because this action replaced another action which moved target data cards to source data card's folder and an update script, which would have generated the necessary configuration, would have been too much work.
- Since >=4226. Works with (tested) string, number, decimal, date, date and time, reference and static string and static number. May work with other data types too. Not tested with DropDownReference, but I don't see why it shouldn't work with it too.
Examples
<action>
<name>Move data card to another folder</name>
<class>com.efecte.datamodel.entity.action.implementations.FolderDataCardAction</class>
<configuration_item>
<name>folder</name>
<value>folder_code</value>
</configuration_item>
</action>
<action>
<name>Move data card to another folder specified by an attribute</name>
<class>com.efecte.datamodel.entity.action.implementations.FolderDataCardAction</class>
<configuration_item>
<name>Folder attribute</name>
<value>attribute_code</value>
</configuration_item>
</action>SaveDataCardAction
Class: com.efecte.datamodel.entity.action.SaveDataCardAction
Trigger: post save
Description: Saves the data card. This enables calculating new values to attributes containing a handler (ExpressionHandler or such).
Configuration items
| Name | Required | Description |
|---|---|---|
| - | - | - |
Example
<action_chain>
<name>Saves datacards</name>
<action>
<name>Saving datacards</name>
<class>com.efecte.datamodel.entity.action.SaveDataCardAction</class>
</action>
</action_chain>SaveDataCardXmlToFileAction
Since: 5.4 5400
Class: com.efecte.datamodel.entity.action.SaveDataCardXmlToFileAction
Trigger: post save
Description: Saves the data card in XML form to a specified file and folder. Note that this action operates only on the source data card that is saved. If the file exists, it will be overwritten (file is deleted before writing new file). Action tries first to write the XML to a temporary file and then renames the temporary file to the specified file. This is to prevent anyone reading the result file before it's completely written.
Configuration Items
| Name | Required | Description |
|---|---|---|
| Target file | Yes | Name of the file (path) where the XML is saved. May contain the following macros: $now$, $TIMESTAMP$, and $ENTITY_ID$. These are expanded, respectively, to current date (in yyyy-MM-dd format), current timestamp (time elapsed in milliseconds since the epoch), and the ID of the data card in the database. |
Example
<action>
<name>Save to file</name>
<class>com.efecte.datamodel.entity.action.implementations.SaveDataCardXmlToFileAction</class>
<configuration_item>
<name>Target file</name>
<value>C:/Temp/entity-$ENTITY_ID$-$TIMESTAMP$.xml</value>
</configuration_item>
</action>SendDataCardXmlToWebService
Since: 4.2 4235
Class: com.efecte.datamodel.entity.action.implementations.webservice.SendDataCardXmlToWebService
Trigger: post save
Description: Sends data card in XML form to configured SOAP web service. Note that this action operates only on the source data card that is saved.
Configuration Items
| Name | Required | Description |
|---|---|---|
| endpointAddress | Yes | Endpoint address that defines where the Web Service is located. An example: http://localhost:8080/axis2/services/EfecteNotifyService. You can put the user and password to the URL directly, if HTTP BASIC authentication is used at the Web Service side. Then, the URL would look like this: http://user:password@localhost:8080/axis2/services/EfecteNotifyService |
| entitysetTargetNamespace | Yes | Target Namespace for the entityset element. An example: http://integration.efecte.com/notify/request |
| operationName | Yes | Operation: currently only value can be "Notify" |
| Require changed data | Yes | "True" or "False". If true, message is sent only when something has changed. If false, message is sent always when the data card is saved. Source conditions can still be used to define when this action is executed. For example, message is sent only when a certain attribute's value has changed. |
SendMailAction
Class: com.efecte.datamodel.entity.action.implementations.SendMailAction
Trigger: post save
Description: Sends mail.
Since: 5.1 build 5114
Notes:
- Data card deletion triggers listeners too, so be careful with source conditions.
- Action doesn't prevent data card storing even if mail can't be sent for any reason (misconfiguration, mail server down, etc.).
- If listeners are configured to be run as non-root user ensure that configured user can access required attributes.
- Mail server settings are defined in Platform Settings. They cannot be overwritten in listener configuration.
- At least one of configuration items To, Cc or Bcc must have value.
- Differences to AutoMailSenderHandler:
- Folder metadatas
automail_recipientandautomail_recipient_[attribute_code]are not supported. They can be replaced with FolderSourceConditions. - Tags
$name$,$template$and$from$are not supported. - Setting do_not_check_for_change isn't supported. Because this action doesn't check if values of datacard change, the setting isn't needed. SourceConditions can be used to implement preconditions for this action.
- Folder metadatas
Configuration Items
| Name | Required | Description |
|---|---|---|
| From | Yes | Sender address(es). May include reference(s) to attribute(s) in format $attribute_code$ or $code_of_reference:attribute_code$. Separate multiple addresses by comma or semicolon. |
| To | No | Recipient address(es). May include reference(s) to attribute(s) in format $attribute_code$ or $code_of_reference:attribute_code$. Separate multiple addresses by comma or semicolon. |
| Cc | No | Carbon copy recipient address(es). May include reference(s) to attribute(s) in format $attribute_code$ or $code_of_reference:attribute_code$. Separate multiple addresses by comma or semicolon. |
| Bcc | No | Blind carbon copy recipient address(es). May include reference(s) to attribute(s) in format $attribute_code$ or $code_of_reference:attribute_code$. Separate multiple addresses by comma or semicolon. |
| Subject | No | Subject of the message. May include reference(s) to attribute(s) in format $attribute_code$ or $code_of_reference:attribute_code$. Multivalues are separated by comma. |
| Message | No | Message text. Text may contain line breaks. <![CDATA[]]> can be used if special characters are needed. May include reference(s) to attribute(s) in format $attribute_code$ or $code_of_reference:attribute_code$. Multivalues are separated by comma. |
| Content-type | No | MIME type for the message. For example, text/html. The default is text/html. Possible values are text/plain and text/html. |
| Send once | No | Unique ID. If Send once is set, the listener will send mail only for once per a given data card. In case AutoMailSender is replaced with a listener, use AutoMailSender's attribute's class attribute ID as value. When creating new SendMailAction without previous AutoMailSender configuration, use whatever unique ID you want. Just make sure no other listener will use the same ID (unless you specifically want two or more listeners to use the same ID). |
| Attachments | No | File name(s) of files in the directory named "uploads/sendmailaction". The files must be manually added to server because there is not a GUI in Efecte for that. Reference(s) to attribute(s) in format $attribute_code$ or $code_of_reference:attribute_code$. Attribute(s) must be of External reference type. Separate multiple files by semicolon. |
Example
<action>
<name>Send mail</name>
<class>com.efecte.datamodel.entity.action.implementations.SendMailAction</class>
<configuration_item>
<name>From</name>
<value>servicedesk@company.com</value>
</configuration_item>
<configuration_item>
<name>To</name>
<value>$customer:email$</value>
</configuration_item>
<configuration_item>
<name>Subject</name>
<value>Your request for support - $Identifier$ has been received</value>
</configuration_item>
<configuration_item>
<name>Message</name>
<value>Thank you for contacting Service Desk.</value>
</configuration_item>
</action>SendSourceChangedJMSMessageAction
Class: com.efecte.datamodel.entity.action.implementations.SendSourceChangedJMSMessageAction
Trigger: pre save or post save
Description: Action will send a JMS message to queue when the data card is saved. The contents of the message is the data card in whole in Efecte XML format.
Configuration Items
| Name | Required | Description |
|---|---|---|
| Url | Yes | URL where the message is sent. |
| Subject | Yes | Subject of the queue. |
| User | No, but needed with Efecte Integration Suite | User account. |
| Password | No, but needed with Efecte Integration Suite | Password for user account. |
| Require changed data | Yes | "True" or "False". If true, message is sent only when something has changed. If false, message is sent always when the data card is saved. Source conditions can still be used to define when this action is executed. For example, message is sent only when a certain attribute's value has changed. |
| XmlEncoding | No | Optional encoding for the XML. |
TargetedSccmUpdateAction
Since: 5.1 51??
Class: com.efecte.integration.database.inventory.TargetedSccmUpdateAction
Trigger: post save
Description: Triggers a targeted SCCM update. This should be attached to Administered software template, and should be triggered when an AS becomes "Monitored" (see the example below). The action finds any computers that seem to have that software installed (based on "All installed software" field). It then takes the SCCM resource IDs of those computers, queues them for update, and finally tells SccmIntegrationTask to perform a targeted run using only the queued IDs.
Note that the task run itself happens in the background, so there is no significant delay when saving the original data card. The task run gets started after a few minutes, so if several AS cards become Monitored within a short period of time, all resource IDs are grouped and updated in the same SccmIntegrationTask task run.
NB: We also considered giving this a more generic name, e.g. something related to database inventory, or even "RunSchedulableTaskAction", but since this is now tied to SCCM and triggering only a certain kind of SccmIntegrationTask run, it is named like this.
Configuration Items
No configuration items needed.
Example
<template code="LicenseManagementSoftware" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
<listener>
<name>postsave.4.When Administered software becomes Monitored, update installation information from SCCM</name>
<trigger>post save</trigger>
<source_conditions boolean="AND">
<source_condition>
<value>
<attribute>
<code>monitored_software_status</code>
<current_value>true</current_value>
</attribute>
<operator>=</operator>
<compared_value>Monitored</compared_value>
</value>
</source_condition>
<source_condition>
<value>
<attribute>
<code>monitored_software_status</code>
<current_value>false</current_value>
</attribute>
<operator>!=</operator>
<compared_value>Monitored</compared_value>
</value>
</source_condition>
</source_conditions>
<action_chain>
<name>Run targeted SCCM update</name>
<action>
<name>Run targeted SCCM update</name>
<class>com.efecte.integration.database.inventory.sccm.TargetedSccmUpdateAction</class>
</action>
</action_chain>
</listener>
</template>TransformDataCardAction
Since: 4.2 4210
Class: com.efecte.datamodel.entity.action.implementations.TransformDataCardAction
Trigger: post save
Description: Action transforms currently edited data card to another data card. Uses rules and target folder defined in transforms. Rules cannot be currently defined in the listener XML itself.
Note:
You must ensure with source conditions that the transform happens only in wanted situations, for example when an attribute gets a value for the first time. Otherwise new data cards may be created whenever host data card is moved or copied to another folder or deleted.
One ActionChain may contain several TransformDataCard actions. Creating several new cards in an ActionChain is also supported since 4.2 4210.
Configuration Items
| Name | Required | Description |
|---|---|---|
| TargetTemplate | Yes | Code of the target template. |
Example
<action_chain>
<name>Transform datacard</name>
<action>
<name>Transform</name> <class>com.efecte.datamodel.entity.action.implementations.TransformDataCardAction</class>
<configuration_item>
<name>TargetTemplate</name>
<value>service_request</value>
</configuration_item>
</action>
</action_chain>
Table of Contents