# Structure of a plugin

> What a plugin module must contain, what it is passed, and what it can return

---

Site [llms.txt](/llms.txt)

---

A plugin module must contain a function called `run()`. The Cloud Management Platform (CMP) job engine calls that function at particular points during a job's execution.

## What run() receives

The function is passed a Job object and a set of keyword arguments that simplify access to the CMP objects the plugin is likely to need. Every keyword argument below is passed to any plugin's `run` method, but its value is `None` when the object it refers to does not apply in that context.

- `logger`: A standard Python [Logger](https://docs.python.org/3/library/logging.html) object.
- `hook_point`: A string naming the trigger point the action was called from. When the action is not running as an orchestration action, this is `None`.
- `servers`: An iterable of all servers the plugin targets. When there is only one, `server` is also available.
- `resources`: An iterable of all deployed resources the plugin targets. When there is only one, `resource` is also available.

## What run() can return

A plugin's `run` method returns either a tuple of three strings, or a dictionary. Use the dictionary form when you want to pass outputs to later steps.

### Three-tuple returns

The tuple is (status, output, errors). On success, return `("", "", "")`. If a non-empty status string is returned, the job engine saves the status, output, and errors to the job and skips any remaining steps. A pre-job plugin can use this to stop a job when its prerequisites are not met.

### Dictionary returns

A dictionary return supports four optional keys:

- `status`: One of the valid status values below.
- `output_message`: The message returned on a successful run.
- `error_message`: The message highlighted in red on the job, drawing attention to the reason for the error.
- `outputs`: A dictionary of everything the plugin wants to hand on.

### Valid status values

These are the status strings a plugin can return, with the text shown to the user on the job:

- `SUCCESS`: Completed successfully
- `WARNING`: Completed with warnings
- `FAILURE`: Completed with errors
- `CANCELED`: Canceled by user

<div class="alert alert-info" role="alert">


Some plugins are exceptions to the structure described here and use different method names, signatures, and return values. These include plugins in rules, Generated Parameter Options, Display Condition, and Discovery on blueprints. See [Special case plugins](/docs/cmp/use/orchestration/plugins/special-cases/).
</div>


## Use outputs in a later step

When a plugin runs as a build step in a blueprint, later steps can reference what it returned with `{{ outputs.<step name>.<key> }}`, where `<key>` is a key from the dictionary the plugin returned. Use this in the code for later steps, or when setting default values for their action inputs.

`<step name>` is the build step's name in lowercase, with spaces and dashes replaced by underscores and all other special characters removed, so that it forms a valid Python identifier.

## Helpful methods

`set_progress()` both writes a message to the job's detail page and adds a logging statement to that job's log. Anything passed in the `logger_kwargs` dictionary is written as key/value pairs in the logging statement.

```python
from common.methods import set_progress

set_progress(message, logger_kwargs={}, **kwargs)
```

## Related

- [Special case plugins](/docs/cmp/use/orchestration/plugins/special-cases/)
- [Development tips for plugins](/docs/cmp/use/orchestration/plugins/development-tips/)
- [Plugin examples](/docs/cmp/use/orchestration/plugins/examples/)