Allow id's for different templates to follow same naming

It is useful to allow templates that can have different settings for
slightly different jobs while still following the same naming scheme.
Additionally this allows for shorter and more descriptive names to be
used without the confusion of the variable placeholders, and for the
resulting job names from the templates to be altered without needing to
update all references.

Change-Id: Idc3517b44873210a33f988ebff449ea2ed567054

doc/source/definition.rst

@@ -70,6 +70,10 @@ itself (e.g. ``{name}-unit-tests`` in the above example) will be
 substituted in. This is useful in cases where you need to trace a job
 back to its template.
 
+Sometimes it is useful to have the same job name format used even
+where the template contents may vary. `Ids` provide a mechanism to
+support such use cases.
+
 .. _project:
 
 Project
@@ -262,6 +266,27 @@ always use ``{{`` to achieve a literal ``{``.  A generic builder will need
 to consider the correct quoting based on its use of parameters.
 
 
+.. _ids:
+
+Item ID's
+^^^^^^^^^
+
+It's possible to assign an `id` to any of the blocks and then use that
+to reference it instead of the name. This has two primary functions:
+
+* A unique identifier where you wish to use the same naming format for
+  multiple templates. This allows to follow a naming scheme while
+  still using multiple templates to handle subtle variables in job
+  requirements.
+* Provides a simpler name for a `job-template` where you have multiple
+  variables in the name and don't wish to have to include this information
+  in every use. This also allows changing the template output name without
+  impacting references.
+
+Example:
+
+.. literalinclude::  /../../tests/yamlparser/fixtures/template_ids.yaml
+
 .. _raw:
 
 Raw config

jenkins_jobs/parser.py

@@ -91,11 +91,13 @@ class YamlParser(object):
                     raise JenkinsJobsException("Syntax error, for item "
                                                "named '{0}'. Missing indent?"
                                                .format(n))
-                name = dfn['name']
-                if name in group:
-                    self._handle_dups("Duplicate entry found in '{0}: '{1}' "
-                                      "already defined".format(fp.name, name))
-                group[name] = dfn
+                # allow any entry to specify an id that can also be used
+                id = dfn.get('id', dfn['name'])
+                if id in group:
+                    self._handle_dups(
+                        "Duplicate entry found in '{0}: '{1}' already "
+                        "defined".format(fp.name, id))
+                group[id] = dfn
                 self.data[cls] = group
 
     def parse(self, fn):

tests/yamlparser/fixtures/template_ids.xml

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <actions/>
+  <description>&lt;!-- Managed by Jenkins Job Builder --&gt;</description>
+  <keepDependencies>false</keepDependencies>
+  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
+  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
+  <concurrentBuild>false</concurrentBuild>
+  <canRoam>true</canRoam>
+  <properties/>
+  <scm class="hudson.scm.NullSCM"/>
+  <builders>
+    <hudson.tasks.Shell>
+      <command>echo &quot;Template name: template-test-ids-{num}-{type}&quot;
+echo &quot;Job name: template-test-ids-1-periodic&quot;
+echo &quot;Hello World&quot;
+</command>
+    </hudson.tasks.Shell>
+  </builders>
+  <publishers/>
+  <buildWrappers/>
+</project>
+
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <actions/>
+  <description>&lt;!-- Managed by Jenkins Job Builder --&gt;</description>
+  <keepDependencies>false</keepDependencies>
+  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
+  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
+  <concurrentBuild>false</concurrentBuild>
+  <canRoam>true</canRoam>
+  <properties/>
+  <scm class="hudson.scm.NullSCM"/>
+  <builders>
+    <hudson.tasks.Shell>
+      <command>echo &quot;Template name: template-test-ids-{num}-{type}&quot;
+echo &quot;Job name: template-test-ids-2-canary&quot;
+</command>
+    </hudson.tasks.Shell>
+    <hudson.tasks.Shell>
+      <command>echo &quot;Goodbye World&quot;
+</command>
+    </hudson.tasks.Shell>
+  </builders>
+  <publishers/>
+  <buildWrappers/>
+</project>

tests/yamlparser/fixtures/template_ids.yaml

@@ -0,0 +1,31 @@
+- project:
+    name: test_template_id
+    jobs:
+        - 'simple-template':
+            test_var: Hello World
+            type: periodic
+            num: 1
+        - 'not-as-simple-template':
+            test_var: Goodbye World
+            type: canary
+            num: 2
+
+- job-template:
+    name: 'template-test-ids-{num}-{type}'
+    id: simple-template
+    builders:
+      - shell: |
+         echo "Template name: {template-name}"
+         echo "Job name: template-test-ids-{num}-{type}"
+         echo "{test_var}"
+
+- job-template:
+    name: 'template-test-ids-{num}-{type}'
+    id: not-as-simple-template
+    builders:
+      - shell: |
+         echo "Template name: {template-name}"
+         echo "Job name: template-test-ids-{num}-{type}"
+      - shell: |
+         echo "{test_var}"
+