Dienstag, 24. Februar 2015

Oracle Managed Files Handson Tutorial



Dieses Tutorial soll durch die ersten Schritte mit dem neuen Oracle Managed File Transfer (MFT) helfen. Als Voraussetzung wird eine installierte SOA-Suite mit MFT benötigt, der grundsätzliche Umgang mit der SOA-Suite sollte bekannt sein. Betriebssystemseitig wurde Oracle Linux benutzt, das Ganze funktioniert aber analog auch unter Windows.

Freitag, 20. Februar 2015

Oracle Managed File Transfer (MFT) Handson - Teil 4: Integration mit der SOA Suite

[Teil 1] [Teil 2] [Teil 3] [Teil 4] 

Nutzt man sowohl MFT, als auch die SOA-Suite, dann macht es Sinn diese miteinander zu integrieren. So kann die SOA-Suite Daten auch direkt an MFT übergeben und dieses kümmert sich dann um die Weiterverteilung im Dateisystem. Umgekehrt kann die SOA-Suite auch Ziel einer MFT-Transaktion sein und die Inhalte direkt entgegennehmen.
Für dieses Beispiel wird eine Domain mit MFT und SOA Suite benötigt. Der grundsätzliche Umgang mit beiden Produkten sollte bekannt sein.


Los geht es auf der Design-Seite der MFT-Console. Hier wird eine neue Source vom Typ SOA angelegt, z.B. mit dem Namen service-source (Wichtig: der Name soa wie abgebildet führt später zu Problemen und sollte nicht verwendet werden).


Als nächstes wird ein Transfer angelegt und die eben erstellte service-source als Quelle eingetragen. Als Target wird ein beliebiges File Target genommen, z.B. das file-target aus Kapitel 3.
Zum Abschluss werden mit Klick auf Save und Deploy die beiden neuen Artefakte deployed.


Weiter geht es im JDeveloper mit einem neuen SOA-Projekt.


In das Composite wird rechts bei den References ein MFT-Adapter gezogen.


Der Default kann übernommen werden.


Hier auch einfach den Default belassen.


Hier wird die bestehende Application-Server Connection angegeben, oder ggf. neu angelegt. Der MFT Server wird dann automatisch gefunden. Per Klick auf Test MFT lässt sich die Verbindung überprüfen.


Die service-source wird automatisch gefunden, beenden mit Finish.


Um den MFT Adapter anzusprechen, wird ein BPEL-Prozess in das Composite gezogen. Dieser wird auf Synchronous BPEL Process umgestellt, der Rest kann so bleiben.


Der BPEL-Prozess wird mit dem MFT-Adapter verbunden und hinterher per Doppelklick geöffnet.


Im Prozess wird mittig eine Invoke-Aktivität platziert und diese mit dem MFT Partner Link verbunden.


Die Input- und Output-Variable wird jeweils über das grüne Plus (+) angelegt. Dann mit OK schließen.


Es wird noch eine Assign-Aktivität benötigt, die vor das Invoke gezogen wird. Diese wird per Doppelklick geöffnet.


ns1:InlinePayload bekommt per Rechtsklick eine Expression zugewiesen.


Passend zum jeweiligen Bundesland kann hier eine angemessene Begrüßung zusammengeklickt werden, in meinem Fall:
concat("Moin, Moin ", $inputVariable.payload/client:input)


Das gleiche wird wiederholt für ns1:TargetFilename. Da sich hier um den Namen der Zieldatei handelt, sollten Sonderzeichen vermieden werden. Z.B.
concat("Hello-",$inputVariable.payload/client:input)


Das Composite ist damit fertig und wird deployed (Rechtsklick auf Projektname|Deploy). Danach wird der Enterprise Manager geöffnet und das Projekt ausgewählt. Auf der Testseite wird ein Teststring eingegeben und der Test gestartet.


Wenn alles geklappt hat, kann hier der Flow Trace aufgerufen werden.


Im Flow Trace wird MFT mit angezeigt, weiter geht es mit einem Klick darauf.


