Skip to content

Troubleshooting

If you encounter any of the following issues or errors, SailPoint recommends that you follow the guidance provided below to resolve the error before contacting SailPoint Support.

For issues or errors that are not addressed in this connector guide, refer to the following resources for troubleshooting information:

Provisioning of Connection_Owner fails

Resolution: Ensure Connection_Owner is the group owners name; not the group name. Pass the following attribute with the intended group owner's name:

CONNECTION_OWNER
<AttributeRequest name="CONNECTION_OWNER" op="Add" value="<value>"/>

Mainframe connectors don't support special character(s)

Resolution - If any special character(s) cause problems for Mainframe Connector passwords, perform the following:

  1. Change the character set to IBM1047 for Mainframe Connector-based applications as follows:

    <entry key="IBMcharacterSet" value="IBM1047"/>

  2. Set the value of the <characterSet> in the init.xml file of the Mainframe connectors to the same value as that of the characterSet in the previous step:

    <characterSet>IBM1047</characterSet>

  3. Restart the Connector Gateway.

Account/Group data updates incorrectly following an aggregation

Resolution - The IBM character set used must be uniform across the source XML, Connector Gateway, and Mainframes; removing anomalies at the time of conversion from one format to another as follows:

  • Source XML: <entry key="IBMcharacterSet" value="IBM1047"/>
  • Connector Gateway: <characterSet>IBM1047</characterSet>
  • Mainframe Host Code Page: 1047

Enable traces

Resolution - On Connector Gateway:

  1. Edit the log4j.properties file on Connector Gateway by setting the following line:

    log4j.rootLogger = ALL, commonLog

  2. Restart the Connector Gateway.

If you perform a test connection while an aggregation process is running, the test connection transaction times out

If you run a test connection during aggregation, the test connection transaction times out because the connector is busy processing the aggregation.

Resolution - To resolve this issue, configure multiple transaction servers on the connector to perform more than one transaction at a time.

Note

You can set up to three multiple transaction servers to handle more concurrent operations, depending on the load.

Transactions take more than 10 minutes to complete

Transactions take an excessive amount of time.

Resolution - If the transaction is expected to take more than 10 minutes, perform the following:

Set the smReadTimeout parameter in the source XML via Debug as follows:

<entry key="smReadTimeout" value="10"/>

The timeout value is in minutes and can be defined to read messages between SailPoint and the Mainframe connector. The default value is 10 minutes.

Unable to find valid certification path to requested target

The following error message appears when multiple versions of Java are installed on the same computer, and the valid certification path is not found by the requested target.

Error - main, handling exception: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Resolution - Ensure that there is a single version of Java installed on your computer.

Connector Gateway printing Java SSL logs when TLS and TRACE level logging are enabled

In the ConnectorGateway-May-2019 version of Connector Gateway release, Connector Gateway prints Java SSL logs when TLS and TRACE level logs are enabled.

  • If the Connector Gateway is running as command line, then logs are printed on the console
  • If the Connector Gateway is running as service (on Windows only) then logs are printed in the stdout.log file inside the log directory of Connector Gateway.

Resolution - Disable the SSL logs as follows:

  • Add and set the value of the disableSSLLogs parameter to true in the init.xml file of the Connector Gateway under the <Server> tag as follows:

    <disableSSLLogs>true</disableSSLLogs>

  • Set the disableSSLLogs to true using the following command:

    java -jar ConnectorGateway.jar -disableSSLLogs true

Connection with the Connector Gateway is interrupted

If the TLS communication channel is enabled between SailPoint and Connector Gateway, and one of the following errors is encountered:

Connection with Connector Gateway is broken
Could not find valid certificate chain

Resolution: Ensure that one of the following entries exists in the source:

  • CGCertSubject - This indicates that the Connector Gateway certificate name, which is available as CN under properties, exists in the Connector Gateway certificate.

    <entry key="CGCertSubject" value="http://sailpoint.com"/>

  • disableHostnameVerification - This is applicable when the Connector Gateway skips the certificate subject verification.

    <entry key="disableHostnameVerification" value="true"/>

java.security.cert.CertificateException error in the Connector Gateway log

When the Connector Gateway communicates with Mainframe Connector using TLS, and if agentCertSubject or disableHostnameVerification are missing in the init.xml file, the following error message is listed in Connector Gateway logs:

java.security.cert.CertificateException: No name matching zpdt1-sysc.test.sailpoint.com found

