Externer Aufruf

Grundlagen

Die Anwendung bietet die Möglichkeit, andere Softwareprodukte zu starten. Dabei können wahlweise einfache oder fixe Parameter oder aber Werte aus z.B. der aktuell geöffneten Maske, an das aufgerufene Programm übergeben werden.

Hierbei wird zwischen verschiedenen Aufruftypen unterschieden:

Typ	Bemerkung
EXCEL	Aufruf zu Microsoft Excel
EXCELTRANSFER	Bidirektionale Excel-Integration
EXE	Aufruf zu einer ausführbaren Windows EXE-Datei
INI	Aufruf .exe mit der Erzeugung einer .ini-Datei Nur im Windows Client
OUTLOOK	Aufruf zu Microsoft Outlook;
SAP	Aufruf von Funktionen und Masken in SAP
SERIESACTION	Aufruf des Serienbriefs aus einer Entität Nur im Windows Client
URL	Aufruf einer Webseite im System eingestellten Standardbrowser
WEBSERVICE	Aufruf von Webservices Nur im Windows Client
WORD	Aufruf zu Microsoft Word

Die Aufrufe sind in einer eigenen Tabelle abgespeichert. Die Verwaltung der Aufrufschnittstelle erreichen Sie im Administrations-Menü über den Knoten Externe Aufrufe. In dem nachfolgenden Suchfenster können Sie dann direkt nach einem bestimmten vorhandenen Aufruf suchen oder Sie schließen das Suchfenster und legen über den Schalter Neu einen neuen Datensatz an.

Abbildung: Maske eines externen Aufrufes

• Im Feld Titel legen Sie den Titel des Aufrufes fest, wie er später im Aufrufmenü angezeigt werden soll.

• Im Feld Beschreibung tragen Sie den Tooltip ein, welcher bei Auswahl des entsprechenden Schalters mit der Maus angezeigt wird. Die Anzeige erfolgt sowohl im Aufrufmenü als auch in der Schalterleiste.

• Im Feld Entität wählen Sie aus, zu welcher Entität der Aufruf verfügbar sein soll. Wenn Sie das Feld leer lassen (Eintrag des Leerschlüssels), wird der Aufruf zu sämtlichen Masken angezeigt, ansonsten lediglich zu der ausgewählten Maske. Beachten Sie, dass sich parametrisierte Aufrufe normalerweise nicht für alle Masken eignen. 

• Im Feld Aufruftyp tragen Sie die Art des Aufrufes ein (siehe oben).

• Im Memofeld oben rechts hinterlegen Sie ein Script zu Konfiguration des Aufrufs (siehe unten)

• Im Feld Bild wählen Sie ein Icon (GIF oder JPG) aus, welches für den Aufruf angezeigt werden soll.

• Das Feld Kommando ist nur für den Aufruftyp EXE aktiv. Hier werden der Pfad und der Dateiname des auszuführenden Programms hinterlegt.

• Das Feld Ausführen in ist nur für den Aufruftyp EXE aktiv. Hier kann optional ein anderes Arbeitsverzeichnis für das aufgerufene Programm festgelegt werden.

• Über ein Häkchen im Feld Navigationsleiste legen Sie fest, ob der Aufruf ebenfalls über die Aufrufleiste verfügbar ist, oder nur im Aufrufmenü angezeigt wird.

• Im Parameterfeld werden die optionalen Parameter eingetragen, die an das Programm übergeben werden sollen. Die Syntax hängt hier natürlich von der aufgerufenen Software ab.

• Felder Symbolleiste und Schalterleiste: Externe Aufrufe, die weder in der Symbolleiste noch in der Schnellstartleiste angezeigt werden sollen (beide Optionen deaktiviert), erscheinen für den Anwender nicht in der Anwendung (nur verfügbar im Maskenskript) und werden daher auch nicht in die Vorschlagsliste (COMMAND) angeboten.

Die Syntax zur Übergabe von Parametern aus der Applikation stellt sich folgendermaßen dar: ${Feldname.Entitätsname}

Die passenden Einträge werden über Administrationskonsole über den Bereich Customizing / Feldeigenschaften über entsprechende Spaltenfilter nachgeschlagen.

Gruppierung und Sortierung

Über das numerische Feld 'Sortierreihenfolge' kann die Reihenfolge beeinflusst werden, in welcher die Schalter für die externen Aufrufe im Dropdown-Menü angezeigt werden. Bei der Pflege dieses Feldes ist zu beachten, dass im Dropdown-Menü sowohl entitätsspezifische als auch entitätsunabhängige Einträge angezeigt werden.

Abbildung: Externer Aufruf 'Excel' und Auswirkungen auf das Pull-Down-Menü

Zusätzlich zur Sortierung (Reihenfolge) der Einträge im Menü können Sie die Aufrufe in Untermenüs gruppieren. Das steuern Sie über das Schlüsselfeld 'Gruppierung der Einträge', wo Sie mögliche Gruppierungen vorgeben.

Bei der Pflege eines externen Aufrufs kann eine bestehende Gruppierung ausgewählt werden. Dadurch wird dieser externe Aufruf innerhalb dieses Menüs angezeigt. Wird keine Gruppierung ausgewählt (Leerschlüssel '?'), erscheint der externe Aufruf auf oberster Ebene. Die Sortierung innerhalb der Gruppierung ist analog zu 'Sortierreihenfolge'.

Für die Sortierung des Menüs mit allen externen Aufrufen gilt folgende Reihenfolge (von oben nach unten):

1. Zuerst werden die Gruppierungen in alphabetisch aufsteigender Sortierung (A --> Z) der internationalisierten Namen angezeigt. Innerhalb jeder Gruppierung wird wieder nach dem Feld Sortierreihenfolge sortiert.

2. Danach folgen die Aufrufe ohne Gruppierung, diese werden nach dem Feld Sortierreihenfolge sortiert

