22 Manage Essbase Using the MaxL Client

To communicate with Essbase using MaxL scripts or statements, use the MaxL Client to issue the statements over HTTP or HTTPS.

If you want to run MaxL statements on the Essbase Server rather than from a client, connect to the server and run the MaxL startup script, startMAXL.sh or startMAXL.bat. The script is located in <Domain Root>/<Domain Name>/esstools/bin. If you do not know where that is in your Essbase Server, refer to Environment Locations in the Essbase Platform.

Prerequisites to Set Up the MaxL Client

Before you can use the MaxL Client, you will need the Essbase URL, and you may need to set up the TLS (SSL) certificate.

To run MaxL scripts or statements, you must be a power user or administrator. To prepare for using the MaxL Client,
  1. Get the URL for the Essbase instance from your Service Administrator. Its basic format is:
    https://IP-address:port/essbase
  2. Using a web browser or cURL, test that you can reach the discovery URL from the client host. A discovery URL is the URL provided by your Service Administrator, with /agent appended to the end. Here is a cURL example (for secure/TLS mode in an independent Essbase deployment):
    curl https://192.0.2.1:9001/essbase/agent --tlsv1.2

    Here is an example for a stack deployment of Essbase on OCI:

    curl https://192.0.2.1:443/essbase/agent --tlsv1.2
  3. Set up the SSL certificate, if applicable to your organization.
    • If you’re using one of these deployment types, a Trusted CA Signed SSL Certificate is included:
      • Oracle Analytics Cloud

      • Oracle Analytics Cloud with Identity Cloud Service (IDCS) and Load Balancing

      • Cloud at Customer with Load Balancing

    • If you’re using Oracle Analytics Cloud or Cloud at Customer with LDAP (without Load Balancing), use a self-signed certificate.
    • To check if a certificate is trusted, paste the discovery URL into a web browser. If https is green or a label says “Secure,” it is trusted. If https is red or a label says “Not secure,” it is untrusted.
    • If you're using the MaxL Client in Essbase 21c with a self-signed certificate, you have two options:
      1. Disable peer verification by setting the environment variable API_DISABLE_PEER_VERIFICATION=1

        Linux example

        Edit startMAXL.sh, adding the following line:

        export API_DISABLE_PEER_VERIFICATION=1

        Windows example

        Edit startMAXL.bat, adding the following line:

        set API_DISABLE_PEER_VERIFICATION=1
      2. Import the self-signed certificate to the client trust store (cacert.pem) and set the environment variable API_CAINFO=CA <certificate file path>. The client verifies the server’s digital certificate using a provided ca-bundle certificate store. Provide the ca-bundle location by specifying the environment variable API_CAINFO=CA <certificate file path>

        Linux example

        Edit startMAXL.sh, adding the following line:

        export API_CAINFO=/u01/cacert.pem

        Windows example

        Edit startMAXL.bat, adding the following line:

        set API_CAINFO=c:/cacert.pem

        If you don't provide certificate file path, the Essbase Runtime Client will try to get ca-bundle from the default OpenSSL installation location (applicable for Linux and Macintosh).

        If you need a ca-bundle (cacert.pem), you can also download it. One sample source is: https://curl.haxx.se/docs/caextract.html.

Download and Use the MaxL Client

To run the MaxL Client for use with Essbase, download the latest version from the Console, set the proxy if needed, run the startup script, and log in.

The Essbase MaxL Client enables you to use MaxL over HTTP or HTTPS. MaxL is an administrative, language-based interface for managing cubes and artifacts. Be sure you are using the latest client version provided in the Console, as older, previously downloaded versions may not work correctly.

To run MaxL statements, you must be a power user or an administrator. Before you download the MaxL Client, see Prerequisites to Set Up the MaxL Client.

If you’re a federated SSO user in Oracle Identity Cloud Service, logging in using MaxL or CLI is not supported. Federated SSO login requires a browser window. Create a native Identity Cloud Service user, and use that instead to log in using MaxL or CLI.

  1. In the Essbase web interface, click Console.

  2. In the Console, go to MaxL Clients.

  3. Click Download Image of the Download icon. next to the MaxL Client that is appropriate for your platform.

  4. Save the compressed EssbaseMaxl file to your local drive.

  5. Extract the contents of the compressed file to a folder.

  6. If you’re using a proxy, you must set the correct proxy in the MaxL execution script, startMAXL.bat or startMAXL.sh. The following example, applicable for editing startMAXL.sh for UNIX, tells MaxL to use the designated proxy (proxy.example.com), but to bypass using a proxy for the specific destinations listed in the exception list (127.0.0.1, localhost, and something.example.com).

    export https_proxy=http://proxy.example.com
    export no_proxy=127.0.0.1,localhost,something.example.com

    For Windows, startMAXL.bat can be edited similarly but with different syntax.

    set proxy proxy-server="https://proxy.example.com" bypass-list="127.0.0.1;localhost;*.example.com"
  7. If you're using Essbase deployed on Oracle Cloud Infrastructure and are using a self signed certificate, you must disable peer verification in the MaxL execution script. Caution: this solution should be only temporary, until you can obtain a trusted CA certificate. Here is an example using bash (for startMAXL.sh):

    export API_DISABLE_PEER_VERIFICATION=1
  8. Run the startMAXL batch or shell script. A command prompt opens, the environment setup completes, and the MaxL Client starts up.

  9. Log in by providing your credentials and the Essbase URL in the MaxL login statement.

    In the following example, the user logging in, User5, is from a federated MSAD directory and logging in to Essbase On-Premise.

    login user User5 P855w0r$4 on "https://192.0.2.1:9001/essbase/agent";

    Tip:

    See MaxL Troubleshooting for On-Premise installations.

    In the following example, the user logging in, admin1@example.com is an Identity Cloud Service administrator who was set as the initial Essbase administrator during Essbase stack deployment on Oracle Cloud Infrastructure. As the password is not entered in this example, the administrator will be prompted to provide it next. The URL is the essbase_url from the job outputs resulting from the stack deployment.

    login admin1@example.com on "https://192.0.2.1/essbase";

    Any Identity Cloud Service user provisioned to work with Essbase can log in to MaxL, as long as they are provisioned as a power user or administrator.

  10. Execute an interactive MaxL statement.

    For example:

    display database all;

To learn more about MaxL, see MaxL Statement Reference.