Spreadsheets Add-on: Webtrends (custom reports generator)

Lingue disponibili per le linee guida (guidelines available languages): ITALIANO - ENGLISH

Add-on Webtrends: linee guida
________________________________________

Come è noto, la richiesta di report su Webtrends non produce una risposta in tempo reale. Con l'Add-on per Spreadsheet 'Webtrends' (Webtrends custom reports generator) è possibile interrogare le API di Webtrends senza preoccuparsi di verificare l'effettiva generazione dei risultati in quanto vengono comodamente recuperati in modo automatico e salvati all'interno di fogli dedicati dello Spreadsheet utilizzato.

- Riferimento per l'uso
La presente pagina ha lo scopo di essere il riferimento per le linee guida d'uso per il componente aggiuntivo dei Fogli di Google in questione nonché adibita per la segnalazione di eventuali problemi (per i quali invito ad utilizzare i commenti a fine pagina).

- Installazione
Da uno Spreadsheet selezionare la voce di menu 'Componenti aggiuntivi -> Installa componenti aggiuntivi...', nella schermata che si aprirà cercare nella casella di ricerca il termine 'webtrends' e cliccare sull'elemento con nome 'Webtrends' (Fig. 1), installarlo cliccando su '+ GTRATIS' scegliendo l'account sul quale abilitarlo nella successiva finestra che si aprirà (acconsentendo poi alle autorizzazioni richieste).
Nel menu 'Componenti aggiuntivi' dello Spreadsheet l'Add-on diventerà disponibile.

Fig. 1 - Webtrends, custom reports generator: add-on per Spreadsheet

- Funzionamento
I passaggi preliminari al primo avvio, per iniziare ad utilizzare subito l'add-on, sono i seguenti:

1) Inserire le credenziali utilizzate per accedere a Webtrends (Infinity, Analytics 10), Fig. 2, dalla voce di menu Componenti aggiuntivi » Webtrends » Manage credentials
Nota: nessuna informazione verrà divulgata, le credenziali rimarranno riservate e legate all'utente che ne fa uso

Fig. 2 - Add-on Webtrends - gestione credenziali

2) Creare un nuovo report, Fig. 3, dalla voce di menu Componenti aggiuntivi » Webtrends » Create new report fornendo le informazioni richieste quali: Account ID, Report ID, data di inizio, data di fine ed il nome che si intende dare al report nonché modificando all'occorrenza le altre opzioni preselezionate (timezone, mostra il totale ed il limite per la prima dimensione):

Fig. 3 - Add-on Webtrends - creare un nuovo report

E' possibile richiedere più di un report ad ogni esecuzione, ovvero lanciarli in contemporanea, purché i relativi nomi, che saranno i nomi dei fogli del documento, siano diversi.
Se non è presente il foglio Report Configurator quest'ultimo verrà creato la prima volta che si clicca su Create report.

3) Eseguire i report, dalla voce di menu Componenti aggiuntivi » Webtrends » Run reports

Dopo aver effettuato il Run verranno generati i vari fogli (qualora non fossero già presenti) relativi ai nomi dei report indicati nei quali verrà mostrato il relativo risultato una volta che il report è stato generato da Webtrends mostrando Done come Status della generazione.
Per i nuovi report interrogati è previsto un lasso di tempo di attesa affinché Webtrends generi il risultato, in tal caso, lo Status di esecuzione sarà Running...; a questo punto l'add-on si occuperà autonomamente di verificare (ogni 2 minuti) la disponibilità del risultato per mostrarlo nell'opportuno foglio dello Spreadsheet, a quel punto lo Status verrà aggiornato a Done.
In caso di configurazione errata, incompleta o di nomi di report duplicati verrà evidenziato un messaggio di errore (rispettivamente Configuration error!, Incomplete configuration!, Duplicate name!).
Per l'errore Configuration error! è possibile visualizzare, all'interno del foglio per il quale il report ha restituito l'errore, il dettaglio dell'errore ricevuto fornito direttamente da Webtrends, di seguito alcuni esempi:

Not found: può essere restituito quando l'Account ID non è corretto.
null: può essere restituito quando l'Account ID è corretto ma non lo è il Report ID.
'begin' may not be after 'end': nel caso in cui la data di inizio indicata è superiore alla data di fine
xyz is not a valid list of integers greater than zero: se si aspetta un numero e gli è stata fornita una stringa con caratteri non numerici
The supplied authentication is invalid: quando le credenziali di accesso non sono corrette.

Il riepilogo al termine dell'esecuzione manuale dei report risulterà simile al seguente, Fig. 4:

Fig. 4 - Add-on Webtrends - riepilogo esecuzione report

I report con Status uguale a Done mostreranno, oltre alla data e l'ora della loro ultima esecuzione, il risultato delle dimensioni e metriche interrogate (Fig. 5) sul quale è possibile effettuare le dovute operazioni, ad esempio calcoli personalizzati o visualizzazione dei dati in formato grafico:

