Build a Custom Action

This page provides instructions on custom actions in AppDynamics.

You can set up a custom action on the Controller instance to integrate notification of AppDynamics health rule violations and events with an alerting or ticketing system. Use a push approach by creating custom notifications that pass the information to your alerting system.

Custom Notifications and Custom Actions

A custom notification lets you integrate alerts about AppDynamics health rule violations and events into your own alerting system. This integration extension requires:

• A custom.xml file that provides information about the custom notification.
• An executable script that accepts parameters from AppDynamics about the events and health rule violations that trigger an alert.
• Configuring AppDynamics events or policies to trigger the custom notification via a custom action.

Create a Custom Action

Create the Script

For each custom action that you want to implement, create an executable script (.bat extension for Windows, .sh extension for Linux) that can accept and process the parameters passed to it by AppDynamics. See Information Passed to the Custom Action Script from AppDynamics for details on the parameters.

For each script:

• Set correct executable permissions for the shell scripts in a Linux environment. For example, chmod 770 script1.sh.
• Ensure that the script file has the correct character encoding. This is especially important when creating a Unix shell script on a Windows machine.

Install the Script on an On-Premises Controller

To install the script on an on-premises Controller:

1. At the top level of the Controller installation directory, create a directory named custom with a sub-directory named actions.

   <controller_home>/custom/actions

   CODE

2. In the <controller_home>/custom/actions directory, create a subdirectory for each custom action script that you will install. For example, for an action that interfaces with a JIRA system.

   <controller_home>/custom/actions/jira

   CODE
3. Move the script to the appropriate subdirectory that you created.

Create the XML File

1. Create a custom.xml file that describes the location and name of your custom action script. See Contents of the custom.xml File.
2. For an on-premises Controller, move the file to the <controller_home>/custom/actions directory. For a SaaS Controller, contact your AppDynamics account representative for instructions.

Verify the Script on an On-Premises Controller

1. After you have installed the script and the custom.xml file, restart the Controller.
2. Verify the script manually. To verify the script:
    a. Open a command-line console on the Controller host machine.
    b. Execute the script file from the command line console.

Create the Custom Action

To arrange how a custom action will be triggered, see Custom Actions.

Contents of the custom.xml File

The custom.xml file has an <actions> element for every custom action on the Controller. 

The <type> element contains the subdirectory that contains the script file.

The <executable> element contains the name of the script.

Sample custom.xml File

<custom-actions>
  <action>
     <type>jira</type>
     <executable>script1.bat</executable>
  </action>
  <action>
    <type>bugzilla</type>
    <executable>script2.sh</executable>
  </action>
</custom-actions>

Information Passed to the Custom Action Script from AppDynamics

The custom action script must handle the parameters that the Controller passes from the health rule violation or other event. The parameter values are passed as an array of strings.

The parameters are passed as $0 for the script name, then $1, $2, . . . $n.  $1 is the first parameter (application name), $2 is the application id, and so on in the order in which they are documented in the sections below.

Health rule violations have a different set of parameters from events.

Parameters Passed by a Health Rule Violation

The parameters describe the violated health rule violation that triggered the action.

The total number of elements in the array depends on the number of entities evaluated by the health rule and the number of triggered conditions per evaluation entity. Examples of evaluation entities are application, tier, node, business transaction, JMX. For each evaluation entity, the script expects the entity type, entity name, entity id, number of triggered conditions, and for each triggered condition, the set of condition parameters.

The parameter values are passed in the order in which they are described.

Structure of Parameters Sent by a Health Rule Violation

• APP_NAME
• APP_ID
• PVN_ALERT_TIME

• PRIORITY

• SEVERITY // INFO, WARN, ERROR 
• ACTION_NAME
• HEALTH_RULE_NAME
• HEALTH_RULE_ ID
• PVN_TIME_PERIOD_IN_MINUTES

• AFFECTED_ENTITY_TYPE

• AFFECTED_ENTITY_NAME
• AFFECTED_ENTITY_ID
• NUMBER_OF_EVALUATION_ENTITIES—The following parameters are passed for each evaluation entity:
  
  • EVALUATION_ENTITY_TYPE

  • EVALUATION_ENTITY_NAME

  • EVALUATION_ENTITY_ID

  • NUMBER_OF_TRIGGERED_CONDITIONS_PER_EVALUATION_ENTITY—The following parameters are passed for each triggered condition for this evaluation entity:
    
    • SCOPE_TYPE_x

    • SCOPE_NAME_x

    • SCOPE_ID_x
    • CONDITION_NAME_x

    • CONDITION_ID_x
    • OPERATOR_x

    • CONDITION_UNIT_TYPE_x

    • USE_DEFAULT_BASELINE_x

    • BASELINE_NAME_x

    • BASELINE_ID_x

    • THRESHOLD_VALUE_x

    • OBSERVED_VALUE_x

• SUMMARY_MESSAGE

• INCIDENT_ID

• DEEP_LINK_URL
• EVENT_TYPE

• ACCOUNT_NAME
• ACCOUNT_ID
• TAG

Definitions of Parameters Sent by a Health Rule Violation

http://<controller-host-url>/#location=APP_INCIDENT_DETAIL&incident=<incident-id>

Parameters Passed by an Event

The parameters describe the event that triggered the action.

The total number of elements in the array depends on the number of event types and event summaries that triggered the action. 

The parameter values are passed in the order in which they are described.

Structure of Parameters Sent by an Event

• APP_NAME
• APP_ID
• EN_TIME 

• PRIORITY

• SEVERITY 

• EN_NAME

• EN_ ID
• EN_INTERVAL_IN_MINUTES

• NUMBER_OF_EVENT_TYPES
The following parameters are passed for each event type:
  
  • EVENT_TYPE_x

  • EVENT_TYPE_NUM_x
    
• NUMBER_OF_EVENT_SUMMARIES
  The following parameters are passed for each event summary:
  
  • EVENT_SUMMARY_ID_x

  • EVENT_SUMMARY_TYPE_x
  • EVENT_SUMMARY_SEVERITY_x
  • EVENT_SUMMARY_STRING _x
• DEEP_LINK_URL

• ACCOUNT_NAME
• ACCOUNT_ID
• TAG

Definitions of Parameters Sent by an Event