1BKR-WORKFLOW-XSLT(1)                Beaker                BKR-WORKFLOW-XSLT(1)
2
3
4

NAME

6       bkr-workflow-xslt - XSLT-based Beaker job generator
7

SYNOPSIS

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
16
17       Job-specific options are defined in the Job Configuration XML, and will
18       be described with --help.
19

DESCRIPTION

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
26   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
31       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
35       --defaults <filename>
36              Adds  more  default values in addition to what may be configured
37              in ~/.beaker-client/bks-defaults and ./bks-defaults.
38
39       --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
44       --job-xml <filename>
45              Defines which Job XML Configuration file to load. This  argument
46              is mandatory, unless configured in a defaults file.
47
48       --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
54       --wait This will cause the bkr workflow-xslt operation to wait for  the
55              Beaker job to complete before exiting.
56
57   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
62       --xslt-override <filename>
63              This  will  override the configured XSLT file defined in the Job
64              Configuration.
65
66       -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
72       -W <text>, --whiteboard <text>
73              Adds the given <text> as a text for the Beaker job whiteboard.
74
75       --save-xml <filename>
76              Saves the generated Beaker Job XML to the given <filename>.
77
78       --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
82   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
90       It will not be explained how to write the needed XSLT documents in this
91       manual.
92
93   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
111   Tag descriptions
112          <JobConfig/>
113                 The XML root node must be a <JobConfig/> tag.
114
115          <name/>
116                 The first <name/> in <JobConfig/> is a plain and short string
117                 describing the purpose of this Job Configuration.
118
119          <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
126          <arguments/>
127                 All  variable options the defined XSLT template needs must be
128                 configured in separate <arg/> tags inside this tag.
129
130          <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
142          <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
149          <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
166          <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
170          <description/>
171                 This tag is used for the --help screen, describing  the  com‐
172                 mand line option to bkr workflow-xslt.
173
174          <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
179   Example
180       Save the contents below as example-job.xml:
181
182          <?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
214       Save this dummy XSLT file as example.xsl:
215
216          <?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
223       Run from a terminal the following command:
224
225          $ 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
253   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
259       The bks-defaults file is an INI-styled configuration file.  It requires
260       a [defaults] section which has one parameter, jobxml.
261
262       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
267   Example
268          [defaults]
269          jobxml: example-job.xml
270
271          [example-job.xml]
272          group: Group1
273
274   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
279   Example
280       This builds upon the example above:
281
282          [example-job.xml:setup2]
283          group: Group2b
284
285       To run the example in the Example section above, execute:
286
287          $ bkr workflow-xslt --dry-run --save-internal-xml example.xml \\
288              -i 99 -n "Example"
289
290       This will use the value Group1 as a default value in the  group  attri‐
291       bute. If you instead do this:
292
293          $ bkr workflow-xslt --dry-run --profile setup2 \\
294              --save-internal-xml example.xml \\
295              -i 99 -n "Example"
296
297       the  generated  example.xml  will  have  the value Group2b as a default
298       value in the group attribute.
299

AUTHOR

301       David Sommerseth <davids@redhat.com>
302
304       2013-2023 Red Hat, Inc.
305
306
307
308
30928.3                             Nov 17, 2023             BKR-WORKFLOW-XSLT(1)
Impressum