IBM Support

Collecting Data: Email Listeners with OAuth

Troubleshooting


Problem

This document outlines the necessary steps to gather diagnostic data, to effectively analyze, identify and resolve the root cause of issues when dealing with Maximo Email Listener problems configured with OAuth.  
A clear and complete problem description is crucial, helping both you and the support team understand the scope and nature of the issue, providing a solid foundation for investigation. Detailed answers to initial questions significantly expedite the troubleshooting process, and the following sections will guide you through collecting the necessary data to efficiently resolve your Maximo Email Listener with OAuth challenges. 
To maximize effectiveness, prepare to provide detailed Maximo environment information, including logs, configurations, system properties, database queries, and OAuth settings. Network captures and refresh tokens may be needed. Answer questions about the issue, timing, recent changes, and replication steps. 
This comprehensive information enables IBM Support to quickly and accurately diagnose and resolve your Email Listener with OAuth problems.


In this section we will provide you with comprehensive, step-by-step instructions on how to collect data, logs, configuration files, database queries, and other relevant information. Each step is carefully outlined to ensure you can gather the data accurately and efficiently. By diligently following these instructions, you'll ensure that IBM Support has all the necessary pieces of the puzzle for a successful diagnosis. 
We recognize that data collection can be time-consuming, and your cooperation in providing complete and accurate data is invaluable. Your efforts here will directly contribute to a faster and more effective resolution, allowing you to get back to your important tasks with minimal disruption. We appreciate your dedication to this process.

Situation Appraisal: Let's Get Clear on What's Happening
Please answer as many of the following questions as possible, and provide answers to IBM Support.
Q1- What's the Main Concern? In simple words, what's the biggest issue you're facing? 
Q2- How impactful is this? Is this something that's causing a major disruption, or is it a minor inconvenience?
Q3- Steps and Screenshots are super helpful! Can you provide screenshots of the issue and the steps to reproduce it? 
Q4- Which specific fields or components are involved?
Q5- Are there similar elements or screens where the issue doesn't occur?
Q6- Provide Error Messages or Unexpected Behavior evidences. What exactly tells you there's a problem? Any specific error messages?
Q7- Can the problem be reproduced at will? Under which conditions does the problem occur?
Q8- If you are experiencing error with Emails not being processed by Email Listener, what type of E-Mails are being used? Free Form or Formatted?
Q9- Does the email you are trying to process have any attachments?  Does it work without attachments?
Q10- Does the email you are trying to process have any signature with images or special or foreign characters?  Does it work without any signatures or special characters, just plain text?

