Skip to main content

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:

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.

Project asset templates screen

Each row includes:

ColumnDescription
NameThe name describing the asset template.
CodeShows the asset template's unique code.
Template typeThe type of template, either Agent or Asset.
Git remoteThe Git remote associated with this template.
Newest versionThe most recent version or Git revision associated with the asset template.
StateThe 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 revisionThe Git revision the template's newest version currently points to.
ArchivedWhether the asset template is archived or not.
note

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

Buttons & linksFunction
Bulk actionsAllows you to add a new version to each selected template, archive, restore or permanently delete multiple asset templates, fetch the revision for the newest version of each selected template, or archive their unused versions.
Search barFilter the contents of the table based on these criteria.
Include archivedList archived asset templates alongside active ones.
ColumnsHide or display columns in the table.
Create templateAdd a new asset template to the project.

Creating a new asset template​

Project asset template details create screen

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
  • Updating its Git remote, archiving or restoring it, and deleting it from the three dots menu

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, MintPress 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, MintPress fetches the Git revision and identifies the actions available for that version, making them available to any asset that switches to it.

If MintPress 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 with the Cancel fetch button, which returns the version to the revision it had previously resolved, or marks it broken if it has none.

A template's newest version is the one whose commit was made most recently, whatever order the versions were added in. Versions whose commit time is not known count as the oldest. The newest version is the one shown in the templates list, picked by default when updating several templates' assets, and marked latest in version pickers.

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, MintPress periodically checks the branch or tag for new commits as part of its background Git fetching. When the revision moves, MintPress 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. MintPress 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 MintPress 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.

Project asset template details screen

Each row includes:

ColumnDescription
Lock iconLock or unlock the version. A locked version cannot be modified until it is unlocked. A version that follows its Git revision cannot be locked.
Waves iconWhether 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.
VersionThe version number or identifier for the asset template.
DescriptionProvides a short summary or purpose of the template version.
AssetsShows the assets that are using this template version.
Git remoteThe Git remote the template version fetches from.
StateThe current status of the template version, such as whether it’s ready for use or has issues.
Git revisionThe specific Git commit or revision that this template version points to.
Committed atWhen the commit the version points to was made. The table is sorted by this column by default, newest first.
Created atTimestamp for when the template version was created.
Updated atTimestamp for when the template version was last updated.
ArchivedIndicates the archival status of the template version.
Buttons & linksFunction
Bulk actionsAllows you to archive, restore, lock, unlock or delete multiple asset template versions, fetch their Git revision in bulk, or turn following a Git revision on or off for the selected versions.
Search barFilter the contents of the table based on these criteria.
Include archivedList archived template versions alongside active ones.
ColumnsHide or display columns in the table.
Create template versionCreate a new template version for the asset template.
note

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

Viewing a template version​

Click a row in the template versions table to open that version's page. Its header shows:

Template version page

CardDescription
StateThe version's state - for example ready, initializing or broken. Hover over a broken state to see the error from the last fetch.
Git revision or Git revision (floating)The Git revision and short commit SHA the version resolved to. The label reads Git revision (floating) when the version follows its Git revision. While a fetch is running, the card shows its progress instead.

The header's buttons and its three dots menu fetch the revision or cancel a fetch, switch following the Git revision on or off, lock, archive or delete the version, and edit its description.

The Linked assets tab (Linked agents for an agent template) lists what is assigned this version, with a Parent column giving each one's location as a trail of codes, such as bank → dev → web for an asset in an environment or bank → monitor for an agent. CSV on the Linked assets tab downloads the list as a CSV file. The Properties and Settings tabs hold the version's own values - see template properties and settings.

Editing the asset template​

Project edit asset template screen

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.

Creating or editing an asset template version​

Project edit asset template version screen

To create a template version or update an existing one, follow these steps:

  1. Click on the Create 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.

A new version starts with a copy of the properties of the version most recently added to the template (or the most recently added archived version, if every version is archived), whatever their commits. This is not necessarily the version marked latest. Edit the new version's properties if it needs different values.

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. The Latest tab shows the most recent one, and Download saves it as a JSON file named for the environment and asset it belongs to.

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 templates or Archive template versions 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.

Archiving unused versions​

Archive the versions of several templates that nothing has used for a while by selecting the templates in the templates table and choosing Archive unused versions… from the Bulk actions menu. It needs permission to update the templates, and acts only on the selected templates that are not archived.

In the dialog, set:

  • Unused for (days) - archive a version only if it has not been created, used by a change, or assigned to an asset in this many days, from 1 to 365. Required.
  • Keep newest per template - keep this many of each template's newest versions, whether or not they are used.
  • Version name contains - archive only the versions whose name contains this text.

The dialog lists the versions that would be archived as you change these values. Versions used by an asset, a change that has not finished or a workflow are never archived, nor are locked versions. Click Archive versions… and confirm. The list is checked again when you confirm, so a version used since the preview is skipped, and the message shown afterwards says how many were archived. The result is recorded in the project's audit history.

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 templates 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.

Deleting template versions​

Delete a template version with Delete template version from the version's actions menu, or delete several at once by selecting them in the template versions table and choosing Delete template versions from the Bulk actions menu. Deleting needs permission to delete the template version.

What happens depends on whether the version has been used:

Template versionResult
Currently assigned to an asset or agentCannot be deleted. Promote the asset or agent to another version first. A bulk delete skips these versions and says how many it skipped.
Assigned to an asset or agent in the pastArchived instead of deleted, so the history of the assets that used it stays intact.
Never assignedDeleted.

The confirmation lists the versions about to be deleted, and the result reports how many were deleted and which were archived instead. A version that could not be deleted is reported separately, naming the version and the reason.