Versions Compared

Old Version 24

changes.mady.by.user Johan Wendelstam

Saved on

compared with

New Version Current

changes.mady.by.user Filip Lindhe (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  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)

    Info

    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 headerExample valueDescription
    acceptapplication/jsonSpecify application/json or application/xml depending on your preferred report response format.
    accept-languageen-GBThe 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-typeapplication/jsonThe 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:

    Info

    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/docdocs (Report section) for a list of available lookup methods.


    Code Block
    languagejavascript
    {
	// 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.

    Code Block
    languagejavascript
    // 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.

...