Asset templates

Asset templates let you reuse a single Git repository to manage many different kinds of asset by pointing each template at a named folder containing its own actions.rb. For example, a repository laid out like this:

my-project/
  db_server/
    actions.rb
  web_server/
    actions.rb

can back two asset templates - one for db_server and one for web_server - with each asset using the actions of its respective template.

Asset templates are also used to:

• represent an asset
• represent an asset's ERB template that conforms to the MintModel JSON schema

The terms asset template and template are used interchangeably in the product and in this documentation.

Listing asset templates

This tab lists all the asset templates created for the project.

Each row includes:

Column	Description
Name	The name describing the asset template.
Code	Shows the asset template's unique code.
Template type	The type of template, either Agent or Asset.
Git remote	The Git remote associated with this template.
Newest version	The most recent version or Git revision associated with the asset template.
State	The state of the template's newest version - for example ready, initializing or broken - with the same fetch/cancel revision control and revision popover as the template versions table.
Git revision	The Git revision the template's newest version currently points to.
Archived	Whether the asset template is archived or not.

note

Asset templates that are in use by an agent or an asset cannot be archived.

Buttons & links

Buttons & links	Function
Bulk actions	Allows you to archive, restore or permanently delete multiple asset templates, or fetch the revision for the newest version of each selected template.
Search bar	Filter the contents of the table based on these criteria.
Show archived	Toggle to show archived asset templates in the table.
Columns	Hide or display columns in the table.
Create template	Add a new asset template to the project.

Creating a new asset template

To create a new asset template, first ensure you have a Git remote configured for the project, and then follow these steps:

1. Click on the create template button.
2. Fill in the mandatory fields in the dialog, including the code and name.
3. (Optional) Add a description to clarify the purpose of the asset template for other users.
4. Select the template type, either Agent or Asset. Templates of type Agent are used to define agents, while templates of type Asset are used to define assets. This cannot be changed after the template is created.
5. Select a Git remote from the dropdown.
6. Click the Create asset template button. If successful, the new asset template will appear on the asset templates list of the project.

Asset template details and versions

Clicking on a specific asset template row will open its details page, where you can manage the template by:

• Editing the asset template name and description
• Adding, editing and archiving its asset template versions
• Editing the template's properties and settings
• Enabling/disabling the asset template

Template properties and settings

The template details page carries Properties and Settings tabs alongside its versions, holding the values shared by every version of the template. Each version has its own properties and settings as well, so put a value on the template when every version should have it, and on a version when only the assets assigned that version should.

Both are edited in the same properties and settings editors used elsewhere. They resolve between the environment and the template version, so an asset's own values still override them — see properties. A template's settings are validated against the same schema a project's are, since a template belongs to a project rather than to a single node.

note

Properties and settings cannot be edited on an archived template, or on a locked template version. Each tab is read only where you do not have permission to see the values behind it.

About asset template versions

To stay in control of the changes made to an asset template, OpsChain lets you create template versions that lock the source code for the template to a specific Git revision. A template version always refers directly to a single Git revision in the asset template's Git repository.

Whenever a template version is created or updated, OpsChain fetches the Git revision and identifies the actions available for that version, making them available to any asset that switches to it.

If OpsChain is unable to fetch the provided Git revision or resolve the template actions, the version will be marked as "broken" and it will not be usable until the issue is resolved.

A template version's Git revision can be re-fetched at any time — for example, after resolving a fetch failure, or to pick up new commits on a branch or tag — using the Fetch revision button in the template version header.

Revisions can also be fetched in bulk: select rows in the template versions table and choose Fetch revision from the Bulk actions menu, or select rows in the templates table and choose Fetch revision for newest version to re-fetch the newest version of each selected template. Both offer a force option to re-fetch versions that are currently in use, and report each failure individually alongside a summary of the successes.

While a fetch is in progress the version is shown as initializing. If the fetch is interrupted before it finishes — for example by the worker running it being restarted — OpsChain detects the stalled fetch and re-attempts it, so the version resolves back to ready or is marked broken rather than staying stuck. An in-progress fetch can also be cancelled through the API's cancel_refresh endpoint, which returns the version to the revision it had previously resolved, or marks it broken if it has none.

You can only update a template version if no assets are using it. If you have a version being used by multiple assets, it is recommended to create a new template version instead and promote each asset as needed.

A template version that has never resolved a Git revision, or whose last fetch failed, cannot be assigned to an asset or an agent, and a change cannot be created against one. Resolve the fetch failure and re-fetch the revision to make the version usable again.

Following a Git revision

A template version normally stays on the commit its Git revision resolved to when it was created, so the code an asset runs does not move underneath it. A version can instead be set to follow its Git revision, which suits a version pointing at a branch you expect to move — a development branch, or a main you want assets to track.

When a version follows its revision, OpsChain periodically checks the branch or tag for new commits as part of its background Git fetching. When the revision moves, OpsChain resolves the new commit and rebuilds the actions of the assets using that version, without anyone asking for it.

