Special case plugins

Plugins that break the usual pattern, either by running outside a job or by returning something other than the standard tuple

4 minute read

Most plugins follow the shape described in Structure of a plugin. A few do not: they may run directly from the front-end appliance rather than inside a job, or they may have their own return types. Three are covered on this page; the rest are documented with the feature they belong to.

Order approval plugins: Replace the built-in approval workflow. Covered below.
Generate parameter options plugins: Decide a parameter’s options at run time. Covered below.
Auto-select environment plugins: Choose where a server tier is built. Covered below.
Order validation plugins: Run at the Blueprint Validation, Server Tier Validation, and Validate Order Recipient trigger points.
External user synchronization plugins: Run at the External Users Sync trigger point each time a directory user logs in.
Display condition plugins for server actions: Decide whether a server action’s button is shown.
Discovery plugins on blueprints: Onboard resources that were created outside Cloud Management Platform (CMP).

Order approval plugins

When an order approval plugin is enabled, it replaces Cloud Management Platform’s default behavior of emailing approvers when an order is submitted. Use one to integrate with a separate change management system, or to replace the standard approval workflow with something that fits your organization.

The “Two Approvers” order approval plugin ships with CMP. More are available in the Content Library.

Order submission actions

When a user submits an order, any enabled Order Submitted for Approval plugins run. With no plugins enabled, the order is set to pending, and a single user from any group with approval permission over the requesting group can approve it.

A plugin at this trigger point can approve the order automatically, deny it automatically, or assign it to a specific group for approval.

Nothing runs at this trigger point if the group has auto-approval enabled.

Post-order approval actions

When a user approves an order, any enabled Post-Order Approval plugins run. With no plugins enabled, the order is approved and its jobs start.

A plugin at this trigger point effectively overrides the approve button. It could require that two distinct users have approved an order, or build a workflow in which any order from the Developers group needs two approvals from Finance and then one from IT.

The most useful method here is order.set_pending(), which records the approval already given but returns the order to a state that needs approval from someone else. It also guarantees that multiple distinct users must approve before the order becomes active.

If a group does not have enough users to supply the approvals an order needs after set_pending() is called on it, that order can become difficult to approve.

Helpful methods

These methods and attributes on the Group and Order classes are useful when writing an order approval plugin.

Method	What it does	Use case
`Group.get_groups_can_approve()`	Returns all groups whose orders this group can approve, including itself.
`Group.get_approved_by_groups()`	Returns all groups that can approve orders submitted by this group, including itself.
`Order.approve()`	Approves a pending order.	Called from an order submission action, approves the order without any user input.
`Order.deny()`	Denies a pending order.	Called from an order submission action, denies the order without any user input.
`Order.set_pending()`	Returns an active order to pending.	Called from a post-order approval action, requires approval or denial from another user while keeping the first user’s approval on record.
`Order.groups_for_approval`	When `None`, returns every group with permission to approve the order. When set to a group, only that group can approve it.
`Order.approvers`	Returns the unique users who have approved this order.	Check that a particular user approved, or that enough users have, with `len(order.approvers)`.
`Order.all_groups_approved(groups)`	Confirms that every group in the `groups` argument has approved the order.

Example order submission plugin

import time
from common.methods import set_progress


def run(order, **kwargs):
    set_progress("In Order Submission plug-in order.id={}".format(order.id))
    # randomly approve or deny the order, replace this logic with your own
    if int(time.time()) % 2 == 0:
        order.approve()
        return ("", "Order approved", "")
    else:
        order.deny()
        # note: the plug-in was still successful, so we return an empty status,
        # even though we have rejected the order.
        return ("", "Order denied", "")

Generate parameter options plugins

Using a plugin to generate the options for a parameter is one of the more involved ways to change CMP’s built-in behavior. See Generated parameter options.

Auto-select environment plugins

A plugin can decide the best place to run a given server tier in a blueprint. Setting up the feature and the plugin details are covered in Environment selection orchestration.