Get Started With Rules
When preparing a deployment, Deploy must determine which steps to take for the deployment, and in what order. This happens in three phases:
- Delta analysis: Determines which deployables are to be deployed, resulting in a delta specification for the deployment.
- Orchestration: Determines the order in which deployments of the deployables should happen. This order can be serial, in parallel, or interleaved.
- Planning: Determines the specific steps that must be taken for the deployment of each deployable in the interleaved plan.
The Deploy rules system works with the planning phase and enables you to use XML or Jython to specify the steps that belong in a deployment plan and how the steps are configured.
Rules and orchestration
Orchestration is important in the planning of a deployment, as it happens immediately before the planning phase and after the delta analysis phase. For more information, see Types of orchestrators in Deploy.
Delta analysis determines which deployables need to be deployed, modified, deleted, or remain unchanged. Each of these determinations is called a delta. Orchestration determines the order in which the deltas should be processed. The result of orchestration is a tree-like structure of sub-plans, each of which is:
- A serial plan that contains other plans that will be executed one after another,
- A parallel plan that contains other plans that will be executed at the same time, or
- An interleaved plan that will contain the specific deployment steps after planning is done.
The leaf nodes of the full deployment plan are interleaved plans, and it is on these plans that the planning phase acts.
Planning provides steps for an interleaved plan, and this is done by invoking rules. Some rules will be triggered depending on the delta under planning, while others may be triggered independent of any delta. When a rule is triggered, it may or may not add one or more steps to the interleaved plan under consideration.
Rules and steps
A step is a action that Deploy performs to accomplish a task, such as deleting a file or executing a PowerShell script. The plugins that are installed on the Deploy server define several step types and may also define rules that contribute steps to the plan. If you define your own rules, you can reuse the step types defined by the plugins.
You can also disable rules defined by the plugins. For more information, see Disable a rule.
Each step type is identified by a name. When you create a rule, you can add a step by referring to the step type's name.
Finally, every step has variable parameters that can be determined during planning and passed to the step. The parameters that a step needs depend on the step type, but they all have at least an order and a description:
- The order determines when the step will run.
- The description is how the step will be named when you inspect the plan.
Rules and the planning context
Rules receive a reference to the Deploy planning context, allowing them to interact with the deployment plan. Rules use the planning context to contribute steps to the deployment plan or to add checkpoints that are needed for rollbacks.
The result of evaluating a rule is that:
- The planning context is not affected, or
- Steps and side effects are added to the planning context.
A rule only contributes steps to the plan in some specific situations, when all of the conditions in its conditions section are met.
How rules affect one another
Depending on their scope, rules are applied one after another. Rules operate in isolation, although they can share information through the planning context. The scope determines when and how often the rule is applied, as well as what data is available for the rule. For more information on planning context, see Understanding the Deploy planning phase.
For example, a rule with the deployed scope is applied for every delta in the interleaved plan and has access to delta information such as the current operation (CREATE, MODIFY, DESTROY, or NOOP) and the current and previous instances of the deployed. The rule can use this information to determine whether it needs to add a step to the deployment plan.
Be aware of the plan to which steps are contributed. Because rules with the deployed and plan scope contribute to the same plan, the order of steps is important.
Rules cannot affect one another, but you can disable rules. Every rule must have a name that is unique across the system.
Pre-plan scope
A rule with the pre-plan scope is applied once at the start of the planning stage. The steps that the rule contributes are added to a single plan that Deploy pre-pends to the final deployment plan. A pre-plan-scoped rule is independent of deltas. It receives a reference to the complete delta specification of the plan, which it can use to determine whether it should add steps to the plan.
Deployed scope
A rule with the deployed scope is applied for each deployed in this interleaved plan, for each delta. The steps that the rule contributes are added to the interleaved plan.
You must define a type and an operation in the conditions for each deployed-scoped rule. If a delta matches the type and operation, Deploy adds the steps to the plan for the deployed.
Plan scope
A rule with the plan scope is applied once for every interleaved orchestration. It is independent of any single delta; however, it receives information about the deltas that are involved in the interleaved plan and uses this information to determine whether it should add steps to the plan.
The steps that the rule contributes are added to the interleaved plan related to the orchestration along with the steps that are contributed by the deployeds in the orchestration.
Post-plan scope
A rule with the post-plan scope is applied once, at the end of the planning stage. The steps that the rule contributes are added to a single plan that Deploy appends to the final deployment plan. A post-plan-scoped rule is independent of deltas. It receives a reference to the complete delta specification of the plan, which it can use to determine whether it should add steps to the plan.
Types of rules
There are two types of rules:
- XML rules are used to define a rule using common conditions such as deployed types, operations, or the result of evaluating an expression. XML rules also allow you to define how a step must be instantiated by writing XML. For more information, see Writing XML rules.
- Script rules are used to express rule logic in a Jython script. You can provide the same conditions as you can in XML rules. Depending on the scope of a script rule, it has access to the deltas or to the delta specification and the planning context. For more information, see Writing script rules.
XML rules are more convenient because they define frequently used concepts in a simple way. Script steps are more powerful because they can include additional logic. You can try an XML rule first, and if it's too restrictive, try using a script rule.
For information about defining rules, refer to How to define rules.