Diese Sortierung gilt unabhängig davon, ob ein Eintrag entitätsspezifisch ist, d. h. es werden alle zum aktuellen Fenster verfügbaren Aufrufe (allgemeine und entitätsspezifische) nach der vorherigen Beschreibung sortiert.

In der Schalterleiste im linken unteren Bereich der Anwendung werden die externen Aufrufe ebenfalls angezeigt (steuerbar durch den Administrator). In dieser Leiste wird ebenfalls die Reihenfolge und Gruppierung beachtet. Die Schalter in der Leiste werden gemäß der vorherigen Beschreibung von links nach rechts hinzugefügt. Zuerst kommen die Gruppierungen in alphabetisch aufsteigender Reihenfolge (A --> Z), innerhalb der Gruppierung wird nach dem Feld Sortierreihenfolge sortiert. Danach folgen die Aufrufe ohne Gruppierung. Eine Gruppierung wird durch einen Schalter mit einem entsprechenden Symbol gekennzeichnet. Über diesen Schalter öffnet sich ein Popupmenü, welches die Einträge dieser Gruppierung enthält.

Internationalisierung

Bei den externen Aufrufen sind zwei Zeilen für die Internationalisierung vorgesehen. Der Titel und die Beschreibung werden untereinander aufgelistet und in Klammern gekennzeichnet.

Wird der Schalter I18n

Das Feld Beschreibung ist in die Systemsuche mit aufgenommen worden, d.h. geänderte Systemsuchen müssen nach dem Update angepasst werden.

Skripting im Memofeld

Das Script (Memofeld oben rechts) funktioniert genau wie ein Maskenskript. Lediglich der Zugriff auf die Felder der Maske sieht anders aus:

Statt Feldname.value muss man ${Feldname.Entitätsname} schreiben.

Beispiel: aus Matchcode.value wird ${Matchcode.Customer}

System-Variablen können auch für externe Aufrufe verwendet werden.

Beispiel

%TEMP%\Dateiname.ini

wird ersetzt durch

C:\Temp\Dateiname.ini

Diese werden zur Laufzeit in folgenden Feldern ersetzt:

• Memofeld (Params.InvocationExt)

• Kommando (Executeable.InvocationExt)

• Ausführen in (WorkingDirectory.InvocationExt)

Typ: EXCELTRANSFER

Dieser Aufruftyp öffnet eine EXCEL-Vorlage, die im System gespeichert wurde. Konfiguration der Vorlage wird in der Adminkonsole unter Verwaltung Dokumentvorlagen vorgenommen. Die Konfiguration des externen Aufrufes muss den korrekten Vorlagennamen und die Vorlageentität berücksichtigen.

Zu beachten sind besonders folgende Felder:

• Aufruftyp (EXCELTRANSFER)

• Entität (muss der Entität der Excel-Vorlage entsprechen)

• Memofeld (Name der Excel-Vorlage)

Abbildung: Zusammenhang zwischen einer gespeicherten Excel-Vorlage und der Konfiguration des externen Aufrufs

Typ: URL

Beispielaufruf Map24

Im folgenden Beispiel wird ein Aufruf zur Internetseite von Map24 eingerichtet. Es soll dabei direkt eine Route von der Firmenzentrale zum Geschäftspartner berechnet werden.

Der Aufruf stellt sich folgendermaßen dar:

• Titel: Map24

• Beschreibung: Routenplan zum aktuellen Datensatz in Map24

• Entität: CUSTOMER (also der aktuelle Geschäftspartner)

• Aufruftyp: URL

• Bild: Das Icon von Map24

• Navigationsleiste: Ja

• Parameterfeld:

link2.map24.com/?lid=0f8488fc&maptype=JAVA&action=route&dstreet=
${Street.Customer}+${StreetNumber.Customer}&dzip=${ZIP.Customer}&dcity=${City.Customer}&dcountry=de&sstreet=
Friedrich-List-Strasse+31&szip=35398&scity=Giessen&scountry=de&sname=CURSOR+Software+AG&submit=+%3E%3E+

Hierbei handelt es sich um eine Mischung aus variablen und festen Parametern, die an das Portal von Map24 übergeben werden.

Variable Parameter sind dabei:

• ${Street.Customer} Straße des Geschäftspartners

• ${StreetNumber.Customer} Hausnummer

• ${ZIP.Customer} Postleitzahl

• ${City.Customer} Ort

Die Startadresse für die Route, in unserem Fall die CURSOR Software AG in Gießen, wird im unteren Teil des Parameterblockes angegeben.

Um die oben aufgeführten Parameter anzusteuern, muss deren Name zuerst über die Administrationskonsole nachgeschlagen werden. Im Bereich Customizing / Feldeigenschaften setzen Sie in unserem Beispiel den Spaltenfilter in der Entitätsspalte auf Geschäftspartner und sie bekommen nur noch die Datenbankfelder des Geschäftspartners angezeigt.

Um jetzt den Namen des Feldes für die Strasse herauszufinden, setzen Sie den Spaltenfilter in der Spalte Feld auf *Straße*. Auf diese Weise werden Ihnen nur noch die Felder angezeigt, in deren Beschreibung irgendwo die Zeichen Straße vorkommen. Als Ergebnis erhalten Sie zwei Einträge: den Speicherort der Straße der Person und den Speicherort der Straße des Geschäftspartners selbst.

Durch variieren des Spaltenfilters können so die zu übergebenden Parameter schnell identifiziert werden.

Typ: SERIESACTION

Den Aufruf konfigurieren

Es muss dabei eine Entität ausgewählt und ein Skript hinterlegt werden.

Nach dem Ausführen wird je nach Konfiguration der Wizard zum Versenden eines Serienbriefes oder einer Serienmail aufgerufen und vorbelegt.

Skript

Das Skript hat immer folgendes Grundgerüst:

 public void init()
{
}

Folgende Konfigurationsmöglichkeiten für den Assistenten bestehen:

