Troubleshooting application registration errors
When you register an application in Pega Process Fabric Hub, you might encounter some errors. To resolve common issues that block you from adding the application to Pega Process Fabric Hub, follow the respective guidelines for each scenario when the registration process fails.
Condition
The process of registering your application in Pega Process Fabric Hub fails, and you receive an error message.
Issue: Missing operator ID
An operator ID that you use in Pega Process Fabric Hub to register applications does not match the operator ID that you use in the Pega Platform system that hosts your applications to register. You receive the following error message:
- Failed to connect - the HTTP response code of 400 indicated a client error. The response data may contain a reason.
- Response - No operator is associated with the token.
Solution
- In your remote Pega Platform system, create an operator ID that is identical to your Pega Process Fabric Hub operator ID. For more information, see Creating operator IDs.
Issue: Unavailable operator ID
An operator ID that you use in Pega Process Fabric Hub to register applications is disabled in your remote Pega Platform system. You receive the following error message:
- Failed to connect - the HTTP response code of 403 indicated a client error. The response data may contain a reason.
- Response - Operator is disabled.
Solution
- Enable an operator ID. For more information, see Enabling operators.
Issue: Disabled DataSyncOperator operator
Activation of a remote application fails because during an import of the
PegaProcessFabricHub.jar
product rule file, a
DataSyncOperator operator remained disabled.
You receive the following error message:
- Failed to connect - the HTTP response code of 500 indicated a server error. The response data may contain a reason.
- Response - Return connection failed with the HTTP response code of 401.
Solution
- In the navigation pane of Dev Studio, click Records.
- Expand the Organization category, and then click Operator ID.
- In the list of instances, click DataSyncOperator.
- On the operator rule form, on the Security tab, clear the Disable Operator check box.
- Click Save.
Issue: Missing applications to register
Pega Process Fabric Hub displays no applications to register. This issue might occur if you fail to add the Pega Process Fabric Hub Connector component to any of your applications in your Pega Platform system or after you register your applications in Pega Process Fabric Hub. You also need to have an Application:Administrators, Application:Authors, or your custom access group with administrative privileges added to your operator ID in the application that you want to register. You receive the following error message:
Sorry, no qualified applications were found to register. Please make sure the component 'Pega-ProcessFabric' is added to your application(s).
Solution
- Add the Pega Process Fabric Hub Connector component to your application. For more information, see Installing the Pega Process Fabric Hub connector component.
- Add an Application:Administrators or Application:Authors access group to your operator ID. For more information, see Defining operator contact information and application access.
- If you use a custom access group other than
Application:Administrators
or Application:Authors,
perform the following actions:
- Add the custom access group to the
AllowedRegistrationAccessGroups dynamic
system setting.For more information, see Modification of the standard mappings published to Pega Process Fabric Hub and Editing a dynamic system setting.
- Add the custom access group to your operator record.For more information, see Defining operator contact information and application access.
- Add the custom access group to the
AllowedRegistrationAccessGroups dynamic
system setting.
Issue: Invalid AsyncProcessor configurations
Pega Process Fabric Hub fails to synchronize data with your application due to invalid AsyncProcessor configurations. The issue can involve an access group or a list of rulesets and roles based on your AsyncProcessor requestor type configuration.
If your remote application is in Pega Platform version 8.1 or 8.2, you receive one of the following error messages:
- Failed to begin synchronization of data due to invalid access group configuration provided on ASYNCPROCESSOR requestor type.
- Failed to begin synchronization of data due to invalid ruleset configuration provided on ASYNCPROCESSOR requestor type.
If your remote application is in Pega Platform version 8.3 or later, you receive the following error message:
- Failed to begin synchronization of data due to invalid System Runtime Context Configuration. Take necessary steps to correct it.
Solution
- In the navigation pane of Admin Studio, click .
- Ensure that the following queue processors run correctly:
- pyPF_PublishAssignment
- pyPF_PublishBulkAssignments
- pyPF_PublishBulkOperators
- pyPF_PublishBulkWorkQueues
Issue: Remote application remains in a Sync-InProgress status
During application registration, a remote application does not change status from Sync-InProgress to Active. This issue can involve failed queue processors or Stream services. Based on the root cause, you receive one of the following error messages:
- Failed to connect - the HTTP response code of 500 indicated a server error. The response data may contain a reason.
- Response - One or more Queue Processors on the remote system that are required for synchronization process are unavailable. Take necessary steps to make these Queue Processors available.
- Failed to connect - the HTTP response code of 500 indicated a server error. The response data may contain a reason.
- Response - Stream service is unavailable. Verify that the service is not stopped and take necessary steps to set it to normal.
- Ensure that your Stream services run correctly.For more information, see Deploying and operating the Stream service.
- Ensure that the following queue processors run correctly:
- pyPF_PublishAssignment
- pyPF_PublishBulkAssignments
- pyPF_PublishBulkOperators
- pyPF_PublishBulkWorkQueues
Issue: Missing component
Pega Process Fabric Hub fails to connect to your application because your application misses the Pega Process Fabric Hub Connector component. This issue might occur when you fail to add the relevant version of the Pega Process Fabric Hub Connector component to your application. You receive the following error message:
Failed to connect - the HTTP response code of 403 indicated a client error. The response may contain a reason. // The body of the service's response, which is set up for mapping in the Connector rule, was empty for this service call.
Solution
- Ensure that your default application contains the version of the Pega Process Fabric Hub Connector component that is relevant to your version of Pega Platform. For more information, see Installing the Pega Process Fabric Hub connector component.
Issue: Exception during creating an OAuth 2.0 client
The remote application fails to connect to Pega Process Fabric Hub when you try to activate the connection. Pega Process Fabric Hub can connect to the remote application, but the communication works only one way because of the connection issues. You receive the following error message:
- Failed to connect - the HTTP response code of 500 indicated a server error. The response data may contain a reason.
- Response - Return connection failed with the exception - com.pega.pegarules.pub.services.OutboundMappingException: Caught Exception while creating OAuth2 client.
Solution
- Ensure that the configuration of the PegaProcessFabricSvcURL dynamic system setting is correct.
- Ensure that your remote application can access the Pega Process Fabric Hub URL with no firewall or network restrictions.
Issue: Unsupported authorization grant type
Users that want to register an application with Pega Process Fabric Hub use credentials from OAuth 2.0 authentication, which has a grant type that differs from JWT, and as a result, receive the following error message:
- Failed to connect - the server responded with an HTTP 401 code, indicating an authorization problem.
- Response - The authenticated client is not authorized to use the given grant type.
Solution
- Ensure that the credentials with which users register applications have
the correct grant type:
- To use existing credentials, change the grant type of the OAuth 2.0 rule to JWT.
- To provide new credentials, create a OAuth 2.0 rule with JWT as a grant type, and then use the client credentials that you obtain from the new rule.
For more information, see Configuring an OAuth 2.0 authentication profile.
Issue: Failed client authentication
Users that want to register an application with Pega Process Fabric Hub provide incorrect credentials, and as a result, receive the following error message:
- Failed to connect - the server responded with an HTTP 401 code, indicating an authorization problem.
- Response - Client authentication failed.
Solution
- Ensure that the credentials that users provide when they register applications are correct.
Issue: Invalid authorization grant
The registration of an application with Pega Process Fabric Hub fails and users who register the application receive an error message. This issue occurs when the truststore value present in the Pega Process Fabric Hub token profile is invalid, and creates the following error message:
- Failed to connect - the HTTP response code of 400 indicated a client error. The response data may contain a reason.
- Response - Unable to retrieve JWK public key.
Solution
- Ensure that the truststore value is correct:
- If you deploy Pega Process Fabric Hub and your remote application on the same system, configure the truststore in the PPFConnect token profile as PPFKS.
- If you deploy Pega Process Fabric Hub and your remote application on different systems, configure the truststore in the PPFConnect token profile as PPFConnect.
Issue: Invalid authorization grant - JSON Web Signature (JWT) use before time
The registration of an application with Pega Process Fabric Hub fails and users who register the application receive an error message. This issue occurs when there is a time difference (clock skew) between Pega Process Fabric Hub and the remote application, and the system creates the following error message:
- Failed to connect - the HTTP response code of 400 indicated a client error. The response data may contain a reason.
- Response - The authorization grant is invalid.
Solution
- Check the logs to see if they contain the JSON web token is rejected during signature verification due to bad signature : JWT before use time error message. If the error message is present in the logs, then adjust the clock skew property in the Token lifetime section of the PPFConnect token profile rule.
Issue: Resource not found
Pega Process Fabric Hub does not display an application to register, and then a user receives a 404 Resource not found error message. This issue occurs when the access group that you map to the ppfconnect service package cannot access the required APIs for registration. You receive the following error message:
Failed to connect - the server responded with an HTTP 404 code, indicating that the resource does not exist.
Solution
- Edit the ppfconnect service package rule to
include the service access group that is any of your application access
groups. For example, to register a Mortgage requests application, use
the Mortgage:Administrators,
Mortgage:Authors, or your custom access
group that includes administrative privileges.
For more information, see Providing access rights for Pega Process Fabric Hub by editing a service package.Note: If you use a custom access group other than Application:Administrators or Application:Authors, add the access group to the AllowedRegistrationAccessGroups dynamic system setting. For more information, see Modification of the standard mappings published to Pega Process Fabric Hub and Editing a dynamic system setting. Ensure that the access group is present in your operator record. For more information, see Defining operator contact information and application access.
Issue: Missing administrator access for the application
Application registration fails when users try to register the application in Pega Process Fabric Hub. This issue occurs when the users that try to register an application have no access group with administrative privileges in the application. You receive the following error message:
- Failed to connect - the HTTP response code of 400 indicated a client error. The response data may contain a reason.
- Response - You do not have an appropriate access to this application.
Solution
- Ensure that users that want to perform an action during the
registration process of an application have an
Application:Administrators,
Application:Authors,
or a custom access group with administrative privileges. For example, if
users want to register a financial operations application in Pega Process Fabric Hub, users need to have a
Financial:Administrators or
Financial:Authors access group.
For more information, see Defining operator contact information and application access.Note: If you use a custom access group other than Application:Administrators or Application:Authors, add the access group to the AllowedRegistrationAccessGroups dynamic system setting. For more information, see Modification of the standard mappings published to Pega Process Fabric Hub and Editing a dynamic system setting. Ensure that the access group is present in your operator record. For more information, see Defining operator contact information and application access.
Issue: Application unable to retrieve JWK public key
Registration of an application in Pega Process Fabric Hub fails, and users that register the application receive an error message. This issue occurs when the keystore URL and the PegaProcessFabricSvcURL dynamic system setting on the remote machine reference an invalid instance of Pega Process Fabric Hub. This issue also occurs when you host Pega Process Fabric Hub and your remote application on the same system, and the truststore configuration is incorrect. You receive the following error message:
- Failed to connect - the HTTP response code of 400 indicated a client error. The response data may contain a reason.
- Response - Unable to retrieve JWK public key.
Solution
- Edit the keystore URL and the PegaProcessFabricSvcURL dynamic system setting on your remote machine to ensure that the system references the correct Pega Process Fabric Hub instance, and then proceed with registration.
- If you host Pega Process Fabric Hub and your remote application in the same instance of Pega Platform, name the truststore in the PPFConnect token profile as PPFKS.
Issue: Pega Process Fabric Hub redirects to a wrong application
After users click the assignment link in Pega Process Fabric Hub, Pega Process Fabric Hub redirects them to an application different from the application that routed the assignment. For example, when the users click the link to open the assignment from a banking operations application, Pega Process Fabric Hub opens the Credit card disputes operations. This issue occurs when a configurator provides an incorrect application URL during application registration, or when users that open the assignment have multiple access groups of an application, and the Application:Users access group is not first in the list of application access groups.
Solution
- Edit the application URL for your registered application:
- For applications that you host in Pega Platform version 8.4 and later, provide the application alias URL.
For example, enter https://uplustelco.com/prweb/app/MyApp1.
- For applications that you host in Pega Platform version 8.3 and earlier, provide the system URL.
For example, enter https://uplustelco.com/prweb.
For more information, see Managing applications in Pega Process Fabric Hub. - For applications that you host in Pega Platform version 8.4 and later, provide the application alias URL.
- Ensure that the Application:Users access group of the users that want to open assignments at run time is at the top of the list of access groups for the application.
Issue: Update Record failed
The registration of an application with Pega Process Fabric Hub fails and users who register the application receive an error message. This issue occurs after application requestor passivation when the remote application has the Use check-out checkbox selected in the topmost unlocked ruleset. You receive the following error message:
- Failed to connect - the HTTP response code of 500 indicated a server error. The response data may contain a reason.
- Response - Update record failed: .pyRuleset: You are not the owner of this checked out rule.
Solution
- Re-submit the Stop sync modal dialog box by clicking the Stop sync button.
Previous topic Pega Process Fabric Hub troubleshooting Next topic Troubleshooting connection with Salesforce Platform