How to collect referenced information.

  • Application Configuration Information
    What is the Maximo version being used on the environment where you experienced that issue ? (see Help > System Info)
    This will indicate the version of Maximo, and any additional components, in case we need to have that info to request a possible fix for this case or to investigate more.
    1. Log into Maximo or Manage
    2. Select Help>System Information
    3. Select the text from the window and paste into a text document (text is preferred, as transcribing information from a picture sometimes introduce errors)
    4. Post the resulting system information text document, or copy and paste the results into the case.
       
  • Application System Properties  (If you have access to run SQL on your database)
    Send us the output of the following SQL, which will display the current System Properties values:
    SELECT PROPNAME, PROPVALUE  FROM MAXPROPVALUE ORDER BY PROPNAME;
  • Collect Logs - Enabling The Proper Logging To Troubleshoot Email Listener Issues
    If the E-mail Listeners application finds any errors while staging e-mail records, the e-mail listener can write error information in the log file on the server.  You use the Logging application to enable logging for the E-mail Listeners application. Another property mail.debug property is also required in System Properties application. Websphere is assumed otherwise consult your application server's documentation.
    System Properties Application Steps:
    1) Be generous with application server log rotation: 
    In the Websphere administrative console this can be adjusted under Logging and Tracing  >  Server Name > JVM Logs
     
    Setting the SystemOut and SystemErr log size to 15 MB and historical log files to 10 should be enough to trap all Java stack traces.
    2) Add mail.debug Property - The mail.debug property does not exist out-of-the-box so it will need to be added via the System Properties application.  Note that this is a JavaMail property and not a Maximo property.
     
       Property Name: mail.debug
       Description: Java debug property
       Global Value:  true
       Current Value:  true
       Maximo Default: It should be set to false when not in use.
    Add and enable JavaMail mail.debug in System Properties:
        mail.debug = true
    JavaMail debug has characteristic appearance.  
    It shows in detail the application server's JavaMail communication sessions with the email server including raw email in transfer.  
    It includes strings such as DEBUG <protocol? (e.g. DEBUG SMTP). 
    This is not an optional step; including this is non-negotiable. This output is not only relevant to email server connectivity problems.
     
    3) Do a clean catch of the logs:
    Shutdown your application server and delete or back up the existing system logs. 
    Upon application server restart, a fresh set of logs will be initiated. It's these SystemOut and SystemErr logs that you will be sending to support.
    4) Reproduce the problematic scenario:
    Perform a test case that causes the problematic behavior to occur.
    5) Check: Before sending the logs, check them to make sure they contain the information requested.
     
    The logs you will send will include:
    ALL MXServer activity since the restart in step # 3 as contained in SystemOut and SystemErr.  No screen shots, cut & paste jobs or fragments of log files.   
    JavaMail debug output - Error indications from the scenario - When sending this in it would be helpful to include timestamps and a description of the areas of interest in SystemOut. 
    Also include any relevant UI indications or screen shots of data related to the problem.

    Logging Application Steps:
    Please configure the following logging properties in Logging application: 
     
    Go to System Configuration > Platform Configuration > Logging 
     
    On the Root Loggers section change the settings for the logger(s) below:
     
    Set the SQL logger to INFO, tick Active checkbox, go to Select Actions menu, Apply Settings
    Set the APPLICATION logger to DEBUG, tick Active checkbox, go to Select Actions menu, Apply Settings
    In the Loggers section:

    Set the EmailListnerCron (log4j.logger.maximo.crontask.LSNRCRON) to DEBUG level, go to Select Actions menu, Apply Settings
    Then save changes, and from Select Action > Click Apply Settings 
    Replicate the problem scenario and send the log to IBM Maximo Support.
    Please also include any SystemErr.log that contain any errors in regards to mail issues.
     
  • Email Listener Record details - Collect the following information on your Email Listener
    From the E-Mail Listeners application, open the e-mail listener.
    Provide us screenshots that display the information below :
    • Protocol field, where we select oauth.
    • OAuth 2.0 Configuration section :
    • Client ID field, where we specify the client ID.
    • Client Secret field, where we specify the client secret.
    • Refresh Token field, where we specify the refresh token for the e-mail address.
    • Token URL field, where we specify the access token URL for the e-mail provider.
  • Collect SSL Configuration from WebSphere (Office 365) - Information needed
    Get the Office 365 SSL Certificate  (In case your Email Listener is configured to work with Office 365)
    Go to Websphere administration console > 
    Security > SSL certificate and key management > 
    Key stores and certificates > CellDefaultTrustStore > 
    Signer certificates    [TAKE A SCREENSHOT]