Individuellen Titel des Assistenten festlegen (ansonsten wird der Standardtitel im Assistenten angezeigt)

//setTitle(String title)                   ab 14.1
config.setTitle("Umschläge und Etikettendruck");

Den Wizard mit einer Vorlage vorbelegen und wählen, ob vom Benutzer eine andere gewählt werden darf. Dieser Parameter muss vorhanden sein und mit einem gültigen Vorlagennamen belegt werden.

//config.setTemplate("NAME DES TEMPLATES", editierbar?)
config.setTemplate("SERIENBRIEF BLANKO (Beispiel)", true);

Festlegen, ob der Benutzer die Suche einsehen und ändern darf.

//config.editSearch(editierbar?)
config.editSearch(true);

Festlegen ob der Benutzer die Ergebnisse der Suche einsehen und eventuell Sätze entfernen darf.

//config.displayResult(darfDerBenutzerDieErgebnisseSehen?)
config.displayResult(true);

Festlegen, ob der Benutzer über das Laden einer Datei Datensätze hinzufügen darf.

//config.addSearch(darfDerBenutzerSuchergebnisseHinzuFügen?)
config.addSearch(true);

Festlegen, ob der Benutzer das Suchergebnis speichern darf.

//config.saveSearch(speichern?)
config.saveSearch(true);

Den Betreff des Dokumentensatzes vorbelegen und bestimmen, ob der Benutzer diesen ändern darf. Dabei können auch Feldinhalte benutzt werden.

//config.setSubject("Mein Text "+ MeinFeldInhalt.value , editierbar?)
config.setSubject("Mein Text "+ MatchCode.value , false);

Eine Datei als vorbelegten Anhang zum Wizard hinzufügen.

//config.addFile("Mein voll qualifizierter Pfad")
config.addFile("C:\\Meinordner\\MeineDatei.txt");

Festlegen, ob der Anwender Dateien als Anlagen hinzufügen.darf

//config.changeFiles(editierbar?)
config.changeFiles(false);

Festlegen, wie das Protokollaktivität-Kontrollkästchen vorbelegt ist und ob der Anwender den Wert ändern darf.

Hinweis: Ab 14.1 wurde die 'createLogActivity'-Methode in 'createProtocolActivity' umbenannt. Der alte Methodenname wird weiterhin unterstützt.

//config.createProtocolActivity(aktivieren?[, editierbar? ])   ab 14.1
config.createProtocolActivity(false);    // identisch zu config.createLogActivity(false) - bis 13.2
//oder
config.createProtocolActivity(false, true);  

Festlegen, wie das Erinnerungsaktivität-Kontrollkästchen vorbelegt ist und ob der Anwender den Wert ändern darf.

//config.createRemindingActivity(aktivieren?[, editierbar? (ab 14.1)])
config.createRemindingActivity(false);
//oder
config.createRemindingActivity(false, true);  // ab 14.1

Festlegen, wie das Sammelaktivitäts-Kontrollkästchen vorbelegt ist und ob der Anwender den Wert ändern darf.

//config.createSeparateActivities(aktivieren?[, editierbar? (ab 14.1)])
config.createSeparateActivities(true);
//oder
config.createSeparateActivities(true, true);  // ab 14.1

Wählen, ob der Serienmail oder der Serienbrief-Wizard gestartet wird.

//config.setType("Typ(LETTER oder MAIL)")
config.setType("LETTER");

Wenn der Typ LETTER gewählt wurde: Wählen, wie und in welchem Format erstellt werden soll.

//config.setFormat("Option zum Wählen", editierbar?)
config.setFormat("Serialletter", true);
config.setFormat("Controlfile", true);
 
//config.setFormat("Option zum Wählen(Controlfile oder Serialletter)","Format(Excel oder CSV)", editierbar?)
config.setFormat("Controlfile","Excel", true);
config.setFormat("Controlfile","CSV", true);
config.setFormat("Serialletter", "Excel", true);
config.setFormat("Serialletter", "CSV", true);

Wenn der Typ LETTER gewählt wurde: Wählen, ob das Serienbriefdokument nur testweise erzeugt werden soll.

//config.setTestMode(Test Modus?, editierbar?)
config.setTestMode(false, true);

Wenn der Typ LETTER gewählt wurde: Wählen, ob der Dokumentensatz zu dem generierten Serienbriefdokument geöffnet werden soll.
Nicht zu verwechseln mit der Serienbriefdokumentdatei.

//config.openWindowLevelForDocument(aktivieren?)    ab 14.1, Standard ist true
config.openWindowLevelForDocument(false);

Wenn der Typ LETTER gewählt wurde: Wählen, ob die generierte Serienbriefdokumentdatei geöffnet werden soll. Im Standardfall wird das Dokument geöffnet.

//config.openDocument(aktivieren?)             ab 14.1, Standard ist true
config.openDocument(false);

Vorbelegung der Protokoll- und Erinnerungsaktivität im Assistenten

Grundsätzlich kann die Protokoll- und Erinnerungsaktivität in allen Dokumentassistenten über einen Propertymapper-Eintrag pro Vorlagentyp vorkonfiguriert werden. In der Regel sind also die Felder im Serienbrief-  bzw. Serienmailassistenten bereits befüllt.
Im Rahmen der SERIESACTION kann jedoch eine individuelle Konfiguration für diesen einen Aufruf hinterlegt werden, der die ursprüngliche Vorbelegung überschreibt. Zur Vorbelegung der Protokoll- und Erinnerungsaktivität stehen zwei Objekte zur Verfügung, die mit Hilfe des Skripts konfiguriert werden können. Für die Protokollaktivität erfolgt die Konfiguration über das Objekt 'protocolConfigVO', für die Erinnerungsaktivität über das Objekt 'reminderConfigVO'. Um beispielsweise den Betreff für die Erinnerungsaktivität vorzubelegen, muss folgender Eintrag in das Skript aufgenommen werden:

