CallAPI Overview

CallAPIs are used to trigger processes in an AE system from external systems by using the Automation Engine scripting language. Use CallAPIs to start executable objects, set or read the contents of Variable objects, or get status details about tasks. As an administrator, you set up the CallAPI and you define the login credentials, the connection data to the AE, and your platform-specific parameters. You can use the CallAPI either with your own program, or with a utility. A CallAPI is limited to 32000 characters, as are all scripts in the Automation Engine scripting language.

Tip: Consider using the REST API instead of the CallAPI in some cases. The REST API has a /scripts endpoint that covers Call API functions. The advantages are that you do not need to use several Service Manager services if you are connecting your own system(s) to several AE systems and/or clients. Also, the REST API does not require a user login whenever it is called. This is very helpful in situations where the workload is high. For more information, see REST API.

Note: This integration capability, like all integrations of the Automic system, can support Service Orchestration Workflows. Such Workflows orchestrate automated processes that run across multiple platforms, domains, and applications to deliver a specific IT service. For more information, see About Service Orchestration.

This page includes the following:

Logging into the AE System

To log in to the AE system, the CallAPI requires valid user credentials. A user must have the privilege Logon via CallAPI and must have Execute rights.

You can specify your login data (client, user, department, and password) in the INI file of the CallAPI. Alternatively, you specify it when you call the CallAPI.

You can obfuscate your password by using the program UCYBCRYP.EXE. The obfuscated string must not exceed 64 characters. For details, see Obfuscating Passwords.

Connecting to the Automation Engine

To activate your script in the required AE system, the CallAPI requires connection information for relevant communication processes. Enter this connection information in the INI file (such as 2217=localhost). In CallAPI calls from your own programs, you can directly assign this information.

Important!

  • As of version 21, the Java and SAP CallAPIs use TLS/SSL to connect to the Automation Engine. They establish a connection to the new Java communication process (JCP). All other CallAPIs still connect to the CP.

  • The CallAPI does not support UTF-8. The AE handles the CallAPI as a non-UTF-8 component. For example, a password's clear text value is always handled as in legacy encoding.

More information:

In Automic Automation Kubernetes Edition, CallAPIs establish a connection to a TCP load balance. The address of the load balancer must be defined on both sides: the Automation Engine and the CallAPI. The only exceptions are the CallAPIs for Java and SAP, which must be upgraded to use TLS/SSL to connect to the Automation Engine. These two CallAPIs establish a connection with the Java communication process (JCP) through an HTTPS load balancer.

More information:

Messages

If you use a Job object that calls the CallAPI utility, you can see the related messages in the job report.

You can use the script statement :STOP to assign message numbers and texts to the CallAPI. They are stored in script variables and can be read with your own programs. The names of these variables depend on the programming language you are using. Depending on the stop mode that you define in the script statement :STOP, the script either aborts or continues to run.

Using the CallAPI with your Own Program

You can use the CallAPI to process scripts in the AE system from your own programs that are written in C, C++, Cobol, Java, or Visual Basic. Sound knowledge of the programming language in which the program is written is required for this purpose.

Scripts are always activated with the following three steps:

  1. Log in to the AE system.
  2. Transfer the script to the AE system.
  3. Log off from the AE system.

You can log in to several AE systems at the same time and process various scripts.

CallAPI with C, C++

The delivery directory contains sample programs that provide a detailed description of how you call the CallAPI with C or C++. The file uccall3.h provides information about structure and functions.

You need to integrate the files uccall3.h and the respective library for your platform. Note that your program requires access to the required libraries such as ucxbwi3c.dll (Windows), or libucxblx6c.so (Linux) etc.

Functions

