1BKR-WORKFLOW-XSLT(1) Beaker BKR-WORKFLOW-XSLT(1)
2
6 bkr-workflow-xslt - XSLT-based Beaker job generator
7
9 bkr workflow-xslt [options]
10 [--defaults=<filename>] [--profile=<profile-name>] [--job-xml=<filename>]
11 [--dry-run | --wait]
12 [--xslt-override=<filename>] [--xslt-name=<name>] [--whiteboard=<text>]
13 [--save-xml=<filename>] [--save-internal-xml=<filename>]
14 [job-specific options]
15 Job-specific options are defined in the Job Configuration XML, and will
18 be described with --help.
19
21 This program will use a Job Configuration XML file which defines vari‐
22 ables useful in a kernel workflow. It will use this information to
23 process the generate a Beaker job XML document, as defined in the con‐
24 figured XSLT files.
25 Beaker arguments
27 Common bkr options are described in the Options section of bkr(1). Note
28 that, in spite of its name, this program does not accept the common
29 workflow options described in the Workflow options section of bkr(1).
30 It is important that the arguments in this section comes before any
32 other options. These arguments define how the rest of the arguments
33 should be processed and their default values.
34 --defaults <filename>
36 Adds more default values in addition to what may be configured
37 in ~/.beaker-client/bks-defaults and ./bks-defaults.
38 --profile <profile-name>
40 The defaults files can be configured with different profiles for
41 the same Job XML file. This argument will define which profile
42 set to use for default values.
43 --job-xml <filename>
45 Defines which Job XML Configuration file to load. This argument
46 is mandatory, unless configured in a defaults file.
47 --dry-run
49 When this option is used, the job will not be sent to the Beaker
50 scheduler at all. If you don't use --save-xml or
51 --save-internal-xml the generated Beaker job XML will be dumped
52 to stdout.
53 --wait This will cause the bkr workflow-xslt operation to wait for the
55 Beaker job to complete before exiting.
56 Global job arguments
58 The global options are specific to the bkr workflow-xslt module, and
59 will use the defaults as defined in the SETTINGS ARGUMENTS. Short argu‐
60 ments may be overrided by the Job XML definition.
61 --xslt-override <filename>
63 This will override the configured XSLT file defined in the Job
64 Configuration.
65 -X <name>, --xslt-name <name>
67 The Job Configuration can have several XSLT templates config‐
68 ured. This option will define which XSLT to use. If this option
69 is not set, it will use the XSLT template which has no name con‐
70 figured.
71 -W <text>, --whiteboard <text>
73 Adds the given <text> as a text for the Beaker job whiteboard.
74 --save-xml <filename>
76 Saves the generated Beaker Job XML to the given <filename>.
77 --save-internal-xml <filename>
79 Saves the internal XML document which is passed to the XSLT pro‐
80 cessor to the given <filename>. This is useful during debugging.
81 Job XML configuration
83 A Job XML Configuration is needed to be able to generate XML files to
84 the Beaker scheduler. The purpose of the Job XML Configuration is to
85 define which parameters and variables which are needed for the XSLT
86 processing to work. This configuration will also define parts of the
87 XML document being sent to the XSLT processor. This configuration file
88 is also an XML document.
89 It will not be explained how to write the needed XSLT documents in this
91 manual.
92 The structure
94 <JobConfig>
95 <name>{Descriptive name of the job configuration}</name>
96 <xslt>{Default XSLT file}</xslt>
97 [<xslt name="variant2">{Named XSLT file}</xslt>]
98 [...more <xslt/> tags...]
99 <arguments>
100 <arg section="recipe" type="{string|bool}" [optional="1"]>
101 <name short="a">{long argument}</name>
102 <tag type="{tagtype}">{XML tag name}</tag>
103 [<default>{default value}</default>]
104 <description>{Argument description</description>
105 <metavar>{Descriptive value substitution<metavar>
106 </arg>
107 [...more <arg/> tags...]
108 </arguments>
109 </JobConfig>
110 Tag descriptions
112 <JobConfig/>
113 The XML root node must be a <JobConfig/> tag.
114 <name/>
116 The first <name/> in <JobConfig/> is a plain and short string
117 describing the purpose of this Job Configuration.
118 <xslt [name="{XSLT-NAME}"]/>
120 This tag defines which XSLT templates this Job Configuration
121 depends on. It must be at least one <xslt/> present. If no
122 name attribute exists, it is defined as the default XSLT
123 file. When the name attribute is set, this XSLT file is used
124 when using the --xslt-name option.
125 <arguments/>
127 All variable options the defined XSLT template needs must be
128 configured in separate <arg/> tags inside this tag.
129 <arg section="recipe" type="{string|bool}">
131 Each option individually is defined by <arg/> tags. The sec‐
132 tion and type attributes are mandatory. Currently only the
133 recipe section is supported. The type attribute defines the
134 type of argument. If the type attribute is set to bool it
135 will define a command line argument which takes no arguments.
136 If this argument is given to bkr workflow-xslt, it will re‐
137 sult in the tag or attribute value being set to true. The
138 optional attribute is optional. If set to 1 it will make
139 this argument purely optional. The default is to require the
140 argument.
141 <name short="{short arg}"/>
143 The <name/> defines the short and long option names. The
144 short attribute is mandatory and can only be one character.
145 If the same argument name is defined several times, the last
146 defined argument will override all other conflicting argu‐
147 ments.
148 <tag type="{attribute|value|list}" [attrname="{Attribute name}"]
150 [element_tag="{list element tag name}"]/>
151 This tag defines which XML tag name the internal XML tag the
152 option value will be stored under. The type attribute is
153 mandatory and can be either attribute, value or list. When
154 set to value the option value given at the command line of
155 bkr workflow-xslt will be embraced by the defined tag name.
156 If type is set to attribute the option value from the command
157 line will be placed as an attribute value to the defined XML
158 tag name. When using attribute the attrname attribute is
159 mandatory. This attribute defines the attribute name to be
160 used in the internal XML. If type is set to list, it will
161 create a list of XML tags based on the value string. The de‐
162 fault value for the children of the tag name is 'value', un‐
163 less the element_tag is set. The value string will be split
164 into separate tokens using comma (,) as the separator.
165 <default/>
167 This tag is optional. It will set a default value if this op‐
168 tion is not used on the command line.
169 <description/>
171 This tag is used for the --help screen, describing the com‐
172 mand line option to bkr workflow-xslt.
173 <metavar/>
175 This is used for the --help screen as well. This is used as a
176 substitute for the variable contents, purely for. To make it
177 obvious, it is recommended to put use capital letters.
178 Example
180 Save the contents below as example-job.xml:
181 <?xml version="1.0"?>
183 <jobConfig>
184 <name>Example Job</name>
185 <xslt>example.xsl</xslt>
186 <arguments>
187 <arg section="recipe" type="string">
188 <name short="i">id</name>
189 <metavar>INTEGER</metavar>
190 <tag type="attribute" attrname="version">name</tag>
191 <description>Unique numeric ID</description>
192 </arg>
193 <arg section="recipe" type="string">
194 <name short="n">name</name>
195 <metavar>FULL-NAME</metavar>
196 <tag type="value">name</tag>
197 <description>Full name</description>
198 </arg>
199 <arg section="recipe" type="string" optional="1">
200 <name short="g">group</name>
201 <metavar>GROUP-NAME</metavar>
202 <tag type="attribute" attrname="group">name</tag>
203 <description>Group identifier</description>
204 </arg>
205 <arg section="recipe" type="string" optional="1">
206 <name>phone-numbers</name>
207 <metavar>PHONE\-NUMBERS</metavar>
208 <tag type="list" element_tag="number">phones</tag>
209 <description>List of phone numbers, comma separated</description>
210 </arg>
211 </arguments>
212 </jobConfig>
213 Save this dummy XSLT file as example.xsl:
215 <?xml version="1.0"?>
217 <xsl:stylesheet version="1.0"
218 xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
219 <xsl:output method="xml" version="1.0"
220 encoding="UTF-8" indent="yes"/>
221 </xsl:stylesheet>
222 Run from a terminal the following command:
224 $ bkr workflow-xslt --dry-run --job-xml example-job.xml \\
226 --save-internal-xml example.xml \\
227 -i 99 -n "Example" -g "Group1" --phone-numbers 123,456,789
228 ----------------------------------------------------
229 Generating Beaker XML
230 Job config: example-job.xml
231 XSLT template: example.xsl
232 Job name: Example Job
233 Whiteboard: None
234 Job arguments:
235 - group: Group1
236 - id: 99
237 - name: Example
238 ----------------------------------------------------
239 $ cat example.xml
240 <?xml version="1.0" encoding="UTF-8"?>
241 <submit>
242 <whiteboard/>
243 <recipe>
244 <phones>
245 <number>123</number>
246 <number>456</number>
247 <number>789</number>
248 </phones>
249 <name group="Group1" version="99">Example</name>
250 </recipe>
251 </submit>
252 Setting defaults
254 It is possible to define defaults in a separate file. This is useful
255 if you often use the same Job Configuration or have other arguments
256 which do not change so often. Two files are attempted read upon
257 startup: ~/.beaker_client/bks-defaults and ./bks-defaults.
258 The bks-defaults file is an INI-styled configuration file. It requires
260 a [defaults] section which has one parameter, jobxml.
261 You can set individual default values depending on which Job XML Con‐
263 figuration you are using. Use the Job XML Configuration filename as the
264 section name. The parameters uses the long options of the Job Configu‐
265 ration to define the default values.
266 Example
268 [defaults]
269 jobxml: example-job.xml
270 [example-job.xml]
272 group: Group1
273 Default profiles
275 It is possible to define several sets of default values for the same
276 Job XML Configuration. This is used by appending :<profilename> to the
277 section name. Notice the 'colon'.
278 Example
280 This builds upon the example above:
281 [example-job.xml:setup2]
283 group: Group2b
284 To run the example in the Example section above, execute:
286 $ bkr workflow-xslt --dry-run --save-internal-xml example.xml \\
288 -i 99 -n "Example"
289 This will use the value Group1 as a default value in the group attri‐
291 bute. If you instead do this:
292 $ bkr workflow-xslt --dry-run --profile setup2 \\
294 --save-internal-xml example.xml \\
295 -i 99 -n "Example"
296 the generated example.xml will have the value Group2b as a default
298 value in the group attribute.
299
301 David Sommerseth <davids@redhat.com>
302
304 2013-2023 Red Hat, Inc.
30528.3 Nov 17, 2023 BKR-WORKFLOW-XSLT(1)