reminderConfigVO.setSubject("Protokolleintrag Umschläge und Etiketten zur Infotagung", true);

• In den folgenden Codebeispielen kann anstelle reminderConfigVO (für Erinnerungsaktivität) natürlich auch protocolConfigVO (für Protokollaktivität) verwendet werden.

• Besonderheiten Nachschlagefelder
  

  • Als Wert wird der Schlüsselname übergeben, z.B. 'A' im Feld Priorität

  • Die Verwendung des Leerschlüssels '?' wird unterstützt

  • Bei ungültigen Nachschlagewerten wird der Wert nicht in das Feld eingetragen.

• Null-Werte werden ignoriert. Der bestehende Feldwert bleibt bestehen

• Die Edit-Eigenschaft des Feldes wird immer gesetzt, auch wenn der Feldwert nicht eingetragen werden kann.

Die folgenden Konfigurationsmöglichkeiten sind für die Protokoll- und Erinnerungsaktivität verfügbar:

Vorbelegung Feld 'Status'

// reminderConfigVO.setStatus("Schlüsselname des Aktivitätenstatus oder Leerschlüssel '?'", editierbar?)
reminderConfigVO.setStatus("E", false);
// oder
reminderConfigVO.setStatus("?", false);

Vorbelegung Feld 'Beginnt am'

// reminderConfigVO.setStartDate("Datumswert" , editierbar?)

// Heutiges Datum
reminderConfigVO.setStartDate("NOW", true);       

// Fixes Datum
reminderConfigVO.setStartDate("15.08.2014 19:36:00", true);   

// Heutiges Datum + 5 Tage
long reminderDays = 5l;
Date reminderTimeDate = new Date(System.currentTimeMillis() + reminderDays * 24 * 60 * 60 * 1000);
String reminderTimeString = java.text.DateFormat.getDateTimeInstance().format(reminderTimeDate); 
reminderConfigVO.setStartDate(reminderTimeString, true);       

Vorbelegung Feld 'Betreff'

// reminderConfigVO.setSubject("Betreff", editierbar?)
reminderConfigVO.setSubject("Protokolleintrag Umschläge und Etiketten zur Infotagung", true);

Vorbelegung Feld 'Beschreibung'

// reminderConfigVO.setDescription("Beschreibungstext", editierbar?)
reminderConfigVO.setDescription("Bitte erfassen Sie hier Ihren Text für die Erinnerungsaktivität", true);

Vorbelegung Feld 'Art'

// reminderConfigVO.setType("Schlüsselname der Aktivitätenart oder Leerschlüssel '?'", editierbar?) 
reminderConfigVO.setType("SERIENBRIEF", false);
// oder bei Leerschlüssel
reminderConfigVO.setStatus("?", false);

Vorbelegung Feld 'Priorität'

// reminderConfigVO.set("Schlüsselname der Priorität oder Leerschlüssel '?'", editierbar?) 
reminderConfigVO.setPriority("A", false);

Vorbelegung Feld 'Anlass'

// reminderConfigVO.setReason("Schlüsselname des Aktivitätenanlass oder Leerschlüssel '?'", editierbar?) 
reminderConfigVO.setReason("PROJEKT", false);

Vorbelegung Feld 'Ergebnis'

// reminderConfigVO.setResult("Schlüsselname des Aktivitätenergebnisses oder Leerschlüssel '?'", editierbar?) 
reminderConfigVO.setResult("MARKETING", false);

Vorbelegung 'Mitarbeiterzuordnung'

Festlegen des 'Delegiert von'-Mitarbeiters

// reminderConfigVO.addDelegatedFrom("Kürzel des Mitarbeiters oder Variable", "Schlüsselname des Mitarbeiterbeziehungtyps");
reminderConfigVO.addDelegatedFrom("MAS", "EMPFÄNGER");
// oder aktueller Anwender per Variable
reminderConfigVO.addDelegatedFrom("USER", "BCC");
// oder Stellvertreter per Variable
reminderConfigVO.addDelegatedFrom("USER_DEPUTY", "BCC");

Festlegen des 'Delegiert an'-Mitarbeiters

// reminderConfigVO.addDelegatedTo("Kürzel des Mitarbeiters oder Variable", "Schlüsselname des Mitarbeiterbeziehungtyps");
reminderConfigVO.addDelegatedTo("CHK", "EMPFÄNGER");
// oder Verwendung einer Variablen aus dem Mapping der Dokumentvorlage
reminderConfigVO.addDelegatedTo("SERIALEmployeeSales", "EMPFÄNGER");

Hinzufügen weiterer Mitarbeiter

// reminderConfigVO.addEmployee("Kürzel des Mitarbeiters oder Variable", "Schlüsselname des Mitarbeiterbeziehungtyps");
reminderConfigVO.addEmployee("CHK", "EMPFÄNGER");
// oder Verwendung einer Variablen aus dem Mapping der Dokumentvorlage
reminderConfigVO.addDelegatedTo("SERIALEmployeeOffice", "EMPFÄNGER");

Hinzufügen von Mitarbeitern

• Für das Hinzufügen von Mitarbeitern ist es notwendig, dass die entsprechende Aktivitätenseite zuvor per Skript aktiviert wurde, z.B.

  ^{config.createProtocolActivity(true);}

