Java connector methods

  • Release version: Xanadu
  • Updated August 1, 2024
  • 7 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Java connector methods

    The Java connector provides a comprehensive set of methods to interact programmatically with Java applications at three levels: connector, screen, and element. These methods enable ServiceNow customers to automate launching, controlling, reading, and manipulating Java application windows and their UI elements, facilitating robust automation workflows.

    Show full answer Show less

    Connector level methods

    • Start: Launches the Java application from a specified local path and brings it into focus. This must be the first method executed.
    • GetMainWindowHandle: Retrieves the window handle of the launched Java application.
    • GetMainWindowTitle: Returns the title of the Java application window.
    • CloseMainWindow and Terminate: Close or terminate the main application window respectively.

    Screen level methods

    These methods control and interact with the active Java application window and its elements:

    • Close, Maximize, Minimize, Restore, Focus: Manage window state and visibility.
    • GetFields: Retrieve data from configured text fields on the Java application screen. Requires prior configuration of text fields.
    • SetFields: Set custom text values in configured text fields to automate data entry.
    • GetInstanceCount: Returns the number of open instances of the Java application.
    • GetScreenShot: Captures a bitmap screenshot of the Java application screen.
    • GetWindowHandle: Fetches the Windows handle number for the Java application screen window.
    • IsCreated and WaitForCreate: Confirm if the Java application screen matches predefined configuration rules, with optional timeout and child element matching parameters.
    • MouseAction: Perform mouse operations (left, right, middle clicks) on the application window.
    • Resize: Adjust window size and position on screen.
    • SendKeys: Send keyboard inputs or data strings to the active field within the application, with options to clear existing data and set typing delays.

    Element level methods

    These methods operate on individual UI elements within the Java application screen:

    • GetAccessibleActions: Lists available actions for an element, such as "Click" for buttons.
    • GetInstanceCount: Returns the count of specific element types (e.g., number of text boxes).
    • GetText: Retrieves text content from configured text box elements.
    • IsCreated: Checks if an element matches its configuration rules.
    • MouseClick: Performs a left mouse click on the element.
    • PerformAction: Executes specified actions on elements, requiring exact action names from GetAccessibleActions.
    • SetPassword: Inputs passwords securely into password fields using secured strings. If it fails, using SendKeys as fallback is recommended.
    • UseSendKeys: Boolean parameter to specify if SendKeys should be used for input, useful for password entry fallback.

    Practical application for ServiceNow customers

    By leveraging these Java connector methods, customers can automate complex interactions with Java-based applications, including launching apps, manipulating windows, reading and writing UI data, and securely handling sensitive inputs like passwords. Proper configuration of ports and UI elements is essential to enable these methods. The connector’s rich method set supports sophisticated automation scenarios to improve efficiency and consistency in Java application workflows integrated with ServiceNow automation solutions.

    The Java connector exposes methods at the connector, screen, and element levels. While all types of elements have common methods, they also have different methods.

    Connector level methods

    Start

    Starts the Java application from its location and brings it to focus.
    Note:
    You must execute this method first.

    To provide inputs to the parameters, see Configure port properties.

    Table 1. Start method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Path Path to the Java application in the local drive. Data in String None Yes
    Args Arguments for the path. Data in String None No

    GetMainWindowHandle

    Returns the window handle of the Java application launched by the Start method.

    Table 2. GetMainWindowHandle method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Return Returns the Window handle of the application. Data out Integer None Not applicable

    GetMainWindowTitle

    Returns the title of the Java application window.

    Table 3. GetMainWindowTitle method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Return Returns the title of the window of the application. Data out String None Not applicable

    CloseMainWindow

    Closes the main Java application window.

    Terminate

    Terminates the main Java application window.

    Screen level methods

    Close

    Closes the active Java application window.

    Focus

    If the Java application window is minimized or running in the background, the method restores the focus.

    GetFields

    Gets the data from the text fields in a Java application. You must first configure the text fields. To configure, do the following steps.
    1. Configure the Java connector and capture one or more text fields.
    2. Expose the screen level methods. See Use connector method.
    3. From the Object Explorer pane, drag the GetFields method to the Design surface.
    4. Click the method settings icon (Method settings icon.).
    5. Select one or more text fields.
    6. Update the data type of the text field.
    7. To close the CHOOSE FORM ELEMENTS window, click OK.

      A Data Out port is created for each text field you select.

    The GetFields method can now return the data contained in the text fields.

    GetInstanceCount

    Returns the total number of instances of the Java application open.

    Table 4. GetInstanceCount method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Return Returns the total number of instances of the Java application open. Data out Integer None Not applicable

    GetScreenShot

    Captures and returns the screenshot of the Java application screen.

    Table 5. GetInstanceCount method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Return Returns the screenshot of the Java application screen. Data out Bitmap None Not applicable

    GetWindowHandle

    Returns the Windows handle number of the Java application screen window.

    Table 6. GetInstanceCount method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Return Returns the Windows handle number of the Java application screen window. Data out Integer None Not applicable

    IsCreated

    Returns the Boolean response based on whether the rules for a configured window match. When you configure a Java application screen, the MATCH RULES section of the Java connector window shows certain rules that match the screen configured. The method matches the same rules.

    To provide inputs to the parameters, see Configure port properties.

    Table 7. IsCreated method parameters
    Parameter Description Data port type Data type Default value Mandatory? Notes
    MatchAllChildren Returns the Boolean response after matching the rules of the elements of the screen. Data in Boolean None No This parameter is relevant if you capture one or more elements.
    Return Returns the Boolean response to whether the rules of the Java application screen you configured matched. Data out Boolean Null Not applicable

    Maximize

    Maximizes the Java application window.

    Minimize

    Minimizes the Java application window.

    MouseAction

    Performs different mouse device actions on the Java application such as left-click, right-click, and middle-click.

    To provide inputs to the parameters, see Configure port properties.

    Table 8. MouseAction method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Action Specifies the mouse device action. Data in Mouse device input None Yes
    ClickMiddle Whether a middle-click will be performed. Data in Boolean None No

    Resize

    Changes the width, height, and the position of the Java application window along the X and Y axis.

    To provide inputs to the parameters, see Configure port properties.

    Table 9. Resize method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    xPos Position of the window on the screen along the X-axis. Data in Integer None No
    yPos Position of the window on the screen along the Y-axis. Data in Integer None No
    Width Width of the window. Data in Integer None No
    Height Height of the window. Data in Integer None No

    Restore

    Restores the original dimensions of the Java application window. You can use the method after you have executed methods like Maximize and Minimize.

    SendKeys

    Send any data or keyboard input to the active field on the Java application. For example, you can send a string data "RPA" or a keyboard input [Space] to clear a check box.

    To provide inputs to the parameters, see Configure port properties.

    Table 10. WaitForCreate method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Keys Sends the data or keyboard input to the active field. Data in String None Yes
    ClearExistingValue Before sending any data or keyboard input, clears any existing value in the active field. Data in Boolean None No
    TypeDelay Sets a delay before sending any data or keyboard input to the active field. Data in Integer None No

    SetFields

    Set custom text in the text field elements captured from the Java application screen.

    To use the method, do the following steps.
    1. From the Object Explorer, drag the SetFields method to the Design surface.
    2. Click the method settings icon (Method settings icon.).
    3. Select one or more text fields.
    4. Update the data type of the text field.
    5. Click OK.

      A Data In port is created for each text field you select. You can pass the string to set in the fields of the Java application.

      To provide inputs to the parameters, see Configure port properties.

    WaitForCreate

    Each screen you configure in the Java connector is identified by some rules, displayed under the MATCH RULES section of the Java Connector window. The method returns a Boolean response based on whether the rules of the screen you had configured matches.

    To provide inputs to the parameters, see Configure port properties.

    Table 11. WaitForCreate method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    timeoutinSeconds Time after which the operation of the method times out. Data in Integer None No
    MatchAllChildren Returns the Boolean response after matching the rules of the elements of the screen. Data in Boolean None No
    Return Returns the Boolean response to whether the rules of the Java application screen you configured matched. Data out Boolean None No

    Element level methods

    GetAccessibleActions

    Returns the list of actions that you can perform on an element. For example, for a button, it returns Click.
    Table 12. GetText method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Return Returns the list of actions that you can perform on an element. Data out List None Not applicable

    GetInstanceCount

    Returns the total count of an element type in the Java application. For example, if there are three text boxes in an application, the instance count is 3.

    Table 13. GetText method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Return Returns the instance count of an element type in the application. Data out Integer None Not applicable

    GetText

    Returns the text from the captured text box element in the Java application. To capture multiple texts from multiple text boxes, you must configure multiple text box elements.

    Table 14. GetText method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Text Returns the text contained in the text box of the Java application. Data out String None Not applicable

    IsCreated

    Returns the Boolean response depending on whether the rules of the element you had configured match.

    Table 15. IsCreated method parameters
    Parameter Description Data port type Data type Default value Mandatory?
    Return Returns the Boolean response depending on whether the rules of the element you had configured match. Data out Boolean null Not applicable

    MouseClick

    Performs a left mouse-click on the captured element.

    PerformAction

    Performs the specified action on an element. For example, click on a button. Each element allows a set of actions that you can get by executing the GetAccessibleActions method.

    To provide inputs to the parameters, see Configure port properties.

    Table 16. IsCreated method parameters
    Parameter Description Data port type Data type Default value Mandatory? Notes
    Action Accepts the action to be performed on the element. Data in String None Yes

    You must specify the action exactly in the format as given by the GetAccessibleActions method.
    Return Returns True if the action was performed, else, False. Data out Boolean None Not applicable

    SetPassword

    Automate entering password securely in the password field of a Java application.

    To provide inputs to the fields see Configure port properties.
    Table 17. SetPassword method parameters
    Parameter Description Data Port type Data type Default value Mandatory? Notes
    Password Accepts the password as a secured string. Data In Secured string None Yes Since it accepts the password as a secured string, it only shows the length of the string when you right-click on the parameter and then click Preview Data.
    UseSendKeys SendKeys is a method used to send keyboard inputs such as characters, numbers, and symbols to text boxes inside an application. Data In Boolean False Yes
    Tip:
    If the SetPassword method fails to input the password in the password field, set the value to True and execute the method again.