BKR-WORKFLOW-XSLT(1)

📦
version 29.2 · 3 versions
, in epel 9

💅 bkr-workflow-xslt

Okay bestie, welcome to BKR-WORKFLOW-XSLT(1) from the Beaker manual ✨ — this is the XSLT-based Beaker job generator, and honestly? it's giving very main character energy 🎀

🌸 NAME

bkr-workflow-xslt — the XSLT-based Beaker job generator. That's it, that's the whole vibe 🦋

✨ SYNOPSIS

bkr workflow-xslt [options]
  [--defaults=<filename>] [--profile=<profile-name>] [--job-xml=<filename>]
  [--dry-run | --wait]
  [--xslt-override=<filename>] [--xslt-name=<name>] [--whiteboard=<text>]
  [--save-xml=<filename>] [--save-internal-xml=<filename>]
  [job-specific options]

Job-specific options are defined inside the Job Configuration XML, and they get described to you with --help 🫶 (iykyk — the config file literally decides what flags exist, which is kind of iconic ngl).

🎀 DESCRIPTION

So here's the tea ☕ — this program takes a Job Configuration XML file that defines variables useful in a kernel workflow. It uses that info to process the... generate a Beaker job XML document, as defined in the configured XSLT files. Like, that's the whole thing: config in, Beaker job XML out 🔥

🧚 Beaker arguments

The common bkr options are described in the Options section of bkr(1). But heads up — in spite of its name, this program does not accept the common workflow options described in the Workflow options section of bkr(1). Not a drill, bestie 💀

🚨 It is important that the arguments in this section come before any other options. These arguments define how the rest of the arguments get processed and what their default values are. Order matters, periodt.
  • --defaults <filename> — adds more default values on top of whatever may already be configured in ~/.beaker-client/bks-defaults and ./bks-defaults. Extra defaults, extra slay ✨
  • --profile <profile-name> — the defaults files can be configured with different profiles for the same Job XML file. This argument picks which profile set to use for default values. Choose your fighter 🎀
  • --job-xml <filename> — defines which Job XML Configuration file to load. This one is mandatory, unless it's already configured in a defaults file. No cap.
  • --dry-run — with this, the job will not be sent to the Beaker scheduler at all. And if you don't use --save-xml or --save-internal-xml, the generated Beaker job XML will just be dumped to stdout. Peek only, no send 🙈
  • --wait — this makes the bkr workflow-xslt operation wait for the Beaker job to complete before exiting. Sit. Stay. Wait for the job 🐕

🌈 Global job arguments

The global options are specific to the bkr workflow-xslt module, and they use the defaults as defined in the SETTINGS ARGUMENTS section. Also — short arguments may be overrided by the Job XML definition. Yep, the XML can snatch the wheel 💅

  • --xslt-override <filename> — overrides the configured XSLT file defined in the Job Configuration. You're the override now 👑
  • -X <name>, --xslt-name <name> — the Job Configuration can have several XSLT templates configured, and this option defines which one to use. If it's not set, it'll use the XSLT template that has no name configured. Default-template behaviour, classic ✨
  • -W <text>, --whiteboard <text> — adds the given <text> as the text for the Beaker job whiteboard. Put it on the board 📌
  • --save-xml <filename> — saves the generated Beaker Job XML to the given <filename>.
  • --save-internal-xml <filename> — saves the internal XML document (the one passed to the XSLT processor) to the given <filename>. Super useful during debugging 🐛 🔍

🦋 Job XML configuration

A Job XML Configuration is needed to be able to generate XML files for the Beaker scheduler. The whole purpose of the Job XML Configuration is to define which parameters and variables the XSLT processing needs to work. This configuration also defines parts of the XML document that gets sent to the XSLT processor. And yes — this configuration file is itself an XML document. XML-ception, we love to see it 🌀

🌸 Real talk: how to actually write the needed XSLT documents is not explained in this manual. That's a different lore drop.

💜 The structure