Following can be switched on and off from the waves icon in the template versions table, from the version's actions menu, and when adding a version. To set it for several versions at once, select the rows and use Enable floating Git revision or Disable floating Git revision from the Bulk actions menu.

note

Following a Git revision and locking a version are mutually exclusive — locking exists to stop the commit moving, which is exactly what following it does. OpsChain rejects an attempt to do both, and the control that would do so is disabled with the reason.

Changes already running are unaffected: a change runs against the actions and the commit resolved when it was created, so a revision that moves mid-change does not disturb it. Assets are not promoted between template versions either — following a revision moves the commit within one version, it does not move an asset onto a different version.

If OpsChain cannot resolve the revision — the branch has been deleted, or the remote cannot be reached — the version keeps serving the commit it already had rather than being marked broken, and reports why it last failed to follow its revision until it succeeds again. A revision that resolves to the same commit as before is not a move, so nothing is rebuilt.

info

Creating new template versions does not automatically update the assets using the template. You must intentionally promote each asset to use the new template version, or create new assets against the new version. This puts you in control of the changes made to your assets and avoids unexpected or unintended changes.

Each row includes:

Column	Description
Lock icon	Allows you to lock the version. This will ensure that it does not float to newer Git revisions until it is unlocked.
Waves icon	Whether the version follows its Git revision, and the control to switch that on or off. Where the last automatic refresh failed, the reason is shown here.
Version	The version number or identifier for the asset template.
Description	Provides a short summary or purpose of the template version.
Assets	Shows the assets that are using this template version.
State	The current status of the template version, such as whether it’s ready for use or has issues.
Git revision	The specific Git commit or revision that this template version points to.
Created at	Timestamp for when the template version was created.
Updated at	Timestamp for when the template version was last updated.
Archived	Indicates the archival status of the template version.

Buttons & links

Buttons & links	Function
Bulk actions	Allows you to archive or restore multiple asset template versions, fetch their Git revision in bulk, or turn following a Git revision on or off for the selected versions.
Search bar	Filter the contents of the table based on these criteria.
Show archived	Toggle to show archived template versions in the table.
Columns	Hide or display columns in the table.
Add template version	Add a new template version to the asset template.

note

Asset template versions that are in use by an agent or an asset cannot be archived.

Editing the asset template

To edit the asset template, follow these steps:

1. Go to the asset template details page.
2. Click on the pencil icon at the top-right of the page.
3. Fill in the fields you need to edit. Note that you cannot edit the template's code or type.
4. Click the Update asset template button. If successful, the asset template will have the updated values that you set.

Adding/editing an asset template version

To add or update an existing template version, follow these steps:

1. Click on the Add template version button.
2. Fill in the mandatory fields in the dialog, including the version and the Git revision.
3. If the version matches an existing template version, a warning message will appear that the version already exists. If it is not in use by an asset, submiting the form will update the existing version.
4. Click the Create template version button.

Documented template actions

All actions defined in the asset template's actions.rb file that include a description as part of their definition will be listed in the asset's action list. Actions without a description remain available to run, but the user must know their name and key it into the action field manually.

Below is an example of actions with and without a description:

action :available_in_dropdown, description: "This action and description will appear in the asset's action tab, and in the actions available in the run change dialog" do
  log.info "Here is the action implementation"
end

action :can_be_run_manually do
  log.info "Here is the action implementation"
end

Read more about actions in the actions reference page.

Asset templates with a MintModel

When creating a template version, if the relevant Git revision contains an ERB file at MintModel/templates/assets/<template_code>.json.erb, then the template version will be marked as having a MintModel. If the asset's template version includes a MintModel ERB file, then the MintModel actions will be available in the asset's action list, along with any action in the actions.rb file.

Each time a change is run for an asset with a MintModel ERB, a concrete MintModel JSON will be generated from the asset's converged properties and the ERB. The MintModel JSON will be linked to the change so it can be viewed via the change details screen in the GUI. Each distinct MintModel created by an asset's changes will also be available to view via the asset's MintModel tab, where it can be viewed and compared with other MintModel JSONs generated for the asset.

info

When running an action that is defined both in the actions.rb file and through the MintModel associated with the asset, the MintModel action will take precedence over the one defined in the actions.rb file.

We suggest not naming any actions in the actions.rb file with a name that matches a MintModel action name.

Archiving asset templates and template versions

Archive one or more asset templates - or individual template versions - by selecting them in their respective table and choosing Archive from the Bulk actions menu.

• Archived asset templates cannot be used to create new assets.
• Archived asset template versions cannot be assigned to assets.
• Asset templates and template versions that are currently in use by an asset cannot be archived. Promote any affected assets to a different version first.

Deleting asset templates

Delete an asset template from its actions menu, or delete several at once by selecting them in the templates table and choosing Delete from the Bulk actions menu.

warning

Deleting an asset template is permanent and irreversible. A template that is still assigned to a node or referenced by a change cannot be deleted - archive it instead.