CallAPI – Übersicht

CallAPIs werden verwendet, um Prozesse im AE-System von externen Systemen aus mithilfe der Automation Engine scripting language auszulösen. Verwenden Sie CallAPIs, um ausführbare Objekte zu starten, Inhalte von Variablenobjekten festzulegen oder zu lesen oder Statusdetails zu Aufgaben abzurufen. Als Administrator richten Sie die CallAPI ein, und Sie definieren die Anmeldeinformationen, die Verbindungsdaten zur AE und ihre plattformspezifischen Parameter. Sie können die CallAPI entweder mit Ihrem eigenen Programm oder mit einem Dienstprogramm verwenden. Eine CallAPI ist auf 32.000 Zeichen beschränkt, wie alle Scripts in der Automation Engine scripting language.

Wichtig! Ab Version 21 wird für die Kommunikation zwischen dem JCP und dem Proxy ausschließlich TLS/SSL verwendet. Da die CallAPI TLS/SSL nicht unterstützt und auch weiterhin eine Verbindung zum CP herstellt, ist es nicht möglich, die CallAPI zusammen mit dem Proxy zu verwenden.

Tipp: Ziehen Sie in einigen Fällen die Verwendung der REST-API anstelle der CallAPI in Betracht. Die REST-API hat einen /scripts-Endpunkt, der CallAPI-Funktionen abdeckt. Weitere Informationen finden Sie unter REST-API.

Hinweis: Diese Integrationsfunktion kann, wie alle Integrationen der Automic system, Workflows für Dienstorchestrierung unterstützen. Solche Workflows koordinieren automatisierte Prozesse, die auf verschiedenen Plattformen bzw. in verschiedenen Domänen und Anwendungen ausgeführt werden, um einen bestimmten IT-Dienst bereitzustellen. Weitere Informationen finden Sie unter Info zur Dienst-Orchestrierung.

Diese Seite beinhaltet Folgendes:

Anmelden beim AE-System

Für die Anmeldung beim AE-System benötigt die CallAPI einen gültigen Benutzer. Dieser Benutzer muss die Berechtigung Anmeldung über CallAPI und Ausführen-Rechte besitzen.

Ihre Zugangsdaten (Kunde, Benutzer, Abteilung und Kennwort) können Sie in der INI-Datei der CallAPI angeben. Alternativ können Sie dies auch beim Aufruf der CallAPI angeben.

Sie können Ihr Passwort mit dem Programm UCYBCRYP.EXE verschleiern. Beachten Sie, dass der verschleierte String maximal 64 Zeichen lang sein darf. Weitere Informationen finden Sie unter Verschleiern von Passwörtern.

Herstellen einer Verbindung zur Automation Engine

Um das Script im gewünschten AE-System aktivieren zu können, braucht die CallAPI die Verbindungsinformationen zum entsprechenden Kommunikationsprozess. Tragen Sie die Verbindungsinformationen in der INI-Datei ein (z. B. 2217=localhost). Bei CallAPI-Aufrufen aus Ihrem eigenen Programm lassen sich diese Informationen auch direkt übergeben.

Wichtig!

  • Ab Version 21 verwenden Java- und SAP-CallAPIs TLS/SSL für die Verbindung mit der Automation Engine. Sie richten eine Verbindung mit dem neuen Java-Kommunikationsprozess (JCP) ein. Alle anderen CallAPIs erstellen weiterhin eine Verbindung mit dem CP.

  • Die CallAPI unterstützt UTF-8 nicht. Die AE behandelt die CallAPI als Nicht-UTF-8-Komponente. Beispielsweise wird der Klartextwert eines Kennworts immer als Legacy-Codierung verarbeitet.

Weitere Informationen:

In Automic Automation Kubernetes Edition stellen CallAPIs eine Verbindung zu einem TCP-Load Balancer her. Die Adresse des Load Balancers muss auf beiden Seiten definiert sein: Automation Engine und CallAPI. Die einzigen Ausnahmen sind die CallAPIs für Java und SAP, die aktualisiert werden müssen, um TLS/SSL für die Verbindung mit der Automation Engine verwenden zu können. Diese beiden CallAPIs stellen eine Verbindung mit dem Java-Kommunikationsprozess (JCP) über einen Ingress/HTTPS-Load Balancer her.

