.. productionHandler.py command line interface documentation

productionHandler.py (CLI)
=============================================

.. automodule::productionHandler

Syntax
++++++++++++++++++++++++++++++++++++++++++

The productionHandler.py script has the following usage: ::

productionHandler.py
Version: 1.0b Build: 2011042001
Framework Version: 1.0b Build: 2011042001

Usage:

productionHandler --importFile=/file.xml --productionID=10
productionHandler --exportFile=/production_10.xml --productionID=10
productionHandler --importFile=/file.xml --createProduction
productionHandler --configFile=/etc/my.conf --importFile=file.xml
productionHandler [option]

Options:
-h, --help Displays this help message
-v, --version Display version number
-c pathtofile, Utilize pathtofile for configuration parameters.
--configFile=pathtofile

Configuration
++++++++++++++++++++++++++++++++++++++++++
By default, the productionHandler.py script utilizes the main
transmogrifier.conf file found at /usr/local/etc. In this file,
productionBuilder will queue off of a number of parameters configured under
the ``[ProductionHandler]`` Section.

The following shows an example productionBuilder configuration: ::

[ProductionHandler]
membersField=Members
membershipKey=Title
missingMembersKey=Missing Members
exportFields=Title,Description
newProductionMDset=pa_production_show
tempProductionMDset=pa_production_show
containerProductionTitle=New Projects
containerProductionMDSet=pa_production_organizer
debug=False

As shown above, there are four specific settings, all read in from the
``[ProductionHandler]`` section, which we will read in from this file.

membersField
Specify the field which contains our membership value, this should be a comma-
separated value string

membershipKey
Specifies the field key used for membership. This can be any Final Cut Server
field name that has an asset-unique value. I.E.: ``Title`` or ``Asset ID``

.. note:
Because this field uses a comma delimeter, you will need to avoid using
comma's in your membership key field; use of the ``Asset ID`` field is
recommended, but other fields, such as ``Title`` can be used if you have
solid naming convention.

missingMembersKey
Specifies the field name used for any missing members, if desired.

exportFields
Specify the fields to include in our XML output when using the ``--exportFile``
option. This should be a comma separated list of field names.

newProductionMDset
Specify the metadata set to use if we are creating a production.

tempProductionMDset
Specify the metadata set to use if we are modifying production membership. This
exists primarily due to limitations with ``fcsvr_client``'s inability to remove
an asset from a production directly. If a temporary production is created to remove
an asset from a production, it will use the metadata set defined here. The
new production will be deleted after the operation finishes.

containerProductionTitle
If specified, any new productions will be nested under a production matching
this name. If this setting is defined and no such production exists, a new
production will be created based on the ``containerProductionMDSet`` value

containerProductionMDSet
This option designates the metadata set that a container production will be
created with, if none exists

debug
Specify whether productionHandler.py will output debug information. Leave
this option out if you want ``[GLOBAL]`` debug to apply.

.. note:
If desired, an alternate configuration file can be used through
the ``--configFile=`` parameter.

Example Usage
++++++++++++++++++++++++++++++++++++++++++
The productionHandler.py script has fairly limited scope in regards to command
line options, we will simply use it to export or import a production.

>>> productionHandler.py --exportFile='/tmp/project_10.xml' --productionID=10

In the above usage, our script will first lookup information for the provided
production (production with ID 10). Provided that the production exists,
it will export an XML file to the location ``/tmp/project_10.xml`` This export
file will contain an additional field, designated by the setting ``membersField``.
This field will contain a string of comma separated values, one for each asset
member, extracted from the field designated by our ``membershipKey`` field.

Using the above example, this XML file will contain output for fields ``Title``
and ``Description``, and will have an additional field ``Members`` which contains
the string: ``my asset 1,my asset 2``; where ``my asset 1`` and ``my asset 2``
are the Title`s of the 2 asset members of our production. If we change the value
of our setting ``membershipKey`` to ``Asset ID``, the ``Members`` string would
have the value: ``49,50``, representing the unique asset ID's of the production's
members.

>>> productionHandler.py --importFile='/tmp/project_10.xml' --productionID=10 --createProduction

In the above usage, our script will first lookup information for the provided
production (production with ID 10). Provided that the production exists,
it will import all values specified in the provided XML file. This will include
all fields designated in the file. In addition to this, we will lookup an
additional field, designated by the setting ``membersField``. Just like in
our export scenario, this field will contain a string of comma separated values,
one for each asset member, extracted from the field designated by our
``membershipKey`` field. Any assets not included in this string will be removed
from the production. In the event that an entry references a non-existant asset,
the asset's entry will be recorded in the ``missingMembersKey`` field. Values
specified in this field will be appended to our membership values on export,
this enables us to do non-destructive pass-through between two systems, preventing
assets not yet ingested into FCS from being removed from the production. The
``--createProduction`` flag designates that if the production specified in the
provided XML file cannot be found, one will be created and metadata and membership
will be imported.