This article describes how to use the HTTP based report Web API that Meridix exposes from another application.The report API allows users to use the Meridix report engine to create custom reports and use it from other systems such as custom build dashboards that displays data from multiple data sources from within the company.

Access the Report API

1. Create an API ticket inside Meridix web UI usign you credentials or contact your administrator if you don´t have any login. The ticket need to have the report rights granted.
   Tickets can  be created per system (system tickets), per customer (customer tickets) or per user (user tickets). The report rights can be granted to any type of ticket. But if its granted to a user ticket the reports created will only have access to the same resources as the user its belongs to.

2. Create a request against http[s]://{your-system-url}/api/report/v1-0/generate with the following request headers set (in addition to the default HTTP headers)
   
   

   For a simpler result try version 1.1 of the report api available at http[s]://{your-system-url}/api/report/v1-1/generate the parameter used is the same but the result payload is easier to use and has more metadata about the content.

   HTTP Request header	Example value	Description
   accept	application/json	Specify application/json or application/xml depending on your preferred report response format.
   accept-language	en-GB	The language you would like column headers and report resources to be presented in. Example: Use sv-SE if you would like the report in Swedish.
   content-type	application/json	The format of the request body where the report parameters is specified. Can be application/json or application/xml

   The following JSON schema should be used when the content-type header is set to application/json:

   The available parameters values for report name, module name etc. can be found by using other Report API methods that load the currently available option. The available values depends on the system configuration and/or ticket rights.

   Browse to http[s]://{your-system-url}/api/docs (Report section) for a list of available lookup methods.

   {
   	// OPTIONAL: The customer id is only needed if you are using a system ticket
   	"CustomerId":null,
   	// The name of the module in the language specified in the accept-language header.
   	"ModuleName":"Name of module here",
   	// The name of the report in the language specified in the accept-language header.						
   	"ReportName":"Name of report here",
   	// The from date in the report in the format yyyyMMdd. Ex: 20130704
   	"FromDate":"20130710",									
   	// The to date in the report in the format yyyyMMdd. Ex: 20130711
   	"ToDate":"20130711",									
   	// The minute of the day the report should include from. Ex: 420 = 07:00. Note that this value is the start of window each date not a start time on the from date.
   	"FromMinute":420,										
   	// The minute of the day the report should include to. Ex: 1020 = 17:00. Note that this value is the end of a window each date not a end time on the to date.
   	"ToMinute":1020,										
   	// OPTIONAL: The format time values should be presented in. [hhmmss|hhmm|mmss|ss]
   	"TimeFormat":"hhhmmss",									
   	// The result grouping. [total|objects|groups]
   	"ResultGrouping":"Objects",							
   	// OPTIONAL: The collection point id that the report should cover. Can be excluded if you only have one and are not using a system ticket.
   	"CollectionPointIdentifier":null,			
   	// OPTIONAL: The name of the measurement object types without explicitly defined types (see below) that the report needs in the language specified in the accept-language header. If the report only has one supported type it will be used if this value is omitted or null.					
   	"MeasurementObjectType":null,		
   	// An array of string with the ids of the measurement objects that the report should contain. Note that this is not the integer Id field of the objects. (The values can be found in the field ObjectIdentifier on the MeasurementObjectDtos). 
       // If the report handles multiple objects types each object can define it's type by defining the measurement object in the following format OBJECT-IDENTIFIER[TYPE] ex: 1234[AcdGroup] or 23456[UserId]
   	"MeasurementObjectIdentifiers":
   					[
   						"object identifier 1 here [optional-type-here]",
   						"object identifier 2 here"
   					],		
   	//  OPTIONAL: An array of string with the names of the measurement object groups that the report should contain. (The values can be found in the field Name on the MeasurementObjectGroupDtos). 
   	"MeasurementObjectGroupIdentifiers":
   					[
   						"group identifier 1 here (group name)",
   					],	
   	// A key value collection for custom report input parameters. Can be excluded if not used.			
   	"CustomParameters":null,								
   	// OPTIONAL: Specifies if the API should ignore any exceptions thrown if a measurement object is specified but does not exist or is accessible
   	"IgnoreNonExistingMeasurementObjectIdentifiers":false,					
   	// OPTIONAL: An array of strings with the column names that you would like to return in the result. Leave empty or skip to include all.
   	"IncludeColumns": [],  
   	// OPTIONAL: An array of strings with the grouping that you would like to return in the result. Leave empty or skip to include all.
   	"IncludeGroupings": [],
   	// OPTIONAL: A boolean value specifying if a the call specification should be included (if possible). Note that there are a max limit of items configured on the system level that cannot be overridden through the API. 
   	"IncludeSpecificationLists": false						
   }

3. Before the request can be sent to the server it need to be signed with a ticket (token/secret). Read this guide for instructions about how to sign a request with a ticket from Meridix.

4. When a request returns successfully the report content is contained in the response body in the format defined in the accept header (application/json or application/xml).
   
   The response format is a object in the structure defined below. The actual report values is mapped against the column name with the same index as the column. Ex 07:00 is in the first position in the time column and is therefore a value for the column period which is the first value in the column list. The report is built this way to minimize the data that needs to be sent to the clients since the column names only need to be included once.

   // This is the format for version 1.0 of the report API - For version 1.1 the content metadata is included directly in the result set.
   {
   	"Columns":	// The columns included in the report.
   		[
   			"Period",				// Column index 0
   			"Name",					// Column index 1
   			"Column-name-1-here",	// Column index 2
   		],
   	"Groupings":
   	{
   		"Time":
   			[
   				["","","0"],	// First row is always the total row
   				[
   					"07:00",				// Maps against column index 0 in the Columns array. This is the same for all column values.
   					"object id 1 here",	// Maps against column index 1 in the Columns array
   					"0"						// Maps against column index 2 in the Columns array
   				],
   				["07:00","subscriber id 2 here","0"]
   				//...trimmed for readability
   			],
   		"Date":
   			[
   				["","","0"],	// First row is always the total row
   				["20130710 wed","object id 1 here","0"],
   				["20130710 wed","object id 2 here","0"],
   				["20130711 thu","object id 1 here","0"],
   				["20130711 thu","object id 2 here","0"]
   			],
   		"Month":
   			[
   				["","","0"],	// First row is always the total row
   				["july","object id 1 here","0"],
   				["july","object id 1 here","0"]
   			],
   		"Year":
   			[
   				//...trimmed for readability
   			],
   		"YearMonth":
   			[
   				//...trimmed for readability
   			]			,
   		"Quarter":
   			[
   				//...trimmed for readability
   			],
   		"Week":
   			[
   				//...trimmed for readability
   			],
   		"Weekday":
   			[
   				//...trimmed for readability
   			],
   		"Period":
   			[
   				["","","0"],	// First row is always the total row
   				["20130710->20130711","object id 1 here","0"],
   				["20130710->20130711","object id 2 here","0"]
   			]
   	}
   }

5. This information can be bound to a custom chart or used from any other application.

You can download a .NET C# console application with the code needed to make report requests here.

Access the Report API with the NuGet package (.NET only)

This section will be added soon. Read more about the NuGet package here.