api login

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, you just need to call the reporting api's /Report/Data end point. The reporting api will return an array of data for that report.

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.

Note: Period based reports (e.g. Allocation report types) use a set period of a year, rather than a custom date range. This means you only need to specify the period start.

POST CONTENT: {PER_BEGIN: "2013-01-01"}
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.

FieldTypeDescriptionView(s)
RptSid Integer Unique SID code for this report.
RptNm String The user-friendly name for this report as it appears in the BigTime UI.
RptNt String A brief description of the report's data and it's function.
RptType/ RptUIType Integer A value indicating the type of data this report contains (1=project, 2=staff, 3=time detail, 4=expense detail, 5=time+expense detail, 7=task info, 8= task assignment data, 10=invoice details).
IsCustom Boolean TRUE if this report was user-generated. FALSE if this is a standard BigTime system report.
IsPermittedByUser Boolean TRUE if the current user should be able to pull reporting information for this report
ShowRptTotal Boolean TRUE if an overall totals "row" is displayed within the BigTime UI for this report.
ShowSubtotals Boolean TRUE if row SUBTOTALS (based on groupings) are displayed within the BigTime UI for this report.
CurrentSettings String[] A plain-english description of the settings that were used to produce the data in the report (see settings and report/data <POST>)
Params Object Indicates the parameters that are used to construct this report
Settings Object Indicates the current value(s) posted to report/data and on which this report's information is based.
Columns Object[] An element for each column returned as a part of this report's data (see below for details)
FieldTypeDescription
IdStringThe unique field name for this column's data (eg - the name found in report/data's FieldList results).
NameStringThe column label used for this column in the BigTime report.
FieldNmStringSame as the Id field.
FieldNm_idStringIf this field also has a unique numeric ID associated with the reported value, then this column will contain the name of that unique Id value in the result set (eg - laborCode and laborCode_id).
HasIdFieldBooleanIndicateds whether this field also has a unique numeric ID associated with the reported value. If it does, then there will also be a value in FieldNm_Id indicating the name of that field in the returned dataset.
FieldNm_sortStringSome reporting columns have a non-alpha sorting value associated with them. This lets users sort, for example, tasks in a project's task list by an arbitrary order not related to their Id or the Name. This is the NAME of the column in the returned dataset that contains this unique sortable value.
HasSortFieldBooleanIndicateds whether this field also has a unique sortable associated with the reported value. If it does, then there will also be a value in FieldNm_Sort indicating the name of that field in the returned dataset.
FieldTypeStringThe type of data returned in this field in the dataset (string, boolean, currency, date, float, int or text).
CanGroupByBooleanTRUE if this field can be used to GROUP/SUBTOTAL the data in this report within BigTime's front-end UI.
TotalTypeStringWhen a report contains numeric fields that can be totalled/sub-totalled, this value indicates the subtotal TYPE that should be used (sum, avg, min or max).
ColumnGroupStringSome reports make use of a column GROUP (eg - a title that spans multiple columns, grouping them together visually). If this column is placed beneath a column group in BigTime, then the value of that group appears in this field.
AlignmentStringLeft, Right or Center
PositionNumberThe physical position of the field within the report (eg - 1 thru 100).
FormatterStringIf the value should be formatted, then this field tells you what formatter to use (eg - currency, #.##0, etc).
IsHiddenBooleanTRUE if this value is returned by the report's data but not displayed on the front-end (eg - column is hidden). Hidden columns allow a suer to filter on the value(s) they contain without displaying them to the end-consumer of the report.
DefaultWidthNumberThe width that this user has set the column to within BigTime.