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:

ACF2 is not provisioning due to a TYPE attribute

When the application has a TYPE attribute for a UID string defined in the schema and splConnection attributes, then ACF2 will not provision.

Resolution - Remove or Rename TYPE from the UID string as an attribute in its definition.

A third party monitoring tool (Port Monitoring software) usage and its implications

Resolution - When using Port Monitoring software to validate the Connector Gateway connections, use one of the following methods to enable this service to work properly:

  • Using a port monitoring solution - Ensure that the port monitoring software is located on a server other than the SailPoint and/or the Connector Gateway server. The proper method of using the software is to establish a connection in the same method used by SailPoint:

    Connect on the defined port +1 and on the defined port 2470, (the port defined in the init.xml file is 2470). This method creates a valid socket connection.

  • Checking the status of the Connector Gateway - This method involves the use of two telnet sessions as described below:

    Connect on the defined port +1 and on the defined port 2470, (the port defined in the init.xml file is 2470). This method creates a valid socket connection.

    This should be tested to ensure that this does not interfere with active connections within your environment.

  • Writing a log parser - Write a log parser to check for socket information within the logs. If the socket connections are not performing properly, preventing the Connector Gateway from determining the proper status, enable DEBUG tracing. The following are other options to use log parser method:

    • Check the log output to see when the connection information was last updated (stale connection check), and if there are no updates from the Connector Gateway within the time variable X (to be defined locally as it pertains to the environment), then Service. With this the Connector Gateway would be Online.
    • Write a log parser that will validate the socket connection pairs for the transactions that are valid and are initiated from the IP address of the SailPoint host only. When using this method, ensure that the connection is misdirected, unclean, or invalid.

Ensure that other unwanted traffic does not interfere with the normal communications in your network. To accomplish this, you can use Firewalls and Routing to isolate traffic to and from only trusted and intended source machines and services. SailPoint recommends that you test the given alternative methods in your environment using the proper Change Management methodologies listed below:

  • Develop
  • Test
  • Promote to production after proper testing is completed

Special characters not working in Mainframe Connector passwords

Resolution - If any special characters are not working in Mainframe Connectors in passwords, perform the following:

  1. Change the character set to IBM1047 for Mainframe Connectors-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 above step:

    <characterSet>IBM1047</characterSet>

  3. Restart the Connector Gateway.

Account/Group data updated incorrectly after 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 the 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.

During aggregation if a user performs Test Connection, the Test Connection transaction times out

During aggregation if you perform a Test Connection, the Test Connection transaction times out.

Resolution - During aggregation if you perform a Test Connection, the Test Connection transaction will time out because the connector is busy processing the aggregation. To resolve this issue, configure Multiple Transaction Servers on the connector to perform more than one transaction at a time.

Note

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

Transactions taking more than 10 minutes

Transactions take an excessive amount of time, usually more than 10 minutes.

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

Set the smReadTimeout parameter in Configuration > System Configuration 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.

During aggregation, records are truncated when data exceeds the buffer limits for one or more entities

Resolution - The FOREVERY MAX_MSG_SIZE 32723 attribute indicates the maximum size of a single object record during aggregation. Any record with a size beyond this limit is truncated during aggregation. The isIncomplete attribute must be set to true in the properties of such records to indicate the truncation. Default value of the attribute is 20480 while the maximum value can be set to 32723.

Custom attributes which start with a hash symbol (#) are excluded from aggregation

Custom attributes in the ACF2 source which start with a hash symbol (#) are not aggregated to SailPoint. For example, the attribute, #EMPL, would be excluded from aggregation.

Resolution - Configure a second attribute with an @ symbol instead of a hash symbol (#). For example, to aggregate #EMPL, create the custom attribute, @EMPL.

Important

Provisioning custom attributes requires that the attribute has the hash symbol (#) in its name. You need to have both attributes configured to support provisioning and aggregation. So, to provision and aggregate the #EMPL attribute in the ACF2 source, you must have two attributes: #EMPL and @EMPL.

An error message appears when creating an account with lowercase characters

When a user tries to create an account in ACF2 with lowercase characters, the following error message appears:

Provisioning account failed for operation Create with error: Identity attribute [USER_ID] was not found.

Resolution - Enter the USER_ID in uppercase or add the following code into the Application Debug page:

  1. Open the Application Debug page and search for the PlanInitializerScript tag.

  2. Add the following code for the Create Account operation to convert the USER_ID entered in lowercase to uppercase.

    {{ if (op == AccountRequest.Operation.Create)
    {
        String userId = req.getNativeIdentity();
            if (userId != null)
                {
                    req.setNativeIdentity(userId.toUpperCase());
                }
    }
}}

Handling multiple LPARs under SYSPLEX and JESPLEX

The ACF2 Connector uses ENQ with SYSTEMS in order to protect and coordinate writing to the Queue file and to the ACF2UDB and ACF2GDB files. When this scenario exists, all ENQ refer to the same file names and therefore locking is caused between the two LPARs and between the two JESPLEXs.

Resolution - Use one of the following methods to resolve this issue:

  1. Use different a STC prefix in the two JESPLEXs. SailPoint recommends doing this before the installation of the connector. If done after installation, changing STC names can be more difficult.
  2. Use different file names in both JESPLEXs for Queue, ACF2UDB, and ACF2GDB files.
  3. Change the QNAME parameter in the CTSPARM member in the PARM library and compile it using the CTSPARMJ job in the INSTALL library.
  4. Restart the connector.

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 to 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.

(Code Refactoring) Connector Gateway printing Java SSL logs when TLS and TRACE level logging are enabled

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

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

Resolution - Disable the SSL logs doing one of the following:

  • 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 by 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"/>

Certificate Exception error in the Connector Gateway log

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

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

Resolution - If TLS communication is enabled between the Connector Gateway and the Mainframe Connector, then the following entry is must be added under the SM tag of the init.xml file:

<agentCertSubject>ENCRYPTED_VALUE</agentCertSubject>

The ENCRYPTED_VALUE can be achieved by using the encryption key mechanism or by 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 an error and transaction ends

While performing a Test Connection or any provisioning operation, 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 the Mainframe Connector, then restart the Mainframe Connector. For more information on the ALLOW_ADMIN_WITHOUT_PSWD parameter, refer to Security Configurations for Mainframe Integration Components.

Test Connection or Provisioning Fails with CTS1081E User SDDEV123 Does Not Exist

While performing a Test Connection or any provisioning operation 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

ACF2 permissions from Target Aggregation not cleaned up

After adding the AccountDirectPermissions and AccountIndirectPermissions attributes were added in an update, older permissions aggregated via Target Permission are not getting cleaned up. Additionally, The accountDirect and indirectPermissions attributes are aggregated using account aggregation. In certification, permissions from Target Aggregation and the same permissions (with format structure changes) were populated. So while deleting such permissions, issues were encountered due to the same permissions but with different format structure.

Resolution - Perform the following steps to clean up target permissions:

  1. Delete the required target source.
  2. Run a refresh so that the target permissions related to the deleted target source will be cleaned up.

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

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, 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.

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.