7. Common Attributes/Options and Properties

There are a number of attributes/options that are common to all DPBuddy tasks/commands.

Any common attribute/option has a corresponding property that can be used to specify a default value in the configuration file or in a build file. This keeps you from having to repeat the same attribute for every task. A value from the attribute/option overrides a value from the property. For example, dp.domain=test property can be overridden using the domain="test1" attribute set at a task level.

Every common property has two aliases, one using dots as a word separator (following Ant naming conventions) and the second one using lower camel case. The second alias should be used when running DPBuddy from Groovy or Gradle (or any other scripting language) since Ant naming conventions conflict with the commonly used dot notation for accessing object properties.

7.1. DataPower Connection Attributes/Options

DPBuddy needs to know the URL of the SOAP interface (XML Management interface) and a user name and a password in order to be able to connect to a device.

Following is the list of common connection properties/attributes:

Property name	Attribute/Option	Description	Required
dp.url dpUrl dp.host dpHost	url host	URL of the SOAP interface (XML Management interface). The path defaults to /service/mgmt/current, which always corresponds to the most up-to-date DataPower schema. If the port is not specified, DPBuddy will attempt to use the port 5550. You can specify just the host name of the appliance, in which case DPBuddy will default to “https:” and the default port.	Yes
dp.username dpUsername	user CLI alias: -u	Valid username with administrative privileges.	Yes
dp.password dpPassword	password CLI alias: -p	Password.	Yes
dp.domain dpDomain	domain	Target domain for DPBuddy tasks.	Yes
dp.trust.all.certs dpTrustAllCerts	trustAllCerts	If this property/option is set to true DPBuddy will ignore SSL certificates’ validation errors when connecting to a device. If this property is not set, or set to false, you will need to add the DataPower certificate to your JDK’s keystore. You can obtain the DataPower certificate from the browser when you access Web GUI. Defaults to true.	No

7.2. Environment Attributes/Options

Environment prefix is used to point to different sets of properties belonging to different environments. Please refer to Managing Environment-Specific Properties/Variables for more details.

Property name	Attribute/Option	Description	Required
dp.env dpEnv dp.device dpDevice	env device	Sets the environment prefix which is used to determine what properties to use. Once the prefix is set, DPBuddy will attempt to pre-pend this prefix to every requested property name and check if the prefixed property is defined. If there are no properties that start with the given prefix, DPBuddy will throw an exception.	No

7.3. Attributes/Options for Running Commands against Multiple Devices

Any DPBuddy command can be executed against multiple devices and/or domains. This is done by providing a comma-delimited list of environment prefixes using “env” option/attribute or “dp.env” property. Please refer to Executing DPBuddy’s Commands against Multiple Devices/Domains for more details.

Property name	Attribute/Option	Description	Required
dp.continue.on.error dpContinueOnError	continueOnError	If this property/option is set to true, DPBuddy will attempt to execute the command against all of the devices in the list regardless of errors with other devices. Defaults to false.	No
	rollbackAllOnError	If this option is set to true DPBuddy will rollback all the devices where the command succeeded if one or multiple devices failed. Note that in order for the rollback to work, the affected domains must have a checkpoint defined. DPBuddy always rolls backs to the latest checkpoint. Defaults to false.	No

7.4. Schema Validation Attributes/Options

DPBuddy can optionally validate SOMA XML requests against the DataPower SOMA XML schema. Several DPBuddy tasks, such as action, request and modifyConfig allow the user to specify free-form XML as part of the request. DataPower itself validates all XML requests, but for security reasons, it does not return validation errors to the client. Instead, it returns the “internal error” message, which is not very helpful for troubleshooting. Validation errors can then be found in the device’s logs, but scanning the logs takes time. DPBuddy, on the other hand, validates XML on the client so that validation error messages are displayed right away

The following DPBuddy properties and attributes control schema validation:

Property name	Attribute/Option	Description	Required
dp.validate dpValidate	validate	If set to true validate all XML SOMA requests. Note that enabling this setting globally (using dp.validate property) will result in slower performance for import and some other tasks. Defaults to false except for the tasks modifyConfig and somaRequest.	No
dp.schema dpSchema	schemaFile	Full path to “xml-mgmt-ops.xsd” or the directory containing all DataPower schema files. DataPower schema files can be downloaded from the “store” filesystem of the device. The schema files include “xml-mgmt-ops.xsd”, “xml-mgmt.xsd”, “xml-mgmt-base.xsd” and, starting with firmware version 6, “xml-mgmt-b2b.xsd”. DPBuddy comes bundled with the schema files for 6.0.1 firmware. When schema validation is enabled, DPBuddy will default to this schema. You may want to download the schemas from your device and specify the dp.schema property if you have a different firmware version.	No

7.4.1. Examples

dp.validate=true
dp.schema=./schemas

7.5. Save Attribute/Option

DPBuddy is capable of automatically saving domain configuration after a change. This is equivalent to clicking “Save Config” in WebGUI.

Most of DPBuddy’s configuration changing tasks support the save attribute/option. If this attribute is set to true, the configuration will be saved after successful completion of the task.

You can also enforce auto-saving globally by setting the dp.auto.save property. If this property is set, all the configuration-changing tasks will save domain configuration upon completion.

The save attribute/option takes the precedence over dp.auto.save property.

The save attribute and dp.auto.save property are supported by the following tasks: import, modifyConfig, delConfig, resetDomain, assertStatus, assertState, action, somaRequest, checkpoint and rollback.

You must explicitly invoke the save save task task to persist domain configuration if dp.auto.save or save attribute are not set or are set to false.

Property name	Attribute/Option	Description	Required
dp.auto.save dpAutoSave	save	If set to true, saves the domain configuration. Defaults to false.	No

7.6. License File Attribute/Option

Please see the DPBuddy License section for more information about the license file. This setting can be ignored if you’re using a trial version of DPBuddy.

Property name	Attribute/Option	Description	Required
dpbuddy.license.file dpbuddyLicenseFile DPBUDDY_LICENSE_FILE environment variable	license	Location of the license file.	No