Basic Troubleshooting

Problem: Unable to connect to ReadyWorks or related servers.

Steps to troubleshoot:

Verify that the server where ReadyWorks is installed meets the minimum requirements, and ensure it has access to all necessary data sources.
Check network configurations to ensure that ReadyWorks can communicate with other systems. Firewalls, lack of necessary credentials (like service account credentials), or DNS issues could block connectivity.
Use the logs: Navigate to Admin > Logs > System Logs to check for any connectivity errors.
Confirm that the required MariaDB database is accessible and the necessary ETL jobs are configured correctly.
Ensure the ReadyWorks server is running, and both the Apache and MariaDB services are started.

Problem: ETL jobs fail or do not pull data as expected.

Steps to troubleshoot:

Verify that ETL jobs are scheduled properly under Admin > Configuration > ETL.
Ensure correct API keys or OAuth tokens are configured for API connections.
Confirm that the REST API connections and job settings (e.g., pagination, query parameters) are correctly defined. Incorrect query parameters or pagination could result in incomplete data imports.
Review the ETL logs under the Logs section to identify specific job failures.
Check the staging tables to ensure data is being ingested properly. If data isn’t appearing in staging tables, check the underlying REST API call or database query.

Problem: Data isn't mapping or transforming correctly during the import process.

Steps to troubleshoot:

Verify data mapping rules under Admin > Configuration > Data Mapping. Ensure that each field from the source is correctly mapped to the corresponding asset type.
Ensure that SQL queries used for data mapping follow best practices, like proper use of indexing, efficient queries, and normalization.
For transformations or calculated fields, confirm that all transformations are correctly defined in the SQL query used for mapping.
Run the mapping on a test dataset to ensure it performs as expected. Check if data appears correctly in the staging tables first, then in the asset tables.
Verify your query returns unique names for mapping to an asset.

Problem: Emails or triggered communications are not being sent.

Steps to troubleshoot:

Ensure that TCOMMs are correctly configured under Admin > Configuration > TCOMMs and that templates are set up properly.
Verify email settings under the E-mail Module to ensure the SMTP server is correctly set up and functional.
Review the TCOMM logs for any errors, particularly around email formatting or incorrect recipient information.
Engage your corporate communications team early to validate compliance with messaging standards.

Problem: Waves aren’t processing as expected, or assets aren’t being processed correctly in waves.

Steps to troubleshoot:

Verify that waves are set up correctly and that the relevant assets are grouped in waves for bulk actions.
Ensure that all automation rules tied to waves are correctly configured under Wave Configuration. This includes checks for data readiness, conditions for wave triggers, and email communications.
Use wave logs to identify any errors or failures in asset processing. This will give insight into whether certain assets are missing key information or if wave triggers are not functioning properly.

Problem: Issues with forms (e.g., not saving data correctly or missing fields).

Steps to troubleshoot:

Verify that the Form Builder is correctly configured and that all form fields are properly mapped to their corresponding asset fields.
Ensure that the appropriate permissions are set up so users can view and submit the form without errors.
Check for any custom scripts (e.g., JavaScript) that might be causing errors on the front end. Debug these using browser developer tools to see if there are any console errors related to forms.

Problem: Cron jobs aren’t executing or not updating as expected.

Steps to troubleshoot:

Confirm that all Cron Jobs are scheduled correctly under Admin > Configuration > Options > Cron Jobs, and that the frequency settings (e.g., daily, hourly) are configured as needed. (e.g., daily, hourly).
Check that Cron Jobs have been added to task scheduler.
If a job isn't running as expected, check the system logs to see if there are any related errors. Cron jobs often fail due to incorrect configurations or issues with dependencies.
If more frequent data updates are needed (e.g., hourly instead of daily), adjust the job schedule, but ensure that your system can handle the increased load without impacting performance.

Problem: Users are unable to log in or access the system.

Steps to troubleshoot:

Ensure that the Single Sign-On (SSO) module is correctly configured. ReadyWorks supports several Identity Providers, and errors often stem from incorrect SSO settings.
If SSO issues occur, check the SSO logs on the settings page for the enabled module. You can also consult the session termination log under Admin > Event Logs for additional troubleshooting.
Check that the LDAP configuration is correct for organizations using LDAP for user authentication.
Use the Admin > Users section to verify that user roles and permissions are set up correctly.