• Es können folgende Werte verwendet werden

  • Kürzel des Mitarbeiternamens, z.B. 'MAS'

  • Variable 'USER' - Kürzel des aktuell angemeldeten Anwenders

  • Variable 'USER_DEPUTY' - Kürzel des Stellvertretenen
    Meldet sich Anwender A als Stellvertreter von Anwender B an, so enthält Variable 'USER_DEPUTY' das Kürzel von Anwender B.
    Meldet sich Anwender A ohne Stellvertreterregelung an, so enthält Variable 'USER_DEPUTY' das Kürzel von Anwender A. 

  • Variable aus dem Mapping der Dokumentvorlage
    Im Mapping der Dokumentvorlage können definierte Variablennamen verwendet werden, um eine dynamische Zuordnung von Mitarbeitern bei der Aktivitätengenerierung in der Serienaktion zu ermöglichen. Dieser Variablen wird letztendlich ein Mitarbeiterfeld aus der Suche zugeordnet, der dann der generierten Aktivität zugeordnet wird (siehe auch Dokumentvorlagen hinzufügen und bearbeiten#DenSerienbriefvorlagensatzerstellenundbearbeiten.)
    Zur Nutzung dieser Variablen ist es notwendig, dass diese im Mapping der Dokumentvorlage vorhanden ist und dass keine Sammelaktivität erzeugt wird. Folgende Variablennamen werden unterstützt:

    • SERIALEmployeeOffice

    • SERIALEmployeeSales

    • SERIALEmployeeKey

    • SERIALEmployeeExtra1

    • SERIALEmployeeExtra2

• Es können beliebig viele Mitarbeiter hinzugefügt werden.

• Die ursprüngliche Mitarbeiterzuordnung wird überschrieben, sobald Mitarbeiter hinzugefügt werden.

• Es kann immer nur ein 'delegiert an' und ein 'delegiert von' Mitarbeiter hinzugefügt werden. Wird der Skriptbefehl mehrfach abgesetzt, so ist der Mitarbeiter aus dem letzten Skriptbefehl der 'delegiert an/von' Mitarbeiter. Die Mitarbeiter aus den vorherigen Skriptbefehlen befinden sich weiterhin in der Liste, sind aber nicht mehr 'delegiert an/von' Mitarbeiter.

Komplettes Beispiel 

public void init()
{
config.setTitle("Seriendruck Umschläge und Etiketten");
config.setType("LETTER");
config.setTemplate("SERIENBRIEF BLANKO (Beispiel)", true);
config.editSearch(true);
config.displayResult(true);
config.addSearch(false);
config.saveSearch(false);
config.setSubject("Text "+ MatchCode.value , false);
config.addFile("C:\\MeinPfad\\MeineDatei.txt");
config.setFormat("Controlfile","Excel", true);
config.setTestMode(false, true);
config.createProtocolActivity(true, false);
config.createRemindingActivity(true, false);
config.createSeparateActivities(true, true);
config.openWindowLevelForDocument(false); 

// Vorbelegung der Felder in der Protokollaktivität
protocolConfigVO.setSubject("Protokolleintrag Umschläge und Etiketten zur Infotagung", true);

// Vorbelegung der Felder in der Erinnerungsaktivität
reminderConfigVO.setStatus("E", false);
reminderConfigVO.setStartDate("TODAY", true);
//reminderConfigVO.setStartDate("15.08.2014 19:36:00", false);
reminderConfigVO.setSubject("Protokolleintrag Umschläge und Etiketten zur Infotagung", true);
reminderConfigVO.setDescription("Bitte erfassen Sie hier Ihren individuellen Text für die generierte Erinnerungsaktivität", true);
reminderConfigVO.setPriority("B", false);
reminderConfigVO.setType("RECHNUNG", false);
reminderConfigVO.setReason("BESCH", false);
reminderConfigVO.setResult("INFO", false);

// Vorbelegung der Mitarbeiterzuordnung in der Erinnerungsaktivität
reminderConfigVO.addDelegatedFrom("USER", "EMPFÄNGER");
reminderConfigVO.addDelegatedTo("SERIALEmployeeSales", "EMPFÄNGER");
reminderConfigVO.addEmployee("TMR", "BCC");
reminderConfigVO.addEmployee("GV", "BCC");
reminderConfigVO.setEmployeeChangeable(false);
}

Sichtbarkeit von Assistentenseiten

Bei vielen der obengenannten Methoden kann die Editierbarkeit der Eingabe konfiguriert werden.
Besonderes Merkmal: Sind alle Eingabemöglichkeiten auf einer Assistentenseite deaktiviert, so wird die Seite im Assistenten nicht mehr angezeigt. Die vorkonfigurierten Einstellungen auf dieser Seite werden weiterhin berücksichtigt. Hierdurch kann der Assistent auch komplett ausgeblendet werden, so dass letztendlich direkt das geöffnete Dokument als Ergebnis angezeigt wird.

Welche Komponenten müssen auf nicht editierbar konfiguriert werden, damit eine Assistentenseite nicht angezeigt wird?

1. Vorlagenauswahl:

   • setTemplate

2. Selektion der Empfänger

   • editSearch

   • displayResult

   • addSearch

   • saveSearch

3. Serienbrief - Optionen

   • setFormat

   • setTestMode

4. Dokumentenbeschreibung eingeben

   • setSubject

5. Dateien anfügen

   • changeFiles

6. Aktivitäten erzeugen

   • createLogActivity

   • createRemindingActivity

   • createSeparateActivities

7. Die Aktivititätenseiten Protokollaktivität (protocolConfig) und Erinnerungsaktivität (reminderConfig)
   

   • setStatus           (Feld 'Status')

   • setStartDate      (Feld 'Beginnt am')

   • setSubject         (Feld 'Betreff')

   • setDescription   (Feld 'Beschreibung')

   • setType             (Feld 'Art')

   • setPriority         (Feld 'Priorität')

   • setReason         (Feld 'Anlass')

   • setResult           (Feld 'Ergebnis')

   • setEmployeeChangeable  (Schalter 'Mitarbeiterzuordnung')

Vorlagen und Suchen

Für den externen Aufruf muss eine passende Dokumentenvorlage hinterlegt werden, für deren komplexe Suche Folgendes gilt:

1. In der Hauptsuche muss der Primärschlüssel der Entität, aus der der externe Aufruf heraus aufgerufen wird, selektiert werden mit der Bedingung ist einer von und dem Template Platzhalter (Wert wird zur Laufzeit gesetzt)

2. Für die Hauptsuche muss als Eingabeparameter für den Wert "PK" der Primärschlüssel der Entität ausgewählt werden.

• Das Feld 'Entität' sollte nicht mit dem Leerschlüssel gefüllt werden. Der Aufruf wird in diesem Fall nicht ausgeführt.

• Es ist möglich Kombinationen zu konfigurieren, in denen der Benutzer im Wizard nicht weiterkommt. Beispielsweise kann man ihm verbieten, neue Adressaten hinzuzufügen und gleichzeitig erlauben, dass er die Dokumentenvorlage ändert. Tut er das, nun werden die initial gesuchten Adressaten gelöscht und er darf nicht wieder welche hinzufügen. ER kann den Wizard nur beenden.

Typ: SAP

Mit der SAP-Schnittstelle können beliebige RFC-Aufrufe von CURSOR-CRM/EVI nach SAP durchgeführt werden.

Die technische Umsetzung erfolgte in den Klassen SAPInvocationExecutor, SAPInvoke und SAPCallConfigVO. Die Klasse SAPCallConfigVO dient lediglich als ValueObject, welches in der Aufrufdefinition über Scripting konfiguriert wird. Aus diesem ValueObject werden zur Laufzeit die notwendigen Informationen für den Verbindungsaufbau und die Durchführung des RFC gezogen.

SAP-Aufruf anlegen

So gehen Sie vor:

1. Wählen Sie aus dem Menü Administration / Externer Aufruf.

2. Legen Sie einen externen Aufruf mit dem Aufruftyp SAP an.

3. Die Konfiguration des Aufrufes erfolgt in einem Script, welches Sie im Memofeld hinterlegen.
   Die Syntax und die verfügbaren Befehle sind identisch mit dem skriptbasierten Customizing. Für die SAP-Schnittstelle können Sie die Methoden public void init () und public void handleResults () verwenden. Die Methode public void init () muss vorhanden sein, da sie zur Konfiguration des Aufrufes notwendig ist. Die Methode public void handleResults () wird nach der Durchführung des RFC's aufgerufen und kann dazu benutzt werden, Ergebnisse des Aufrufes zu verwenden (siehe: Rückgabewerte).

4. Speichern Sie den Aufruf ab.

Konfiguration der Verbindung mit JCo 2.X

Für die Konfiguration des Aufrufs und die Parameterübergabe wird die implizit vorhanden Variable config verwendet. Auf diesem Konfigurationsobjekt können die folgenden Eigenschaften gesetzt werden.

Allgemeine Parameter

Diese Parameter können (oder müssen) in jedem Fall angegeben werden:

Direkte Verbindung

Für eine direkte Verbindung auf einen SAP Server können (oder müssen) folgende Parameter angegeben werden:

Verbindung zu einer Servergruppe (Load Balancing)

Um die Lastverteilung (alternativ zur direkten Verbindung) beim Start zu nutzen, können (oder müssen) folgende Parameter genutzt werden:

Es gibt zwei Möglichkeiten, statt auf einen einzelnen Server auf eine Servergruppe zuzugreifen. In beiden Fällen müssen die Angaben der allgemeinen Parameter zusätzlich gemacht werden.

public void init()
{
config.setConnectToGroup(true);
config.setUrl("<Url zur Servergruppe>");
}

Mit setConnectToGroup das Load Balancing aktivieren und die URL der Gruppe angeben.

public void init()
{
config.setConnectToGroup(true);
config.setMessageServerHost("<IP des Messageservers>");
config.setR3Name("<Name des SAP Systems>");
config.setGroup("<Name der Servergruppe>"));
}

