Write XML rules
The Deploy rules system enables you to use XML or Jython to specify the steps that belong in a deployment plan and how the steps are configured. For more information, see Get started with rules and Writing script rules.
An XML rule is fully specified using XML and has the following format in
scopeattributes, both of which are required.
- One or more
typetags that identify the UDM types or subtypes to which the rule is restricted. This allows you to write rules that apply to a UDM type and all of its subtypes, as well as rules that only apply to a specific subtype.
typeis required if the scope is
deployed, otherwise, you must omit it. The UDM type name must refer to a deployed type and not a deployable, container, or other UDM type.
- One or more
operationtags that identify the operations that the rule is restricted to. The operation can be
operationis required if the scope is
deployed, otherwise, you must omit it.
- An optional
expressiontag with an expression in Jython that defines a condition upon which the rule will be triggered. This tag is optional for all scopes. If you specify an
expression, it must evaluate to a Boolean value.
- One or more
stepstag that contains a list of steps that will be added to the plan when this rule meets all conditions. For example, when its types and operations match and its
expressionevaluates to true. Each step to be added is represented by an XML tag specifying the step type and step parameters such as
Define steps in XML rules
Steps in XML rules are defined in the
steps tag. There is no XML schema verification of the way that rules are defined, but there are guidelines that you must follow.
stepstag contains tags that must map to step names.
- Each step contains parameter tags that must map to the parameters of the defined step.
Each parameter tag can contain:
- A string value that will be automatically converted to the type of the step parameter. If the conversion fails, the step will not be created and the deployment planning will fail.
- A Jython expression that must evaluate to a value of the type of the step parameter. For example, the expression
60will evaluate to an
"60"will evaluate to a
Stringvalue. If you use an expression, the surrounding parameter tag must contain the attribute
- In the case of map-valued parameters, you can specify the map with sub-tags. Each sub-tag will result in a map entry with the tag name as key and the tag body as value. Also, you can specify
expression="true"to place non-string values into a map.
- In the case of list-valued parameters, you can specify the list with
valuetags. Each tag results in a list entry with the value defined by the tag body. Also, you can specify
expression="true"to place non-string values into a list.
stepstag may contain a
checkpointtag that informs Deploy that the action the step takes must be undone in the case of a rollback.
All Jython expressions are executed in same context with the same available variables as Jython scripts in script rules.
Using dynamic data
You can use dynamic data in steps. For example, to show a file name in a step description, use:
<description expression="true">"Copy file " + deployed.file.name</description>
Note: You must set
true to enable dynamic data.
Escaping special characters
xl-rules.xml is an XML file, some expressions must be escaped. For example, you must use
myParam < 0 instead of
myParam < 0. Alternatively, you can wrap expressions in a
Using special characters in strings
You can set a step property to a string that contains a special character, such as a letter with an umlaut.
If the parameter is an expression, enclose the string with single or double quotation marks (
") and prepend it with the letter
u. For example:
If the parameter is not evaluated as an expression, no additional prefix is required. You can assign the value. For example:
Deploy uses checkpoints to build rollback plans. The rules system allows you to define checkpoints by inserting a
<checkpoint> tag immediately after the tag for the step on which you want the checkpoint to be set. Checkpoints can be used only in the following conditions:
- The scope of the rule must be
- You can set one checkpoint per rule.
If a rule specifies a single
MODIFYoperation, you can:
- Set two checkpoints: One for the creation part and one for the deletion part of the modification, if applicable.
- Use the attribute
checkpointtag to specify the operation that is actually performed for the step.
Sample XML rules
Successfully created artifact
This is an example of a rule that is triggered for every deployed of type
udm.BaseDeployed and operation
CREATE. It results in the addition of a
noop step, a step that does nothing, with order
60 to the plan.
<rules xmlns="http://www.xebialabs.com/deploy/xl-rules"> <rule name="SuccessBaseDeployedArtifact" scope="deployed"> <conditions> <type>udm.BaseDeployedArtifact</type> <type>udm.BaseDeployed</type> <operation>CREATE</operation> </conditions> <steps> <noop> <order>60</order> <description expression="true">'Dummy step for %s' % deployed.name</description> </noop> </steps> </rule> </rules>
Successfully deployed to Production
This is an example of an XML rule that is triggered once for the whole plan, when the deployment’s target environment contains the word
<rules xmlns="http://www.xebialabs.com/deploy/xl-rules"> <rule name="SuccessBaseDeployedArtifact" scope="post-plan"> <conditions> <expression>"Production" in context.deployedApplication.environment.name</expression> </conditions> <steps> <noop> <order>60</order> <description>Success step in Production environment</description> </noop> </steps> </rule> </rules>
expression tag does not need to specify
expression="true". Also, in this example, the description is now a literal string, so
expression="true" is not required.
Using a checkpoint
This is an example of an XML rule that contains a checkpoint. Deploy will use this checkpoint to undo the rule’s action if you roll back the deployment. If the step was executed successfully, Deploy knows that the deployable is successfully deployed. Upon rollback, the planning phase needs to add steps to undo the deployment of the deployable.
<rule name="CreateBaseDeployedArtifact" scope="deployed"> <conditions> <type>udm.BaseDeployedArtifact</type> <operation>CREATE</operation> </conditions> <steps> <copy-artifact> <....> </copy-artifact> <checkpoint/> </steps> </rule>
Using checkpoints when operation is
This is an example of an XML rule in which the operation is
MODIFY. This operation involves two sequential actions, which are removing the old version of a file (
DESTROY) and then creating the new version (
CREATE). This means that two checkpoints are needed.
<rule name="ModifyBaseDeployedArtifact" scope="deployed"> <conditions> <type>udm.BaseDeployedArtifact</type> <operation>MODIFY</operation> </conditions> <steps> <delete> <....> </delete> <checkpoint completed="DESTROY"/> <upload> <....> </upload> <checkpoint completed="CREATE"/> </steps> </rule>