079-reports.rst (3563B)
1 DD 79: Reports 2 ############## 3 4 Summary 5 ======= 6 7 Provide a way for merchants to be periodically sent 8 reports about payments without requiring them to open 9 the merchant backend in a browser. 10 11 Motivation 12 ========== 13 14 * We had merchants say that receiving e-mails with 15 transaction statistics is a "MUST" requirement for them 16 (see #10803). 17 * We had banks say that sending merchants reports on 18 transaction amounts and especially transaction fees is 19 a legal requirement for them to be able to say that the 20 merchant accepted the fees (see #9361). 21 22 Requirements 23 ============ 24 25 * Frequencies differ, daily, weekly, monthly, quarterly, yearly 26 are all frequencies we have already been told as desirable. 27 * In some cases, an offset is desired, like every day at 3am 28 to ensure business concluded around midnight is included in the 29 "daily" report received in the morning. 30 * The reports should include statistics grouped by "category". 31 We are right now interpreting "category" as "tax classes", and 32 thus should report the statistics with the sale amounts in 33 each tax category and the respective amount of taxes due in 34 each category, and the payment fees that were charged --- 35 and the total number of transactions made. 36 * We want this to be reasonably generic, so probably best to 37 immediately plan for E-mail, SMS and other transmission mechanisms. 38 So we should use a helper-program for the actual transmission. 39 * The target e-mail may not be the public e-mail address associated 40 with the instance. 41 * Multiple alerts at different frequencies and different content 42 may apply to the same instance. 43 44 45 Proposed Solution 46 ================= 47 48 * Do a "GET" request to some endpoint of the 49 instance to generate the PDF/CSV/TEXT/HTML and then pass that 50 on to the helper program instead of re-implementing the main 51 reporting logic. This way, the configuration would just 52 pick the endpoint (and content-type), which is quite flexible. 53 * Add new "reports" or "alerts" table with 54 (0) serial, (1) instance, (2) name, (3) frequency, 55 (4) time offset, (5) address type, (6) address, 56 (7) mime-type of the data to send, (7) URL 57 path (below /instance/$ID) to request the data from, 58 (8) next-transmission timestamp, (9) last error (EC), 59 (10) last error detail (text). 60 * Define helper programs in the configuration for each supported 61 address type that deal with the transmission of the report. 62 * Expose supported report address types in /config. 63 * Add CRUD API to manipulate report list. 64 * Implement helper program that scans the reports table, 65 requests the data and invokes the helper program for 66 transmission and possibly stores/clears errors. 67 68 Test Plan 69 ========= 70 71 * Shell-script based tests for the new CRUD API. 72 * Shell-script based tests for reports using 73 a "cat"-based helper that writes to a local file. 74 * Manual tests for SPA. 75 * Manual tests for PDF/CSV/etc. generation. 76 77 78 Definition of Done 79 ================== 80 81 * Specification updated 82 * Database updated 83 * Merchant backend updated: 84 85 * CRUD API for report definitions 86 * INI-based configuration for reporting helper programs 87 * New background process for creating reports 88 * New endpoints for generating reports (#9361) 89 90 * Merchant backend SPA updated: 91 92 * CRUD for report definitions 93 * Statistics (?) page with links to various 94 GET pages that generate (PDF, CSV) reports (#10487) 95 96 97 Alternatives 98 ============ 99 100 None. 101 102 Drawbacks 103 ========= 104 105 Discussion / Q&A 106 ================ 107 108 (This should be filled in with results from discussions on mailing lists / personal communication.)