Mit setConnectToGroup das Load Balancing aktivieren und Messageserver, Name des SAP-Systems sowie Name der Gruppe angeben.

Konfiguration der Verbindung mit JCo 3.X

Für die Konfiguration des Aufrufs und die Parameterübergabe wird die implizit vorhanden Variable config verwendet. Auf diesem Konfigurationsobjekt können die folgenden Eigenschaften gesetzt werden.

Allgemeine Parameter

Diese Parameter können (oder müssen) in jedem Fall angegeben werden:

Direkte Verbindung

Für eine direkte Verbindung auf einen SAP Server können (oder müssen) folgende Parameter angegeben werden:

Verbindung zu einer Servergruppe (Load Balancing)

Um die Lastverteilung (alternativ zur direkten Verbindung) beim Start zu nutzen, können (oder müssen) folgende Parameter genutzt werden:

Experimentelle Zusatzparameter mit JCo 3.X

Folgende Parameter wurden zusätzlich zur Verfügung gestellt, befinden sich aber noch in der Testphase. Es kann keinerlei Garantie auf Funktionstüchtigkeit gegeben werden.

Diese Parameter können (oder müssen) in jedem Fall angegeben werden:

• Secure Network Connection (SNC) Konfiguration

Mit den folgenden Parametern kann eine sichere Verbindung konfiguriert werden:

• Ziel-Konfiguration

Mit den folgenden Parametern kann das Ziel konfiguriert werden:

• Zusätzliche Parameter

Zusätzlich stehen noch die folgenden Parameter zur Verfügung:

Single Sign On (SSO)

Clientseitig über externe Aufrufe

Voraussetzungen

Zusätzlich zu den obenstehenden allgemeinen Voraussetzungen bestehen für SSO folgende:

• SAPCRYPTOLIB muss aus dem SAP Marketplace heruntergeladen und die sapcrypto.dll in das custExt Verzeichnis des Clients gelegt werden.

• Zum Ausführungszeitpunkt muss das Zertifikat für den aktuellen Anwender im lokalen Microsoft-Store (auf Clientseite) verfügbar sein.

Konfiguration

Die Konfiguration des Aufrufs muss

• des SNC Modus aktivieren.

• Die Bibliothek für die Verschlüsselung einbinden

• Den eigenen Namen setzen (dazu kann die neue Konstante USER verwendet werden, um den aktuellen Benutzernamen auszulesen)
  

