Gunther Oracle APEX und Datenbank Wiki

Diese Seite ist nicht editierbar. Sie können den Quelltext sehen, jedoch nicht verändern. Kontaktieren Sie den Administrator, wenn Sie glauben, dass hier ein Fehler vorliegt.
=====Oracle Apex 22.2.3 - APEX Mail Templates einsetzen - Wie meist sieht es viel einfacher aus als es am Ende ist  =====


**<fc #ff0000>Die Probleme mit der API:</fc>
**

**Große Probleme:**

**1)**
Mail Subject Text im Header von Outlook mit Umlauten wird nicht richtig dargestellt;
Mit neuen Templates nach dem Upgrade auf 22.2.3 erstellt, oder Template wurde aktualisiert.


{{ :prog:apex_umlaut_problem_mail_subject_22_2_3.png | Fehlerhafte Darstellung in APEX 22.2 }}

Das Text für das Feld "EMail Subject" Template dazu: **Dies ist das Newsletter äöo  subject - #MAIL_SUBJECT#**.

Der erste Teil des Strings diente nur dazu zu beweisen das Umlaute an sich übertragen werden können, das Problem also in dem Parsen von #MAIL_SUBJECT# liegen muss.


**2)**
Inline Images werden in der Apple Welt leider inline und dann nochmal als Anhang geöffnet angezeigt, in der MS Welt klappt es in Outlook aber perfekt.

**Kleine / keine Probleme**

**3)**
Wird das ganze über SQL*Developer/SQL*Plus getestet, muss zuvor eine APEX Session gesetzt werden. 
Nach dem ersten Aufruf eines Templates wird diese in der Session gecached und nicht mehr neu aus der Definition geladen. 
Das macht ja auch Sinn wenn eine große Anzahl von Mails versandt werden, diese nicht immer neu aus den Metadaten zu lesen.
Allerdings muss dann beachtet werden, das bei jeder Änderung man sich auch wieder aus- und einloggt um eine saubere neue Session zu erhalten, sonst wundert man sich warum sich in der Mail gar nichts verändert.



<fc #008000>**Lösung:**</fc>

Für alles gibt es eine Lösung...

**Zu 1)** 
Sogar relativ einfach, im Subjekt muss mit **!RAW** (#MAIL_SUBJECT!RAW#) verhindert werden das die Substitution nochmal geparst wird! 

**Zu 2)** 
Kurzfristig auf inline verzichten und mittelfristig Oracle nerven, das die Mail RFC kleinteilig besser umgesetzt wird.


**zu 3)** 
Das muss man einfach nur wissen, dann spart man sich etwas Zeit beim Verstehen warum Änderungen am Template nicht gleich sichtbar werden.

----

----

==== Voraussetzung ====


