Adding or editing a custom action adapter

Use the instructions in this topic to add or edit a custom action adapter using the The referenced document [xwiki:Automation-DevSecOps.Network-Automation.TrueSight-Network-Automation.tsna251.TrueSight Network Automation 25\.1._Inclusion-Library._Common-terminology.WebHome] was not found. UI.

For an overview of the device adapter creation process, see Adding-or-editing-device-adapters. See Example-of-creating-a-custom-action-adapter-using-UI for an example of creating a custom action adapter.

Adding a custom action adapter

On the Admin > Network Admin > Device Adapters page, click Add > Custom Action, and do the following:

1. On the Declaration tab, enter the following information:

   Field	Description
   Name	Specify a unique name for the custom action that will be displayed to the custom action users on the job, predefined job, or policy page.
   Menu Group (Optional)	Specify a name that defines the group or category of this custom action within the cascaded menus on the job, predefined job, or policy page (for example, VLAN Management or Interface Monitoring). You can add your own groups by clicking Add New Group or you can select from the groups shared with the out-of-the-box content (such as Diagnostics, Hardware, or Topology). If you do not specify a name, custom action appears on the first level of cascaded menu.
   Classification (Optional)	Select the category or the type of the action. The classification is based on how the action manipulates the device. Valid values are: Deployment: The action makes a modification to the device. Snapshot: The action takes a snapshot of some settings in the device, but makes no changes. Notification: The action does not access the device, but emits a notification (such as an email message or trap). Other: The action does something other than deployment, snapshot, and notification. If you do not select any option, action does not fall into any classification. Note: TrueSight Network Automation – Data Warehouse uses this information when it generates various reports based on the types of jobs and actions that were performed. Otherwise, this value does not affect any processing.
   Description (Optional)	Specify a description that should be displayed to the users when they are creating or editing an instance of this action in a job, predefined job, or policy, to provide instructions or detailed information about what the action does.
   General Information (Optional)	Specify general notes, warnings, quirks, or anything else special about executing this custom action on this particular device type that might affect how users use it. Note: Use the CDATA tag to enclose HTML elements that format this information for display in the Device Adapter Capabilities report. Refer to Common-concepts-and-XML-elements for more information about CDATA.
   Options (Optional)	Select the following options: Browser Executable: Indicates whether this custom action can be executed from the UI. Otherwise, it is available only through web services. Approvable: Indicates whether the custom action is available in the list of actions for the Enable Job Approval For Action system parameter on the Admin > System Admin > System Parameters page. The administrator can control whether the action requires job approval and which users can perform the approval. Inspection Only: Indicates whether the custom action makes any changes to the device. If you do not select this option (meaning changes are made), the system automatically takes a snapshot to keep track of the changes. If selected, no snapshot is taken.This option also affects when the discover-core command is run, which discovers the model and operating system version. When this option is selected, discover-core is not executed at all. When selected, it is executed after the custom action logic and before the automatic snapshot. In either case, your custom action logic cannot depend on properties being present that are normally populated by discover-core. Hide the Mark As Trusted Option: Indicates whether the users are presented with the Mark As Trusted option for this custom action on the job, predefined job or policy page. This option controls what happens to the configurations taken during the snapshot. This option is ignored if you have selected the Inspection Only option.
   Device Dynamic Fields to Be Populated (Optional)	Add the device dynamic fields into which custom action results should be populated. Click Add, and enter the following information for the dynamic field: Dynamic Field to Be Populated: Select the name of the dynamic field to be populated. The dynamic field must exist at the time the custom action is executed by a job. If the dynamic field does not exist, value assignment is silently skipped. Name of the Source Result Property: Specify the name of the property this custom action populates, whose value is to be the value for the dynamic field. If the property is not populated by the custom action and the dynamic field is system assigned, then any current value in the device is removed. On Bad Value: Select how the system should handle invalid values. The value pulled from the specified property is checked against the constraints imposed by the specified dynamic field. For example, a Text type field imposes a maximum length; an Integer type field can impose minimum and maximum values; a single-select and multi-select Menu type field restricts values to those in its menu options. By default, invalid values are silently ignored. Valid values are: Log an Event: Log the warning event, custom action captured an invalid value for a dynamic field. Flag the Action as Completed With Error: Report this as a minor failure of the custom action, which results in the job completing with warning. Flag the Action as Completed With Warning: Report this as a minor failure of the custom action, which results in the job completing with error. Reject Unknown Menu Options: Indicates whether the menu option not already present in a single-select or multi-select Menu type field is rejected. When this option is selected, only known menu options are accepted, with error handling per the On Bad Value field. When not selected, new values are automatically added to the menu of the dynamic field.
   Result Properties That Populate Imported Hardware Inventory (Optional)	Specify the name of the result property this custom action populates, whose value is to be the value for the device's imported hardware inventory. The imported inventory is displayed when the users view the device or the Device Inventory report. You can specify multiple result properties, in which case the property values are concatenated together. If none of the properties are populated while executing the custom action, then the device's imported hardware inventory is not changed.
   Runtime Parameters (Optional)	Add the parameters that need to be passed from the user into the custom action on the job, predefined job, or policy page, for use in running the command or the request on the device. While referring to this parameter in other elements or attributes, use keyword syntax, %runtime.ResultPropertyName%. Click Add and enter the following information: Result Property Name: Specify the name of the parameter to be populated with the data the user supplies. By convention (not mandatory), avoid using spaces as spaces reduce the readability of the resulting code. Display Label: Specify the prompt to be displayed to the users, telling the users what needs to be entered. Value Is Required: Select this option if users need to supply a value for this parameter. Sort Order: Specify a number indicating where this parameter should appear among the rest of the parameters, when displaying the data entry controls to the users. Default value is 1. Type: Select one of the following values, indicating the type of data that users can enter on the job, predefined job, or policy page: Text: Users can enter a plain text value. Integer: Users can enter a number. Menu: Users can select value from a menu. Password: User can enter a plain text value, whose data entry control prevents the data from being seen. Default Value: Specify the value to appear into the data entry control when the page is initially presented to the user. Default value is none, meaning data entry controls are initially empty. Maximum Length: For a Text or Password type of parameter, specify a number indicating the maximum number of characters users can supply for the value. Default value is 40. Text values are limited to a maximum of 2000 characters; password values are limited to a maximum of 255 characters. Validation Mask: For a Text type of parameter, specify a regular expression that the user-entered text must match in order to be considered valid. Default value is none, which means that no validation done beyond the length check. Minimum Value: For an Integer type of parameter, specify a number indicating the minimum value that users can enter. Default is no minimum defined. Supports numbers in the range of a 32-bit integer. Maximum Value: For an Integer type of parameter, specify a number indicating the maximum value that users can enter. Default is no maximum defined. Supports numbers in the range of a 32-bit integer. Source of Menu Options: Specify the source of the values to be displayed for selection in a drop-down list using one of following options: Static Options Entered Here: Reads menu values you provide in the Static Menu Options field. Options Listed in a File: Reads menu values from a text file that you provide in the File Name field. Each line in the file is treated as a menu option. The file must be located in the BCAN_DATA\endorsed directory. If the file cannot be read, the menu will be empty. Options Listed in a Database: Reads menu values from the results of an SQL query in the database. Specify the path to the database server in the Database URL field, and the SQL query to be executed in the Database Query field. The first column from each returned row in the query result becomes a menu option, arranged in the order the query generated its rows (so use an ORDER BY clause if necessary). If the URL or the query are invalid or the database server is unreachable, the menu is empty. Error Message: Specify the error message that should be displayed to users when the supplied value is not valid. Default is a canned error message that varies by the type of error detected.