Fig. 5 - Add-on Webtrends - Risultato dell'estrazione di un report

Tramite la voce di menu Componenti aggiuntivi » Webtrends » Schedule reports è possibile programmare l'esecuzione automatica dei report potendo configurare l'avvio basato sul tempo: ogni ora oppure ad una determinata ora di ogni giorno oppure ad una determinata ora di un determinato giorno della settimana oppure ad una determinata ora di uno specifico giorno di ogni mese.

- Termini di servizio
L'add-on è gratuita ed il suo utilizzo è a piena responsabilità dell'utente che ne fa uso.

- Log versioni
2018/05/06 - v3: migliorata l'usabilità dell'interfaccia per la gestione delle credenziali e per la comunicazione degli errori di esecuzione dei report
2018/05/02 - v2: aggiunta la funzionalità per la programmazione automatica dell'esecuzione dei report
2018/04/25 - v1: versione di lancio

Add-on Webtrends: guidelines
________________________________________

As is known, the report request on Webtrends does not produce a real-time response. With the Spreadsheet Add-on 'Webtrends' (Webtrends custom reports generator) it is possible to query the Webtrends API without worrying about checking the actual results generation as they are conveniently recovered automatically and saved in dedicated sheets of the Spreadsheet used.

- Reference for use
This page is the reference for the guidelines for this add-on (Webtrends) of the Google Sheets and is also used to report any problems (leaving a comment at the end of the page).

- Installation
From a Spreadsheet select the menu item 'Add-ons -> Install add-ons ...', in the screen that will open write in the search box the term 'webtrends' and click on the element with the name 'Webtrends' (Fig. 1 ), install it by clicking on '+ FREE' choosing the account on which to enable it in the next window that will open (consenting then to the required permissions).
In the Spreadsheet 'Add-ons' menu the Add-on will become available.

Fig. 1 - Webtrends, custom reports generator: add-on for Spreadsheet

- How it works
The preliminary steps for the first start are the following:

1) Enter the credentials used to access Webtrends (Infinity, Analytics 10), Fig. 2, from the menu item. Add-ons » Webtrends » Manage credentials
Note: no information will be disclosed, the credentials will remain confidential and linked to the user who uses it

Fig. 2 - Add-on Webtrends - manage credentials

2) Create a new report, Fig. 3, from the menu item Add-ons » Webtrends » Create new report providing the required information such as: Account ID, Report ID, start date, end date and the name you want to give to report as well as changing the other pre-selected options (timezone, shows the total and the limit for the first dimension):

Fig. 3 - Add-on Webtrends - create new report

3) Run the reports, from the menu item Add-ons » Webtrends » Run reports

After running the report will generate the various sheets (if they were not already present) related to the names of the reports in which the result will be shown once the report was generated by Webtrends showing Done as the status of the generation.
For the new queried reports there is a waiting period for Webtrends to generate the result, in which case, the execution Status will be Running...; at this point the add-on will autonomously check (every 2 minutes) the availability of the result to show it in the appropriate sheet and the Status will be updated to Done.
In case of incorrect, incomplete configuration or duplicate report names an error message will be highlighted (respectively Configuration error!, Incomplete configuration!, Duplicate name!).
For the error Configuration error! you can view, in the sheet for which the report has returned the error, the detail of the error received directly from Webtrends, here are some examples:

Not found: may be returned when the Account ID is incorrect.
null: may be returned when the Account ID is correct but the Report ID is incorrect.
'begin' may not be after 'end': in case the start date is higher than the end date.
xyz is not a valid list of integers greater than zero: if the API wait for a number and have been given a string with non-numeric characters.
The supplied authentication is invalid: when the login credentials are incorrect.

The summary at the end of the manual execution of the reports will be similar to the following, Fig. 4:

Fig. 4 - Add-on Webtrends -summary of the execution of the reports

The reports with Status equal to Done will show, in addition to the date and time of their last execution, the result of the requested dimensions and metrics (Fig. 5) on which it is possible to carry out the necessary operations, for example custom calculations or data visualization in graphic format:

Fig. 5 - Add-on Webtrends - Report result

You can schedule the automatic execution of reports through the menu item Add-ons » Webtrends » Schedule reports to configure the execution based on time: every hour or at a specific time for each day or at a specific time of a specific day of each week or at a specific time on a specific day of each month.

- Terms of service
The add-on is free and all responsibility of use is delegated to the user.

- Log versions
2018/05/06 - v3: improved usability of the interface for the management of credentials and communication of errors in the execution of reports
2018/05/02 - v2: added functionality for automatic programming of the execution of reports
2018/04/25 - v1: launch version

Scopes:

https://www.googleapis.com/auth/script.external_request
Allows the project to make UrlFetch requests to call Webtrends API

https://www.googleapis.com/auth/script.container.ui
To show add-on menu

https://www.googleapis.com/auth/script.scriptapp
To store add-on parameters and manage triggers

https://www.googleapis.com/auth/spreadsheets
To read data from and write data to user’s Spreadsheet