Weitere Informationen:

Meldungen

Wenn Sie ein Job-Objekt verwenden, das das CallAPI-Dienstprogramm aufruft, können Sie die zugehörigen Meldungen im Job-Report sehen.

Mit der Script-Anweisung :STOP ist es möglich, Meldungsnummern und -texte an die CallAPI zu übergeben. Diese werden in Script-Variablen gespeichert und können so mit Ihren eigenen Programmen ausgelesen werden. Die Namen dieser Variablen hängen von der verwendeten Programmiersprache ab. Abhängig vom Stoppmodus, den Sie in der Script-Anweisung :STOP definieren, bricht das Script entweder ab oder fährt mit der Ausführung fort.

Verwendung der CallAPI mit Ihrem eigenem Programm

Mit der CallAPI können Sie Scripts im AE-System aus eigenen Programmen heraus verarbeiten, die in C, C++, Cobol, Java oder Visual Basic geschrieben sind. Gute Kenntnisse der Programmiersprache, in denen dieses Programm geschrieben wurde, werden dafür vorausgesetzt.

Der Ablauf zur Script-Aktivierung läuft immer in folgenden drei Schritten:

  1. Anmelden beim AE-System
  2. Übertragen des Scripts an das AE-System
  3. Abmelden vom AE-System

Natürlich können Sie sich gleichzeitig an verschiedene AE-Systeme anmelden und mehrere Scripts ausführen.

CallAPI mit C, C++

Im Auslieferungsverzeichnis sind auch Programmbeispiele enthalten, die Ihnen zeigen, wie Sie die CallAPI mit C oder C++ aufrufen. Die Datei "uccall3.h" gibt genauen Aufschluss über die Struktur und die Funktionen.

Sie müssen die Dateien vom Typ "uccall3.h" und die entsprechende Bibliothek für Ihre Plattform integrieren. Beachten Sie, dass Ihr Programm Zugriff auf die erforderlichen Bibliotheken wie "ucxbwi3c.dll" (Windows) oder "libucxblx6c.so" (Linux) usw. benötigt.

Funktionen

Die folgenden Funktionen können Sie in Ihrem Programm nutzen. Als Rückgabewert liefern die Funktionen entweder 0, wenn die Aktion erfolgreich war, oder eine Meldungsnummer im Fehlerfall. Der Datentyp aller Rückgabewerte ist long.

  • UCCALL3_Logon (Struktur, Login-Daten, Verbindung)
    Für die Anmeldung am AE-System
    Datentyp der Struktur: UCCALL_PARAMS*
    Datentyp der Login-Daten: char*
    Datentyp der Verbindung: char*
    Datentyp des Rückgabewertes: long

    • Format der Login-Daten: Mandant, Benutzer, [Abteilung, [Passwort]]

    Format der Verbindungsdaten für den Kommunikationsprozess: DNS-Name:Port-Nummer oder TCP/IP-Adresse:Port-Nummer

  • UCCALL3_ActivateScript (Struktur, Script)
    Für die Aktivierung eines Scripts
    Datentyp der Struktur: UCCALL_PARAMS*
    Datentyp des Scripts: char*
    Datentyp des Rückgabewerts: long

  • UCCALL3_Logoff (Struktur)
     Für die Abmeldung vom AE -System
    Datentyp der Struktur: UCCALL_PARAMS*
    Datentyp des Rückgabewerts: long

  • UCCALL3 (Strukturen)
    Universelle Funktion
    UCCALL3 kann anstelle der oben beschriebenen Funktionen aufgerufen werden. Allerdings ist es dann erforderlich, den OpCode in der Struktur anzugeben, damit die gewünschte Operation durchgeführt wird.
    Datentyp der Struktur: UCCALL_PARAMS*
    Datentyp des Rückgabewerts: long

Variablen

Informationen wie z. B. der Systemname oder die zurückgegebene RunID des Scripts sind in der Struktur UCCALL_PARAMS gespeichert. Sie enthält folgende Variablen:

  • cOpCode
    Datentyp: char [4]
    Operationscode
    Diese Variable muss gesetzt werden, wenn die universelle Funktion verwendet werden soll.

    • Zulässige Werte:

    • OPC_LOGON
      Führt eine Anmeldung beim AE-System durch.
    • OPC_LOGOFF
      Führt eine Abmeldung vom AE-System durch.
    • OPC_ACTIVATE_SCRIPT
      Aktiviert ein Script.
  • cErrorCode
    Datentyp: char

    • Der Fehlercode in "cErrorCode" wird automatisch gesetzt und kann einen der folgenden Werte enthalten:

    • " "
      Kein Fehler aufgetreten
    • P
      Ungültige(r) Parameter
    • O
      Ungültiger OpCode
    • Q
      Login fehlgeschlagen
    • R
      Speicherzuordnung fehlgeschlagen
    • L
      Speicherfreigabe fehlgeschlagen
    • S
      Socket-Fehler
    • T
      Timeout
    • U
      Fehlermeldung vom AE-System
  • cInterface
    Datentyp: char [3]
    Die Schnittstellennummer muss immer den Wert 3 enthalten
  • cSystemName
    Datentyp: char [8]
    Name des AE–Systems, zu dem die Verbindung hergestellt werden soll
  • sTimeout
    Datentyp: unsigned short
    Zeitraum in Sekunden, wie lange die CallAPI wartet, bis das AE-System antwortet
  • cLanguage
    Datentyp: char
    Sprache, in der Meldungen geschrieben werden
  • cFlag1
    Datentyp: unsigned char

    • Dieses Kennzeichen bewirkt je nach gesetztem Wert eine der folgenden Verarbeitungsoptionen:

    • CALL_FLAG1_INI_SERVER
      Die Verbindung zum Kommunikationsprozess wird aus der INI-Datei abgerufen.
    • CALL_FLAG1_INI_LOGIN
      Login-Daten werden aus der INI-Datei abgerufen.
    • CALL_FLAG1_INI_USEMSL
      Diese Option wandelt Variablenmeldungsteile in einen vollständigen Meldungstext um.
    • CALL_FLAG1_INI_USEALL
      Die Einstellungen, die im Abschnitt [GLOBAL] der INI-Datei definiert sind, werden verwendet.
    • CALL_FLAG1_TRC_HANDLE
      Nur für die interne CallAPI-Verarbeitung
    • CALL_FLAG1_LOG_HANDLE
      Nur für die interne CallAPI-Verarbeitung
    • CALL_FLAG1_INI_FILE
      Name der INI-Datei
    • CALL_FLAG1_TRC_OUTPUT
      Nur für die interne CallAPI-Verarbeitung
  • lUnused1
    Datentyp: unsigned long [4]
    Nicht verwendet
  • Output
    Datentyp: unsigned long
    Nicht verwendet
  • lUnsued2
    Datentyp: unsigned long [4]
    Nicht verwendet
  • lScriptRunNr
    Datentyp: unsigned long
    RunID des Scripts
  • lRetCode
    Datentyp: unsigned long
    Rückgabewert der Script-Ausführung
  • cRetText
    Datentyp: char [256]
    Variabler Meldungsteil, der den Wert des Rückgabewerts erklärt
  • pIniFile
    Datentyp: char*
    Pfad und Name der INI-Datei
  • hZuLog
    Datentyp: unsigned long
    Nur für interne CallAPI-Verarbeitung
  • hZuTrc
    Datentyp: unsigned long
    Nur für interne CallAPI-Verarbeitung
  • hZuHlp
    Datentyp: unsigned long
    Nur für interne CallAPI-Verarbeitung
  • lUnused3
    Datentyp: unsigned long [11]
    Nicht verwendet
  • pOwnPointer
    Datentyp: void*
    Nur für interne CallAPI-Verarbeitung

CallAPI mit Cobol

Sie können das CallAPI mit dem Kommando CALL UCCALL3 aufrufen. Als Rückgabewert liefert der Aufruf entweder 0, wenn die Aktion erfolgreich war, oder eine Meldungsnummer im Fehlerfall.

  • CALL UCCALL3 USING Struktur, Login-Daten, Verbindung
    Für die Anmeldung am AE-System
    Format der Login-Daten:Mandant, Benutzer, [Abteilung, [Kennwort]]
    Format der Verbindungsdaten für den Kommunikationsprozess:DNS-Name:Port-Nummer oder TCP/IP-Adresse:Port-Nummer
  • CALL UCCALL3 USING Struktur, Script
    Für die Aktivierung eines Scripts
  • CALL UCCALL3 USING Struktur
    Für die Abmeldung vomAE-System