Von hier wird man in die MFT Console weitergeleitet und bekommt hier direkt den Transfer angezeigt.


Auch im Filesystem ist das Resultat zu finden.

Damit ist das MFT-Tutorial abgeschlossen.

[Teil 1] [Teil 2] [Teil 3] [Teil 4] 

Dienstag, 10. Februar 2015

Oracle Managed File Transfer (MFT) handson - Teil 3: Custom Callouts in Java

[Teil 1] [Teil 2] [Teil 3] [Teil 4]

Über Custom Callouts in Java lässt sich die eingebaute Funktionaltität von MFT durch eigenen Code erweitern. Dabei lässt sich feingranular steuern, wann im Prozess dieser Code ausgeführt werden soll. Grundsätzlich werden drei Dinge benötigt: der eigentliche Java Code, eine XML-Datei welche MFT beschreibt, was sie mit diesem Code anfangen soll und ein WLST-Call mit dem das Callout bei MFT bekannt gemacht wird. Die komplette Dokumentation findet sich auf OTN, dieses Tutorial soll an einem simplen Beispiel das Erstellen und Einbinden von Custom Callouts demonstrieren.
In diesem Beispiel wird ein Custom Callout entwickelt, welches den Dateinamen durch die aktuelle Systemzeit ersetzt. Als Voraussetzung sollte man wissen, wie man eine Java-Klasse erstellt und übersetzt sowie den Teil 1 dieses Tutorials abgeschlossen haben.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
package com.oracle.callout.sample;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.Map;
import java.util.Date;

import oracle.tip.mft.engine.processsor.plugin.PluginContext;
import oracle.tip.mft.engine.processsor.plugin.PluginOutput;
import oracle.tip.mft.engine.processsor.plugin.PreCalloutPlugin;


public class FilenameCallout implements PreCalloutPlugin {

 @Override
 public boolean isPayloadChangeRequired(PluginContext context,
   Map<String, String> calloutParams) {
  return false;
 }

 @Override
 public PluginOutput process(PluginContext context, InputStream input,
   OutputStream out, Map<String, String> calloutParams) {
  String type = calloutParams.get("Type");

  return null;
 }

 @Override
 public PluginOutput process(PluginContext context, InputStream input,
   Map<String, String> calloutParams) {

  PluginOutput pOutput = new PluginOutput();
  pOutput.setNewFileName("MFT " + new Date() );
  return pOutput;
 }
}

Alle Imports bis auf java.util.Date werden für jedes Callout benötigt. Mit isPayloadChangeRequired() wird unterschieden, welche der beiden folgenden Methoden aufgerufen wird. Da in diesem Beispiel nur der Dateiname, nicht aber der Inhalt geändert wird, gibt isPayloadChangeRequired() false zurück und die zweite process() Methode wird aufgerufen. Die erste Variante wird nicht benötigt und gibt einfach null zurück.

[oracle@oel6ab src]$ javac -classpath "/home/oracle/Oracle/Middleware/soa12103/mft/modules/oracle.mft_12.1.3.0/core-12.1.1.0.jar" com/oracle/callout/sample/FilenameCallout.java 
[oracle@oel6ab src]$ jar cf FilenameCallout.jar com/oracle/callout/sample/FilenameCallout.class 
[oracle@oel6ab src]$ ll
total 12
drwxr-xr-x. 3 oracle oinstall 4096 Feb  6 15:23 com
-rw-r--r--. 1 oracle oinstall 1187 Feb  9 16:42 FilenameCallout.jar

Die Klasse wird dann einfach wie oben übersetzt, hier sind ggf. nur die Pfadnamen anzupassen. Im zweiten Schritt wird ein jar-File erzeugt, welches damit auch schon fertig ist.
Im nächsten Schritt wird die XML-Datei erzeugt, damit MFT weiss, was es mit dem JAR anfangen soll.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
<?xml version="1.0" encoding="UTF-8"?>
<mft:Callouts xmlns:mft="http://xmlns.oracle.com/mft" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:schemaLocation="http://xmlns.oracle.com/mft callout.xsd ">
 <mft:Callout description="Filename conversion"
  helpText="File name conversion"
  groupName="Source-pre,Target-pre,Target-post" 
  timeout="300" 
  implementationClass="com.oracle.callout.sample.FilenameCallout"
  libraryName="FilenameCallout.jar" 
  name="Filename conversion">
 </mft:Callout>