2. On the Implementation(s) tab, click Add Device Type to add information about the device type for which the custom action will be applicable. 
   You can implement your custom action for as many device types as you like.

3. Select the vendor and device type.

   Warning

   You cannot add the same device type again. If you do so, the existing entry for that device type is overwritten, which leads to data loss.

4. (Optional) Click Supplementary Elements, and enter the following information:
   • General Information: Specify general notes, warnings, quirks, or anything else special about this custom action that might affect how users use it.
   • Minimum OS Version: Specify the OS version that you want to compare against the device's current OS version. If the current OS version is later than the version you have specified, the custom action is executed. Otherwise, an exception is thrown.
   • Capture All Output to Property: Specify the property into which the entire transcript of the command's execution will be substituted.
   • Retry on Any Command Timeout: Select whether the custom action should be attempted a second time if the first time results in some command time out.
     Use this option if timeouts are random and flaky.
   • Supports Tunneled Transfer Mode: Select whether the custom action performs a tunneled snapshot or a tunneled deploy function.
     This option is used to inform users about supported tunneled operations in the Device Adapter Capabilities report.
   • Syntax Error Patterns: Specify a regular expression that indicates a syntax error in a device's response. The response is checked against these expressions when the Syntax Error Check element appears in an Interaction element, and at the end of a Deploy To Active span action.
