Setting up IBM Maximo Application Suite

After you install IBM® Maximo® Application Suite, the setup program guides you through the initial configuration.

Before you begin

  1. Complete the installation.

    Obtain the link to the Maximo Application Suite setup program and the login credentials that you need to complete the setup process.

    For more information about obtaining the login credentials, see how to locate the default username and password.

  2. Enable login for Maximo Application Suite self-signed certificates.
    If you are using self-signed certificates in a development or test environment, you must manually enable login by using either of the following methods.
    • Download the certificates from the cluster and add them to your local certificate manager.
    • In your browser, go to the Maximo Application Suite API URL https://api.<mas_domain>/ and accept the certificate security risks. After you accept the risks, an AIUC01999E error is displayed. This message is expected. You can now continue with the setup process.

    If the Maximo Application Suite dashboard does not load after you login for the first time and instead see a spinning wheel, see how to troubleshoot the issue.

About this task

The Maximo Application Suite setup configurations are set at the System scope. For more information about configuration scopes, see Configure Maximo Application Suite.

Procedure

  1. Log in to the Maximo Application Suite setup program by using the superuser credentials that were created during installation.
    https://admin.<mas_domain>/initialsetup
    Important: Treat the superuser account the same way that you treat the root account on your servers. Use it only for the initial setup. As part of the setup, you create a default administrator user account that has access to the Maximo Application Suite administrative interface. Use this administrative account to add and manage users, deploy applications, and more.
    For more information about obtaining the superuser credentials, see how to locate the default username and password.
  2. Configure MongoDB.
    MongoDB is used as the data dictionary for Maximo Application Suite and its applications. It is also used as the default user registry.
    Specify the following MongoDB information:
    Hostname and port
    You can configure one or more MongoDB hostname and port combinations.
    Authentication mechanism
    Specify the mechanism that is used to authenticate Maximo Application Suite when it connects to MongoDB. Select the closest match to the mechanism that is configured for your MongoDB cluster. For example, if your cluster uses the SCRAM-SHA-256 mechanism, select DEFAULT (SCRAM).

    To authenticate by using LDAP, specify PLAIN as the authentication mechanism.

    Auth db

    Provide the name of the authentication database. If you are authenticating with LDAP, the value must be $external.

    MongoDB login credentials
    At a minimum, the MongoDB administrator needs table creation privileges.
    Note: The MongoDB verification might take up to a minute. The configuration cannot be modified after the MongoDB verification is complete. MongoDB is a prerequisite for Maximo Application Suite. Changing the configuration requires careful coordination and possible data migration to avoid service outages. System administrators can change the configuration in the Red Hat® OpenShift® console. For assistance with changing the MongoDB configuration, contact your IBM representative.

    For more information, see Installing MongoDB.

  3. Upload a CA certificate.
    If the service uses the transport layer security (TLS) communication protocol and is not secured with a certificate that is issued by a well-known certificate authority (CA), then provide the certificate of the CA that issued the service's certificate. Because the CA might use intermediate CAs, you can provide more than one certificate.

    For each certificate that you provide, the following details are displayed:

    • The name of the certificate issuer.
    • The name of the subject, such as the organization, that the certificate is issued to.
    • The start and end dates of the certificate's validity period. If the validity of any certificate that you provide expires soon, a warning message appears.

    You can automatically retrieve or manually add certificates.

    Important: If your MongoDB cluster uses self-signed CA certificates that you must retrieve or add a certificate.
    • Automatically retrieving certificates

      In the certificates section, click Retrieve. If the connection credentials that you specify are correct, all CA certificates that are configured on the server are automatically retrieved and displayed.

      These certificates are not validated. Verify that only the correct certificates are retrieved and remove any unexpected certificates.

      After you retrieve the certificates, you can manually add more certificates.

    • Manually adding certificates
      In the certificates section, click Add manually and specify the following values for each certificate that you want to add:
      Alias
      An alphanumeric identifier that is in the range 3 - 50 characters long.
      Certificate content
      The content of a certificate file in either the X.509 or PEM formats.
    For more information, see Configuring certificate authority certificates.
  4. Configure a Simple Mail Transfer Protocol (SMTP) server connection to enable email notifications for system events, such as new user welcome emails and password reset communication. For more information, see Setting up email notifications.
  5. Configure analytics data.
    Note: Starting in IBM Maximo Application Suite 9.0, 8.11.7, and 8.10.10, the User Data Services (UDS) is deprecated and replaced with IBM Data Reporter Operator (DRO).

    For more information, see Data Reporter Operator.

    • If you are using Maximo Application Suite 8.11, 8.10 or earlier versions, you must migrate your User Data Services to Data Reporter Operator . For more information, see Migrating Maximo Application Suite from User Data Services to Data Reporter Operator.
    • If you are using Maximo Application Suite 9.0, 8.11.7, 8.10.10 or later versions, configure IBM Data Reporter Operator.

      The IBM Data Reporter Operator accepts events and transforms them into reports that are submitted to the Data Service of the IBM Metrics Operator.

      1. Enter the following information to configure Data Reporter Operator for Maximo Application Suite:
        • URL - This URL is the DRO URL endpoint. To find it, go to your Red Hat OpenShift console, switch to ibm-common-services project, then Networking > Routes. Copy the URL displayed under the Location column for the dro-endpoint route.

          For example, https://dro-endpoint-ibm-common-services.<your-cluster-domain>

        • API Key - This API key is the DRO API Key credential. To find it, go to you Red Hat OpenShift console, switch to ibm-common-services project, then Workloads > Secrets > Search and select the secret named dro-api-key. Under the Data section, copy the apikey value.

          For example, k2wnQY...

        • Email - Enter a contact email address to use for DRO communication. The email address does not have to match an existing Maximo Application Suite user.
        • Given Name - Enter the given name of the owner of the provided contact email address that is used for DRO communication.
        • Surname - Enter the surname of the owner of the provided contact email address that is used for User Data Services communication.
        • Certificates - Enter the chain of SSL certificates for your DRO. To retrieve the certificates, you can click the Retrieve button (under Certificates section) while configuring DRO into Maximo Application Suite. The DRO certificates to configure in Maximo Application Suite will vary according to the cloud service provider's cluster that is hosting your DRO installation.
      2. Click Add to add the intermediate of the certificate chain.
      3. Enter an alias. Example: drocertpart1.
      4. Enter the Certificate content.. Include the Let's Encrypt R3 intermediate certificate, issued to US, Let's Encrypt, R3. For more information, see certificate content. Example:
        