Resolution - If TLS communication is enabled between Connector Gateway and Mainframe Connector then following entry is mandatory in the SM tag of the init.xml file:

<agentCertSubject>ENCRYPTED_VALUE</agentCertSubject>

The ENCRYPTED_VALUE can be achieved by using an encryption key mechanism or using the default encryption key supported by the connector while executing the following command:

java -jar ConnectorGateway.jar -agentCertSubject CertSubject

To skip the agent certificate subject validation, the following entry must be added in the init.xml file under the SM tag, the default value is false.

disableHostnameVerification>true</disableHostnameVerification>

CTS1036E R Application name UNDEFAPL specified error and transaction ends

While performing Test Connection or any provisioning operations, the transaction fails with the following error message:

CTS1036E R Application name UNDEFAPL specified in APPL_NAME RSSPARM parameter is not defined in Mainframe Connector.

Resolution - Provide permissions to the administrators performing the transactions.

For more information, refer to Security Configurations for Mainframe Integration Components.

CTS10480E R Provisioning Engine needs to be upgraded or ALLOW_ADMIN_WITHOUT_PSWD should be set to Y in RSSPARM.

Resolution - Upgrade to the latest Provisioning Engine.

Or

Set the ALLOW_ADMIN_WITHOUT_PSWD parameter in RSSPARM of Mainframe Connector and restart the Mainframe Connector.

For more information on the ALLOW_ADMIN_WITHOUT_PSWD parameter, refer to Security Configurations for Mainframe Integration Components.

CTS1081E User SDDEV123 does not exist

While performing a test connection or any provisioning operations, the transaction fails with the following error message:

CTS1081E User SDDEV123 does not exist

Resolution - Ensure that the application configuration credentials are correct and the user exists on the managed system.

Timeout Exception

With correct TLS configuration for communication between Mainframe Connector and Connector Gateway the following error displays:

Timeout Exception

Resolution - Add the TLSCommWait attribute in milliseconds using SailPoint REST API:

PATCH https://sailpoint.api.identitynow.com/v3/sources/:id

Use the form-data as follows:

  • Key - Connector_TLSCommWait
  • value - 100

Interception throws Null pointer exception

Resolution - Ensure that the Connector Name mentioned in the application configuration is in upper-case.

Peer not authenticated

Test Connection displays the following error when using TLS communication:

peer not authenticated

Resolution - During TLS configuration, ensure that the certificate or the keystore / truststore path in the init.xml file is correct. If the truststore is not the default truststore on IdentityIQ then set -Djavax.net.ssl.trustStore in JAVA_OPTS to the full path of the truststore.

Mainframe tools used to handle x37 abends (such as IBM Tivoli® Allocation Optimizer) prevent the Mainframe connector from initializing

Resolution - Any Mainframe tools which handle x37 abends should be avoided when using the SailPoint Mainframe connector.

Note

If you use IBM Tivoli® Allocation Optimizer for z/OS, you should add the SailPoint Mainframe connector to its Exclude list.

Account attributes are not updated after provisioning

Issue: Provisioned account attributes are not updated correctly in SailPoint, even when the provisioning operation completes successfully.

Resolution:

  1. Set disableHotpathForUpdate to false on the SailPoint source.

  2. Use the Patch Source API to update the configuration.

    When disableHotpathForUpdate is set to true, provisioning continues to execute on the mainframe, but SailPoint does not use the provisioning response to refresh the account object.

Self-change password does not set password with NOEXPIRED

Issue: The system does not set the password with NOEXPIRED during a self-change password operation. The user must change the password at first logon.

Resolution:

Set RCF_CHK_PWD_HISTORY to N in the RSSPARM member of the PARM library.

When you set RCF_CHK_PWD_HISTORY to N, the system does not perform a password history check during the change password operation.

Provisioning fails when Account Attribute Mappings static values include $

Issue: Provisioning fails during account creation when an Account Attribute Mappings static value includes the $ character. The system returns this error:

com.sailpoint.seaspray.template.TemplateException: Invalid get reference: <attributeValue> seaspray|line 1, column 2

Resolution: Wrap the static value in a variable before you pass it.

Use: #set(v='<attributeValue>')v

Example for PADMINS: #set(v='PADMINS')v

Documentation Feedback

Feedback is provided as an informational resource only and does not form part of SailPoint’s official product documentation. SailPoint does not warrant or make any guarantees about the feedback (including without limitation as to its accuracy, relevance, or reliability). All feedback is subject to the terms set forth at https://developer.sailpoint.com/discuss/tos.