generated 1.5.1 release user documentation

Author: klehman-rally

doc/build/doctrees/environment.pickle

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 710a2f9f03546537ef3561c438ba8030
+config: c8054da9968b3e8b26a06982d918e387
 tags: 645f666f9bcd5a90fca523b33c5a78b7

doc/build/doctrees/index.doctree

@@ -268,8 +268,8 @@ Rally
 
 To instantiate a Rally object, you'll need to provide these arguments:
         * **server**    usually rally1.rallydev.com unless you are using an OnPrem version
-        * **user**      AgileCentral UserName
-        * **password**  AgileCentral password for the given user
+        * **user**      Rally UserName
+        * **password**  Rally password for the given user
 
     either in this specific order or as keyword arguments.
 
@@ -281,8 +281,8 @@ To instantiate a Rally object, you'll need to provide these arguments:
 
     You can optionally specify the following as keyword arguments:
         * apikey      (alternate credential specification)
-        * workspace   (name of the AgileCentral workspace)
-        * project     (name of the AgileCentral project)
+        * workspace   (name of the Rally workspace)
+        * project     (name of the Rally project)
         * verify_ssl_cert  (True or False, default is True)
         * warn     (True or False, default is True) 
                     Controls whether a warning is issued if no project is specified
@@ -307,7 +307,7 @@ To instantiate a Rally object, you'll need to provide these arguments:
                    For subscriptions with a small to moderate number of workspaces (up to a few dozen),
                    the performance savings will be relatively minor when using isolated_workspace=True
                    vs. isolated_workspace=False.  However, for subscriptions with a large number of
-                   workspaces, using isolated_workspace=False results in a request to AgileCentral
+                   workspaces, using isolated_workspace=False results in a request to Rally
                    for each workspace, which can result in a noticeable lag before the instantiation
                    statement returns a ready-for-use Rally instance.
         * headers  dict with entries for name, vendor, version of software/integration using this package.
@@ -707,11 +707,11 @@ pyral.Rally experimental convenience methods
 .. warning:: 
 
         This method only works when the collection attribute on the target_item is Modifiable.
-        Consult the AgileCentral WSAPI documentation for the target_item attributes to see whether
+        Consult the Rally WSAPI documentation for the target_item attributes to see whether
         the attribute of interest has a notation of 'Collection Modifiable  yes'.  If there is no 
         'Colletion Modifiable' notation or the value for that is 'no', then use of this method 
         should not be attempted.
-        At this time, the AgileCentral WSAPI schema endpoint does not include information about 
+        At this time, the Rally WSAPI schema endpoint does not include information about 
         'Collection Modifiable' for any of the attributes, you'll have to consult the documentation.
 
 .. method:: dropCollectionItems(target_item, collection_items)

doc/build/doctrees/interface.doctree

@@ -17,14 +17,9 @@ For more information on how workspaces and projects in Rally are set up and conf
 the Rally documentation available via the 'Help' link from the Rally landing page 
 displayed after your initial login.
 
-.. warning::
-
-   As of the 1.0.0 version of **pyral** (the Python toolkit for the Rally REST API),
-   the implementation works with Rally WSAPI 2.0 and is **not** backward compatible 
-   with Rally WSAPI 1.x.
-
 .. _Rally: http://www.rallydev.com
 
+
 Simple Use
 ==========
 
@@ -42,11 +37,11 @@ Here's a prototype of simple use of the **pyral** package.::
     response = rally.get('Release', fetch="Project,Name,ReleaseStartDate,ReleaseDate",
                          order="ReleaseDate")
 
-    for release in response:
+    for rls in response:
         rlsStart = rls.ReleaseStartDate.split('T')[0]  # just need the date part
         rlsDate  = rls.ReleaseDate.split('T')[0]       # ditto
-        print "%-6.6s  %-16.16s   %s  -->  %s" % \
-              (rls.Project.Name, rls.Name, rlsStart, rlsDate)
+        print("%-6.6s  %-16.16s   %s  -->  %s" % \
+              (rls.Project.Name, rls.Name, rlsStart, rlsDate))
 
 
 Rally Data Model
@@ -72,15 +67,19 @@ But, it is not limited to those as it is very possible to view/operate on other
 entities such as Workspace, Project, UserProfile, Release, Iteration, TestCaseResult, 
 TestFolder, Tag and others.
 
+
 Full CRUD capability
 ====================
 
 The Python toolkit for the Rally REST API offers the full spectrum of CRUD capabilities that the 
-credentials supplied for your subscription/workspace/project permit.  While the Rally
-REST API itself doesn't support bulk operations, there are example usages of 
-**pyral** that you can adapt to offer the end-user or scriptwriter the
+credentials supplied for your subscription/workspace/project permit.  Rally
+REST API did not originally support bulk operations when this toolkit was written.
+Since the 2017/2018 timeframe the Rally REST WSAPI has provided some bulk operations, but this
+toolkit doesn't use those or provide access to them.
+There are example usages of **pyral** that you can adapt to offer the end-user or scriptwriter the
 capability of specifying ranges of identifiers of artifacts for querying/updating/deleting.
 