This section will help you to learn more about about Maximo Email Listeners with OAuth configuration. Here, we've curated a collection of valuable resources, including links to relevant documentation, in-depth how-to guides, and informative articles. These resources are designed to provide you with deeper insights and practical knowledge, empowering you better manage and optimize your Maximo environment. Whether you're seeking to enhance your understanding of specific configuration details or looking for best practices, this section has you covered. 
We believe that informed users are empowered users, and we've compiled these resources to support your continuous learning and growth. 
Explore the links, dive into the content, and discover new ways to enhance your Maximo experience. 
The E-mail Listeners application can poll multiple e-mail accounts to retrieve messages. Each account is checked at periodic intervals that you establish. Based on the subject line of an e-mail message or the contents of the e-mail message body, an e-mail listener can determine if the e-mail is new or is an updated service request, incident, or problem. An e-mail listener can also determine if an e-mail is a query for information on any business object.
You use e-mail listeners to receive and process incoming e-mail messages. The E-mail Listeners application can monitor multiple e-mail accounts to retrieve messages. It also supports embedded and normal message attachments. To configure E-mail Listener with Oauth, we recommend keeping the environment in the latest version, as improvements are constantly being made to this application. The versions before 7.6.1.2 IFIX005 are not supported for Oauth configuration
OAuth 2.0 (Open Authorization) is standard to provide consented access and restricts actions of what a client application can perform on resources, hosted by other applications, on behalf of the user, without sharing the user's credentials. As a system administrator, you can configure e-mail listeners to use OAuth 2.0 for cloud-based e-mail providers that also use OAuth 2.0. When you configure OAuth2.0 for an e-mail listener, you specify information for the e-mail address and provider. A limited-lifespan access token is automatically obtained by using that information.
When configuring the Maximo Email Listener with OAuth, establishing a secure connection between the Maximo application server and the mail server is paramount.  OAuth 2.0, by its nature, relies on HTTPS, which necessitates valid SSL/TLS certificates.
See document :
How to add the signer/public key/remote server certificate to the WebSphere Application Server TrustStore trust.p12 or java TrustStore cacerts? 
https://www.ibm.com/support/pages/node/6590877
It addresses the critical task of managing the WebSphere Application Server or Java TrustStore to facilitate this secure communication. The TrustStore holds certificates that the application server uses to verify the identity of remote servers during SSL/TLS handshakes. In the context of the Email Listener, this means that the certificate of the mail server or the issuing Certificate Authority must be added to the TrustStore. Without these certificates, the application server cannot establish a trusted connection, leading to handshake failures and preventing the Email Listener from functioning correctly. 
This process is particularly vital for OAuth configurations, as these connections almost always use secure protocols, and the services may update their certificates, requiring periodic TrustStore updates. Therefore, understanding and implementing the steps outlined in this document is essential for ensuring successful and secure Email Listener operations with OAuth.
As you can create, update, query, and change the status of tickets, you can configure security settings for e-mail listeners. Using these settings, you can ensure that only authorized users can execute these functions using e-mail messages. For the sender of an e-mail message, security authorizations are checked against the security configuration for the system. This check establishes the ability of the sender to run each specific function.
The person record is a basic requirement to be able to process e-mail messages. Additional processing of e-mail messages only occurs after the person record associated with the e-mail address of the sender has been located.
The following points apply to security settings for e-mail listeners:
  • If a person record is active, the corresponding user record is found.
  • If a person record does not exist or is inactive, the e-mail message is not processed. An error e-mail message is sent to the sender and the administrator.
  • If a user record is found, the associated authorizations are applied when the E-mail Listeners application performs security checks on incoming e-mail messages.
  • If a user record is not found, the Run As user of the cron task instance for the e-mail listener is used.

To specify security settings for e-mail listeners, you can use the Select Security Settings action in the E-mail Listeners application. The settings identify business objects supported by each e-mail listeners workflow process. The settings also identify the corresponding applications that must be used to determine security restrictions on incoming e-mail messages. 
To assign the appropriate authorizations to the users who send formatted e-mail messages, configure security settings you can use the Security Groups application.  Using these settings, you can ensure that only authorized users can execute these functions using e-mail messages.
This section is designed to be your hands-on guide, providing valuable hints, tips, and step-by-step troubleshooting procedures. We'll cover a range of topics, including verifying configurations, checking network connectivity, reviewing logs for error messages, and much more. By following these troubleshooting guidelines, you can often identify and resolve issues independently, or gather more specific information to provide to IBM Support, streamlining the resolution process. 
We understand that troubleshooting can be challenging, and we're committed to providing you with the tools and knowledge you need to succeed.
Here is a quick checklist to be used for Problem Analysis, which we believe can help you not only to pinpoint a root cause for Email Listener issues but also for any other related issues.
Please try to answer as many of the following questions as possible:
P1- What's different? What should be happening, and what's actually happening?
P2- Where is it happening? Which specific record screen, field, or application is causing the issue? Are there places/environments where it works correctly?
P3- When did it start? When did you first notice the problem? Has anything changed since it was working fine?
P4- How often does it happen? Does it happen every time, or just sometimes? Is there a pattern for the issue?
P5- What's unique? What's different about the part that's having the issue, compared to the parts that are working fine?
P6- Are all users experiencing this issue or only specific users? Are you aware of any users who do NOT experience this issue?
P7- Does the issue happen even if using other browsers? Any browsers that do NOT show this issue?  Same behavior in Private/Incognito window?
P8- Any recent changes? Have you made any changes to the system around the time the problem started?