<JobConfig>
    <name>{Descriptive name of the job configuration}</name>
    <xslt>{Default XSLT file}</xslt>
    [<xslt name="variant2">{Named XSLT file}</xslt>]
    [...more <xslt/> tags...]
    <arguments>
        <arg section="recipe" type="{string|bool}" [optional="1"]>
            <name short="a">{long argument}</name>
            <tag type="{tagtype}">{XML tag name}</tag>
            [<default>{default value}</default>]
            <description>{Argument description</description>
            <metavar>{Descriptive value substitution<metavar>
        </arg>
        [...more <arg/> tags...]
    </arguments>
</JobConfig>

⭐ Tag descriptions

🌟 <JobConfig/>

The XML root node must be a <JobConfig/> tag. It's the parent, the main character of the file 🫶

🌟 <name/>

The first <name/> inside <JobConfig/> is a plain and short string describing the purpose of this Job Configuration. Short, sweet, to the point 🎀

🌟 <xslt [name="{XSLT-NAME}"]/>

This tag defines which XSLT templates this Job Configuration depends on. There must be at least one <xslt/> present. If there's no name attribute, it's defined as the default XSLT file. When the name attribute is set, that XSLT file is the one used when you use the --xslt-name option ✨

🌟 <arguments/>

All the variable options the defined XSLT template needs must be configured in separate <arg/> tags inside this tag. Everything lives in here 💅

🌟 <arg section="recipe" type="{string|bool}">

Each option is individually defined by <arg/> tags. The section and type attributes are mandatory. Currently only the recipe section is supported. The type attribute defines the type of argument:

  • If type is set to bool, it defines a command line argument that takes no arguments. If that argument is given to bkr workflow-xslt, the tag or attribute value gets set to true ✅
  • The optional attribute is optional (lol, yes, fr). If set to 1, it makes this argument purely optional. The default is to require the argument. No pressure… okay, some pressure 😭

🌟 <name short="{short arg}"/>

The <name/> defines the short and long option names. The short attribute is mandatory and can only be one character. And if the same argument name is defined several times? The last defined argument overrides all other conflicting arguments. Last one wins, sorry 🏆

🌟 <tag type="{attribute|value|list}" [attrname="{Attribute name}"] [element_tag="{list element tag name}"]/>

This tag defines which XML tag name the internal XML tag stores the option value under. The type attribute is mandatory and can be either attribute, value or list:

  • When set to value, the option value given at the command line of bkr workflow-xslt will be embraced by the defined tag name 🫂
  • If type is set to attribute, the option value from the command line gets placed as an attribute value on the defined XML tag name. When using attribute, the attrname attribute is mandatory — it defines the attribute name to be used in the internal XML 🏷️
  • If type is set to list, it creates a list of XML tags based on the value string. The default value for the children of the tag name is value, unless element_tag is set. The value string will be split into separate tokens using a comma (,) as the separator 🍓

🌟 <default/>

This tag is optional. It sets a default value if this option isn't used on the command line ✨

🌟 <description/>

This tag is used for the --help screen, describing the command line option to bkr workflow-xslt. Be nice, it's what everyone reads 📖

🌟 <metavar/>

Also used for the --help screen. It's used as a substitute for the variable contents, purely for [that display]. To make it obvious, it's recommended to put use capital letters 🔠

🌈 Example

Save the contents below as example-job.xml:

<?xml version="1.0"?>
<jobConfig>
  <name>Example Job</name>
  <xslt>example.xsl</xslt>
  <arguments>
    <arg section="recipe" type="string">
      <name short="i">id</name>
      <metavar>INTEGER</metavar>
      <tag type="attribute" attrname="version">name</tag>
      <description>Unique numeric ID</description>
    </arg>
    <arg section="recipe" type="string">
      <name short="n">name</name>
      <metavar>FULL-NAME</metavar>
      <tag type="value">name</tag>
      <description>Full name</description>
    </arg>
    <arg section="recipe" type="string" optional="1">
      <name short="g">group</name>
      <metavar>GROUP-NAME</metavar>
      <tag type="attribute" attrname="group">name</tag>
      <description>Group identifier</description>
    </arg>
    <arg section="recipe" type="string" optional="1">
      <name>phone-numbers</name>
      <metavar>PHONE\-NUMBERS</metavar>
      <tag type="list" element_tag="number">phones</tag>
      <description>List of phone numbers, comma separated</description>
    </arg>
  </arguments>
</jobConfig>

Save this dummy XSLT file as example.xsl:

<?xml version="1.0"?>
<xsl:stylesheet version="1.0"
        xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
   <xsl:output method="xml" version="1.0"
           encoding="UTF-8" indent="yes"/>
</xsl:stylesheet>

Run from a terminal the following command:

$ bkr workflow-xslt --dry-run --job-xml example-job.xml \\
     --save-internal-xml example.xml \\
     -i 99 -n "Example" -g "Group1" --phone-numbers 123,456,789
----------------------------------------------------
Generating Beaker XML
   Job config:    example-job.xml
   XSLT template: example.xsl
   Job name:      Example Job
   Whiteboard:    None
   Job arguments:
      - group: Group1
      - id: 99
      - name: Example
----------------------------------------------------
$ cat example.xml
<?xml version="1.0" encoding="UTF-8"?>
<submit>
   <whiteboard/>
   <recipe>
     <phones>
        <number>123</number>
        <number>456</number>
        <number>789</number>
     </phones>
     <name group="Group1" version="99">Example</name>
   </recipe>
</submit>

Obsessed with how clean that internal XML looks, ngl 💖

🧚 Setting defaults

It is possible to define defaults in a separate file. This is useful if you often use the same Job Configuration, or you have other arguments that don't change so often. Two files are attempted to be read upon startup: ~/.beaker_client/bks-defaults and ./bks-defaults 🌸

The bks-defaults file is an INI-styled configuration file. It requires a [defaults] section which has one parameter, jobxml 🎀

So like, you can totally set individual default values depending on which Job XML Configuration you're using — it's giving personalized ✨. Just use the Job XML Configuration filename as the section name, bestie. And the parameters? They use the long options of the Job Configuration to define the default values. No cap.

🌸 Example

[defaults]
jobxml: example-job.xml

[example-job.xml]
group: Group1

💅 Default profiles

Okay so this is the icon behavior: it is possible to define several sets of default values for the same Job XML Configuration 🫶. You do it by appending :<profilename> to the section name. Notice the 'colon' — that colon is the main character, don't forget it 💀.

🎀 Example

This builds upon the example above:

[example-job.xml:setup2]
group: Group2b

To run the example in the Example section above, execute:

$ bkr workflow-xslt --dry-run --save-internal-xml example.xml \
    -i 99 -n "Example"

This will use the value Group1 as a default value in the group attribute. Slay. 👑

But if you instead do this:

$ bkr workflow-xslt --dry-run --profile setup2 \
    --save-internal-xml example.xml \
    -i 99 -n "Example"

then the generated example.xml will have the value Group2b as a default value in the group attribute. Literally that easy 🌈.

✨ AUTHOR ✨

David Sommerseth <davids@redhat.com> — the legend who wrote this, we stan 🫶

2013-2025 Red Hat, Inc.

🧚 That's the whole page, bestie — you made it to the end and you ate, fr fr 💖

And that's a wrap, gorgeous! This lil masterpiece is from version 29.2, dated May 26, 2025, filed under BKR-WORKFLOW-XSLT(1) in section 29.2 — go forth and migrate your Job XMLs, you absolute icon 🎀✨💜

📦 where this page comes from