Variablen

Im ausgelieferten Beispielprogramm sehen Sie den Aufbau der Struktur AE-RECORD. Sie enthält folgende Variablen:

  • UC-OPERATION
    Datentyp:     PIC X(4)
    Operationscode
    Diese Variable muss gesetzt werden, wenn die universelle Funktion verwendet werden soll.

    • Zulässige Werte:

    • OPC_LOGON
      Führt eine Anmeldung beim AE-System       durch.
    • OPC_LOGOFF
      Führt eine Abmeldung vom AE-System       durch.
    • OPC_ACTIVATE_SCRIPT
      Aktiviert ein Script.
  • UC-ERROR-CODE
    Datentyp: PIC X

    • Der Fehlercode in "cErrorCode" wird automatisch gesetzt und kann einen der folgenden Werte enthalten:

    • " "
      Kein Fehler aufgetreten
    • P
      Ungültige(r) Parameter
    • O
      Ungültiger OpCode
    • I
      Initialisierung fehlgeschlagen
    • Q
      Login fehlgeschlagen
    • R
      Speicherzuordnung fehlgeschlagen
    • L
      Speicherfreigabe fehlgeschlagen
    • S
      Socket-Fehler
    • T
      Timeout
    • U
      Fehlermeldung vom AE-System
  • UC-INTERFACE-NR
    Datentyp: PIC X(3)
    Schnittstellennummer muss immer den Wert 3 enthalten.
  • UC-SYSTEM-NAME
    Datentyp: PIC X(8)
    Der Name des AE -Systems, zu dem die Verbindung hergestellt werden soll.
  • UC-TIMEOUT
    Datentyp: PIC 9(4) COMP-4
    Zeitraum in Sekunden, wie lange die CallAPI wartet, bis das AE-System antwortet.
  • UC-LANGUAGE
    Datentyp: PIC X
    Sprache, in der Meldungen geschrieben werden
  • FILLER
    Datentyp: PIC X(2)
    Nicht verwendet
  • UC-FLAG1
    Datentyp: PIC X

    • Dieses Kennzeichen bewirkt je nach gesetztem Wert eine der folgenden Verarbeitungsoptionen:

    • CALL_FLAG1_INI_SERVER
      Die Verbindung zum Kommunikationsprozess wird aus der INI-Datei abgerufen.
    • CALL_FLAG1_INI_LOGIN
      Login-Daten werden aus der INI-Datei abgerufen
    • CALL_FLAG1_INI_USEMSL
      Diese Option wandelt Variablenmeldungsteile in einen vollständigen Meldungstext um.
    • CALL_FLAG1_INI_USEALL
      Die Einstellungen, die im Abschnitt [GLOBAL] der INI-Datei definiert sind, werden verwendet.
    • CALL_FLAG1_TRC_HANDLE
      Nur für die interne CallAPI-Verarbeitung
    • CALL_FLAG1_LOG_HANDLE
      Nur für die interne CallAPI-Verarbeitung
    • CALL_FLAG1_INI_FILE
      Name der INI-Datei
    • CALL_FLAG1_TRC_OUTPUT
      Nur für die interne CallAPI-Verarbeitung
  • FILLER
    Datentyp: PIC X(2)
    Nicht verwendet
  • UC-OUTPUT-LEN
    Datentyp: PIC 9(8) COMP-4
    Nicht verwendet
  • UC-RUNNR
    Datentyp: PIC 9(8) COMP-4
    RunID des Scripts
  • UC-RETURN-CODE
    Datentyp: PIC 9(8) COMP-4
    Rückgabewert der Script-Ausführung
  • UC-MESSAGE-TEXT
    Datentyp: PIC X(256)
    Variabler Meldungsteil, der den Wert des Rückgabewerts erklärt
  • UC-PRT-INI
    Datentyp: PIC S9(8)
    Nur für die interne CallAPI-Verarbeitung
  • UC-HND-LOG
    Datentyp: PIC S9(8)
    Nur für die interne CallAPI-Verarbeitung
  • UC-HND-TRC
    Datentyp: PIC S9(8)
    Nur für die interne CallAPI-Verarbeitung
  • UC-HND-HLP
    Datentyp: PIC S9(8)
    Nur für die interne CallAPI-Verarbeitung
  • UC-POINTER
    Datentyp: PIC S9(8)
    Nur für die interne CallAPI-Verarbeitung
  • FILLER
    Datentyp: PIC X(12)
    Nicht verwendet
  • UC-INIFILE
    Datentyp: PIC X(45)
    Pfad und Name der INI-Datei

CallAPI mit Java

Wichtig! Ab Version 21 verwendet die CallAPI für Java TLS/SSL und stellt eine Verbindung zum neuen Java-Kommunikationsprozess (JCP) her. Weitere Informationen finden Sie unter Verbindungen zur AE sichern (TLS/SSL).

Um die CallAPI mit Java verwenden zu können, müssen Sie die Klasse "UCCALL3" importieren, die aus dem Paket "com.uc4.uccall3" importiert werden muss.

Das Auslieferungsverzeichnis enthält Beispielprogramme, die Ihnen zeigen, wie Sie sich anmelden, Scripts aktivieren, sich mit verschiedenen Systemen verbinden, Verbindungsfehler finden usw. Die mitgelieferte CallAPI-Dokumentation bietet aktuelle Informationen über die Java-Klasse, Methoden und verfügbare Funktionen.

CallAPI mit Visual Basic

Um die CallAPI mit Ihren eigenen Visual Basic-Programmen zu verwenden, müssen Sie das COM-Objekt AE.Call3 registrieren.

Beispiel

regsvr32 c:\AUTOMIC\callapi\windows\bin\ucxbwi3c.dll

Verwenden Sie das Beispielprogramm, das in unserem Lieferverzeichnis enthalten ist. Hier finden Sie eine detaillierte Beschreibung, wie Sie ein Script aktivieren können.

Methoden

Die folgenden Funktionen können Sie in Ihrem Programm nutzen. Als Rückgabewert liefern die Funktionen entweder 0, wenn die Aktion erfolgreich war, oder eine Meldungsnummer im Fehlerfall.

  • Logon Mandant, Benutzer, [Abteilung, [Passwort]]
    Für die Anmeldung am AE-System
  • SetIniFile Pfad und Name der INI-Datei
    Gibt die INI-Datei an.
  • LogonAsDefault
     Die Anmeldung erfolgt über die Daten, die in der INI-Datei gespeichert sind.
  • ActivateScript Script
    Aktiviert ein Script.
  • Abmeldung
     Führt eine Abmeldung vom AE-System durch.

Attribute

Informationen über die Script-Ausführung werden automatisch in den folgenden Variablen hinterlegt:

  • lRunNr
     RunID des Scripts
    Datentyp: Long
  • lRetCode
     Rückgabewert der Script-Ausführung
    Datentyp:     Long
  • cRetText
     Variablenmeldungsteil, der den Rückgabewert erklärt
    Datentyp:     String

Verwendung des CallAPI-Dienstprogramms (ucxbxxxc)

Ein CallAPI-Dienstprogramm steht für jede unterstützte Plattform zur Verfügung. Für diesen Zweck sind keine Programmierkenntnisse erforderlich. Abhängig von Ihrem Betriebssystem können Sie dieses Dienstprogramm über Jobs, Prozeduren und ausführbare Dateien oder direkt von der Kommandozeile aus aufrufen.

Schreiben Sie das gewünschte Script in eine Textdatei und übergeben Sie diese beim Aufruf des Dienstprogramms. Für alle Plattformen gilt folgende Syntax:

CallAPI-Datei SCRIPT=Skriptdatei [LOGON=Mandant,Benutzer,Abteilung,Kennwort] [INI=INI-Datei] [QUEUE=Name des Queue-Objekts]

Parameter:

  • SCRIPT=
    Pfad und Name der Textdatei, welche das Script enthält
  • (Optional) LOGON=
    Automation Engine-Anmeldeinformationen, die sich aus Mandant, Benutzer, Abteilung und Kennwort zusammensetzen.
    Hinweis: Single Sign-On wird verwendet, wenn kein Benutzername angegeben ist
  • (Optional) INI=
    Pfad und Name der INI-Datei, die verwendet werden soll
    Hinweis: Sie müssen diesen Parameter angeben, wenn die INI-Datei umbenannt oder verschoben wurde.
  • (Optional)QUEUE=
    Keine Standardparameter
    Definiert die Queue, in der das Script ausgeführt werden soll, siehe Queue (QUEUE).
  • (Optional für z/OS) REMOTEID=
    Kein Standardparameter
    Definiert die ID, die das CallAPI verwendet, um sich anzumelden.
    Details hierzu finden Sie unter Verbindungen.

(Windows) Beispiel

UCXBXXXC SCRIPT=C:\AUTOMIC\CallAPI\script.txt LOGON=98,SMITH,DEPARTMENT,PASSWORD INI=C:\AUTOMIC\CallAPI\WINDOWS\ucxbxxxc.ini

Hinweise:

  • LOGON-Parameter ist nicht definiert: Die Anmeldeinformationen werden aus der INI-Datei abgerufen und Sie können sich erfolgreich anmelden.
  • LOGON-Parameter ist definiert, aber kein Kennwort: ein Anmeldefehler tritt auf, und der Zugriff wird verweigert.

Rückgabewerte

Das CallAPI-Dienstprogramm liefert Ihnen verschiedene Rückgabewerte, mit denen Sie den Script-Aktivierungsprozess verfolgen können:

  • 0
    AE Script wurde fehlerfrei aktiviert.
    Hinweis: Es können auch Fehler auftreten, die zwar eine Ausgabe im Meldungsfenster der Automic Web Interface und/oder im Report verursachen, aber das AE-Script nicht abbrechen. Dies kann passieren, wenn die Kommandos ACTIVATE_UC_OBJECT und IMPORT Fehler enthalten. In diesem Fall endet das CallAPI-Dienstprogramm immer mit dem Rückgabewert 0.
  • 4
    AE Script wurde aktiviert, aber dann mit der Script-Anweisung :STOP MSG, 50, "Beliebiger Text" beendet.
  • 8
    Fehler bei der Aktivierung des Scripts oder das AE-Script wurde mit dem Script-Befehl :STOP MSG, 51 -59, "Beliebiger Text" oder :STOP, NOMSG beendet
    Hinweis: Rückgabecode 8 wird angezeigt, wenn die Aktivierung des AE-Scripts aufgrund eines Fehlers abgebrochen wurde und nicht fortgesetzt werden kann. Dies kann passieren, wenn ein Script-Element nicht korrekt geschrieben ist oder wenn eine falsche Anzahl an Funktionsparametern angegeben wurde.
  • 12
    Fehler während der Anmeldung/Ausführung
    Hinweis: Der Rückgabewert 12 kann auf alle schwerwiegenden Fehler verweisen, die während der Anmeldung oder bei der Ausführung des CallAPI-Scripts aufgetreten sind. Sie müssen diese Ursachen manuell lösen.
  • 16
    Fataler Fehler: Die Script-Datei konnte nicht geöffnet oder gelesen werden.

(SAP) Der Startparameter für den RFC-Server ist unterschiedlich. "-I" ist der einzige Parameter und gibt den Pfad zur INI-Datei an:

  • (Windows) Beispiel

    UCXBRXXC -IC:\AUTOMIC\CallAPI\SAP\UCXSAPC.INI

  • (UNIX) Beispiel

    nohup ./ucxsapc -I./ucxsapc.ini

Scripts, die über eine CallAPI gestartet werden, werden in der Process Monitoring-Perspektive angezeigt. Ein statistischer Datensatz und ein Report werden erstellt.

Tipp: Verwenden Sie das Kontrollkästchen Deaktivierte Aufgaben einbeziehen oder ausschließen, um nach Ihrem Script zu suchen, und geben Sie den Aufgabentyp CallAPI an, oder geben Sie die Aufgaben-RunID des CallAPI-Scripts ein.

Plattformen für CallAPIs

Siehe auch: