Generare un'email schedulata

Abstract

• Introduzione
• Requisiti per affrontare il tutorial
  • Conoscenze
  • Permessi
• Dipendenze
  • env_conf.ps1
  • GenerateRowLink.ps1
  • SqlConnection.ps1
  • GetRows.ps1
  • SendEmail.ps1
  • Baseline.Common.Management.dll
  • Template.html
• Script Powershell Commentato
• Pianificare il Job per il Powershell

Introduzione

Verifica i requisiti

Controlla la sezione Requisiti per affrontare il tutorial per verificare se hai le conoscenze e i permessi d'amministrazione richiesti per completare il tutorial.

Inoltre, hai bisogno dei seguenti file per il tutorial:

• env_conf.ps1
• GenerateRowLink.ps1
• SqlConnection.ps1
• GetRows.ps1
• Baseline.Common.Management.dll
• SendEmail.ps1
• Template.html

Clicca qui per scaricare l'archivio che contiene i file. La sezione Dipendenze spiega ciascun file.

Questo tutorial ti insegna passo dopo passo a creare una email programmata che contiene le righe della settimana e i relativi link grazie a uno script Powershell. Questo tutorial prende com esempio il seguente caso d'uso: un utente necessità di un promemoria email settimanale che elenchi tutte le righe registrate negli ultimi 7 giorni; ciascuna voce della mail deve avere un link che conduca alla riga nell'applicazione.

Tutte le dipendenze sono pronte e devi solo capire come lo script commentato d'esempio funziona. Dopodiché potrai usare lo stesso script come template per le tue necessità.

Prima di cominciare, controlla se hai le conoscenze necessarie nella sezione Requisiti per affrontare il tutorial. Questo tutorial da per scontato questi requisiti durante la spiegazione.

Example

Il tutorial considera il seguente caso d'uso per spiegare come creare email ricorrenti tramite Powershell.

Hai un'applicazione eLegere chiamata Invoices.

Un utente ricevere un'email settimanale che elenca tutte le fatture emesse nell'ultima settimana. La lista deve contenere anche un link alla riga della fattura nell'applicazione Invoices.

In questo modo, l'utente può controllare le righe create l'ultima settimana e vederle nell'applicazione tramite il link.

In questo tutorial, seguirai 4 passaggi:

1. Scompattare tutte le dipendenze per eseguire lo script nella cartella dedicata agli script Powershell.
2. Aggiungere informazioni richieste nel file di configurazione env_conf.
3. Cambiare le impostazioni richieste nello script Powershell.
4. Configurare dentro eLegere un'azione Powershell Script nello Scheduler.

Requisiti per affrontare il tutorial

Leggi la lista richiesta di conoscenze e permessi d'amministrazione per l'installazione eLegere.

Se soddisfi i requisiti sotto, puoi affrontare il tutorial.

Conoscenze

Il tutorial da per scontato le seguenti conoscenze:

• Powershell: Una conoscenza basilare è richiesta per comprendere lo script. Qualsiasi guida introduttiva è abbastanza per campire il contenuto del tutorial.
• Transact SQL: Una conoscenza basilare è richiesta per comprendere una parte dello script. Qualsiasi corso introduttivo a Transact SQL è sufficiente per questo tutorial.
• HTML: Una comprensione basilare dell'HTML è richiesta. Il template HTML fornito in questo tutorial come esempio è semplice, ma richiede una comprensione minima di cosa sia l'HTML. Qualsiasi guida introduttiva sarà sufficiente.

Permessi

Devi avere accesso FTP a:

• La macchina di front end dell'installazione eLegere. (Il tuo amministratore sa cos'è la macchina di front end e ti daranno accesso.)
• Al percorso che conserva gli script Powershell sulla macchina di front end. (Tutti gli script personalizzati sono custoditi nella cartella del percorso deciso dall'amministratore. Devi avere accesso a questa cartella.) Il tutorial la chiamerà cartella dei Powershell.

Inoltre, hai bisogno del permesso Scheduler Management dal tuo amministratore nel Dominio in cui vuoi configurare la notifica email.

Richiedi i permessi sopra all'amministratore della tua installazione eLegere.

Dipendenze

Warning

Lo script Powershell alla sezione Script Powershell Commentato richiede tutte le dipendenze fornite per funzionare. Non posizionare i file richiesti dove specificato causa errori durante l'esecuzione dello script.

Per favore, scarica l'archivio con le dipendenze e segui le istruzioni.

Il tutorial richiede di posizionare nella cartella dei Powershell le dipendenze già pronte che puoi scaricare qui. Scaricherai un archivio che contiene tutto quello che serve per eseguire lo script.

Devi posizionare le due cartelle delle dipendenze Common, Library e Templates nella cartella dei Powershell (vedi Permessi).

La cartella dei Powershell deve avere la seguente struttura dopo aver decompresso l'archivio.

.
├── Common/
│   ├── env_conf.ps1
│   ├── generateRowLink.ps1
│   ├── GetRows.ps1
│   ├── GetSqlConnection.ps1
│   └── SendEmail.ps1
├── Library/
│   └── Baseline.Common.Management.dll
└── Templates/
    └── Template.html

Leggi cosa fa ciascuna dipendenza. Non devi conoscere tutti i dettagli ma avere un'idea basilare di cosa facciano.

env_conf.ps1

env_conf.ps1 è uno script che contiene delle configurazione di cui hai bisogno per lo script Powershell principale.

Perché un file di configurazione separato?

Se hai svariati script Powershell che richiedono gli stessi parametri per setting email, credenziali e Connection String, è utile avere un file separato. Avere un file separato permette di aggiornare tutte le impostazioni condivise senza cambiare ciascuno script manualmente.

Devi configurare alcune impostazioni nel env_conf.ps1 prima di preparare lo script. Leggi i commenti per capire quali parametri devi digitare in ciascuna variabile.

<# 
    env_conf contiene una funzione che crea un oggetto.
    L'oggetto contiene tutte le informazioni per connettersi al database SQL e alla configurazione
    email.
    I valori nello script sono esempi. Sostituisci con i valori forniti dal tuo amministatore.
#>

<# 
    La funzione incapsula tutte le informazioni relative alle connessioni, 
    all'SMTP email e alla cartella Share della tua installazione eLegere in un oggetto.
#>

function getConf(){
$confProperties = @{

    <# 
        SqlConnectionString = La Connection String per collegarsi alla macchina con il database. 
        Chiedi al tuo amministratore. 
    #>

    SqlConnectionString = "[Inserire qui la Connection String.]" 

    # HostBaseUrl = Your eLegere's installation URL 

    HostBaseUrl         = "https://myserver.com/" 

    # Chiave d'accesso segreta per accedere a HostBaseUrl. Chiedi al tuo amministratore.

    HostSecretKey       = "[Inserire qui la chiave d'accesso.]"

    #  I parametri dell'SMTP che invierà la mail

    MailServer          = "[Inserire qui il server STMP.]" 
    MailPort            = 587
    MailEnableSSL       = $true
    MailUsername        = "your.email@provider.com"
    MailPassword        = "[Inserire qui la password.]"
    MailFrom            = "[Inserire qui la email del mittente.]"

    # Lo schema del database eLegere.

    CommonSchema        = "[Inserire lo schema del database SQL.]"

    <# 
        Cartella che contiene la dipendenza Baseline.Common.Management.dll 
        Non devi cambiare il nome se hai decompresso l'archivio allegato al tutorial.
    #>

    LibrariesFolderName = "Libraries"
}

# La funzione crea un oggetto Powershell che contiene tutte le informazioni richieste e le ritorna.

$conf = New-Object -TypeName psobject -Property $confProperties
return $conf
}

GenerateRowLink.ps1

Questo script Powershell richiama e applica la funzione =GENERATEROWLINK(), permettendo di usarla tramite un metodo dedicato.

SqlConnection.ps1

Questo script Powershell fornisce tutti i metodi per connettersi alla macchina che ospita il database SQL.

GetRows.ps1

Questo script Powershell fornisce tutti i metodi per inoltrare una query al database e recuperare le righe che ti servono.

SendEmail.ps1

Questo script Powershell fornisce il metodo per configurare un'email personalizzata.

Baseline.Common.Management.dll

Un file di librerie personalizzate per eseguire alcune azioni dall'installazione eLegere.

Template.html

Il template che lo Script Powershell Commentato compilerà e formatterà con le righe recuperate.

Il layout apparirà nella email. Lo Script Powershell Commentato riempirà la componente _TABLE_ nell'HTML.

Tip

Puoi cambiare Title e Subtitle secondo le tue esigenza. Modifica le intestazioni nell'HTML.

Script Powershell Commentato

Questa sezione commenta ciascuna parte dello script Powershell principale (SendScheduledEmailWithRows.ps1) che genererà la tua email con la lista delle righe e i link all'applicazione

Cambia ciò che i commenti indicheranno secondo le impostazioni fornite dal tuo amministratore.

# Recupera la locazione della cartella dei Powershell e la assegna a una variabile.

$scriptPath = (Get-Location).Path

# Importa le dipendenze dalla cartella Common. Chiamera i metodi da questi file .ps1

. $scriptPath\Common\env_conf.ps1
. $scriptPath\Common\GetSqlConnection.ps1
. $scriptPath\Common\GetRows.ps1
. $scriptPath\Common\generateRowLink.ps1
. $scriptPath\Common\SendEmail.ps1

# Acquisice dalla cartella Templates l'HTML da riempire cone le righe.

$template=Get-Content -Path $scriptPath\templates\Template.html

# Recupera l'oggetto generato dalla funzione in env_conf.ps1

$conf = getConf

# La funzione converte la data numerica di 12 cifre in un formato leggibile.

function convertDate($numericDate){

    return $numericDate.Substring(6,2)+'/'+$numericDate.Substring(4,2)+'/'+$numericDate.Substring(0,4)

}

<# 
    La funzione per creare la tabella HTML dalle righe recuperate per il template.
    Accetta come argomenti la lista delle righe e un dizionario contenente un mappa
    di ciascuna riga e del relativo link ($links). La funzione main creerà questo dizionario. 
#>

function createTable($rows,$links){

    # Prepare l'HTML dell'intestazione della tabella con i nomi dei campi.

    $table =  "
        <style>
        {font-family: Helvetica; font-size: 10pt;}
        TABLE{border: 1px solid black; border-collapse: collapse; font-size:11pt;}
        TH{border: 1px solid black; background: #d6feff; padding: 5px; color: #1c4d8a; font-size:13pt;}
        TD{border: 1px solid black; padding: 5px;}
        </style>
        <table>
        <tr>
        <th>Invoice ID</th>
        <th>CustomerName</th>
        <th>EmissionDate</th>
        <th>Item</th>
        <th>Quantity</th>
        <th>UnitPrice</th>
        <th>VAT</th>
        <th>Total</th>
        </tr>
    "

    <# 
        $rows contiene i campi da riportare e formatte nel template HTML.
        foreach ripere l'operatione per ciascuna riga recuperata dalla query. 
    #>

    $rows |foreach {  

        # Lo script arrotonda i prezzi e formatta Data e IVA prima di posizionarli nell'HTML.

        $openedDate = convertDate($_.EmissionDate.ToString())
        $convertedPercentage =  $_.VAT.ToString("P")
        $roundedTotal = [math]::Round($_.Total, 2)
        $roundedUnitPrice = [math]::Round($_.UnitPrice, 2)        

        <# 
            Formatta i campi delle righe in HTML sostituendo i valori all'interno 
            della stringa $tablerow. Ciascuna variable corrisponde al campo della tabella. 
            La funzione piazza l'URL della riga conservato del dizionario $link all'interno del campo. 
            In questo modo, l'ID è cliccabile e conduce alla riga nell'applicazione.
        #>

        $tableRow = " 
            <tr>
            <td style='text-align:center;'><a href="""+$links[$_.IdEntry]+""">"+$_.IdEntry+"</a></td>
            <td>"+$_.CustomerName+"</td>
            <td>"+$openedDate+"</td>
            <td style='text-align:center;'>"+$_.Item+"</td>
            <td style='text-align:center;'>"+$_.Quantity+"</td>
            <td style='text-align:center;'>"+$roundedUnitPrice+"&#8364</td>
            <td style='text-align:center;'>"+$convertedPercentage+"%</td>
            <td style='text-align:center;'>"+$roundedTotal+"&#8364</td>
            </tr>
        "

        # Ciascuna riga formattata in HTML è registrata in ordine di inserimento nella variable $table

        $table += $tableRow 
    }

    <# 
        Dopo avere iterato l'operazione su tutte le righe,
        la funzione ritorna la variable che contiene la tabella HTML 
        formattata con tutte le righe.
    #>

    return $table
}

# La funzione sostituisce l'elemento _TABLE_ nell'HTML con le righe formattate.

function addTemplate($table){
    return $template.Replace("__TABLE__",$table)
}

<#
    Aggiunta di ulteriori parametri di configurazione che non sono comuni ai vari script.

    Questo è il motivo per cui sono stati scritti qui invece che in env_conf
    env_conf contiene solo le impostazioni comuni a tutti gli script personalizzati.

    Impostazioni che cambiano da app ad app sono l'Id dell'applicazione (application Id), 
    il Soggetto della mail,  l'Id dell'applicazione (applicationId) o lo schema della tabella SQL.

    Modifica i valori in base al tuo database, applicazione e account email.
#>

$applicationId="02b28572-d66c-467b-a8f8-2046755b097c"
$schema="finance001"
$tableName="TBL_INVOICES"
$appBusinessKey = "IdEntry"
$toEmail="your.email@email.com"
$mailSubject="Promemoria settimanale | Invoices"
$commonSchema=$conf.CommonSchema

<# 
    Definisce la variabile che contiene la stringa con la query SQL.
    Usa [elegere].[F_APP_BIGINT2DATETIME] per convertire il valore di un campo Date
    in un formato che puoi usare per comparare altri valori

    Cambia la query in base alla tue necessità.
    Lo script recupera lo schema del database da env_conf ($commonSchema)
#>

$rowsQuery = "          
    SELECT * FROM [$schema].TBL_INVOICES WHERE [$commonSchema].[F_APP_BIGINT2DATETIME](DT_CREATION)>=DATEADD(d,-7,GETDATE());
"

<# 
    Questa è la funzione princiaple che lo script eseguirà. 
    Richiama la funzione definita sopra e i metodi dalle dipendenze 
    Powershell nella cartella Common. 
#>

function main() {

    # Ottiene la ConnectioN String dall'oggetto fornito da env_conf.ps1

    $connection=getSqlConnection $conf.SqlConnectionString

    # Apre la connessione a SQL.

    $connection.Open()

    # Tenta ti ottenere le righe che soddisfano la query dalla variable $rowsQuery e formattare la mail.

    try
    {
        # Recupera le righe secondo la query della variable $rowsQuery.

        $rows = GetRows $connection $rowsQuery

        # Un dizionario che registrerà per ciascun Id di riga il link corrispondente.

        $rowLinks=@{}

        <# 
            Applica la funzione Formula =GENERATEROWLINK() 
            a ciascuna rifa e registra l'URL nel dizionario $rowLinks. 
        #>

        $rows |foreach{
            $link=GenerateRowLink $connection   $conf.HostBaseUrl  $applicationId  $conf.HostSecretKey $schema $tableName "IdEntry" $_.IdEntry
            $rowLinks.Add($_.IdEntry,$link)
        }

        # Usa la funzione createTableRow per creare la tabella con le righe.

        $rowsTable=createTable $rows $rowLinks

        # Prende il template HTML e rimpiazza  _TABLE_ con la tabella formattata contenente le righe.

        $emailBody=addTemplate $rowsTable

        <# 
            Genera la notifica email dal testo HTML formattato e lo invia. 
            Richiede i parametri che contengono le informazioni per connettersi 
            al SMTP e inviare la mail.
        #>

        sendEmail $conf.MailServer $conf.MailPort $conf.MailEnableSSL $conf.MailUsername $conf.MailPassword $conf.MailFrom $toEmail $mailSubject $emailBody

        # Ritorna un messaggio di conferma per l'utente nel Log.

        $message = @{
            Message = "Success"
            ReturnCode = "200"
          }
          $result = New-Object psobject -Property $message
        }
    # Se accade un eccezione, lo script riporta il messaggio di errore nel Log.
    catch [Exception] 
    {
        echo $_.Exception.Message
        $message = @{
            Message = $_.Exception.Message
            ReturnCode = "500"
          }
        $result = New-Object psobject -Property $message
    }
    # Qualunque sia il risultato, chiude la connessione con SQL.
    finally 
    {
        $connection.Close()
        $connection.Dispose()

    }
    return $result
}

# Lancia la funzione 'main'.

main

Salva lo script nella cartella dei Powershell. Scegli un nome per il file *.ps1., per esempio SendScheduledEmailWithRows.ps1.

La cartella dei Powershell dovrebbe apparire come segue.

.
├── Common/
│   ├── env_conf.ps1
│   ├── generateRowLink.ps1
│   ├── GetRows.ps1
│   ├── GetSqlConnection.ps1
│   └── SendEmail.ps1
├── Library/
│   └── Baseline.Common.Management.dll
├── Templates/
│   └── Template.html
└── SendScheduledEmailWithRows.ps1

Il prossimo passo è configurazione il lancio dello script nello Scheduler dentro eLegere.

Pianificare il Job per il Powershell

Hai configurato lo script Powershell che eLegere eseguirà. Adesso, devi configurare l'azione pianificata nello Scheduler che lancerà lo script.

Example

L'utente deve ricevere la notifica email con una certa regolarità. Nel caso d'uso considerato, una volta a settimana.

Segui i passi in Come programmare un'azione o notifica a una Data e Ora specifici per creare un'azione Powershell Scriptnello Scheduler.

Una volta creata l'azione, segui i passaggi sotto per configurare tutte le impostazioni richieste nella finestra Add Job per selezionare lo script Powershell.

1. Personalizza le seguenti impostazioni

   

   • (1) Scegli un nome per l'azione (Name)
   • (2) Scegli il tipo Recurring e spunta Enabled
   • (3) Scegli come frequenza Weekly e il giorno un cui vuoi ricevere la mail (e.g. Venerdì)
   • (4) Scegli l'orario in cui vuoi ricevere la mail.

2. Nella tab Powershell Script Composer, specifica il file dello script Powershell da eseguire dalla cartella dei Powershell.

   

3. Clicca sul pulsante Confirm.

Riceverai una notifica email ogni Venerdì che ti informare degli ultimi inserimenti. Cliccare sull'Invoice ID aprirà un link alla riga nell'applicazione.

Success

Riceverai ogni settimana una mail con il sommario delle righe inserite e il link per visualizzarle singolarmente nell'applicazione.

Puoi usare lo stesso script e dipendenze per differenti applicazioni: cambia il valori delle variabile dove richiesto (e.g. la query SQL) o sostituisci il template HTML per plasmare l'esempio sulle tue esigenze.