Rally Software

Expand all | Collapse all

API to Rally

Jump to Best Answer
  • 1.  API to Rally

    Posted 03-27-2018 11:07 AM

    I am looking for a method to retrieve rally event timestamps (MVP). The objective is to

    1) pick a begin and end date

    2) retrieve CUMULATIVE time a story is blocked

    2a) by story type

    2b) with "reason blocked." (likely multiple reasons as story progresses)

    3) export to file

    3a) excel file (preferred)

    3b) export to database file - pick one - (not great)

    3c) export to CSV - I just need to parse - (least desirable)



    If all that can be retrieved is timestamps (MVP) I can live with that. 1 through 3c MVP -> end state 

  • 2.  Re:  API to Rally

    Posted 03-27-2018 05:22 PM

    Hi Walt,

    This is a very nice question, I'm not sure it can be easily done. 


    The main challenge here is that the Block/Unblock events are recorded to the Revision History of each artifact. You will need to read the Revision History, filtered by the start and end dates , then from the partial revision history that meets the time frame you will need to filter by block and unblock events and calculate the cumulative 'block time' this way. 


    At that point you may continue to group by 'story type' and so forth.


    From the API perspective: 

    Artifact is the top-object for all artifacts. Artifact is linked with 'Revision History' so this way all artifacts have their private revision history. You can find more on that in our online help for WSAPI: https://rally1.rallydev.com/slm/doc/webservice/   (look at Artifact, see the Revision History field.  Also, see the Revision History object and see the collection of 'Revision' objects it has. 


    We don't have a sample that puts all of that together , but this should be the way to approach it at least from an API standpoint.


    Please let us know if helpful and if further questions.




  • 3.  Re:  API to Rally

    Posted 03-28-2018 12:23 PM


    Thanks for rapid reply!  I already knew it wasn’t going to be easy once I read the LookBack API documentation.  You just confirmed. However, it seems if I can retrieve the artifact revision history, then I can write the code to do all the logic.  That retrieval is where the documentation lets me down.  Can you give me a sample query where the revision history can be accessed.  This seems to be the first PoC. Then I would need to extend the query for time basis, the artifacts by project id, then story type. I have someone on my team that can construct the query in general, but learning the syntax always seems to be the issue that slows things down.  If you could provide a couple of “proper syntax” queries. That would be a great help. In particular, I could not determine how to get the workspace and project ID. I’ll worry about the front end later.


    Is there anyone you can point me to that I could work with more closely. Essentially the whole thing is writing an app.


    Walt Dietz

    Agile Coach - Affinity Products

    302 457 3795


    “If you need to complain - I will empathize.  If you want to complain - I will work with you to create a solution. That is what a coach does.”

    Me (Servant Leader)

  • 4.  Re:  API to Rally
    Best Answer

    Posted 03-28-2018 01:22 AM

    Hi Walt,

    I was looking more into this. Working with the Lookback API will work better than with the WSAPI. However, still much uneasy, probably doable though.


    I advise you go over the documentation of the Lookback API. There is a 'Try It Now' section where you can try a few things: https://rally1.rallydev.com/analytics/doc/#/tryitnow 


    Specifically notice example #6 in that page which is attempted to calculate time an artifact was in a certain state.


    Here is a query for a user story I had with an OID: 208602609512 for a condition where it's Blocked is 'true' and previously was 'false' (which means it turned to Blocked). This is still not good enough because:


    - This only returns the last time stamp this condition was met. So, if the story went into a blocked state a few times then this will only get you the last time it happened (latest revision). Even still in order to calculate the length of time in that condition you will need to offset that timestamp by 'today' (it mentions that in that URL).


    Example (using POST):



    {find:{ "ObjectID": 208602609512, "Blocked": true, "_PreviousValues.Blocked": { "Blocked": false }},fields:[ 'Name', 'Blocked', '_ValidFrom', '_ValidTo', '_PreviousValues.Blocked' ],start:0,pagesize:10,removeUnauthorizedSnapshots:true}



    All in all, much not easy. What you'll need to do is run a series of such queries to find all the time stamps of the artifacts you're interested with and toggle between the state (blocked vs. non-blocked). You will need to run the math calculation to offset these timestamps by 'today' and then start aggregating them per your requirement to achieve the cumulative time you are asking for.



    I hope it helps. Let me know if that helped and if you are familiar with the Lookback API to give that a try.



  • 5.  Re:  API to Rally

    Posted 03-28-2018 01:38 AM

    Hi Walt,


    I am also including for you two text files, please see the two attachments. These are two examples of working with the Lookback API to try to retrieve what I mentioned earlier.

    One file has a request for a full revision history of the user story. You can see the response and that it went in and out of Blocked a few times. The second file is what I had mentioned previously where I am receiving the last entry condition into a Blocked state.


    You will see how raw the responses are and as mentioned, what needs to be done is use similar queries per your needs and then make the necessary calculations to prepare the outcome that you're asking for including aggregating the times of all these events to end up with what you need.



  • 6.  Re:  API to Rally

    Posted 03-28-2018 12:31 PM

    This is very helpful if only to show the amount of effort involved.  I read the lookback API user manual yesterday and my thinking follows what you just said.  But I also thought this might be possible with a snapshot approach.  But I think that would be a very lengthy query.  Your thoughts?


    Walt Dietz

    Agile Coach - Affinity Products

    302 457 3795


    “If you need to complain - I will empathize.  If you want to complain - I will work with you to create a solution. That is what a coach does.”

    Me (Servant Leader)

  • 7.  Re:  API to Rally

    Posted 03-28-2018 01:18 PM

    Hi Walt,

    So, glad you saw the two samples I provided which should form the basis for this type of development. I'd say you're correct about compressing the snapshots of your queries only to the Blocked field only so that you can eliminate so much else which may happen with the user stories which isn't related to Blocked/Not-Blocked/Reason and not relevant here, so yes, you're right about that.


    You mentioned you didn't know how to get the workspaceID or the projectID:

    For the 'Try it out' section in the Lookback API docs you don't really need it cause you can select your workspace from the dropdown. However, in general you probably want to use the WSAPI to retrieve all of your workspace, project and also user stories Object IDs , then use them with the Lookback API calls.


    My take on your overall requirement is that you would like to get the cumulative time stories were blocked within a certain time period where each story might have been blocked more than once (meaning blocked, unblocked , then blocked again ... ) during that time.


    So you need to first find all stories that were blocked at all during that time period. 

    Then, for each such story you need to go along my examples, use the Lookback API to find all times they entered block status, each time they got out of block status and compute/add the total time of that story being in blocked status - then you shall add it to the total cumulative blocked time of all stories in that time period.


    The most straight forward way to do that is to get the full revision history (compressed for snapshots where Blocked was changed) and then analyzing it, and computing the _ValidFrom and _ValidTo of the instances where the story is blocked. Within that computing you shall offset the timestamps so that your calculation is accurate.


    An alternative approach could be similar to the second file I included where you query the Lookback API for specific instances of Blocked changing by querying when it enters its state based on previous state. However, it's a longer approach overall, will require more queries and your code will still need to do the computing, so I don't see how this approach is better, but it's a way to get it done as well.


    If you have further more specific questions (perhaps about my provided sample queries) on that then let me know. It also sounded as if you are considering a consultant help. If so, please let me know and I'll have a manager follow up with you on that.


    With all that said, I also would like to offer that you post a formal Idea to enhance the product and offer such or similar report as part of the product. Please let me know if you would like to consider that and if you know where/how to post it.




  • 8.  Re:  API to Rally

    Posted 03-28-2018 02:03 PM

    Sagi, your engagement on my issue is exemplary, thank you.  Yes I would like for it to be a suggested app / report for Rally. Where do I do that and what would be the wording that makes sense to those evaluating the idea. And yes I am looking for a consultant, but I have no budget.  Unless consultation (app development) is part of the Bank of America subscription I’ll have to continue to work with the community.  The recent hackathon produced “estimation calibration” which I find very useful. How would I add my idea to the potential hackathon objectives?


    Walt Dietz

    Agile Coach - Affinity Products

    302 457 3795


    “If you need to complain - I will empathize.  If you want to complain - I will work with you to create a solution. That is what a coach does.”

    Me (Servant Leader)

  • 9.  Re:  API to Rally

    Posted 03-28-2018 02:39 PM

    Hi Walt,


    In our community page you should see an icon for "Ideas" , it should take you to: https://ideas.rallydev.com/ 

    This would be where you can post any new idea, share with us and other customers and hopefully it gets promoted and possibly offered. The decision if/what/when to offer is with Product Management.


    As to the wording of that idea:

    It's really up to you. I feel as if a general requirement along what you're asking could be:


    Requirement for User Story Blockage Report.

    A report that will provide an overall blockage time user stories were blocked in a requested time period. The report should list the overall blocked time, the percent of blocked time, provide the top stories blocked in same requested period, provide list of blocking reasons and also break the data by story type. Preferably the report needs to be printed. Preferably the report can display the information in a chart, preferably exported via Excel.


    Above is just my take on your requirement. You are welcome to present it to the ideas site in way that works best for you.


    About the possibility of consultation:

    I will ask my manager to make contact so you both can explore further.





  • 10.  Re:  API to Rally

    Posted 03-30-2018 07:17 PM

    There's an app on Github that may be of help. It includes generating metrics related to blockages and blocked time. The output isn't exactly what you're looking for, but it does handle working with the Lookback API, getting snapshots between two dates, and other parts that might be useful for you:


    GitHub - RallyTechServices/SAFe-delivery-metrics: An app to show delivery metrics for teams and iterations for a given P… 




  • 11.  Re:  API to Rally

    Posted 04-02-2018 09:26 AM

    Cathrin, Thanks!

    Unfortunately, our security system does not allow access to github. Could you please copy the code from github and forward to walt(dot)dietz(at)bankofamerica(dot)com?


    Walt Dietz

    Agile Coach - Affinity Products

    302 457 3795


    “If you need to complain - I will empathize.  If you want to complain - I will work with you to create a solution. That is what a coach does.”

    Me (Servant Leader)