README.rtf

{\rtf1\ansi\ansicpg1252\cocoartf1265
{\fonttbl\f0\fswiss\fcharset0 Helvetica;\f1\fmodern\fcharset0 Courier;\f2\fnil\fcharset0 LucidaGrande;
}
{\colortbl;\red255\green255\blue255;\red38\green38\blue38;\red52\green110\blue183;\red246\green246\blue246;
\red100\green100\blue100;}
{\*\listtable{\list\listtemplateid1\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc0\leveljcn0\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid1\'01\uc0\u8226 ;}{\levelnumbers;}\fi-360\li720\lin720 }{\listname ;}\listid1}
{\list\listtemplateid2\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc0\leveljcn0\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid101\'01\uc0\u8226 ;}{\levelnumbers;}\fi-360\li720\lin720 }{\listlevel\levelnfc23\levelnfcn23\leveljc0\leveljcn0\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{circle\}}{\leveltext\leveltemplateid102\'01\uc0\u9702 ;}{\levelnumbers;}\fi-360\li1440\lin1440 }{\listname ;}\listid2}
{\list\listtemplateid3\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc0\leveljcn0\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid201\'01\uc0\u8226 ;}{\levelnumbers;}\fi-360\li720\lin720 }{\listname ;}\listid3}}
{\*\listoverridetable{\listoverride\listid1\listoverridecount0\ls1}{\listoverride\listid2\listoverridecount0\ls2}{\listoverride\listid3\listoverridecount0\ls3}}
\margl1440\margr1440\vieww18960\viewh13400\viewkind0
\deftab720
\pard\pardeftab720\sl1020\sa300

\f0\b\fs60 \cf2 AwReporting (Beta)\
\pard\pardeftab720\sl800

\fs48 \cf3 \
\pard\pardeftab720\sl800\sa300
\cf2 Special Note\
\pard\pardeftab720\sl500\sa300

\b0\fs30 \cf2 Please let us know if you run into issues in the project's issue tracker ({\field{\*\fldinst{HYPERLINK "https://github.com/googleads/aw-reporting/issues"}}{\fldrslt \cf3 https://github.com/googleads/aw-reporting/issues}}), this Beta release may not fit your needs if you work with very large accounts but we are working to make the project better, your feedback is very important.\
\pard\pardeftab720\sl800

\b\fs48 \cf3 \
\pard\pardeftab720\sl800\sa300
\cf2 Overview\
\pard\pardeftab720\sl500\sa300

\b0\fs30 \cf2 AwReporting is an open-source Java framework for large scale AdWords API reporting.\
\pard\tx220\tx720\pardeftab720\li720\fi-720\sl500\sa300
\ls1\ilvl0\cf2 {\listtext	\'95	}You can use this project to generate reports for all the AdWords accounts managed by an MCC.\
{\listtext	\'95	}15 common reports are included in the reference implementation. You can easily follow the code examples to implement more.\
{\listtext	\'95	}Reports are stored in your
\b relational database
\b0 , so you can integrate them with your existing systems.\
\pard\pardeftab720\sl800

\b\fs48 \cf3 \
\pard\pardeftab720\sl800\sa300
\cf2 Quick Start\
\pard\pardeftab720\sl600

\fs36 \cf3 \
\pard\pardeftab720\sl600\sa300
\cf2 Prerequisites\
\pard\pardeftab720\sl500\sa300

\b0\fs30 \cf2 You will need Java, Maven and MySQL installed before configuring the project.\
\pard\pardeftab720\sl600

\b\fs36 \cf3 \
\pard\pardeftab720\sl600\sa300
\cf2 Build the project using Maven\
\pard\pardeftab720\sl500\sa300

\f1\b0\fs24 \cf2 \cb4 $ git clone {\field{\*\fldinst{HYPERLINK "https://github.com/googleads/aw-reporting"}}{\fldrslt \cf3 https://github.com/googleads/aw-reporting}}
\f0\fs30 \cb1 \

\f1\fs24 \cb4 $ mvn clean install eclipse:eclipse
\f0\fs30 \cb1 \

\f1\fs24 \cb4 $ mvn compile dependency:copy-dependencies package
\f0\fs30 \cb1 \
\pard\pardeftab720\sl600

\b\fs36 \cf3 \
\pard\pardeftab720\sl600\sa300
\cf2 Configure your MySQL database\
\pard\pardeftab720\sl500\sa300

\f1\b0\fs24 \cf2 \cb4 CREATE DATABASE AWReports DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci;
\f0\fs30 \cb1 \

\f1\fs24 \cb4 CREATE USER 'reportuser'@'localhost' IDENTIFIED BY 'SOME_PASSWORD';
\f0\fs30 \cb1 \

\f1\fs24 \cb4 GRANT ALL PRIVILEGES ON AWReports.* TO 'reportuser'@'localhost' WITH GRANT OPTION;
\f0\fs30 \cb1 \
\pard\pardeftab720\sl600

\b\fs36 \cf3 \
\pard\pardeftab720\sl600\sa300
\cf2 Configure AwReporting\
\pard\pardeftab720\sl500\sa300

\b0\fs30 \cf2 Now we'll create a properties file to specify your MCC, developer token, OAuth and database credentials.\
\pard\pardeftab720\sl500\sa300

\f1\fs24 \cf2 \cb4 $ vi ../aw-reporting/src/main/resources/aw-report-sample.properties
\f0\fs30 \cb1 \
Fill in the following fields with your MCC account ID and developer token.\
\pard\pardeftab720\sl500\sa300
\cf5 mccAccountId=\
\pard\pardeftab720\sl500
\cf5 developerToken=\
\pard\pardeftab720\sl500\sa300
\cf2 Fill in your OAuth credentials. If you need to create them, visit: {\field{\*\fldinst{HYPERLINK "https://code.google.com/apis/console#access"}}{\fldrslt \cf3 https://code.google.com/apis/console#access}}\
\pard\pardeftab720\sl500\sa300
\cf0 Note that you don't have to enter RefreshToken as AwReporting takes care of getting a new one when it runs for the first time.\cf5 \
clientId=\
\pard\pardeftab720\sl500
\cf5 clientSecret=\
\pard\pardeftab720\sl500\sa300
\cf2 Fill in the following with the number of rows that will be parsed from the CSV file before persisting to the DB. The bigger the number, the bigger the memory usage, but also might give an improvement in performance.\
\pard\pardeftab720\sl500
\cf5 aw.report.processor.rows.size=1000\
\pard\pardeftab720\sl500\sa300
\cf2 Fill in the following to set the number of threads for the CSV processing and DB insertion.\
\pard\pardeftab720\sl500
\cf5 aw.report.processor.threads=4\
\pard\pardeftab720\sl500\sa300
\cf2 Fill in the following with your database connection.\
\pard\pardeftab720\sl500\sa300
\cf5 aw.report.model.db.sql.url=jdbc:mysql://localhost:3306/AWReports?rewriteBatchedStatements=true\
aw.report.model.db.sql.username=reportuser\
\pard\pardeftab720\sl500
\cf5 aw.report.model.db.sql.password=SOME_PASSWORD\
\pard\pardeftab720\sl600\sa300

\b\fs36 \cf2 \
Run the project and verify it's working\
\pard\pardeftab720\sl500\sa300

\b0\fs30 \cf2 It's possible to run the project using either Eclipse or the command line. If using Eclipse, open and run:\
\pard\pardeftab720\sl500
\cf5 aw-reporting/src/main/java/com/google/api/ads/adwords/jaxws/extensions/AwReporting.java\
\pard\pardeftab720\sl500\sa300
\cf2 Be sure to specify the properties file you edited above on the command line.\
As it's running, the project will provide status messages about the reports it's downloading on the command line.\
Check your database when the run finishes to be sure it's been populated with the reporting data, e.g.:\
\pard\pardeftab720\sl500
\cf5 SELECT * FROM AWReports.AW_ReportAd limit 1;\
\pard\pardeftab720\sl600

\b\fs36 \cf3 \
\pard\pardeftab720\sl600\sa300
\cf2 Command line options\
\pard\pardeftab720\sl500\sa300

\b0\fs30 \cf2 Set the following command line options before running the project:\
\pard\pardeftab720\sl380

\f1\fs26 \cf2 \cb4 Note: aw-reporting.jar is in the aw-reporting/aw-reporting/target/ directory.\
\
\pard\pardeftab720\sl380

\fs24 \cf2 java -Xmx1G -jar aw-reporting.jar -startDate YYYYMMDD -endDate YYYYMMDD -file <file>
\fs26 \
\

\fs24 java -Xmx1G -jar aw-reporting.jar -generatePdf <htmlTemplateFile> <outputDirectory> -startDate YYYYMMDD -endDate YYYYMMDD -file <file>
\fs26 \
\
\

\fs24 Arguments:\
\
   -accountIdsFile <file>           Defines a file that contains all the account IDs, one per line, to be used\
                                          instead of getting the accounts from the API. The list can contain all the accounts,\
                                          or just a specific set of accounts\
\
   -dateRange              ReportDefinitionDateRangeType.\
\
   -debug     Will display all the debug information. If the option 'verbose' is\
              activated, all the information will be displayed on the console as\
              well\
\
   -endDate <YYYMMDD>      End date for CUSTOM_DATE Reports (YYYYMMDD)\
\
   -file <file>            aw-report-sample.properties file.\
\
   -generatePdf <htmlTemplateFile> <outputDirectory>\
                           \
                           Generate Monthly Account Reports for all Accounts in PDF\
   \
                           NOTE: For PDF use aw-report-sample-for-pdf.properties instead, the fields need to be different.\
\
   -help                   Print this message.\
\
   -startDate <YYYYMMDD>   Start date for CUSTOM_DATE Reports (YYYYMMDD).\
\
   -verbose                The application will print all the tracing on the console\
\
\pard\pardeftab720\sl380

\fs26 \cf2 \
\pard\pardeftab720\sl800

\f0\b\fs48 \cf3 \cb1 \
\pard\pardeftab720\sl600\sa300

\fs36 \cf2 Import the project into Eclipse (optional)\
\pard\pardeftab720\sl500\sa300

\b0\fs30 \cf2 To import the project into Eclipse, first import the model:\
\pard\pardeftab720\sl500\sa300
\cf5 File -> Import -> General -> Existing projects into workspace.\
\pard\pardeftab720\sl500
\cf5 aw-reporting/aw-report-model\
\pard\pardeftab720\sl500\sa300
\cf2 Next import the database code:\
\pard\pardeftab720\sl500\sa300
\cf5 File -> Import -> General -> Existing projects into workspace.\
\pard\pardeftab720\sl500
\cf5 aw-reporting/aw-reporting\
\pard\pardeftab720\sl600

\b\fs36 \cf3 \
\pard\pardeftab720\sl800\sa300

\fs48 \cf2 Details about the code\
\pard\pardeftab720\sl500\sa300

\b0\fs30 \cf2 For better organization and encapsulation, the project groups the reporting workflow into two parts:
\b Aw-Report-Model
\b0  for the logic (API services, downloader and processors) and
\b Aw-Reporting
\b0  for persistence, entities and the CSV mapping to AdWords information.\
\pard\pardeftab720\sl600

\b\fs36 \cf3 \
\pard\pardeftab720\sl600\sa300
\cf2 Aw-Report-Model\
\pard\pardeftab720\sl500\sa300

\b0\fs30 \cf2 Provides all the necessary classes to persist data and the entities\'92 mapping to AdWords report data.\
\pard\tx220\tx720\pardeftab720\li720\fi-720\sl500\sa300
\ls2\ilvl0
\b \cf2 {\listtext	\'95	}Entities:
\b0  these POJOs define all the available fields for each report kind as java fields, by using annotations. The Entities contain the information to link the java fields to the report fields definition, the csv display name header fields and the datastore fields.\
\ls2\ilvl0
\b {\listtext	\'95	}CSV:
\b0  The CSV classes use the OpenCSV library to convert CSV files into Java beans using annotations. The package also contains two new annotations to define the Report Definition Type and the mapping between java field, report\'92s Column Name and Display Name headers. For example:\
\pard\tx940\tx1440\pardeftab720\li1440\fi-1440\sl500\sa300
\ls2\ilvl1\cf2 {\listtext
\f2 \uc0\u9702
\f0 	}Annotation
\b @CsvReport
\b0  at the Report class level, for example for ReportAccount:
\f1\fs24 \cb4 @CsvReport(value= ReportDefinitionReportType.ACCOUNT_PERFORMANCE_REPORT) public class ReportAccount extends Report \{...
\f0\fs30 \cb1 \
{\listtext
\f2 \uc0\u9702
\f0 	}Annotation
\b @CsvField
\b0  at the java field level, for example for avgCpm:
\f1\fs24 \cb4 @CsvField (value = "Avg. CPM", reportField = "AverageCpm") public BigDecimal avgCpm;
\f0\fs30 \cb1 \
\pard\tx220\tx720\pardeftab720\li720\fi-720\sl500\sa300
\ls2\ilvl0
\b \cf2 {\listtext	\'95	}Persistence:
\b0  The persistence layer uses Spring for bean management, injection and in class annotations, this helps to clearly demarcate the application layers. AuthTokenPersister: is the interface for the authorization token storage, we have implemented it for Mysql and a MongoDB. ReportEntitiesPersister is the interface for the report entities storage, we have implemented it for Mysql and a MongoDB.\
\pard\pardeftab720\sl600

\b\fs36 \cf3 \
\pard\pardeftab720\sl600\sa300
\cf2 Aw-Reporting\
\pard\pardeftab720\sl500\sa300

\b0\fs30 \cf2 Provides the logic (API services, downloader and processors)\
\pard\tx220\tx720\pardeftab720\li720\fi-720\sl500\sa300
\ls3\ilvl0
\b \cf2 {\listtext	\'95	}Downloader:
\b0  Based on MultipleClientReportDownloader java example (it uses the Library ReportDownloader) the Downloader is in charge of downloading all the report files using multiple threads.\
\ls3\ilvl0
\b {\listtext	\'95	}Processors:
\b0  The ReportProcessor is the class with the main logic, it is responsible for calling the downloader, use the CSV classes for the parsing and call the Persistence helpers for the storage. This class can be replaced by a custom processor by changing the bean component in the projects xml configuration files.\
\ls3\ilvl0
\b {\listtext	\'95	}API Services:
\b0  Beside the report Downloader calls to AdHoc Reports, the ManagedCustomerDelegate is the only class talking to the AdWords API, it is in charge of getting all the account ids in the MCC tree.\
\ls3\ilvl0
\b {\listtext	\'95	}AwReporting main:
\b0  The AwReporting main class is in charge of printing the help information, of the properties file example and of passing the command line parameters to the processor for execution.\
\pard\pardeftab720\sl800

\b\fs48 \cf3 \
\pard\pardeftab720\sl800\sa300
\cf2 PDF Generation\
\pard\pardeftab720\sl500\sa300

\b0\fs30 \cf2 PDF generation works monthly and also needs the use of a HTML template like ACCOUNT_PERFORMANCE_REPORT.tmpl\
First run the date range without the -generatePdf to download the data needed to generate them.\
Here's an example properties file for PDF generation:\
\pard\pardeftab720\sl500
\cf5 aw-report-sample-for-pdf.properties\
\pard\pardeftab720\sl600

\b\fs36 \cf3 \
\pard\pardeftab720\sl600\sa300
\cf2 Fine print\
\pard\pardeftab720\sl500\sa300

\b0\fs30 \cf2 Pull requests are very much appreciated. Please sign the {\field{\*\fldinst{HYPERLINK "http://code.google.com/legal/individual-cla-v1.0.html"}}{\fldrslt \cf3 Google Individual Contributor License Agreement}} (There is a convenient online form) before submitting.\
\pard\pardeftab720\sl500

\i\b\fs28 \cf2 Authors\
\pard\pardeftab720\sl500
{\field{\*\fldinst{HYPERLINK "https://plus.google.com/+JulianCToledo/"}}{\fldrslt
\i0\b0\fs30 \cf3 Julian Toledo (Google Inc.)}}
\i0\b0\fs30 \
\pard\pardeftab720\sl500
{\field{\*\fldinst{HYPERLINK "https://plus.google.com/+GustavoMenezes/"}}{\fldrslt \cf3 Gustavo Menezes (Google Inc.)}}\
\pard\pardeftab720\sl500

\i\b\fs28 \cf2 Copyright\
\pard\pardeftab720\sl500

\i0\b0\fs30 \cf2 Copyright \'a9 2013 Google, Inc.\
\pard\pardeftab720\sl500

\i\b\fs28 \cf2 License\
\pard\pardeftab720\sl500

\i0\b0\fs30 \cf2 Apache 2.0\
\pard\pardeftab720\sl500

\i\b\fs28 \cf2 Limitations\
\pard\pardeftab720\sl500

\i0\b0\fs30 \cf2 This is example software, use with caution under your own risk.\
}