Lab4 "Field API Web Intro Ex"

(This is a continuation from the previous post: Lab3 "Field API Web Intro")

The last piece of functionalities that we want to add to our Intro Labs app is a simple reporting feature. We will add a chart that shows the number of issues sorted by status (i.e., Open, Completed, etc.). Reporting or monitoring the “health” of a project is one of frequently discussed use case scenarios of Field API. 

As mentioned in the previous post, currently Field API is fully REST based. Unlike Glue and View and Data API, Field API does not have any visualization component. Luckily, creating a chart is generic enough. We can make use of tools publically available for this purpose. For example, Visual Studio comes with built-in tools to create a chart. You may be interested in looking into JavaScript library, too. (In fact, this is one topic that I hope to come back at later time.) For now, we are going with the Chart control that comes with Microsoft Visual Studio (MSVS) without introducing additional tools. 

Counting Issues by Status

As data to create a chart, we use the list of issues obtained in the Lab2: i.e., the list returned from Field.IssueList(). We simply save it as a session object:

List<Issue> issue_list = Field.IssueList(ticket, project_id);
Session["issueList"] = issue_list;

And retrieve it later when we want to create a chart:   

List<Issue> issue_list = Session["issueList"] as List<Issue>;

To count issues for each status, we need to iterate through the list of issues, check the value of “Status” in each issue, and add up counters for each status.

A tricky thing is that Field documentation is completely silent about response format of those REST calls and (feels like) we are left to our own to figure them out. This is where our little Labs app having the response text box and tools like Online JSON Viewer I mentioned earlier get extremely handy. I will describe how I approached the lack of documentation shortly.

But before I do so, below is the code that counts the number of issues for each status from the given list of issues: 

CollectData

        // Collect data from the issue list.
        // Count the number of issues for each status.
        // data is a dictionary of (status, count) pair
         
        protected Dictionary<string, int> CollectData(List<Issue> issue_list)
        {
            Dictionary<string, int> data = new Dictionary<string, int>();

            foreach (Issue issue in issue_list)
            {
                string status = issue.fields.Find(x => x.name.Equals("Status")).value;
                if (data.ContainsKey(status))
                {
                    data[status]++;
                }
                else
                {
                    data.Add(status, 1);
                }
            }

            return data;
        }

In the above code, this is the line that we needed to know the format of the issue:

string status = issue.fields.Find(x => x.name.Equals("Status")).value;

Re-visiting Issue List

Here is what I did to decipher the format from an actual response:

1. Using Field API Intro app (either Lab2 or Lab3 will do), make Issues/List call ("Issue" button). 

2. In “Response” text box, right click and [Select All] and [Copy]: 

3. Go to http://jsonviewer.stack.hu/, in the “Text” tab, paste (Cntl + V) the response that we just copied in the step 2.  (In my case, I added HttpStatusCode at the top of Response text box. If you do something similar, make sure to take them out.): 

4. Go to  “Viewer” tab, where you can easily examine the response:

For example, you can see each issue has “fields”, which is a collection of “field”, where each “field” has "id", "name", "display_type" and "value". In our case, we are interested in the value of field whose name is equals to “Status” for each issue.  

Adding a Chart  

Using MSVS, you can use Data/Chart tool to add a chart to your web page. Simply drag and drop a tool to the web form. It will automatically place a chart <asp:Chart/> on your web page. You can adjust color and other details for the appearance of the chart in the property window. To change the type of chart, go to “Series” property; in the Series Collection Editor, change the ChartType, for example, to “Bar”. 

Actual data goes to Chart >> Series >> Points. The below is an example of code that creates a chart when a “Report” button is clicked: 

ButtonReport_Click

        protected void ButtonReport_Click(object sender, EventArgs e)
        {
            List<Issue> issue_list = Session["issueList"] as List<Issue>;

            // Collect data from the issue list.
            // Count the number of issues for each status.
            Dictionary<string, int> data = CollectData(issue_list);

            // Clear the chart data
            Chart1.Series[0].Points.Clear();

            // Fill the chart data  
            foreach (var item in data)
            {
                Chart1.Series[0].Points.AddXY(item.Key, item.Value);
            }

            // Add a title text
            Chart1.Titles[0].Text = "Issues by Status";

        }

An example of final web page will look like this:

You can download the Field API Intro Labs code from here.

This concludes the tour of our Field API Intro Labs. I hope this helps you jump start with the Field API.

Mikako