Troubleshooting Email Listener issues :
Checking/Testing IMAP connection and if it fails, check IMAP settings in Office 365 to ensure that IMAP access is enabled.
(Reference: https://www.ibm.com/support/pages/node/6566151)
Test IMAP connection
  1. Access: https://testconnectivity.microsoft.com/tests/O365Imap/input. Click Sign in:
  2. Sign in with your email address and password. Use the same credentials defined in the Maximo email Listener.
  3. Proceed with verification code and check Notice agreement. Click Perform test:
  4. If connectivity test runs successfully, IMAP is enabled for the user

If it fails, check following IMAP settings in Office 365.
  1. Access: https://admin.microsoft.com/Adminportal/Home#/users. Sign in with administration credentials
  2. On Active users, select your referenced account
  3. Click Mail and then Manage email apps
  4. If IMAP isn’t checked, mark it true and save. This action might take some time to reflect (around 30min).
  5. After around 30 min, test it again to check whether IMAP Access is enabled.
Recommended :

Office 365 - Check Azure Active Directory Application Settings as per technote below:
https://www.ibm.com/support/pages/node/6566159
Office 365 - Generating a new Refresh Token as per technote below:
https://www.ibm.com/support/pages/node/6566161
Office 365 - Verify installed SSL Certificates as per technote below:
https://www.ibm.com/support/pages/node/6566163
Office 365 - Check Email Listeners Application configuration as per technote below:
https://www.ibm.com/support/pages/node/6827107
GMAIL - Check Google Cloud Console configuration as per technote below:
https://www.ibm.com/support/pages/node/7148386
GMAIL - Generating a new Refresh Token as per technote below:
https://www.ibm.com/support/pages/node/7148639
GMAIL - Verify installed SSL Certificates as per technote below:
https://www.ibm.com/support/pages/node/7148641

NOTE:
Microsoft expires refresh tokens after 90 days.
The default lifetime for the refresh tokens is 24 hours for single page apps and 90 days for all other scenarios.
According to Microsoft, this is expected and we do not have control over the expiry. It impacts all email users.
It can definitely be a burden to have to regenerate them so frequently.
From an internet research, you can find detailed information on Refresh Tokens here:
https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens

 
In Summary, ensure the following configuration steps were carefully performed (according to each scenario)
Email Listener OAuth Configuration with Office 365 Technote Series
https://www.ibm.com/support/pages/email-listener-oauth-configuration-office-365
Email Listener OAuth Configuration with Google Gmail Technote Series
https://www.ibm.com/support/pages/email-listener-oauth-configuration-google-gmail
E-mail Related Problems? Let the Logging Do the Talking
https://www.ibm.com/support/pages/e-mail-related-problems-let-logging-do-talking
Troubleshooting E-mail Listener Problems
https://www.ibm.com/support/pages/node/6988789
Enabling The Proper Logging To Troubleshoot Email Listener Issues
https://www.ibm.com/support/pages/enabling-proper-logging-troubleshoot-email-listener-issues
Email Listeners are unable to connect to mail servers using TLSv1.2
https://www.ibm.com/support/pages/email-listeners-are-unable-connect-mail-servers-using-tlsv12
Encountered error processing e-mails from mail server. psdi.util.MXApplicationException: BMXAA10029E - Fetching the OAuth access token failed.
https://www.ibm.com/support/pages/encountered-error-processing-e-mails-mail-server-psdiutilmxapplicationexception-bmxaa10029e-fetching-oauth-access-token-failed

 
Additional recommendations:
Review Network configuration and connectivity - Collaborate with your network team to ensure a stable connection between the Maximo server and outlook.office365.com.  Tools like ping or traceroute can help identify bottlenecks in the network path.  Here is a list of recommendations:
Review Firewall Rules - Check firewall configurations on both the Maximo server and Office 365 side. We have seen issues being resolved by adding an explicit firewall rule for the Office 365 service IP ranges. This highlights the importance of firewall configuration review.
Ensure necessary ports used by Office 365 for IMAP (port 993) are allowed for communication.
Monitor Office 365 Service Status - Check the Office 365 service status dashboard to rule out any temporary server overload impacting response times.
Adjust Cron Schedule (Temporary Relief) - Important Note: This is not a long-term solution. Consider temporarily increasing the cron schedule interval for the email listener (e.g., to 15 or 20 minutes). This reduces connection attempts and might improve success rates if the issue is related to server load.
Review OAUTH2 Token Configuration (if necessary) - Ensure your OAUTH2 token configuration in Maximo is valid and functioning correctly.
This section is designed to be a quick reference guide, highlighting common issues such as authentication failures, connection errors, email processing issues, and more. For each issue, we'll provide practical solutions and actionable advice to help you quickly resolve problems. By familiarizing yourself with these common issues, you can anticipate and prevent potential problems, or quickly identify solutions when they arise. 
We've compiled this information to save you time and provide practical guidance for maintaining a stable and efficient Email Listener environment.  We believe that proactive problem-solving is key to maximizing your Maximo experience, and this section is designed to support your efforts. Your understanding of these common issues will contribute to a smoother and more reliable Maximo environment.
If Oauth 2.0 Configuration section is not available in E-mail Listener application, it's required to include the information in xml.
https://www.ibm.com/support/pages/node/6995203
BMXAA4211E - Database error number -302 has occurred when operating on INBOUNDCOMMCFG, when you save Listener Definition
https://www.ibm.com/support/pages/node/6995225
Person does not exist or person is inactive for sender XXX for address XXX on mail server outlook.office365.com
https://www.ibm.com/support/pages/node/6995321
Security check failed for the e-mail with subject XXX having object and action. The staging table identifier for this e-mail is 383. Administrative action is required.
https://www.ibm.com/support/pages/node/6995339
BMXAA0478E: The ROWSTAMP trigger was not found for the following tables: INBOUNDCOMMCFG
https://www.ibm.com/support/pages/node/7150236
Error connecting to mail server for email address XXX on mail server outlook.office365.com, when configuring E-mail Listener with Oauth
https://www.ibm.com/support/pages/node/6997967
BMXAA10029E - Fetching the OAuth access token failed. This is caused by invalid client credentials, an invalid refresh token or other problem related to fetching the access token.
Error processing e-mails from mail server. psdi.util.MXApplicationException: BMXAA10029E - Fetching the OAuth access token failed.
https://www.ibm.com/support/pages/encountered-error-processing-e-mails-mail-server-psdiutilmxapplicationexception-bmxaa10029e-fetching-oauth-access-token-failed
ORA-12899: Value too large for column "INBOUNDCOMMCFG"."OAUTHACCESSTOKEN", when configuring Email Listener with Oauth
https://www.ibm.com/support/pages/node/6995319
Encountered error processing e-mails from mail server. javax.mail.MessagingException: A3 BAD User is authenticated but not connected, when configuring E-mail Listener with Oauth
https://www.ibm.com/support/pages/encountered-error-processing-e-mails-mail-server-javaxmailmessagingexception-a3-bad-user-authenticated-not-connected%C2%A0when%C2%A0configuring-e-mail-listener-oauth
Encountered error processing emails from mail server. java.util.NoSuchElementException when configuring E-mail Listener with Oauth
https://www.ibm.com/support/pages/encountered-error-processing-emails-mail-server-javautilnosuchelementexception-when-configuring-e-mail-listener-oauth

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB77","label":"Automation Platform"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SSLKT6","label":"IBM Maximo Asset Management"},"ARM Category":[{"code":"a8m50000000CbU1AAK","label":"System Administration-\u003EE-Mail Listeners"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"7.6.1;and future releases"},{"Product":{"code":"SSRHPA","label":"IBM Maximo Application Suite"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Component":" ","Platform":[{"code":"","label":""}],"Version":"","Edition":"","Line of Business":{"code":"LOB77","label":"Automation Platform"}},{"Product":{"code":"SSWT9A","label":"IBM Control Desk"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Component":" ","Platform":[{"code":"","label":""}],"Version":"","Edition":"","Line of Business":{"code":"LOB77","label":"Automation Platform"}}]

Log InLog in to view more of this document

This document has the abstract of a technical article that is available to authorized users once you have logged on. Please use Log in button above to access the full document. After log in, if you do not have the right authorization for this document, there will be instructions on what to do next.

Document Information

Modified date:
18 September 2025

UID

ibm17185710

Page Feedback