Anbindung E-Mail Relay, am besten verschlüsselt => [[prog:apex_mail_acl|Oracle Apex 5.0 Mail Versandt mit SSL -Hinterlegen einer ACL's in 11g und 12c und Hinterlegen von SSL Zertifkaten]]

Anzahl der Mails pro Tag auf Instance Ebene höher setzen, Default 1000, für produktive Umgebung meist zu klein.
Einstellung auf der APEX Instance:
{{ :prog:apex:apex_22_3_mail_versandt_instance_settings.png?600 | Mail Settings auf Instance Ebene}}


Prüfen ob der APEX Mail Job alle 5 Minuten auch wirklich regelmäßig zur erwarten Zeit läuft; Problem können zum Beispiel ein zu niedrige JOB_QUEUE Parameter Eintrag sein.




----




===== Der Weg zum Ziel =====


==== Mail Template in APEX anlegen ====

Ab Apex 22.3 scheint sich das Mail Template grundlegende geändert zu haben, alte Mail Templates unterstützen keine "Template Directives", mit diesen "Template Directives" kann zusätzliche Logik in das Templating (if then / else /case etc.) in so einer Art PHP Stil eingebettet werden.

Als Template kann ein reines Text Template hinterlegt werden oder auch ein komplexes HTML Template bei hohen Layout Anforderungen. Alternativ solle auch bei einem HTML Template der Texte Template Bereich gefüllt werden, kann der E-Mail Client keine HTML oder wurde das dort verboten, kann der E-Mail Client beim Empfänger auf TEXT zurückgreifen.

== Das besondere in >22.3 in der Subjekt Zeile==

Durch das interessante Feature "Template Directives" hat sich das Parsing Verhalten verändert. Per Default werden Umlaute nun in HTML Notation umgewandelt. Mit dieser kann der E-Mail Client aber nichts anfangen und zeigt keine Umlaute mehr an (siehe Screenshot oben).

Das betrifft nur neue oder nicht migrierte Templates und führt dazu das schnell ein halber Tag verbraucht wird weil die Umlaute nicht dargestellt werden im neuen Code, in der anderen App mit ähnlichen Code aber alles funktioniert.

D.H. im Subjekt muss mit !RAW (#MAIL_SUBJECT!RAW#) verhindert werden das die Substitution nochmal geparst wird-

Ist der Fehler erkannt ist er schnell gelöst, mit dem ! Syntax in Ersetzungsvariablen lässt sich der Text im Original ausgeben und das Problem ist behoben. Wäre schön wenn das in der Online Hilfe gestanden wäre, so Effekte dämpfen doch die APEX Begeisterung kurzfristig wieder sehr stark. 

Siehe dazu  Controlling Output Escaping in Substitution Strings  =>  https://docs.oracle.com/en/database/oracle/application-express/20.1/htmdb/understanding-substitution-strings.html#GUID-CA3ABA44-D03D-4396-A527-B160F1FFE933



=== Das HTML Template ===

Das HTML Template besteht aus mehreren Bereichen, auf die sich im Advanced Template dann wieder referenzieren läßt.

{{ :prog:apex:apex_22_3_mail_versandt_aufbau_advanced_mail_template.png?600 | APEX Mail Template - Zusammenhang der Verschiedenen Html Template Bereiche }}

Damit lässt sich das Template besser strukturieren.

Mit der APEX Methode pex_mail.send mit dem Parameter p_placeholders können nun die Platzhalter im Template über einen JSON Record mit allen Ersetzungstexten "ausgefüllt" werden.

Das funktioniert auch wie beschrieben; wie das aufgerufen werden muss wird im Template sogar generiert:
<code sql>
begin
    apex_mail.send (
        p_to                 => email_address_of_user,
        p_template_static_id => 'MYTEMPLATE',
        p_placeholders       => '{' ||
        '    "TITEL":' || apex_json.stringify( some_value ) ||
        '}' );
end;
</code> 

Wie das prinzipell funktioniert ist auf folgenden Seiten auch gut beschrieben:

  * https://srihariravva.blogspot.com/2020/09/including-images-in-oracle-apex-emails.html
  * https://tm-apex.hashnode.dev/summary-apex-mail-apex-mail-10

----


==== Inline Image in der Mail einbetten ====

Im nächsten Schritt war die Idee die Bilder in dem HTML Template in die Mail einzubinden, dann ist kein Nachladen von Bildern erforderlich und Datenschutz Einstellungen etc. sind nicht mehr so technisch wichtig.

Seit APEX 21.2 wird es auch etwas von APEX unterstützt, mit einen Einfachen Metoden Aufruf lassen sich Bilder in die E-Mail integrieren, die ID des Bildes wird zuvor mit eine eigenen Directive **src="cid:xxx"** refenziert.

Wie:
<code html>
<img src="cid:my_company.jpg" alt="Company Logo" >
</code>

Nun muss das Bild mit der ID my_company.jpg in der Mail eingebettet werden und dann kann oder kann auch nicht der E-Mail Client das richtig anzeigen.

Ob das wie gewünscht klappt wird leider im Zusammenspiel der Implementierung des ganzen in APEX und der Implementierung im Mail Klient ermittelt.

Die aktuelle Implementierung in APEX triff anscheinend recht gut die Interpretation des Standards dahinter im MS Outlook Client. 

Allerdings scheint dies wiederum nicht für den Standard E-Mail Client auf einen Apple Endgerät (Notebook/Smartphone) zutreffen. Die Inline Images werden zwar in der HTML ohne Fehler angezeigt, aber am Ende der Mail nochmals aufgelistet für den Download und erscheinen damit doppelt in der Mail. 

Die Protokolle für E-Mail sind schon relativ lange im Einsatz und wurden schon immer sehr variabel ausgelegt. Wer nun hier an welcher Stelle was tun muss das es am Ende geht, ist wohl auch nicht trivial.

Siehe dazu https://stackoverflow.com/questions/3902455/mail-multipart-alternative-vs-multipart-mixed , dort findet sich ein gutes Diagramm bzgl. der unterschiedlichen Reihenfolgen mit denen eine Multipart Message aufgebaut werden kann. 

Allerdings zeigen Tests mit Mail aus Apple Quellen, das es besser gehen kann, diese Mails mit Inline Images werden auf beiden System korrekt angezeigt.


Code zum Anbinden der Bilder, in dem Fall werden alle Bilder in einem Static Files Ordner an das Template gehängt:
<code sql>
..
IS
..
   cursor c_news_letter_images(p_app_id number)
   is
 	 select replace(filename,'newsletter_images/','') as filename
		  , blob_content
		  , mime_type
		  , replace(filename,'newsletter_images/','') as content_id
	 from apex_application_files
	where flow_id = p_app_id
	  and filename like 'newsletter_images/%';
..
begin



    for rec in c_news_letter_images(p_app_id => p_app_id)
	loop	 
		 apex_mail.add_attachment( 
			      p_mail_id      => v_mail_id
 				, p_attachment   => rec.blob_content
				, p_filename     => rec.filename
				, p_mime_type    => rec.mime_type
				, p_content_id   => rec.content_id     
			);
  end loop;
...
end;
</code>

siehe dazu => https://docs.oracle.com/en/database/oracle/apex/22.1/aeapi/ADD_ATTACHMENT-Procedure-Signature-1.html#GUID-5B514926-2C0A-40E3-82BB-7E357CB0C927


----
==== Attatchement anbinden ====


Über den Aufruf von "apex_mail.add_attachment" können dann Dateien der Mail hinzugefügt werden.

<code plsql>
..
IS
  cursor c_get_attachment(p_file_id number)
      is	  
	  select f.FILENAME
           , f.MIMETYPE
           , f.FILE_CONTENT
	   from DOK_FILES f 
          where f.ID = p_file_id ;

begin
..

     for file_rec in c_get_attachment( p_file_id => p_file_id )
     loop
          apex_mail.add_attachment(
                p_mail_id    => v_mail_id,
                p_attachment => file_rec.FILE_CONTENT,
                p_filename   => file_rec.FILENAME,
                p_mime_type  => file_rec.MIMETYPE);      
      end loop;         
  
...

end;
</code>
Siehe dazu => https://docs.oracle.com/en/database/oracle/apex/22.1/aeapi/ADD_ATTACHMENT-Procedure-Signature-2.html#GUID-0C43024A-D0B5-4358-A43E-8BF8FAD30E08






----
----
==== Ein generelles Beispiel ====

Hier ein Beispiel am Stück, ohne großes Logging und Exception Handling, in der Praxis würde das entsprechend optimiert in eine Package ausgelagert und mit logger erweitert.

<code sql>


declare
   -- get inline Images from Apex Static Resource
   cursor c_news_letter_images(p_app_id number)
   is
 	 select replace(filename,'newsletter_gpi/','') as filename
		  , blob_content
		  , mime_type
		  , replace(filename,'newsletter_gpi/','') as content_id
	 from apex_application_files
	where flow_id = p_app_id
	  and filename like 'newsletter_gpi/%';
  
    -- get PDF from application document store
    cursor c_get_attachment(p_file_id number)
      is	  
	  SELECT f.FILENAME
           , f.MIMETYPE
           , f.FILE_CONTENT
	   FROM GPI.DOK_FILES f 
          WHERE f.ID = p_file_id ;
	   
  v_mail_id        number; 
  v_workspace_id   number;
  v_placeholders   clob;

begin
    -- ------------------------------------------- 
    -- Set Apex Workspace ID and Security Group ID
    SELECT workspace_id
      INTO v_workspace_id
      FROM apex_applications
     WHERE apex_applications.application_id = (SELECT nvl(nv('APP_ID'),
                                                          250)
                                                 FROM dual); 
    apex_util.set_security_group_id(p_security_group_id => v_workspace_id);
    if nv('APP_ID') is null then
        apex_session.create_session(p_app_id                   => 250,
                                    p_page_id                  => 1,
                                    p_username                 => 'SYSTEM',
                                    p_call_post_authentication => FALSE);
    end if;
    
     -- ------------------------------------------- 
    -- Fill the Template Record with values for the template
    apex_json.initialize_clob_output;
    apex_json.open_object;
    apex_json.write('DATUM'        , '03.04.2023',true);        
    apex_json.write('ANREDE'       , 'Anrede',true);
    apex_json.write('MAIL_SUBJECT' , 'Ein Mail Subject mit ÄÖÜ und öäü',true);
    apex_json.write('MAIL_BODY'    , 'Ein Mail Text    mit ÄÖÜ und öäü',true);
    apex_json.close_object; 
    v_placeholders:=apex_json.get_clob_output;   
    apex_json.free_output;
    
     -- ------------------------------------------- 
     -- prepare the mail
     v_mail_id:=apex_mail.send (
          p_to                 => 'info@pipperr.de'
        , p_template_static_id => 'NEWSLETTER'
        , p_application_id     => 250
        , p_from               => 'info@pipperr.de'
	, p_placeholders       => v_placeholders		
	);
 
     -- ------------------------------------------- 
     -- add inline images
     -- Rec.content_id value must match cid:content_id in HTML Template
     --
    for rec in c_news_letter_images(p_app_id => 250)
	loop	 
		 apex_mail.add_attachment( 
			      p_mail_id      => v_mail_id
				, p_attachment   => rec.blob_content
				, p_filename     => rec.filename
				, p_mime_type    => rec.mime_type
				, p_content_id   => rec.content_id     
			);
	end loop;
	
	
    -- ------------------------------------------
	-- add Attachment
	for file_rec in c_get_attachment( p_file_id => 56)
	loop
          apex_mail.add_attachment(
                p_mail_id    => v_mail_id,
                p_attachment => file_rec.FILE_CONTENT,
                p_filename   => file_rec.FILENAME,
                p_mime_type  => file_rec.MIMETYPE);      
      end loop;         
  
    
    --
    commit;
 
    -- ------------------------------------------
	-- sent mail now
    apex_mail.push_queue;
end;
/


</code>



----

==== APEX Mail überwachen ====

<code sql>
 select * from apex_mail_queue;
</code>


----

==== Mail Log löschen ====

Mit der Zeit häufen sich die Logs, das Log Handling wiederum erfolgt auf Instance Ebene.
Allerdings finde ich dort keine Möglichkeit für das Mail Log.

Auch in der Doku https://docs.oracle.com/en/database/oracle/apex/22.1/aeadm/configuring-and-deleting-logs-and-log-entries.html#GUID-FAD74DA3-B34A-4E69-B18B-48E6023B1F3D wird das nicht erwähnt.


Praktisch kann aber auch einfach die Tabelle direkt gelöscht werden.

<code plsql>
set serveroutput on

set serveroutput on

declare
 -- ========================================
 -- APEX Mail Log Handling
 -- ========================================
  
 v_username   varchar2(32);
 v_sql        varchar2(4000); 
 v_delete_count pls_integer:=0;
  
 -- ========================================
 -- setze auf 0 um die Tabelle abzuschneiden
 -- x Tage aufbewahren 
 v_keep_days    pls_integer:=31;
 -- ========================================
  
begin
   
   v_sql:='delete from #USER#.WWV_FLOW_MAIL_LOG where MAIL_MESSAGE_SEND_END < (sysdate -#KEEP_DAYS#)';
  
  -- hole den aktuellen aPEX Owner aus der DB
  select max(username) 
   into v_username
   from dba_users 
  where regexp_like(username,'^APEX_[[:digit:]].*');

 
  
  if v_keep_days > 0 then
 
      dbms_output.put_line('-- Info :: Lösche Mail Logs aus WWV_FLOW_MAIL_LOG vom User '|| v_username ||' älter als '|| v_keep_days ||' Tage');   
      
      v_sql:=replace(v_sql,'#USER#',v_username);
      v_sql:=replace(v_sql,'#KEEP_DAYS#',to_char(v_keep_days));
      
      dbms_output.put_line('-- Info :: Lösche mit '||v_sql);

      execute immediate v_sql;
      
      v_delete_count:=SQL%ROWCOUNT;
      
     commit;
     
     dbms_output.put_line('-- Info :: Anzahl gelöschter Zeilen '|| v_delete_count);  
  
  else
     dbms_output.put_line('-- Info :: Tabelle WWV_FLOW_MAIL_LOG wird mit Truncate gelöscht');
     
	 v_sql:='truncate table '|| v_username ||'.WWV_FLOW_MAIL_LOG drop storage';  
     execute immediate v_sql;
     
	 dbms_output.put_line('-- Info :: Tabelle WWV_FLOW_MAIL_LOG komplett mit Truncate gelöscht');
  end if;
  
exception 
 when others then 
   dbms_output.put_line('-- Error :: Fehler mit '|| v_sql || ' SQLERR Meldung '||SQLERRM);
end;
/

</code>


----

==== Quellen ====


Oracle:
  * https://docs.oracle.com/en/database/oracle/apex/22.1/aeapi/APEX_MAIL.html#GUID-14F51C6D-CB82-4B38-AB6E-61C46E75596F
  * https://docs.oracle.com/en/database/oracle/application-express/20.1/htmdb/understanding-substitution-strings.html#GUID-CA3ABA44-D03D-4396-A527-B160F1FFE933


Web:
  * https://stackoverflow.com/questions/3902455/mail-multipart-alternative-vs-multipart-mixed
  * https://srihariravva.blogspot.com/2020/09/including-images-in-oracle-apex-emails.html
  * https://tm-apex.hashnode.dev/summary-apex-mail-apex-mail-10
  * http://www.oneoracledeveloper.com/2021/11/creating-apex-session-from-plsql.html