• Den Namen des Verbindungspartners setzen

• Das Zertifikat auslesen und setzen

Konfiguration

config.setSystemNumber("03");
config.setSapServer("104.3.6.52");
config.setClient("003");
config.setSncMode("1"); //SNC aktivieren
config.setSncLibrary("c:\\My\\Library\\Path\\sapcrypto.dll"); //Bibliothek zum Verschlüsseln auf dem Client, alternativ weglassen, dann greift die Umgebungsvariable SNC_LIB.
config.setSncMyName("p:CN=" + SessionConstants.USER + ", O=Cursor, L=Gießen, C=DE"); //eigener Name
config.setSncPartnername("p:CN=User CA Cursor, O=Cursor, L=Gießen, C=DE"); //Namen des Partners
config.setSncQOP("9"); //optional
config.setX509Cert(SAPUtils.readCertificate()); //Lokal installiertes Zertifikat lesen
  
config.setConnectToGroup(false);
config.setRfcName("Z_TEST");

Serverseitig über BPM Prozesse

Voraussetzungen

Zusätzlich zu den obenstehenden allgemeinen Voraussetzungen bestehen für SSO folgende:

• SAPCRYPTOLIB muss aus dem SAP Marketplace heruntergeladen und die sapcrypto.dll in das standalone\lib\dll Verzeichnis des Servers gelegt werden.

• Zum Ausführungszeitpunkt muss das Zertifikat für den aktuellen Anwender im lokalen Microsoft-Store (auf Clientseite) verfügbar sein.

Konfiguration

Die Konfiguration sieht grundsätzlich genauso aus wie in der Client-Variante:

Konfiguration

Object config = SAPUtils.createConfig();
config.setSystemNumber("03");
config.setSapServer("104.3.6.52");
config.setClient("003");
config.setSncMode("1"); //SNC aktivieren
config.setSncLibrary("c:\\My\\Library\\Path\\sapcrypto.dll"); //Bibliothek zum Verschlüsseln auf dem Server
config.setSncMyName("p:CN=" + USER + ", O=Cursor, L=Gießen, C=DE"); //eigener Name
config.setSncQOP("9"); //optional
  
config.setConnectToGroup(false);
config.setRfcName("Z_TEST");

Die beiden Parameter setX509Cert und setSncMyName erfordern aber ein anderes vorgehen.

Für setSncMyName muss statt USER SessionConstants.USER verwendet werden:

Konfiguration

config.setSncMyName("p:CN=" + SessionConstants.USER + ", O=Cursor, L=Gießen, C=DE"); //eigener Name

Das Zertifikat muss auf dem Clientrechner ausgelesen werden. Es erfordert daher zunächst eine Benutzeraktion. Dort muss das Zertifikat an die folgende Skript-Aktion weitergereicht werden.

• So sieht der ganze Prozess aus:

• Im Skript der Benutzeraktion wird das Zertifikat ausgelesen und in die Variable "sapcert" geschrieben. Dieser Name kann frei gewählt werden.
  

In der folgenden Skript-Aktion wird diese Variable wieder ausgelesen und im Konfigurationsobjekt gesetzt:

Konfiguration

Object config = SAPUtils.createConfig();
//..

config.setX509Cert(ProcessUtils.getVariable("sapcert"));

Serverseitig überserverseitige Workflows

Die Verwendung von SSO in serverseitigen Workflows ist nicht möglich, da hier keine Clientinteraktion erfolgt.

Parameterübergabe

Das Setzen von einfachen Parametern ist mit dem Aufruf von config.setSimpleParam("<Parametername>", <Wert>) möglich. Der Name des Parameters muss mit dem von dem RFC-Baustein erwarteten Namen übereinstimmen. Der Wert (2. Parameter) kann fest vergeben werden oder mittels der Notation ${Feldname.Entity} aus einem Feldwert des aktuell geöffneten Fensters gelesen werden. Handelt es sich nicht um einen Zahlwert, muss das ${Feldname.Entity} mit Anführungszeichen umschlossen werden.

SAP unterstützt sogenannte Strukturen als Parameter. Dabei handelt es sich im Wesentlichen um eine Gruppierung von diversen einfachen Feldern unter einem Namen. In der init-Methode kann mit der Methode setStructureParam(String structure, String field, Object value) ein Struktur-Parameter gefüllt werden. Der erste Parameter ist der Name der Struktur (wie von der RFC-Spezifikation vorgegeben), der zweite Wert identifiziert das Feld innerhalb der Struktur und der letzte Parameter stellt den eigentlichen Wert dar.

Eine weitere Möglichkeit für eine Parameterübergabe sind Tabellenparameter. Dabei handelt es sich um eine geordnete Liste von Strukturen. Zusätzlich zu den im vorigen Abschnitt erwähnten Parametern für die Konfiguration einer Struktur kommt damit ein weiterer Parameter für die Zeilennummer hinzu: setTableParamMapping(String tableName, int row, String field, Object value). Der erste Parameter gibt wieder den Namen des Tabellenparameters an, wie er von dem RFC-Baustein erwartet wird. Der zweite Parameter gibt die Zeilennummer an (die erste Zeile hat die Nummer 0!). Der dritte Parameter identifiziert das Feld innerhalb der Zeile, welches schließlich mit dem letzten Parameter gefüllt wird.

Rückgabewerte

SAP unterstützt Rückgabewerte in Form von Strukturen und Tabellen. Diese werden nach dem Aufruf unter einem Namen im Kontext der Aufrufdefinition zur Verfügung gestellt. Nach einem erfolgreichen Aufruf stehen in den Variablen String[] tableParams und String[] exportParams die Namen der jeweils zurückgegebenen Parameter zur Verfügung.

Die Variablen String[] tableParams und String[] exportParams können auch null sein.

Folgender Code zeigt die Namen aller zurückgegebener Tabellenparameter als Dialog an:

 public void handleResults()
{
for(int i = 0 ; tableParams != null && i < tableParams.length ; i++)
{
alert(tableParams[i]);
}
}

