Usage
=====

Overview
~~~~~~~~

The intended use for the Ticket Generator is to generate a set of tickets to
keep track of progress when deploying a Member Node. The included template and
value files contain the information required for generating these tickets.

By creating new template and value files, the Ticket Generator can be used for
generating tickets for any purpose.

To insert a value from the value file into the template, insert a string on the
form ``{{level1.level2}}``. For instance, in the value file for MN deployments,
there is ``Content`` section with a ``VolumeGB`` value that is set to ``20``.
Inserting the string ``{{Content.VolumeGB}}`` in the template will cause the
value ``20`` to appear in that location.

The Ticket Generator requires an API key for the account under which the the
tickets will be generated.


Check the install
~~~~~~~~~~~~~~~~~

Check that the utility has been correctly installed. Open a command prompt on
Windows or a shell on Linux and type::

  ticketgen

The following help message should be returned::

  Usage: C:\Python2f\Scripts\ticketgen-script.py <Redmine API Access Key> <Story #> <MN TAG>
  
  Options:
    -h, --help            show this help message and exit
    --redmine-url=REDMINE_URL
                          URL of Redmine server
    --project=REDMINE_PROJECT
                          Redmine project under which tickets will be created
    --tracker=REDMINE_TRACKER
                          Redmine tracker to use for tickets
    --version=REDMINE_VERSION
                          Version of Redmine server (API changes between some
                          versions)
    --template-path=TICKET_TEMPLATE_PATH
                          Path to YAML ticket template file
    --verbose            


Get your Redmine API Access Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The API Access Key is essentially a username and password combined into a single
string of hexadecimal numbers.

- Log into Redmine.
- Select "My account"
- In the default layout, locate the "My account" panel on the right.
- Click Show under API Access Key.
- Copy the Access Key to the clipboard.


Create the deployment tickets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In Redmine, locate the story to which the deployment tickets should be added and
note its number. The default project is ``Member Nodes`` (ID = mns). If the
story is in another project, look at the URL to find its ID. There will be a
section, ``/projects/abc/``, where ``abc`` is the ID. Use ``--project=ID`` to
set the project.

Decide on a tag for the MN. 3-5 upper case characters is best.

Then run the following command::

  ticketgen <Your Redmine API Access Key> <Story #> <MN Tag>

E.g.::

  ticketgen 345a908f3450235a49348fa293f84a5a0a4598af 1234 MYMN2

A series of "Starting HTTPS Connection" messages should be displayed, followed
by a "All tickets successfully created" message.


Editing the template
~~~~~~~~~~~~~~~~~~~~

The template is a yaml file. Under Windows, it resides at
``C:\Python27\Lib\site-packages\d1_ticket_generator\mn_deployment_template.yaml``.


Troubleshooting
===============

Error::

  redmine.exceptions.ValidationError: Resource already exists

Ensure that the Redmine API Access Key is correct.

The project (set with ``--project``) is the ID for the project, not the name
that is displayed in the drop down box in Redmine. To find the ID, open a page
in the project and look at the URL. There will be a section, ``/projects/abc/``,
where ``abc`` is the project ID.