An Introduction to the Analytics API in Apex. Peter Knolle - peterknolle.com Salesforce.com Solutions Architect Trifecta Technologies

Transcription

1 An Introduction to the Analytics API in Apex Peter Knolle - peterknolle.com Salesforce.com Solutions Architect Trifecta Technologies

2 What will be covered History / Background Example uses Running a report Accessing report metadata Filtering Unit testing Debugging / Exploring the API

3 History Salesforce had excellent reporting capabilities, but did not have an official/supported way to access the reports through code. Screen scraping Ick! iframe Yuck!

4 Analytics API Releases Winter 14 REST-based API released Requires Oauth session JSON requests/ responses Spring 14 Apex-based API released Same functionality as REST-based API, but in Apex

5 What can we do with it? Easily use with charting libraries such as d3, Google Charts, etc.

6 What can we do with it? Dynamic filtering

7 What can we do with it? Reduce maintenance: no need to create parallel SOQL to get report data. Dynamic Dashboards It is very new, so much much more to come

8 API REST and Apex APIs have same functionality Run reports (synchronous and asynchronous) Get report metadata Get report result data Dynamic filtering Get list of recent asynchronous report runs Classes are in the Reports namespace, e.g., Reports.ReportManager, Reports.ReportMetadata, etc.

9 Running a Report Set of four overloaded methods for both synchronous and asynchronous Synchronously Reports.ReportResults res = Reports.ReportManager.runReport(reportId); Asynchronously Reports.ReportInstance instance = Reports.ReportManager.runAsyncReport(reportId); // later Reports.ReportResults res = instance.getreportresults();

10 Overloaded runreport / runasyncreport methods runreport(reportid) Includes summary level information but will not include details (i.e., rows). runreport(reportid, includedetails) Includes the details, too. runreport(reportid, metadata) Applies additional filters specified in the Reports.ReportMetadata metadata argument runreport(reportid, metadata, includedetails) Includes the details, too.

11 More on Asynchronous Reports.ReportInstance instance = Reports.ReportManager.runAsyncReport(reportId); instid = instance.getid(); //some other method Reports.ReportInstance inst = Reports.ReportManager.getInstance(instId); String status = inst.getstatus(); if (status!= 'Running && status!= 'New ) { } reportresults = inst.getreportresults();

12 ReportResults Contains the results of running a report. getfactmap() Returns summary-level data or summary and detailed data for each row or column grouping. Detailed data is available if the includedetails parameter is set to true when the report is run.

13 Fact Map Keys Report format Tabular Fact map key pattern T!T: The grand total of a report. Both record data values and the grand total are represented by this key. Summary <First level row grouping_second level row grouping_third level row grouping>!t: T refers to the row grand total. Matrix <First level row grouping_second level row grouping>!<first level column grouping_second level column grouping>.

14 Report with two grouping levels

15 Using ReportResults Aggregates Map<String,ReportFact> fm = results.getfactmap(); Reports.ReportFact fact = fm.get( T!T ); Decimal grandtotal = (Decimal) fact.getaggregates().get(0).getvalue(); Decimal rowcount = (Decimal) fact.getaggregates().get(1).getvalue();

16 Using ReportResults - Details Reports.ReportResults results = Reports.ReportManager.runReport(REPORT_ID, true);

17 Using ReportResults - Details Reports.ReportFactWithDetails detailfact = (Reports.ReportFactWithDetails)results.getFactMa p().get('0_0!t'); List<Reports.ReportDetailRow> allrows = detailfact.getrows(); Decimal cellvalue = (Decimal) rows.get(0).getdatacells().get(0).getvalue(); System.assert(cellValue == );

18 Want more on the fact map? See Decode the Fact Map section in Apex Developer s Guide: apexcode/content/apex_analytics_fact_map.htm

19 Metadata Three types of metadata Report Metadata Reports.ReportMetadata Report Extended Metadata Reports.ReportExtendedMedtadata Report Type Metadata Reports.ReportTypeMetadata

20 ReportMetadata Report metadata gives information about the report as a whole, such as the report type, format, summary fields, row or column groupings, and filters that are saved to the report. Simple attributes - getid(), getname(), getdevelopername(), getreportformat(), getreporttype() Complex collections - getreportfilters(), getdetailcolumns(), getaggregates(), getgroupingsdown/across()