</mft:Callouts>

Das XML-File dazu ist recht gradlinig. Wichtig ist der Name, welcher in einem MFT-System eindeutig sein muß. Die Attribute libraryName und implementationClass sind selbsterklärend.


Die beiden Dateien müssen jetzt in das mft-Verzeichnis der jeweiligen WLS-Domain kopiert werden. Falls der Unterordner callouts noch nicht vorhanden ist, wird er manuall erstellt. Danach werden FilenameCallout.jar und FilenameCallout.xml in das callouts-Verzeichnis kopiert.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
CLASSPATH=:/home/oracle/Oracle/Middleware/soa12103/mft/modules/oracle.mft_12.1.3.0/core-12.1.1.0.jar

Initializing WebLogic Scripting Tool (WLST) ...

Welcome to WebLogic Server Administration Scripting Shell

Type help() for help on available commands

wls:/offline> connect("weblogic","welcome1","t3://localhost:7003")
Connecting to t3://localhost:7003 with userid weblogic ...
Successfully connected to managed Server "mft_server1" that belongs to domain "soa_domain".

Warning: An insecure protocol was used to connect to the 
server. To ensure on-the-wire security, the SSL port or 
Admin port should be used instead.

wls:/soa_domain/serverConfig> crtCalls("/home/oracle/Oracle/Middleware/soa12103/user_projects/domains/soa_domain/mft/callouts/FilenameCallout.xml")
Callout Filename conversion created.

wls:/soa_domain/serverConfig> listCallouts() 
Callouts
-----------
[Name:Filename conversion, Library:FilenameCallout.jar, Impl Class:com.oracle.callout.sample.FilenameCallout, Description:Filename conversion, Group:Source-pre,Target-pre,Target-post]
wls:/soa_domain/serverConfig> 

Um MFT mit seinem neuen Callout bekannt zu machen, wird das WLST benötigt. Damit es die spezifischen Kommandos von MFT kennt, wird es gestartet über das wlst.sh aus dem MFT-Verzeichnis unter $MW_HOME/mft/common/bin. Dass man das richtige Skript benutzt hat, erkennt man dann wie oben in der ersten Zeile am CLASSPATH Ausdruck.
Als erstes ist es mit dem WLST notwendig, sich auf den betreffenden Server zu verbinden. Dann wird über crtCalls(...) mit einem Parameter, der auf die XML-Datei zeigt, das Callout registriert. Via listCallouts() kann man sich alle registrierten Callouts anzeigen lassen, deleteCallout(...) entfernt es wieder.


Jetzt werden wieder zwei Verzeichnisse für Quelle und Ziel benötigt. Das können z.B. die Verzeichnisse aus dem ersten Teil sein, oder man legt einfach zwei neue an.


In der MFT-Console werden die beiden Verzeichnisse, analog zu Teil 1, wieder als Source und Target bekannt gemacht. Dann wird ein Transfer mit diesen beiden Verzeichnissen erstellt.


Nach Klick auf <add pre-processing actions> kann im Dialog jetzt auch 'Filename conversion' ausgewählt und mit Add to List hinzugefügt werden.


Das Ergebnis sollte dann wie oben abgebildet aussehen. Speichern mit Save, danach abschließen mit Deploy.


Nach kurzer Zeit sollte der erfolgreich verlaufene Transfer im Dashboard angezeigt werden.


Auch im Dateisystem sollte die übertragene Datei mit dem geänderten Dateinamen jetzt auftauchen. Damit ist das Handson-Tutorial zu Custom Callouts in Java abgeschlossen.

Teil 4: Integration mit der SOA Suite

[Teil 1] [Teil 2] [Teil 3] [Teil 4]