Alle Strukturen und Tabellen haben einen Namen. Unter diesem werden die einzelnen Parameter ebenfalls verfügbar gemacht.

Beispiele

Beispiel 1: Absprung nach SAP aus einem Geschäftspartner

public void init()
{
config.setClient("001");
config.setUser("user");
config.setPassword("userpw");
config.setSystemNumber("00");
config.setSapServer("172.16.0.22");
config.setRfcName("ZE_CURSOR_RFC_OBJECT_DISPLAY");
config.setSimpleParam("OBJECTTYPE", "01");
config.setSimpleParam("OBJECTKEY", "${CustomerNo1.Customer}");
}

Die ersten Zeilen dienen der Verbindungskonfiguration. Danach wird der aufzurufende RFC mittels config.setRfcName("ZE_CURSOR_RFC_OBJECT_DISPLAY") bestimmt und zwei einfache Parameter übergeben. Das erste Mapping OBJECTTYPE ist fest, das Mapping für den Parameter OBJECTKEY wird aus dem Wert des Feldes CustomerNo1 des aktuell geöffneten Geschäftspartners gelesen.

Beispiel 2: Auslesen der Tabelle KNA1:

public void init()
{
config.setClient("001");
config.setUser("user");
config.setPassword("userpw");
config.setSystemNumber("00");
config.setSapServer("172.16.0.22");
config.setRfcName("RFC_READ_TABLE");
config.setSimpleParam("QUERY_TABLE", "KNA1");
config.setSimpleParam("DELIMITER", ";");
config.setSimpleParam("ROWCOUNT", 10);
config.setTableParamMapping("FIELDS", 0, "FIELDNAME", "NAME1");
config.setTableParamMapping("FIELDS", 1, "FIELDNAME", "NAME2");
config.setTableParamMapping("FIELDS", 2, "FIELDNAME", "MANDT");
}
 
public void handleResults()
{
TAB512.writeHTML("c:/temp/sap/TAB512.html");
alert("Ausgabewerte wurden als HTML-Datei gespeichert!");
}

Die Verbindungskonfiguration ist wie im ersten Beispiel. Danach werden einige einfache Parameter gesetzt. Die letzten drei Zeilen der init-Methode füllen einen Tabellenparameter. Es werden die Namen der auszulesenden Spalten definiert.

Die Methode handleResults() wird verwendet, um das Ergebnis des Aufrufs (u. a. eine Tabelle mit dem Namen TAB512) mit dem Aufruf der Methode writeHTML zu speichern. Dies ist ein Beispiel dafür, wie Rückgabewerte aus SAP-Aufrufen gehandhabt werden können. Die zweite Zeile alert("...") ist lediglich ein Aufruf einer vordefinierten Methode, so wie er in jedem Script verwendet werden kann.

Beispiel 3: Aufruf eines RFC's mit einem Struktur-Parameter:

public void init()
{
config.setClient("001");
config.setUser("user");
config.setPassword("userpw");
config.setSystemNumber("00");
config.setSapServer("172.16.0.22");
config.setRfcName("Z_FBO_TESTPARAM_01");
config.setStructureParam("VTR", "MANDT", "001");
config.setStructureParam("VTR", "VERTRAG", "${InstallationNo.Installation}");
}

Dieses Beispiel demonstriert die Konfiguration eines Struktur-Parameters. In den letzten beiden Zeilen wird innerhalb der Struktur VTR zuerst das Feld MANDT auf den Wert 001 gesetzt und danach das Feld VERTRAG in der gleichen Struktur auf den Wert des Feldes InstallationNo.Installation gesetzt. Das Ersetzen des Platzhalters erfolgt zur Laufzeit analog zu einer beliebigen Aufrufdefinition.

Änderungen an Version, Schnittstellen und Restriktionen der Zielsoftware können verursachen, dass bei einzelnen Versionen der SAP-Aufruf nicht funktioniert, wodurch zusätzlicher Integrationsaufwand seitens CURSOR Software AG entsteht.

Integration des SAP JavaConnectors 3.x

Wird beim Kunden die SAPGUI 7.1 oder höher installiert, wird auf den JavaConnector 3.x (statt wie bisher 2.x) zurückgegriffen. Dieser enthält neue Klassen, was einige Änderungen in der Benutzung nach sich zieht.

JCo 2.x

• librfc32.dll in windows\system32 ablegen.

• sapjco.jar und sapjcorfc.dll im Ordner CustExt ablegen.

JCo 3.x

• librfc32.dll und librfc32u.dll in windows\system32 ablegen.

• sapjco3.jar und sapjco3.dll im Ordner CustExt ablegen.

Änderungen im Skript

Es wurde versucht keine Änderungen an bestehenden Skripten zu machen. Da SAP aber die Klassen geändert hat, konnte das nicht ganz erreicht werden. Die Methode "getField(..)" auf einer Struktur existiert nicht mehr. Stattdessen muss nun "getString(...)" (bzw. "getInt(..)" etc.) benutzt werden.

Beispiel:

public void handleResults()
{
String text = "";
 
RET.firstRow();
for (int i = 0 ; i < RET.getNumRows(); i++)
{
text += RET.getField("COUNTER").Value + " ";
Name2.Value = RET.getField("COUNTER").Value;
text += RET.getField("LINE").Value + "\n";
Name3.Value = RET.getField("LINE").Value;
RET.nextRow() ;
}
}

wird zu

public void handleResults()
{
String text = "";
 
RET.firstRow() ;
for (int i = 0 ; i < RET.getNumRows(); i++)
{
text += RET.getString("COUNTER") + " ";
Name2.Value = RET.getString("COUNTER");
text += RET.getString("LINE") + "\n";
Name3.Value = RET.getString("LINE");
RET.nextRow() ;
}
}

Typ: WEBSERVICE

Siehe →Ausgehende Webservices .