21 Accessing ReportMetadata Reports.ReportDescribeResult descres = Reports.ReportManager.describeReport(reportId); ReportMetadata md = descres.getreportmetadata(), OR the ReportMetadata from a specific run ReportMetadata md = reportresults.getreportmetadata(); // Example Uses Id reportid = md.getid(); List<String> colapinames = md.getdetailcolumns();

22 ReportExtendedMetadata Report extended metadata provides additional, detailed metadata about summary and grouping fields, including data type and label information. getaggregatecolumninfo() API name, label, data type of aggregations (row count, sum, etc.) getdetailcolumninfo() API name, label, data type of columns getgroupingcolumninfo() API name, label, data type, grouping level of each grouping in the ReportMetadata s groupingsdown/across.

23 Accessing ReportExtendedMetadata Reports.ReportDescribeResult descres = Reports.ReportManager.describeReport(reportId); Reports.ReportExtendedMetadata md = descres.getreportextendedmetadata(), OR the ReportExtendedMetadata for a specific run Reports.ReportExtendedMetadata emd = reportresults.getreportextendedmetadata();

24 Accessing ReportExtendedMetadata Integer level = emd.getgroupingcolumninfo() System.assert(0 == level);.get( STAGE_NAME ).getgroupinglevel();

25 ReportTypeMetadata Contains report type metadata, which gives you information about the fields that are available in each section of the report type, plus filter information for those fields. List<Reports.ReportTypeColumnCategory> getcategories() returns a list of categories, which in turn contain their list of fields with information about the fields

26 Accessing ReportTypeMetadata Reports.ReportDescribeResult descres = Reports.ReportManager.describeReport(reportId); Reports.ReportTypeMetadata tmd = descres.getreporttypemetadata(), // Not part of Reports.ReportResults

27 Accessing ReportTypeMetadata Reports.ReportTypeColumnCategory category = tmd.getcategories().get(0); String oppinfolabel = category.getlabel(); Boolean isfilterable = category.getcolumns().get( AMOUNT ).getfilterable();

28 Filtering Columns must be filterable. Must use only allowed filter operators per data type ReportManager. getdatatypefilteroperatormap() Can override existing filter by getting and setting value Can add additional filters Use Reports.ReportMetadata run/asyncreport versions, e.g., runreport(reportid, reportmetadata)

29 Adding a filter Reports.ReportFilter fromfilter = new Reports.ReportFilter(); fromfilter.setcolumn('close_date'); fromfilter.setoperator('greaterorequal'); fromfilter.setvalue(' '); Reports.ReportDescribeResult dr = Reports.ReportManager.describeReport(REPT_ID) Reports.ReportMetadata md = dr.getreportmetadata(); md.getreportfilters().add(fromfilter); Reports.ReportResults results = Reports.ReportManager.runReport(REPT_ID, md, true);

30 Unit Testing Report runs always ignore SeeAllData annotation, and always include org data Use a filter to limit testing to data created in the unit test Opportunity opp = TestUtil.generateOpp( ApexUnitTest ); List<Reports.ReportFilter> filters = gettestfilter(opp.name); reportmetadata.setreportfilters(filters);

31 Exploring / Debugging Useful to see entire object Helpful to determine API names Debug logs and Developer Console aren t really designed for viewing that information

32 Debugging - JSON Output to <pre> tag JSON.serailizePretty(results); public String debugres{ get; set; } // somewhere in a method Reports.ReportResults results = Reports.ReportManager.runReport(REPORT_ID); debugres = JSON.serializePretty(results); <apex:outputpanel id="debug"> <pre>{!debugres}</pre> </apex:outputpanel>

33 Debugging View State

34 Debugging REST Explorer

35 Selected Limitations 500 synchronous report runs / hour 20 synchronous report run requests at a time 1,200 asynchronous requests / hour 200 requests at a time for async instances Returns up to the first 2,000 report rows Apex: Asynchronous not allowed in Batch Apex: Report runs in unit tests include org data

36 What was covered Apex API new in Spring 14 Some examples Methods to run reports, filter, get results, get metadata Unit testing Debugging / Exploring

37 More Apex Developer s Guide - apexcode/content/apex_analytics_intro.htm Articles by Product Manager, Salesforce: Articles on my blog Spring 14 right around the corner or get a pre-release org in the meantime