You can use the several functions in your programs. They supply return code 0 if the action was successful, or a message number if an error occurred. The data type of all return codes is long.

  • UCCALL3_Logon (structure, login data, connection)
    Use it to log in to the AE system
    Data type of structure: UCCALL_PARAMS*
    Data type of login data: char*
    Data type of connection: char*
    Data type of return code: long

    • Format of login data: client, user, [department, [password]]

    Format of connection data for the communication process: DNS name:port number or TCP/IP address:port number

  • UCCALL3_ActivateScript (structure, script)
    Use it to activate a script
    Data type of structure: UCCALL_PARAMS*
    Data type of script: char*
    Data type of return code: long

  • UCCALL3_Logoff (structure)
    Use it to log off from the AE system
    Data type of structure: UCCALL_PARAMS*
    Data type of return code: long

  • UCCALL3 (structures)
    Universal function
    UCCALL3 can be called instead of the functions described above. In this case, indicate the opcode in the structure in order to have the required operation processed.
    Data type of structure: UCCALL_PARAMS*
    Data type of return code: long

Variables

Information such as the system name or the RunID of the script is stored in the structure UCCALL_PARAMS. It contains the following variables:

  • cOpCode
    Data type: char [4]
    Operation code
    This variable must be set if the universal function should be used.

    • Allowed values:

    • OPC_LOGON
      Logs in to the AE system
    • OPC_LOGOFF
      Logs off the AE system
    • OPC_ACTIVATE_SCRIPT
      Activates a script
  • cErrorCode
    Data type: char

    • The error code in cErrorCode is automatically set and can contain one of the following values:

    • " "
      No error occurred
    • P
      Invalid parameter(s)
    • O
      Invalid opcode
    • Q
      Login failed
    • R
      Memory allocation failed
    • L
      Memory release failed
    • S
      Socket error
    • T
      Timeout
    • U
      Error message of the AE system
  • cInterface
    Data type: char [3]
    The interface number must always contain the value 3.
  • cSystemName
    Data type: char [8]
    Name of the AE system to which the connection should be established
  • sTimeout
    Data type: unsigned short
    Period in seconds during which the CallAPI waits for the AE system to respond
  • cLanguage
    Data type: char
    Language in which messages are written
  • cFlag1
    Data type: unsigned char

    • Depending on the specified value, this flag results in one of the following processing options:

    • CALL_FLAG1_INI_SERVER
      The connection to the communication process is retrieved from the INI file.
    • CALL_FLAG1_INI_LOGIN
      Login data is retrieved from the INI file.
    • CALL_FLAG1_INI_USEMSL
      This option converts variable message parts to a complete message text.
    • CALL_FLAG1_INI_USEALL
      The settings that are defined in the INI file section [GLOBAL] are used.
    • CALL_FLAG1_TRC_HANDLE
      For internal CallAPI processing only
    • CALL_FLAG1_LOG_HANDLE
      For internal CallAPI processing only
    • CALL_FLAG1_INI_FILE
      Name of INI file
    • CALL_FLAG1_TRC_OUTPUT
      For internal CallAPI processing only
  • lUnused1
    Data type: unsigned long [4]
    Not used
  • Output
    Data type: unsigned long
    Not used
  • lUnsued2
    Data type: unsigned long [4]
    Not used
  • lScriptRunNr
    Data type: unsigned long
    RunID of the script
  • lRetCode
    Data type: unsigned long
    Return code of script execution
  • cRetText
    Data type: char [256]
    Variable message part that explains the value of the return code
  • pIniFile
    Data type: char*
    Path and name of INI file
  • hZuLog
    Data type: unsigned long
    For internal CallAPI processing only
  • hZuTrc
    Data type: unsigned long
    For internal CallAPI processing only
  • hZuHlp
    Data type: unsigned long
    For internal CallAPI processing only
  • lUnused3
    Data type: unsigned long [11]
    Not used
  • pOwnPointer
    Data type: void*
    For internal CallAPI processing only

CallAPI with Cobol

You can call the CallAPI by using the command CALL UCCALL3. Return code 0 is supplied if the action was successful or a message number if an error occurred.

  • CALL UCCALL3 USING structure, login data, connection
    Use it to log in to the AE system
    Format of login data: Client, user, [department, [password]]
    Format of connection data for the communication process: DNS name:port number or TCP/IP address:port number
  • CALL UCCALL3 USING structure, script
    Use it to activate a script
  • CALL UCCALL3 USING structure
    Use it to log off from theAE system

