BigTime's reporting engine offers a powerful way to extract exactly the data you need from the system -- combining thousands of possible fields and calculations into a single table, adding your own customized filters and settings and limiting the data users are able to pull based on their unique system permissions.

The Reporting API offers you the ability use that same powerful set of data in external reporting and dashboard applications.

Reporting API HowTo's (a simple example)

Let's assume that you'd like to create a summary of total time logged for the current month, subtotalled by staff member, for an external dashboarding application. You can use BigTime's report designer, together with the reporting api, to accomplish that goal.

Step 1: Create the report you'd like to export.

Before you can export a report's data, you need to create it. In this case, we need to create a new Timesheet Summary report with the fields Staff Member and Total Input Hours. Since the report we design is a copy of the "timesheet summary" basic report, it will allow the user to enter a start/end date when they view the report online.

Step 2: Note the report's "Id" in BigTime.

Once the report has been published, it now appears in our list of system report in BigTime's Report Center. When you click on it, the system forwards you to the report "Detail" page. You can determine the report's Id based on the URL used to display it (the url is in the format ../Report/Detail/{id}).

The report's Id is used throughout the reporting api, and once you create a report it's Id doesn't change.

Step 3: Use the reporting API to pull the report's data.

Every report in the system is made up of a schema and data. To get the information contained in a report, first make a POST request to the reporting api's /Report/Data endpoint to ensure the report is up-to-date. Then simply make a GET request to the /Report/Data endpoint to retrieve the data. The reporting api will return an array of data for that report.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP POST:  /report/data/{id}
POST CONTENT:  {DT_BEGIN: "2013-01-01", DT_END: "2013-01-31"}
HTTP RESPONSE: 
	{
		"Data": [
			[1,"Evil Corp: Odd Job","Odd Job","2016-04-01","On Hold"],
			[2,"Evil Corp: Jaws","Jaws","2016-04-01","On Hold"]
		]
		"FieldList": [
			{"FieldNm":"systemid", "FieldType":"intType","Maxlen":8},
			{"FieldNm":"dname", "FieldType":"varchar","Maxlen":250},
			{"FieldNm":"prjnm", "FieldType":"varchar","Maxlen":50},
			{"FieldNm":"prjstartdt", "FieldType":"datetime","Maxlen":4},
			{"FieldNm":"prjstatusprod","FieldType":"varchar","Maxlen":30},
		]
	}

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /report/data/{id}
HTTP RESPONSE: 
      [[0,"#NA#",144536,false,"Jake Moneypenny",761,"Moneypenny",18.25],
      [0,"#NA#",144536,false,"Joseph Nobody",761,"Nobody",12.25],
      [100,"Overall Totals","","","","","",30.50]]

Schema vs. Data -- Understanding the information returned from the Reporting API.

On it's own, the array of data returned from the previous example will be difficult to under stand. Which fields should your dashboarding application use to indicate staff member? Which field shows the total input hours? To interpret this data, you'll need to use the report's schema.

Use the report's Schema to understand how it's Data is organized.

A report's data is designed to be fast and efficient. It's meant to allow you to pull ONLY the information that a report is comprised of. But, if you are designing a system to consume that information, you'll need to work with the report's schema to start.

Based on the example above, a call to the report's schema will yield a more detailed understanding of a report's dataset.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP GET:  /report/detail/{id}
HTTP RESPONSE:  {"RptSid": 108, "RptNm": "Active Staff Members, Contact List",
  "RptNt": "A simple report which contains a list of all active staff members",
  "RptType": 2, "RptUIType": 2, "IsCustom": false, "IsPermittedByUser": true,
  "ShowRptTotal": true, "ShowSubtotals": false,
  "CurrentSettings": [
    "Hide Inactive Staff"
  ],
  "Params": {
    "UseDt": 0, "Param1Type": 2, "Param1Caption": "Hide Inactive Staff"
  },
  "Settings": {
    "PARAM1": true, "ShowOnlyMyStaff": false
  },
  "Columns": [
    {
      "Id": "stname", "Name": "Name", "FieldNm_id": "stname_id", "FieldNm_sort": "stname_sort",
      "FieldType": "string", "HasIdField": true, "HasSortField": true, "CanGroupBy": true,
      "Alignment": "left", "Position": 2, "IsHidden": false, "DefaultWidth": 150
    },
    {
      "Id": "staddressfull", "Name": "Address", "FieldType": "string", "HasIdField": false,
      "HasSortField": false, "CanGroupBy": false, "Alignment": "left", "Position": 3,
      "IsHidden": false, "DefaultWidth": 150
    },
	...
  ]
}

From this response, we can see that the data from the report we are pulling contains several fields (or "columns"). The first field in the list has an id of "stname" in the dataset, and we can see that this value also has a unique Id associated with it (called "stname_id"). We can use that information to see how BigTime has organized those fields into a simple report. We can also see what the user has labeled each column and we can see some formatting information as well (eg - text alignment, format et al).

Getting vs. Posting -- Using the API to change a report's settings.

When you make an HTTP GET call to /Report/Data/{id} BigTime will pull the data for the report you specify based on the settings used last time that report was pulled. In or example above, the Total Time by Staff Member report supports a date range. When we pull the report from /Report/GetData -- the date range used to generate the report is based on the data range specified in the BigTime UI.

For our example, however, we'd like to pull a summary of time for a specific date range (the current month's start/end date). To do that, we need to use a POST request instead.

HEADERS:  X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId}
HTTP POST:  /report/data/{id}
POST CONTENT:  {DT_BEGIN: "2013-01-01", DT_END: "2013-01-31"}
HTTP RESPONSE: 
	{
		"Data": [
			[1,"Evil Corp: Odd Job","Odd Job","2016-04-01","On Hold"],
			[2,"Evil Corp: Jaws","Jaws","2016-04-01","On Hold"]
		]
		"FieldList": [
			{"FieldNm":"systemid", "FieldType":"intType","Maxlen":8},
			{"FieldNm":"dname", "FieldType":"varchar","Maxlen":250},
			{"FieldNm":"prjnm", "FieldType":"varchar","Maxlen":50},
			{"FieldNm":"prjstartdt", "FieldType":"datetime","Maxlen":4},
			{"FieldNm":"prjstatusprod","FieldType":"varchar","Maxlen":30},
		]
	}

When we use an HTTP POST request, we can specify report settings which govern how that data is pulled from the system. Then, subsequent HTTP GET calls to /Report/Data will use the settings we've specified.

Different Reports support different report settings.

Obviously, not every report in the system requires a date range. It wouldn't make sense to pull a list of staff members, for example, filtered by date range. To determine what filter settings a report supports, you can use the report's SCHEMA. Supported filter settings are listed as a part of the rptSettings object.

The reporting API supports a small number of report settings. If you'd like to filter your reports on more advanced criteria, you can build those filters into the actual report definition. The BigTime reporting UI supports an advanced set of filters on ANY of the columns you include on a report. In addition, there is no limit to the number of reports you can create in the system -- so specialized reporting requirements can be satisfied customized report filters.

Report Detail: Basic Fields

The data from the calls to report/detail will return the following fields.