+
 Rally Introspection
 ===================
 
@@ -89,12 +88,14 @@ and the attributes associated with each type.  You can also use **pyral** capabi
 to obtain the list of allowed values for Rally type attributes that have a pre-allocated
 list of values.
 
+
+
 Queries and Results
 ===================
 
 The Rally REST API has two interesting characteristics that the Python toolkit for the Rally REST API 
 insulates the scriptwriter from having to deal with.  The first is that the Rally REST API
-has a maximum "pagesize" of 200 records to limit volume and prevent unwarranted hijacking of the
+has a maximum "pagesize" to limit volume and prevent unwarranted hijacking of the
 Rally SaaS servers.  But, having script writers deal with this directly to obtain further 
 "pages" would be burdensome and out of character with the mainstream of Python interfaces
 to SaaS services.  The Python toolkit for the Rally REST API (**pyral**) takes care 
@@ -104,19 +105,31 @@ requests on the Rally server.
 
 The second characteristic is that the Rally REST API for some queries and results returns
 not a scalar value but a reference to yet another entity in the Rally system.  A Project or
-a Release are good examples of these.  Say your query specified the retrieval of some UserStories,
+a Release are good examples of these.  Say your query specified the retrieval of some Stories,
 and you listed the Project as a field to return with these results.  From an end-user perspective,
 seeing the project name as opposed to an URL with an ObjectID value would be far more intuitive.
 
 The Python toolkit for the Rally REST API offers this sort of intuitive behavior by "chasing" the URL 
 to obtain the more human friendly and intuitive information for display.  This sort of behavior is 
-also present in so-called "lazy-evaluation" of entity attributes that may be containers as well
-as references.  The scriptwriter merely has to refer to the attribute with the dot ('.') notation
-and **pyral** takes care of the communication with the Rally server 
+also present in so-called "lazy-evaluation" of entity attributes that may be containers (collections)
+ as well as references.  The scriptwriter merely has to refer to the attribute with the
+ dot ('.') notation and **pyral** takes care of the communication with the Rally server
 to obtain the value.  There are two significant advantages to this, one being lightening 
 the load on the server with the reduction of data returned and the other being easy and 
 intuitive attribute access syntax.
 
+The query relational operators that pyral supports are: 
+   =  !=  >  <  >=  <=  contains  !contains  in  !in  between  !between
+The contains and !contains relational operators a helpful in expressing a condition where 
+you are looking for a field that does (or does not) contain a specific substring.
+For example 'Name contains "Prior Art"' or 'ThermalPhase !contains "hot lava"'.
+The in and !in relational operators are commonly used for expressions involving subsets of a
+finite set of values.  For example 'Severity in High, Burning, Explosive' or 'Priority !in Moribund, Meh'.
+The between and !between relation operators are commonly used for expressions involving date ranges.
+For example 'CreatedDate between 2018 and 2022' or 'LastUpdated !between 2021-09-22T00:00:00.000Z and 2021-09-22T07:59:59.999Z'.
+
+
+
 Custom Fields
 =============
 
@@ -127,11 +140,21 @@ has a DisplayName of 'Burnt Offerings Index' you can use the String of 'BurntOff
 a fetch clause or a query clause or refer to the field directly on an artifact 
 as artifact.BurntOfferingsIndex.
 
+
+PortfolioItem tips
+==================
+Rally has 4 standard PortfolioItem sub-types (Theme, Strategy, Initiative, and Feature).
+In this toolkit, for the primary methods (get, create, update, delete), you must supply a
+entity name (eg, 'Story', 'Defect', 'Task', etc). For a PortfolioItem sub-type you may
+specify just the name of the sub-type, ie., 'Feature' or you may fully qualify it as
+'PortfolioItem/Feature'.
+
+
 Introduction of Dyna-Types
 ==========================
 
-As of Rally WebServices API 1.37, Rally has introduced a modification of their data model, which
-is termed dyna-types.  This modification offers a means of establishing and using a parent type
+Prior to the release of Rally WebServices API v2.0, Rally introduced a modification of their data model, 
+which is termed dyna-types.  This modification offers a means of establishing and using a parent type
 and defining sub-types of that parent.  The PortfolioItem type is now an "abstract" type from which
 there are some pre-defined sub-types (Theme, Strategy, Initiative, Feature).  
 By convention, the preferred way to identify a PortfolioItem sub-type is via slashed 
@@ -152,4 +175,10 @@ here is that if you don't use PortfolioItem instances with pyral, you don't have
 If you use PortfolioItem instances with pyral or you've defined your own "abstract" 
 parent types and specific sub-types thereof, you are strongly encouraged to use the slashed specification 
 to avoid ambiguity in identifying the Rally entity type.
+
+In the event your organization has created a sub-type with the same name as a standard Rally entity
+(eg, 'Project', 'Release', 'Milestone', etc.) you will be unable to use this toolkit to access those items.
+There will be no consideration given to supporting any custom PortfolioItem sub-type whose name conflicts 
+with a Rally standard entity name.
 
+