5. Under Main Logic Elements, in Interface Protocol, select Command Line (CLI) to add a CLI based device type or HTTP/HTTPS or REST API to add an HTTP, HTTPS, or a REST based device type.

   1. Click an element and then add its attributes as desired, as described in the following table.

      Element	Description
      Assert	Use this element to test a condition. When the condition evaluates to anything except false, the assertion passes and processing proceeds to the next element. If the condition evaluates to false, the assertion fails; processing stops and the status is reported to the executing span action (and ultimately to the user in the job's results). This element contains the following attributes: Assertion Failure Message (Optional): Specify the message that should be displayed to the users on the job, predefined job or policy page if the assert condition is not satisfied. Attributes (Optional): Select the On Failure attribute and select one of the following value to indicate the severity of the failed assertion: Show Action as Skipped: The calling span action should treat the device as skipped. Show Action as Succeeded With Warning: The calling span action should succeed with a warning. Show Action as Failed: The calling span action should fail with an error. If you do not define the value of this attribute, the span action fails with an error. Condition: Enter the expression to be evaluated. See Conditional expressions for the supported syntax.
      Assign	Use this element to populate a property with a value. That property can then be used in other command elements. The value assigned is either specified explicitly, or specified as a BeanShell script. This element contains the following attributes: Bean Shell Script to Calculate the Value (Optional): Specify the value as a BeanShell script that you want to assign to the property. You must set a String variable called value to hold the result of your assignment calculations. The contents of value finally become the property value. Attributes (Optional): Select the attributes you want to include and define their values: Append to Any Existing Value: Indicate whether the value is to be appended to any existing value in the property. If you do not define the value of this attribute, any existing property value is replaced with the new value. Copy Value From Property: Specify the name of the property whose value is to be assigned to the property if it is not calculated by the BeanShell script or by the Value attribute. Omit Line Breaks When Appending: Indicate whether a newline separator should be appended to an existing value before appending the new value. If you do not define the value of this attribute, values are strung together without any separators. URL-Encode the Value: Indicate whether the value should be encoded to make it suitable for later use as a URL parameter. If you do not define the value of this attribute, value is not encoded and cannot be used as a URL parameter later. Value: Specify the value to be assigned to the property if it is not calculated by a BeanShell script. Property To Be Populated: Specify the name of the property to be populated.
      Comment	Use this element to provide comments before an element.
      Condition	Use this element to specify a block of elements that should be executed only if the Value/Expression to Test evaluates to true. A condition tests whether some processing state is present. When its test expression evaluates to true, execution proceeds into the contained elements. When the test expression does not evaluate to true, then the contained elements are skipped. Enter the value for the following attribute of the Condition element: Value/Expression To Test: The value or expression to be evaluated. See Conditional expressions for the supported syntax. Add other inner elements, as desired, to the Condition element.
      Interaction	Use this element to define a command to send to the device and processing of the device's output from running the command. See Interactions for more details. This element contains the following attributes and child elements: Disconnect (Optional): Specify one of the following values to indicate if the execution of this interaction might cause the system to be disconnected from the device (such as during a reboot). If the system knows that a disconnect is normal, it reconnects, instead of treating the disconnect as an error. See Disconnect for more details.  Never: The device is not expected to disconnect the system during execution of the command. The system considers it an error if the device disconnects.  Sometimes: The device might disconnect while executing the command. If it disconnects, the system will reconnect. If it does not disconnect, the system proceeds to the next element. Always: The device always disconnects when it runs the command. The custom action ends without an error and any further elements are ignored. The system reconnects if the custom action is flagged not inspection-only, to perform the trailing snapshot. If you do not define the value of this attribute, the device is not expected to disconnect the system during execution of the command (Never). The system considers it an error if the device disconnects.  Kick At Response Timeout (Optional): Specify the string to send to the device when the device seems to be stuck waiting for input and has not emitted any response. You may specify non-printable characters using \xnnn notation, where nnn is the numeric hex value for the character (for instance, \x003 is the control-C character). Optional (Optional): Indicate whether this interaction is optional. When this attribute is selected, the system looks to match the data read from the device against the prompts in this interaction or any subsequent interactions up to and including the next non-optional interaction. If you do not define the value of this attribute, this interaction is not considered as optional. Post-Disconnect Reconnect Timeout (seconds) (Optional): Specify the time, in seconds, for which the system waits before reconnecting to the device after a disconnect (such as to allow the device to reboot). This attributes overrides the Timeout for Re-Establishing Connection After a Reboot system parameter. If you do not define the value of this attribute, the system waits for 480 seconds. Response Read Jitter (milliseconds) (Optional): Specify the time, in milliseconds, that controls how the system should read the device's response, specifying how long a delay there may be between characters. A longer jitter might be necessary if the device tends to take pauses while emitting output (that is, its output is in bursts with little pauses in between). A device may be jittery if it is busy doing other things than servicing this command, where it is context switching in and out of producing the command's output. See Jitter time for more details. If you do not define the value of this attribute, there is a delay of 10 milliseconds between characters. Response Timeout (seconds) (Optional): Specify the time, in seconds, indicating how long to wait for the device to begin emitting a response. If you do not define the value of this attribute, the system waits for 60 seconds. Treat Prompt, Response, and Error Elements as Regular Expressions (Optional): Indicate whether to treat the Prompt, Response, or Error elements or the Prefix or Start Delimiter or Suffix or End Delimiter attributes of the Capture All Output to Property element as regular expressions. If you do not define the value of this attribute, these elements are not treated as regular expressions. See Regular expression support for more details.  Prompt (Optional): Specify the prompt that must be received from the device before sending the command. It can be a regular expression if the Treat Prompt, Response, and Error Elements as Regular Expressions attribute is included and selected. This element contains the following attribute: Jitter (milliseconds) (Optional): Specify the time, in milliseconds, that controls how the system reads the prompt from the device and indicates how long a delay there can be between characters. If you do not define the value of this attribute, a jitter of 10 milliseconds is considered. Command: Specify the command to be executed by the device. This element contains the following attributes: Contains Sensitive Data (Optional): Indicate whether the command contains sensitive data (such as a password). Such data is sent to the device in clear text, which normally would show up in the transcript in clear text. When you select this attribute, the command is masked in the transcript. If you do not define the value of this attribute, sensitive data in the command is ignored and data is sent in clear text. See Sensitive commands for more details. Do Not Add Line Break to the Command (Optional): Indicate whether an end-of-line sequence should be added to the command. If you do not define the value of this option, no end-of-line sequence is added. Inter-Character Stutter (milliseconds) (Optional): Specify the time, in milliseconds, defining the pause between characters. Pausing a little bit after sending each character can mimic how a human types. Some devices cannot read its command line at machine speed, but only at human speed. Some devices try to auto-complete as you type, which can slow down its input processing. A longer stutter slows down the input of the command into the device so that the device is able to read it without losing any characters. If you do not define the value of this option, characters are sent with a pause of 50 milliseconds. See Stutter time for more details. Sensitive Phrase (Optional): Specify the string in the command that is to be masked. This attribute is used only if you have included and selected the Contains Sensitive Data attribute. If the string is present, only part of the command is masked; else, the entire command is masked. Pause (seconds) (Optional): Specify the number of seconds to pause (and do nothing) after sending the command and before reading the response. Normally, no such pause is done, but if the device spends a long time silently running the command, the system might consider the device to be unresponsive and error out. Adding a pause can resolve such errors. Response (Optional): Specify the expected response in Content. It can be a regular expression if the Treat Prompt, Response, and Error Elements as Regular Expressions attribute is included and selected. If there are multiple Response elements, they are checked in order and the checking stops as soon as a match is made. So it may be necessary to code the most specific responses first, and the most general responses last (if it is important to distinguish between responses by setting a property). That is, be careful not to match the wrong response. See Response properties for more details. This element contains the following element and attribute: Property to Be Populated: Specify the name of the property to populate with the value of the response. Value to Assign to the Property (Optional): Specify the value to be assigned to the property. That is, the value of the Response element is the response you expect from the device, which may be a just a trailing piece of what the device emits, or might be just a success message that comes out at the end. It is this value that is assigned to the property, not the entire output from the device. Response Block Reference (Optional): Specify the name of a previously-defined <responseBlockDeclaration> element in the device type adapter, to use the referenced responses here. See Reusable responses and errors for more details. Error (Optional): Specify the expected response that indicates an error has occurred in Content. Error elements take precedence over the Response elements. It can be a regular expression if the Treat Prompt, Response, and Error Elements as Regular Expressions attribute is included and selected. If there are multiple Error elements, they are checked in order and the checking stops as soon as a match is made. So it may be necessary to code the most specific errors first, and the most general errors last (if it is important to distinguish between errors by setting a property). Note that when an error is matched, execution of the custom action terminates; it does not move on to the next interaction; the error is reported to the user as a failed job. Any elements included in the Finally Block section are executed, as well as the logout. These sections can utilize any property this error has set. See Error properties for more details. This element contains the following attributes: Property to Be Populated (Optional): Specify the name of the property to populate with the value of the error. Retry Interaction When Receive This Error (Optional): Indicate whether the entire custom action should be re-tried once if this error occurs. If you do not define the value of this attribute, custom action terminates and it does not move on to the next interaction. The error is reported to the user as a failed job. See Retry for more details.   Error Block Reference (Optional): Specify the name of a previously-defined <errorBlockDeclaration> element in the device type adapter, to use the referenced errors here. See Reusable responses and errors for more details.  Capture All Output to Property (Optional): Specify the name of the property and the value to be assigned to the property. See the Property capture–XML reference example and other reference examples that follow this example, for more details. This element contains the following attributes and elements: Append to Any Existing Value (Optional): Indicate whether the new value should be appended to any existing property value. If you do not define the value of this attribute, any existing value is removed. Capture Multiple Values (Optional): Indicates whether the buffer is to be matched multiple times, producing multiple properties whose names are augmented with a counter value starting at zero. If you do not define the value of this attribute, buffer is matched only once and a single property is produced. Capture Only When Preceding Capture Failed (Optional): Indicate whether a capture should only be attempted if the preceding capture failed. This is useful for instance if a given interaction has two capture tags, but you only want the second one to be used if the first one fails. If you do not define the value of this attribute, all captures are attempted. Default Value (Optional): Specify the default value to assign to the property. This attribute is used only if the Do Not Fail the Action When Capture Fails attribute is included and selected, to assign a value to the property when the input is not matched to the other capture criteria. Do Not Fail the Action When Capture Fails (Optional): Indicate whether it is considered an error if the capture criteria is not matched. When this option is selected, if nothing is captured, then the logic continues. If you do not define the value of this attribute, the IOException exception causes the action to fail. Do Not Treat Missing Prefix as a Failure (Optional): Indicate whether the absence of the prefix is to be treated as an error. When you select this attribute, and the prefix is not matched in the command's output, the capture becomes unbounded at the beginning (no start delimiter). If you do not define the value of this attribute, absence of the prefix is not treated as an error. Do Not Treat Missing Suffix as a Failure (Optional): Indicate whether the absence of the Suffix is to be treated as an error. When you select this attribute and the suffix is not matched in the command's output, then the capture becomes unbounded at the end (no ending delimiter). If you do not define the value of this attribute, absence of the suffix is not treated as an error. Ignore Prefix (Optional): Indicate whether the prefix is to be ignored, making the capture unbounded at the beginning (no start delimiter). If you do not define this attribute, prefix is not ignored. Ignore Suffix (Optional): Indicate whether the suffix is to be ignored, making the capture unbounded at the end (no ending delimiter). If you do not define this attribute, suffix is not ignored. Include Prefix In Captured Value (Optional): Indicate whether the prefix is to be included in the text to be examined. If you do not define this attribute, prefix is not included in the text. Include Suffix in Captured Value (Optional): Indicate whether the suffix is to be included in the text to be examined. If you do not define this attribute, suffix is not included in the text. Match Last Occurrence of Prefix (Optional): Indicate whether the last match of the prefix in the received text is the starting delimiter, as opposed to the first match. If you do not define this attribute, the first match of the prefix in the received text is the starting delimiter. Match Last Occurrence of Suffix (Optional): Indicate whether the last match of the suffix in the received text is the ending delimiter, as opposed to the first match. If you do not define this attribute, the first match of the suffix in the received text is the ending delimiter. Multi-Pass Iteration Arrays (Optional): Used in multi-pass style capture. Holds a comma-delimited list of property-array names to use as inputs to assign values to Iterate Variables, in order to make multiple passes over the text received from the device to capture property values. If populated, it must contain the same number of names as Iterate Variables. Multi-Pass Iteration Variables (Optional): Used in multi-pass style capture. Can hold a comma-delimited list of variable names which appear as "%capture.variableName%" keywords within the capture buffer. Used in conjunction with the Iterate Arrays attribute to support multiple pass capture logic. If populated, it must contain the same number of names as Iterate Arrays. Multiple Value Naming Index (Optional): Specify the information about how to construct an associative index name for a property array in a multi-value capture. Omit Line Breaks When Appending (Optional): Indicate if the Append to Any Existing Value attribute is included and selected, an end-of-line sequence is to separate the values appended to the property. If you do not define the value of this attribute, there is no separator (not even a space), unless you include it yourself as part of the value. Path to the Value in XML-Based Command Output (Optional): Specify the xpath to use to narrow down the input from which to capture. If specified, then the normal input which is captured from (after being trimmed using prefix and suffix specifications) is interpreted as an XML document, then it will have this xpath expression applied to it to select a desired piece (or pieces) from it, then the desired piece will be translated back into an XML string. The resulting XML string is then what we will try to capture values from.  Prefix or Start Delimiter (Optional): Specify the delimiter (string or regular expression) that starts the text to be examined for storage into property values. If the Treat Prompt, Response, and Error Elements as Regular Expressions attribute is not included, delimiter can be a string to search for an exact match. If the Treat Prompt, Response, and Error Elements as Regular Expressions attribute is included and selected, delimiter can be a regular expression to search for an inexact match. Default is to examine the command output from the echoed command string (but not including that string). Regular Expression to Match Command Output (Optional): Specify a regular expression to match only a part of the command's output. Include parentheses around parts to define a capture group, which you can then refer to by number on the value. Default value is blank, meaning to capture from all of the command's output between prefix and suffix. Suffix or End Delimiter (Optional): Specify the delimiter (string or regular expression) that ends the text to be examined for storage into property values. If the Treat Prompt, Response, and Error Elements as Regular Expressions attribute is not included, delimiter can be a string to search for an exact match. If the Treat Prompt, Response, and Error Elements as Regular Expressions attribute is included and selected, delimiter can be a regular expression to search for an inexact match. Default is to examine the command output up to but not including the matched Response. Property: Specify the value to be assigned to the property. Syntax Error Check (Optional): Indicates that the command's output should be checked for syntax errors. The errors are defined in the Syntax Error Patterns field under Overall Elements. When a syntax error is found, the property specified in this element is created and set to true. The property can now be used for conditional logic (such as breaking out of a loop).
      HTTP Interaction	Use this element to define a command to send to the device and processing of the device's output from running the command. See this interaction for more details. This element contains the following attributes and child elements: Comment Inserted into Transcript (Optional): Specify a comment to insert into the transcript (which the user can see) describing the interaction, to facilitate troubleshooting. Disconnect (Optional): Specify one of the following values to indicate if the execution of this interaction might cause the system to be disconnected from the device (such as during a reboot). If the system knows that a disconnect is normal, it reconnects, instead of treating the disconnect as an error. See Disconnect for more details.  Never: The device is not expected to disconnect the system during execution of the command. The system considers it an error if the device disconnects.  Sometimes: The device might disconnect while executing the command. If it disconnects, the system will reconnect. If it does not disconnect, the system proceeds to the next element. Always: The device always disconnects when it runs the command. The custom action ends without an error and any further elements are ignored. The system reconnects if the custom action is flagged not inspection-only, to perform the trailing snapshot. If you do not define the value of this attribute, the device is not expected to disconnect the system during execution of the command (Never). The system considers it an error if the device disconnects.  Do Not Fail the Action on HTTP Exceptions (Optional): Indicate whether to ignore HttpExceptions while executing this interaction. If you do not define the value of this attribute, such exceptions are not ignored and the custom action terminates. HttpException indicates that a request sent to the device yielded either no response or an error response. Do Not Throw HTTP Exception When Receive Bad Status Code (Optional): Indicate whether the system should skip throwing an HttpException if a bad status code is found in the response. Clearing this attribute can be helpful if you want to use an error tag (with a property setting) to perform more fine-grained error handling, instead of just having an exception thrown which aborts the entire custom action that this interaction is a part of.Note: Clearing this attribute is different than selecting the Do Not Fail the Action on HTTP Exceptions attribute. Selecting the Do Not Fail the Action on HTTP Exceptions attribute prevents the entire custom action that this interaction is a part of, from aborting when an exception is thrown. In addition, Do Not Throw HTTP Exception When Receive Bad Status Code also skips the normal trailing processing of the response received (including skipping the matching of error tags). Include Response Header in Response and Error Matching (Optional): Indicate whether the received HTTP headers should be included in the interaction's response. When this attribute is selected, each header appears on a separate line as name:value pairs for use in captures. If you do not define the value of this attribute, HTTP headers are not included in the interaction's response. Post-Disconnect Reconnect Timeout (seconds) (Optional): Specify the time, in seconds, for which the system should wait before reconnecting to the device after a disconnect (such as to allow the device to reboot). This attributes overrides the Timeout for Re-Establishing Connection After a Reboot system parameter. If you do not define the value of this attribute, the system waits for 480 seconds. Response Timeout (seconds) (Optional): Specify the time, in seconds, indicating how long to wait for the device to begin emitting a response. If you do not define the value of this attribute, the system waits for 60 seconds. Treat Response and Error Elements as Regular Expressions (Optional): Indicate whether to treat the Response or Error elements or the Prefix or Start Delimiter or Suffix or End Delimiter attributes of the Capture All Output to Property element as regular expressions. If you do not define the value of this attribute, these elements are not treated as regular expressions. See Regular expression support for more details.  Request Type: Select from the following request types to include in the interaction: Get (Optional): Specify the URL or path to receive the GET request. See Start a web search and capture the result into a property for the example. This element contains the following attributes: Contains Sensitive Data (Optional): Indicate whether the command contains sensitive data (such as a password). Such data is sent to the device in clear text, which normally would show up in the transcript in clear text. When you select this attribute, the command is masked in the transcript. If you do not define the value of this attribute, sensitive data in the command is ignored and data is sent in clear text. See Sensitive commands for more details.  Properties to Send as Query Parameters (Optional): Specify the prefix, which includes the subset of properties to use to populate query parameters to send with the GET request when it is executed. That is, any property whose name starts with this prefix, plus a dot, will be added to the request as a query parameter. The name of the query parameter will be the property name stripped of the prefix and the dot. Sensitive Phrase (Optional): Specify the string in the command that is to be masked. This option is used only if the Contains Sensitive Data attribute is included and selected. If the string is present, only part of the command is masked; else, the entire command is masked. Post (Optional): Specify the URL or path that is to receive the POST request. See Send request body with the POST request for the example. This element contains the following attributes: Contains Sensitive Data (Optional): Indicate whether the command contains sensitive data (such as a password). Such data is sent to the device in clear text, which normally would show up in the transcript in clear text. When you select this option, the command is masked in the transcript. If you do not define the value of this attribute, sensitive data in the command is ignored and data is sent in clear text. See Sensitive commands for more details.  Form to Include in the Body (Optional): Specify the name of the form being filled in the request body. Sensitive Phrase (Optional): Specify the string in the command that is to be masked. This option is used only if the Contains Sensitive Data attribute is included and selected. If the string is present, only part of the command is masked; else, the entire command is masked. Redirection Prefix (Optional): Specify the path to prepend to any redirection URLs received in response to this post request. This provides a hint as to how to compose the URL involved, to work around glitches in underlying third-party software. Put (Optional): Specify the URL or path that is to receive the PUT request. See Send request body with the PUT request for the example. This element contains the following attributes: Contains Sensitive Data (Optional): Indicate whether the command contains sensitive data (such as a password). Such data is sent to the device in clear text, which normally would show up in the transcript in clear text. When you select this option, the command is masked in the transcript.  If you do not define the value of this attribute, sensitive data in the command is ignored and data is sent in clear text. See Sensitive commands for more details.   Form to Include in the Body (Optional): Specify the name of the form being filled in in the request body. Sensitive Phrase (Optional): Specify the string in the command that is to be masked. This option is used only if the Contains Sensitive Data attribute is included and selected. If the string is present, only part of the command is masked; else, the entire command is masked. Delete (Optional): Specify the URL or path that is to receive the DELETE request. See Send a delete request for the example. Response (Optional): Specify the expected response in Content. It can be a regular expression if the Treat Response and Error Elements as Regular Expressions attribute is included and selected. If there are multiple Response elements, they are checked in order and the checking stops as soon as a match is made. So it may be necessary to code the most specific responses first, and the most general responses last (if it is important to distinguish between responses by setting a property). That is, be careful not to match the wrong response. See Response properties for more details. This element can contain the following attributes: Value to Assign to the Property (Optional): Specify the name of the property to populate with the value of the response. That is, the value of the Response element is the response you expect from the device, which may be a just a trailing piece of what the device emits, or might be just a success message that comes out at the end. It is this value that is assigned to the property, not the entire output from the device. Property to Be Populated: Specify the name of the property to populate with the value of the response. Response Block Reference (Optional): Specify the name of a previously-defined <responseBlockDeclaration> element in the device type adapter, to use the referenced responses here. See Reusable responses and errors for more details. Error (Optional): Specify the expected response that indicates an error has occurred in Content. Error elements take precedence over the Response elements. It can be a regular expression if the Treat Response and Error Elements as Regular Expressions attribute is included and selected. If there are multiple Error elements, they are checked in order and the checking stops as soon as a match is made. So it may be necessary to code the most specific errors first, and the most general errors last (if it is important to distinguish between errors by setting a property). Note that when an error is matched, execution of the custom action terminates; it does not move on to the next interaction; the error is reported to the user as a failed job. Any elements included in the Finally Block section are executed, as well as the logout. These sections can utilize any property this error has set. See Error properties for more details. This element contains the following attributes: Property to Be Populated (Optional): Specify the name of the property to populate with the value of the error. Retry Interaction When Receive This Error (Optional): Indicate whether the entire custom action should be re-tried once if this error occurs. If you do not define the value of this attribute, custom action terminates and it does not move on to the next interaction. The error is reported to the user as a failed job. See Retry for more details.  Error Block Reference (Optional): Specify the name of a previously-defined <errorBlockDeclaration> element in the device type adapter, to use the referenced errors here. See Reusable responses and errors for more details. Capture All Output to Property (Optional): Specify the name of the property and the value to be assigned to the property. See the Property capture–XML reference example and other reference examples that follow this example, for more details. This element contains the following attributes and elements: Append to Any Existing Value (Optional): Indicate whether the new value should be appended to any existing property value. If you do not define the value of this attribute, any existing value is removed. Capture Multiple Values (Optional): Indicates whether the buffer is to be matched multiple times, producing multiple properties whose names are augmented with a counter value starting at zero. If you do not define the value of this attribute, buffer is matched only once and a single property is produced. Default Value (Optional): Specify the default value to assign to the property. This attribute is used only if the Do Not Fail the Action When Capture Fails attribute is included and selected, to assign a value to the property when the input is not matched to the other capture criteria. Capture Only When Preceding Capture Failed (Optional): Indicate whether a capture should only be attempted if the preceding capture failed. This is useful for instance if a given interaction has two capture tags, but you only want the second one to be used if the first one fails. If you do not define the value of this attribute, all captures are attempted. Do Not Fail the Action When Capture Fails (Optional): Indicate whether it is considered an error if the capture criteria is not matched. When this option is selected, if nothing is captured, then the logic continues. If you do not define the value of this attribute, the IOException exception causes the action to fail. Do Not Treat Missing Prefix as a Failure (Optional): Indicate whether the absence of the prefix is to be treated as an error. When you select this attribute, and the prefix is not matched in the command's output, the capture becomes unbounded at the beginning (no start delimiter). If you do not define the value of this attribute, absence of the prefix is not treated as an error. Do Not Treat Missing Suffix as a Failure (Optional): Indicate whether the absence of the Suffix is to be treated as an error. When you select this attribute and the suffix is not matched in the command's output, then the capture becomes unbounded at the end (no ending delimiter). If you do not define the value of this attribute, absence of the suffix is not treated as an error. Ignore Prefix (Optional): Indicate whether the prefix is to be ignored, making the capture unbounded at the beginning (no start delimiter). If you do not define this attribute, prefix is not ignored. Ignore Suffix (Optional): Indicate whether the suffix is to be ignored, making the capture unbounded at the end (no ending delimiter). If you do not define this attribute, suffix is not ignored. Include Prefix In Captured Value (Optional): Indicate whether the prefix is to be included in the text to be examined. If you do not define this attribute, prefix is not included in the text. Include Suffix in Captured Value (Optional): Indicate whether the suffix is to be included in the text to be examined. If you do not define this attribute, suffix is not included in the text. Match Last Occurrence of Prefix (Optional): Indicate whether the last match of the prefix in the received text is the starting delimiter, as opposed to the first match. If you do not define this attribute, the first match of the prefix in the received text is the starting delimiter. Match Last Occurrence of Suffix (Optional): Indicate whether the last match of the suffix in the received text is the ending delimiter, as opposed to the first match. If you do not define this attribute, the first match of the suffix in the received text is the ending delimiter. Multi-Pass Iteration Arrays (Optional): Used in multi-pass style capture. Holds a comma-delimited list of property-array names to use as inputs to assign values to Iterate Variables, in order to make multiple passes over the text received from the device to capture property values. If populated, it must contain the same number of names as Iterate Variables. Multi-Pass Iteration Variables (Optional): Used in multi-pass style capture. Can hold a comma-delimited list of variable names which appear as "%capture.variableName%" keywords within the capture buffer. Used in conjunction with the Iterate Arrays attribute to support multiple pass capture logic. If populated, it must contain the same number of names as Iterate Arrays. Multiple Value Naming Index (Optional): Specify the information about how to construct an associative index name for a property array in a multi-value capture. Omit Line Breaks When Appending (Optional): Indicate if the Append to Any Existing Value attribute is included and selected, an end-of-line sequence is to separate the values appended to the property. If you do not define the value of this attribute, there is no separator (not even a space), unless you include it yourself as part of the value. Path To the Value In XML-Based Command Output (Optional): Specify the xpath to use to narrow down the input from which to capture. If specified, then the normal input which is captured from (after being trimmed using prefix and suffix specifications) is interpreted as an XML document, then it will have this xpath expression applied to it to select a desired piece (or pieces) from it, then the desired piece will be translated back into an XML string. The resulting XML string is then what we will try to capture values from.  Prefix Or Start Delimiter (Optional): Specify the delimiter (string o regular expression) that starts the text to be examined for storage into property values. If the Treat Response and Error Elements as Regular Expressions attribute of the containing HTTP Interaction element is not included, delimiter can be a string to search for an exact match. If the Treat Response and Error Elements as Regular Expressions attribute is included and selected, delimiter can be a regular expression to search for an inexact match. Default is to examine the command output from the echoed command string (but not including that string). Regular Expression to Match Command Output (Optional): Specify a regular expression to match only a part of the command's output. Include parentheses around parts to define a capture group, which you can then refer to by number on the value. Default value is blank, meaning to capture from all of the command's output between prefix and suffix. Suffix or End Delimiter (Optional): Specify the delimiter (string o regular expression) that ends the text to be examined for storage into property values. If the Treat Response and Error Elements as Regular Expressions attribute of the containing HTTP Interaction element is not included, delimiter can be a string to search for an exact match. If the Treat Response and Error Elements as Regular Expressions attribute is included and selected, delimiter can be a regular expression to search for an inexact match. Default is to examine the command output up to but not including the matched Response. Property: Specify the value to be assigned to the property. Form (Optional): Specify the name of the form in the body of the reply that needs to be filled in as the body of the next request. Request Header (Optional): Specify a field to be included in the request's header, formatted as fieldName.fieldValue. See Send HTTP request headers with the request for more details. This element contains the following attribute: Encode Value In Base64 (Optional): Indicate whether the name can contain binary or if the recipient expects an encoded value, to encode the data in base64. If you do not define the value of this attribute, data is not encoded. Request Body (Optional): Specify the body to be included in the request. This element contains the following attribute: Encode Value In Base64 (Optional): Indicate whether the name can contain binary or if the recipient expects an encoded value, to encode the data in base64. If you do not define the value of this attribute, field name is not encoded.
      Loop	Use this element to start a processing loop. This element contains the interactions and other elements to be executed repeatedly until the loop termination condition is reached. See Loops - Types for more details. This element contains the following attributes: Input Properties (Optional): Specify an input string which will be "iterated" over to assign individual values to the variable property, used in the for-each type of loop. Loop Counter Property (Optional): Specify the name of the property that is used as a loop counter, getting incremented by one each pass through the loop. Namespace (Optional): Specify the namespace to be used for this loop. The namespace is used as a prefix for the name of the counter and variable properties. It is also used to remove any property which matches the value "namespace.*" after the loop is complete. Allowing different loops to use different namespaces enables you to nest loops. If you do not define the value of this attribute, "loop" is considered as the default namespace. Property Names Form an Associative Array (Optional): Indicates whether the property array being iterated over in a for-each type loop is an associative array or not. An associative array would be a collection of properties of the form "%MyProp[A]%", "%MyProp[B]%", ... while a non-associative array would be a collection of properties of the form "%MyProp.0%", "%MyProp.1%", ... Separate Input Into Lines By (Optional): Specify the separator to specify how to divide the input if it is not already divided into lines, such that the pieces can be iterated over. Start Loop Counter At (Optional): Specify the initial value for Loop Counter Property. Stop When Loop Counter Reaches (Optional): Specify the final value for Loop Counter Property. Store Current Loop Variable into Property (Optional): Specify the name of the property that contains the current loop variable, getting updated to the next input value each pass through the loop. Value/Expression to Test for Loop Termination (Optional): Enter an expression that, when evaluates to false, terminates the loop. See Conditional expressions for the supported syntax. Add other elements, as required, to the Loop element.
      Sleep	Use this element to pause the system for the specified number of seconds before continuing on to the next element. See Sleep for more details. This element contains the following attribute: Time (seconds): Specify the time, in seconds, for which you want to pause the system.
      Unassign	Use this element to remove the specified property from the current set of connection properties if the property exists. This element contains the following attribute: Property: Specify the name of the property to be removed.

6. Click Finally Block and select the Include Finally Block option if you want to include elements that are to be executed at the end of the custom action, even if an error has occurred in the preceding elements.
7. Include the desired elements that you want to be executed at the end of the custom action.
8. Click Enter to finish adding implementation of the device type.
9. (Optional) On the Implementation(s) tab, click Add Device Type to add information about another device type for which the custom action should be applicable. 
10. (Optional) Once you are done adding elements, click the Preview button on top of the page to preview the device adapter XML. 
    For more information about the preview option, see Preview of the custom action adapter XML.
11. Click Save on the top of the page.

Editing a custom action adapter

On the Admin > Network Admin > Device Adapters page, do the following: 

1. Navigate to the custom action device adapter that you want to modify.
2. From the Actions menu, click Edit.

3. Add, edit, or delete elements and attributes as required. 

   Note

   You cannot change the device type.

4. Click Save.

Related topics

Adding dynamic fieldsViewing-a-Device-Adapter-Capabilities-report