-----BEGIN CERTIFICATE-----
MIIF5jCCBM6gAwIBAgISA0Y...
-----END CERTIFICATE-----
      5. Click Confirm. The first part of this certificate should include valid dates and look like the following example:
        
Issued to: US, Let's Encrypt, R3 
Issued by: US, Internet Security Research Group, ISRG Root X1 
Valid from: Thu Aug 01 2024
Valid to: Mon Sep 15 2025

This is the intermediate certificate which is required for the SSL connection to DRO endpoint.
      6. Click Add to add the root of the certificate chain.
      7. Enter an alias. Example: drocertpart2.
      8. Enter the Certificate content. Include the ISRG Root X1 self-signed certificate. For more information, see certificate content. Example:
        
-----BEGIN CERTIFICATE-----
MIIFazCCA1OgAw...
-----END CERTIFICATE-----
      9. Click Confirm. The second part of this certificate should have valid dates and look like the following example:
        
Issued to: US, Internet Security Research Group, ISRG Root X1 
Issued by: US, Internet Security Research Group, ISRG Root X1 
Valid from: Thu Jun 04 2015
Valid to: Mon Jun 04 2035


This is the root certificate which is required for the SSL connection to DRO endpoint.
      10. Save the DRO configuration.
      11. Now, wait for the DRO configuration to reconcile, this process might take up to 10 minutes. The configuration will be successfully completed when the configuration status is set to Ready. Example:
        Configuration Ready - DRO configuration was successfully verified
  6. Configure the Suite License Service.

    The Suite License Service (SLS) stores and manages the Maximo Application Suite license.

    Each Maximo Application Suite instance can be connected to a unique SLS instance. Two or more Maximo Application Suite instances can also share an SLS and the corresponding license file.

    Enter the following SLS information to configure Maximo Application Suite:

    • URL - The URL for the SLS server.
    • Registration key - Enter the SLS registration key.
    Depending on your environment, the SLS configuration might take 10 minutes or more to complete.
  7. Optional: Upload your license key file.
    If the IBM Suite License Service that you configured for use with Maximo Application Suite includes a valid license file, you do not need to upload a license file. You can continue with the next configuration step.

    To activate Maximo Application Suite, you must provide your license key from the IBM License Key Center. The login information is provided in the license Key Center welcome letter. For more help on licensing, see the IBM Support - Licensing page.

    1. Log in to the license Key Center.
    2. Select your company name.
    3. Select the IBM AppPoints product line.
    4. Select the IBM Maximo Application Suite... license key name.
    5. Select the product or sales order for which to create the license key.
    6. Enter the number of keys to generate. These correspond to the AppPoints that are allocated to the license key.
    7. Provide the Maximo Application Suite license server parameters.
      Use the parameters that are displayed in the Advanced settings > license key section of the Maximo Application Suite setup program, or provide the following parameters:
      • For Configuration, specify a Single License Server.
      • For Host ID type, specify the Ethernet address.
      • For Host ID, specify the host ID that was generated when you installed the Suite License Service (SLS). To display this ID, connect to your Red Hat OpenShift cluster and run the following command:

        oc -n <sls_project_namespace> get licenseservice sls

        For example, if the namespace of the SLS project is mas-sls-dev5, run the following command:

        oc -n mas-sls-dev5 get licenseservice sls

        In the command output, the host ID is displayed in the LICENSEID column.

      • For Hostname, specify a hostname of your choice, for example: sls-mas
      • For Port, specify 27000.
    8. Download the key and then upload it to the Maximo Application Suite setup program.
  8. Create the workspace.

    The Maximo Application Suite workspace is a unique collection of configuration settings for your instance of Maximo Application Suite. Enter the following information to create your Maximo Application Suite workspace:

    • Workspace ID

      The workspace ID forms part of the Maximo Application Suite URL, for example:

      https://<workspace_id>.home.<mas_domain>

      Note: The workspace ID must be 3 - 12 characters in length, and can contain only lowercase letters and numbers. The first character must be a letter.
    • Workspace display name

      The display name is shown in your Maximo Application Suite user interface.

  9. Review the setup configuration.

    Your Maximo Application Suite setup is now complete. Verify that all configuration settings are done and then click Finish to complete the setup.

What to do next

After the Maximo Application Suite setup is complete, you can start to use your environment by going to the Maximo Application Suite administration or the Maximo Application Suite navigator page: 
https://admin.<mas_domain>
https://<workspace_id>.home.<mas_domain>

As the Maximo Application Suite superuser, you can now continue configuring your environment to suite your enterprise needs:

  • Configure authentication

    Maximo Application Suite supports local user authentication by MongoDB and authentication by using LDAP or SAML.

  • Configure LDAP user registry synchronization

    User registry synchronization simplifies Maximo Application Suite user management by synchronizing users and groups between an LDAP server and your local Maximo Application Suite user registry.

  • Create administrator user accounts

    The initial superuser account is used to complete the Maximo Application Suite setup. You can add application administrator users or system administrator users for day-to-day administrative tasks.

  • Getting started

    With the setup completed, your users can log in and start to use Maximo Application Suite.