Variables

The supplied sample program explains the structure AE-RECORD. It contains the following variables:

  • UC-OPERATION
    Data type:     PIC X(4)
    Operation code
    This variable must be set if the universal function should be used.

    • Allowed values:

    • OPC_LOGON
      Logs on to the AE system
    • OPC_LOGOFF
      Logs off from the AE system
    • OPC_ACTIVATE_SCRIPT
      Activates a script
  • UC-ERROR-CODE
    Data type: PIC X

    • The error code in cErrorCode is automatically set and can contain one of the following values:

    • " "
      No error occurred
    • P
      Invalid parameter(s)
    • O
      Invalid opcode
    • I
      Initialization failed
    • Q
      Login failed
    • R
      Memory allocation failed
    • L
      Memory release failed
    • S
      Socket error
    • T
      Timeout
    • U
      Error message of the AE system
  • UC-INTERFACE-NR
    Data type: PIC X(3)
    The interface number must always contain the value 3.
  • UC-SYSTEM-NAME
    Data type: PIC X(8)
    The name of the AE system to which the connection should be established.
  • UC-TIMEOUT
    Data type: PIC 9(4) COMP-4
    Time in seconds during which the CallAPI waits for the AE system to respond.
  • UC-LANGUAGE
    Data type: PIC X
    Language in which messages are written
  • FILLER
    Data type: PIC X(2)
    Not used
  • UC-FLAG1
    Data type: PIC X

    • Depending on the specified value, this flag results in one of the following processing options:

    • CALL_FLAG1_INI_SERVER
      The connection to the communication process is retrieved from the INI file.
    • CALL_FLAG1_INI_LOGIN
      Login data is retrieved from the INI file
    • CALL_FLAG1_INI_USEMSL
      This option converts variable message parts to a complete message text.
    • CALL_FLAG1_INI_USEALL
      The settings that are defined in the INI file section [GLOBAL] are used.
    • CALL_FLAG1_TRC_HANDLE
      For internal CallAPI processing only
    • CALL_FLAG1_LOG_HANDLE
      For internal CallAPI processing only
    • CALL_FLAG1_INI_FILE
      Name of INI file
    • CALL_FLAG1_TRC_OUTPUT
      For internal CallAPI processing only
  • FILLER
    Data type: PIC X(2)
    Not used
  • UC-OUTPUT-LEN
    Data type: PIC 9(8) COMP-4
    Not used
  • UC-RUNNR
    Data type: PIC 9(8) COMP-4
    RunID of the script
  • UC-RETURN-CODE
    Data type: PIC 9(8) COMP-4
    Return code of script execution
  • UC-MESSAGE-TEXT
    Data type: PIC X(256)
    Variable message part that explains the value of the return code
  • UC-PRT-INI
    Data type: PIC S9(8)
    For internal CallAPI processing only
  • UC-HND-LOG
    Data type: PIC S9(8)
    For internal CallAPI processing only
  • UC-HND-TRC
    Data type: PIC S9(8)
    For internal CallAPI processing only
  • UC-HND-HLP
    Data type: PIC S9(8)
    For internal CallAPI processing only
  • UC-POINTER
    Data type: PIC S9(8
    For internal CallAPI processing only
  • FILLER
    Data type: PIC X(12)
    Not used
  • UC-INIFILE
    Data type: PIC X(45)
    Path and name of INI file

CallAPI with Java

Important! As of version 21, the CallAPI for Java uses TLS/SSL and establishes a connection to the new Java communication process (JCP), see Securing Connections to the AE (TLS/SSL)

To use the CallAPI with Java, you must import the UCCALL3 class to be imported from the com.uc4.uccall3 package.

The delivery directory contains sample programs that show you how to log on, activate scripts, connect to different systems, find connections error, and so on. The supplied CallAPI documentation provides up-to-date information about the Java class, methods and available functions.

CallAPI with Visual Basic

To use the CallAPI with your own Visual Basic programs, you must register the COM object AE.Call3.

Example

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

Use the sample program that is included in our delivery directory. It provides a detailed description of how you can activate a script.

Methods

In your program, you can use the following functions. These functions supply return code 0 if the action was successful, or a message number if an error has occurred.

  • Logon client, user, [department, [password]]
    Use it to log in to the AE system
  • SetIniFile path and name of INI file
    Specifies the INI file
  • LogonAsDefault
    Logs on by using the data that is specified in the INI file
  • ActivateScript script
    Activates a script
  • Logoff
    Use it to log off from the AE system

Attributes

Information about script execution is automatically stored in the following script variables:

  • lRunNr
    RunID of the script
    Data type: Long
  • lRetCode
    Return code of the script execution
    Data type:     Long
  • cRetText
    Variable message part which explains the return code value
    Data type:     String

Using the CallAPI Utility (ucxbxxxc)

You can use a CallAPI utility which is provided for each supported platform. No programming knowledge is required for this purpose. Depending on your operating system, you can call this utility from jobs, procedures, executable files or directly from the command line.

Write the script that you want to use in a text file and assign this file when you call the utility. The following syntax applies to all platforms:

CallAPI file SCRIPT=script file [LOGON=client,user,department,password] [INI=INI file] [QUEUE=Name of Queue object]

Parameters:

  • SCRIPT=
    Path and name of the text file that contains the script
  • (Optional) LOGON=
    Automation Engine login information that is composed of client, user, department and password.
    Note: Single Sign-On is used if no user name is provided
  • (Optional) INI=
    Path and name of the INI file that should be used
    Note: You must specify this parameter when the INI file has been renamed or moved.
  • (Optional) QUEUE=
    No default parameter
    Defines the Queue in which the script should run, see Queue (QUEUE).
  • (Optional for z/OS) REMOTEID=
    No default parameter
    Defines the identification that the CallAPI uses to log on.
    For details, see Connections

(Windows) Example

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

Notes:

  • LOGON parameter is not defined: The login information is retrieved from the INI file, you can successfully log on.
  • LOGON parameter is defined, but no password: A logon error will occur, and access is denied.

Return Codes

The CallAPI utility supplies several return codes that can be used to monitor the script activation process:

  • 0
    AE Script was activated without an error.
    Note: There are errors that cause an output in the Messages pane of the Automic Web Interface and/or the report but they do not cause the AE Script to abort. This can happen if the commands ACTIVATE_UC_OBJECT and IMPORT include errors. The CallAPI utility always ends with the return code 0 in such a case.
  • 4
    AE Script was activated, but then terminated with the script statement :STOP MSG, 50, "Any text."
  • 8
    Error when activating script or the AE Script was terminated with the script statement :STOP MSG, 51 - 59, "Any text." or :STOP, NOMSG
    Note: Return code 8 is displayed if the activation of AE Script has been canceled because of an error, and cannot be continued. This can happen if a script element is not spelled correctly, or if an incorrect number of function parameters is specified.
  • 12
    Error during logon/execution.
    Note: Return code 12 can refer to any fatal error that occurred during logon or the execution of the CallAPI script. You need to solve these causes manually.
  • 16
    Fatal error: The script file could not be opened or read.

(SAP) The start parameter for the RFC Server is different. -I is the only parameter and it specifies the path to the INI file:

  • (Windows) Example

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

  • (UNIX) Example

    nohup ./ucxsapc -I./ucxsapc.ini

Scripts that are started through a CallAPI are displayed in the Process Monitoring perspective. A statistical record and a report are created.

Tip: Use the Including or Excluding Deactivated Tasks checkbox to search for your script and specify the task type CallAPI, or enter the Task RunID of the CallAPI script.

Platforms for CallAPIs

See also: