Detailed Descriptions of ESM Listener Actions
Detailed Descriptions of ESM Listener Actions
AlwaysFailDataCardAction
- Prevents saving the data card.
Class
com.efecte.datamodel.entity.action.implementations.AlwaysFailDataCardAction
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). |
ChangeDataCardValuesAction
- Sets an attribute's value.
- Clears an attribute's value.
Class
com.efecte.datamodel.entity.action.implementations.ChangeDataCardValuesAction
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 (<value></value>) means emptying the attribute's value. |
CopyDataCardValuesAction
- 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.
- If the copied attribute is multivalue, existing values will be REPLACED.
- Multivalues work only on host data card, not behind references.
- If copying values to a multivalue target attribute, only the first value is copied if the target attribute is of the reference datatype, and the source attribute is not.
Class
com.efecte.datamodel.entity.action.implementations.CopyDataCardValuesAction
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$ |
CopySourceReferenceAction
- Creates a reference from target data cards to source data card.
Class
com.efecte.datamodel.entity.action.implementations.CopySourceReferenceAction
Configuration Items
| Name | Required | Description |
|---|---|---|
| Code | Yes | A code of reference attribute in target data card. This attribute will get a reference to source data card. |
CreateDataCardAction
- Creates a new data card, based on the configured template and in a configured folder.
- Optionally, adds references between the creator and the created data cards.
- Optionally, sets any attribute values in the created card.
- As a special case, can add the time when editing in the ESM UI was started (see “:EDITING_START_TIME:” below).
Class
com.efecte.datamodel.entity.action.implementations.CreateDataCardAction
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. |
EntityDataCardAction
- Moves a data card to trashcan or restores it from the trashcan.
- Permanently deletes a data card.
- Hides or makes a data card visible.
Note:
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. Check the execution order of listeners and handlers.
Class
com.efecte.datamodel.entity.action.implementations.EntityDataCardAction
Configuration Items
| Name | Required | Description |
|---|---|---|
| Entity Action | Yes | Action: "trashcan", "restore", "delete permanently", "hide", “set visible”. |
ExpressionAction
- Will execute a defined Python script on target data cards.
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).
Class
com.efecte.datamodel.entity.action.implementations.ExpressionAction
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
- Moves a data card to a specific folder.
Class
com.efecte.datamodel.entity.action.implementations.FolderDataCardAction
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. |
SaveDataCardAction
- Creates a reference from target data cards to source data card.
- This enables calculating new values to attributes containing a handler (ExpressionHandler or such).
Class
com.efecte.datamodel.entity.action.SaveDataCardAction
Configuration Items
| Name | Required | Description |
|---|---|---|
| - | - | - |
SaveDataCardXmlToFileAction
- Saves the data card in XML form to a specified file and folder.
- 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.
Class
com.efecte.datamodel.entity.action.SaveDataCardXmlToFileAction
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. |
SendDataCardXmlToWebService
- 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.
Preemptive Basic Authentication
This feature allows for more efficient authentication processes by sending credentials proactively, reducing the number of round-trips required for authentication.
How to Enable:
- Globally: Set the platform setting datacard.listeners.preemptive.authentication=true
- Per Listener: In the action configuration, add "preemptiveAuthentication=true" to the "connectionParameters" item
Note: If enabled globally, you can disable it for specific actions by setting "preemptiveAuthentication=false" in the action's "connectionParameters" configuration item.
Class
com.efecte.datamodel.entity.action.implementations.webservice.SendDataCardXmlToWebService
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. |
| username | No | Username for http basic authentication. If not given basic authentication is not used. |
| password | No | Password for http basic authentication. If not given basic authentication is not used. |
| useChunkedTransferEncoding | No | "True" or "False". Default is "True". If false chunked transfer encoding is not used. |
| connectionParameters | Defines the connection configuration options. <configuration_item> <name>connectionParameters</name> <value>acceptSelfSignedCertificates=false,allowAllHostnamesInCertificate=true,connectionRequestTimeout=60,connectTimeout=60,socketTimeout=60</value> </configuration_item> If the preemptive basic authentication is not set as “true” in the Platform setting “ datacard.listeners.preemptive.authentication” and you want to turn it on for this Listener, add this under “connectionParameters”: preemptiveAuthentication=true |
SendDataCardXmlToHttpAction
- Sends data card as an XML message to an external service.
- The sent message can be transformed to any desired format using an XSLT transformation.
- The messages are sent to a queue, which takes care of resending the message if sending fails.
Preemptive Basic Authentication
This feature allows for more efficient authentication processes by sending credentials proactively, reducing the number of round-trips required for authentication.
How to Enable:
- Globally: Set the platform setting datacard.listeners.preemptive.authentication=true
- Per Listener: In the action configuration, add "preemptiveAuthentication=true" to the "connectionParameters" item
Note: If enabled globally, you can disable it for specific actions by setting "preemptiveAuthentication=false" in the action's "connectionParameters" configuration item.
Class
com.efecte.datamodel.entity.action.implementations.http.SendDataCardXmlToHttpAction
Configuration Items
| Name | Required | Description |
|---|---|---|
| endpointURL | The URL on where 3rd party provide the service. Port, service context should be combined in this URL. | |
| endpointMethod | Defines what kind of method will be used to contact 3rd party. (post/delete). | |
| endpointService | The service that is going to consume provided by 3rd party, i.e. ESSAnnouncement, Other(=ESM). | |
| username | Username defined in the BASIC authentication from 3rd party. | |
| password | Password defined in the BASIC authentication from 3rd party. | |
| datetimePattern | Defines the datetime format pattern will be used in xml as payload to be sent out. Example: <configuration_item> <name>datetimePattern</name> <value>yyyy-MM-dd'T'HH:mm:ssXXX</value> </configuration_item> |
|
| expectedResponseCodeMessage |
The combination of expected Response code and message. Example 1: Both 200 and 404 are accepted as response code. For code 200, the response message should be empty or null. For code 404, "Cannot delete a non-existent announcement" should be contained in the response message. |
|
| xslTransformFile | Defines the place where we could define the xsl file in file system. <configuration_item> <name>xslTransformFile</name> <value>/home/likewise-open/server777/ESSAnnouncement1.xsl</value> </configuration_item> |
|
| xsl |
Defines the code as embedded xsl: <xsl:transform version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.efecte.com/integration/update/xsd/1.0" > ]]> |
|
| xslParameters | Defines multiple input parameters for transforming by XSL. Example 1: <configuration_item> <name>xslParameters</name> <value>ess_tenant=customer</value> </configuration_item> Example 2: <configuration_item> <name>xslParameters</name> <value>ess_tenant=customer, xxx=yyy</value> </configuration_item> |
|
| xsdSchemaFile | Defines the corresponding xsd file to validate the xml content going to be sent out. <configuration_item> <name>xsdSchemaFile</name> <value>/home/likewise-open/server777/update.xsd</value> </configuration_item> |
|
| connectionParameters | Defines the connection configuration options. <configuration_item> <name>connectionParameters</name> <value>acceptSelfSignedCertificates=false,allowAllHostnamesInCertificate=true,connectionRequestTimeout=60,connectTimeout=60,socketTimeout=60</value> </configuration_item> If the preemptive basic authentication is not set as “true” in the Platform setting “ datacard.listeners.preemptive.authentication” and you want to turn it on for this Listener, add this under “connectionParameters”: preemptiveAuthentication=true |
|
| outputEncoding | Defines the encoding for output XML. <configuration_item> <name>outputEncoding</name> <value>UTF-8</value> </configuration_item> |
SendMailAction
- Sends mail.
- 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.
Class
com.efecte.datamodel.entity.action.implementations.SendMailAction
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. |
SendSourceChangedJMSMessageAction
- 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.
Class
com.efecte.datamodel.entity.action.implementations.SendSourceChangedJMSMessageAction
Configuration Items
| Name | Required | Description |
|---|---|---|
| Url | Yes | URL where the message is sent. |
| Subject | Yes | Subject of the queue. |
| User | No | User account. |
| Password | No | 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
- Triggers a targeted SCCM update.
- This should be attached to Administered software template, and should be triggered when an AS becomes "Monitored" (usually a part of baseline configuration).
- 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:
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.
Configuration Items
| Name | Required | Description |
|---|---|---|
| - | - | - |
TransformDataCardAction
- Action transforms currently edited data card to another data card. Uses rules and target folder defined in transforms.
- One ActionChain may contain several TransformDataCard actions. Creating several new cards in an ActionChain is also supported.
Note:Title
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.
Configuration Items
| Name | Required | Description |
|---|---|---|
| TargetTemplate | Yes | Code of the target template. |
Table of Contents