Templates for the Installer Assistant

Role: Administrator

Overview

The assistant Creating a package from an installer creates the scripts and files of a new package from the templates. They are the templates of the opsi-setup-detector (template-files), which oPBWeb ships. On the first start oPBWeb copies them into the database; there you can change them in the view Templates, add your own, delete them or import a newer version from a ZIP. No new image is needed for that.

All users see the view Templates in the activity bar. Only administrators may change it; everybody else sees the note “Read only: only administrators may change templates.”

Structure: channels and groups

As in the opsi-setup-detector, the templates are organised in channels and groups. Every file has the path <channel>/<group>/<file>.

The packager chooses the channel of a new package in the assistant; it is preset with the channel from the settings .

Lookup order

The generator looks for every file in this order and takes the first match:

1. in the chosen channel, in the group of the package, for example custom/win/setup.opsiscript,
2. in the channel Default, same group, default/win/setup.opsiscript,
3. in default/generic.

So in the channel Own (custom) you only create the files that differ from Default. If the generator finds a file nowhere, it skips the building block and reports “Template … is missing, the building block is skipped”.

Placeholders

The templates contain placeholders of the form #@name*#, for example #@productId*# for the product id or #@installCommandLine1*# for the install command of the first installer. When creating a package the generator replaces them with the values from the assistant; upper and lower case do not matter. If a placeholder stands for several lines, the generator indents all of them like the placeholder’s line.

To the right of the editor, the pane Placeholders lists all placeholders of the open file. If a placeholder is left over because the generator knows no value for it, the job reports “Placeholders left in the generated files: …”. You cannot introduce placeholders of your own; in your own templates use only the names that occur in the shipped files.

The Templates view

The tree with channels, groups and files is on the left, with a filter field above it. Clicking a channel or a group collapses or expands it; clicking a group also makes it the target for new files and uploads. Every file carries a badge:

Clicking a file opens it in the editor on the right. You edit text files there with the same features as in the script editor ; images and other binary files can only be downloaded or replaced by an upload.

Editing a template

1. Open Templates in the activity bar.
2. Click the file in the tree, for example Default › win › setup.opsiscript.
3. Change the text in the editor.
4. Click Save or press Ctrl+S. The message “Template saved” confirms it. A shipped file then carries the badge modified.

The change applies to all packages the assistant creates from then on. Packages created earlier do not change.

More actions

File names consist of letters, digits, dot, plus, space, hyphen and underscore; separate sub folders with /. Group names consist of lower case letters, digits, hyphen and underscore. A file may be at most 16 MB.

Deleting and restoring

• An own file is gone after deleting it.
• A shipped or modified file stays as a deleted entry. The generator no longer uses it, and an update of oPBWeb does not bring it back either. Tick Deleted shipped templates below the tree to see these entries; Restore brings back the shipped content.

If you delete a file in the chosen channel, the lookup order applies when creating a package: the generator then takes the file from Default or default/generic, if it exists there.

Templates and updates

A new oPBWeb image may bring newer templates. On start, the API brings the database up to date:

• Unchanged shipped files get the new content.
• Modified files keep your content. Reset then leads to the new shipped version.
• Deleted shipped files stay deleted.
• New files are added; your own files stay untouched.

Importing templates from a ZIP

This is how you take over a newer version of the opsi-setup-detector’s templates without waiting for a new image, or bring your own templates to a second oPBWeb installation.

1. Get the folder template-files of the opsi-setup-detector: from the GitHub repository opsi-org/lazarus (folder opsi-misc/opsisetupdetector/template-files) or from an installation of the opsi-setup-detector.
2. Pack it as a ZIP. Two layouts are allowed, each also with one extra folder on top such as template-files/:
   • <channel>/<group>/<file> with one or more channels (training, default, structured, custom),
   • <group>/<file> for a single channel; you choose the channel when importing.
3. In the view Templates, click Import templates above the tree.
4. Choose the file under ZIP file.
5. Under Import into channel, choose the target channel or as in the ZIP.
6. Tick Replace existing templates if existing files should get the content from the ZIP. Without it, only new files are added.
7. Click Import. The message shows the result, for example “Import: 3 new, 12 replaced, 140 skipped”.

New files from the ZIP become own templates. Replaced shipped files count as modified and can still be reset. Deleted shipped files that are in the ZIP are brought back by the import. Skipped are unchanged files, folders, links, files over 16 MB and names the editor does not accept. A ZIP may contain at most 5000 files.

Audit log

Every change to the templates appears in the audit log : detector.template_created, detector.template_uploaded, detector.template_updated, detector.template_reset, detector.template_deleted and detector.templates_imported.