In this page

It seems that a rule is not working. How do I know what went wrong?

By now you probably know that a complete PDF automation requires a pair of automation rules. Both rules can potentially fail, with the following remarks:

  1. When the PDF export rule fails: it means that the request sent to the PDF Automation API was invalid. In this case, the request is rejected and the automation does not actually start.
    The problem details are available in the audit log of the PDF export rule. Solution: fix the request so that it can be accepted! (In other words, make sure that request is formally valid.)
  2. When the PDF callback rule fails: it means that the request sent to the PDF Automation API was valid. In this case, the request is accepted and the automation starts, then some error occurs while executing the requested actions.
    The problem details are available in the audit log of the PDF callback rule. Solution: fix the request so that it can be executed successfully! (In other words, make sure that request is parametrized correctly.)

Regardless of which rule fails, finding the root cause in the automation audit log is nearly identical.

If you have enabled the Notify on error setting on the rule, when a rule fails, Jira Cloud automation sends an email to the rule owner with the details of the failing rule. When you get an email with the subject "Automation rule '{{rule name}}' failed!", follow these steps:

  1. Open the email.
  2. Copy the execution ID shown in brackets next to the automation admin section link (e.g. "(33588366806)") to the clipboard.
  3. Click the automation admin section link.
  4. Search for the execution by the ID in the Audit Log. (The execution should be in the SOME ERRORS status.)
  5. Click the Show more link in its row.
  6. Having the problem details, proceed to the matching item in the typical problems section.

If you have disabled the Notify on error setting on the rule, you will not receive any email related to the failure. In this case, the symptoms are that the PDF files that weren't emailed or attached to an issue. If that's the case, follow these steps:

  1. Navigate to Settings (cog icon "⚙" in the top right) → System → Global automation → Audit log.
  2. Find the recent rule execution with the SOME ERRORS status that may cause the problem. (Check both the PDF export and PDF callback rules, because any of them can lead to the root cause of the problem.)
  3. Click the Show more link in its row.
  4. Having the problem details, proceed to the matching item in the typical problems section.
  5. (Plus, consider turning on Notify on error to make it easier next time.)

Notes:

  • When using a "shared" PDF callback rule that is paired with multiple PDF export rules, the problem details contain a fragment like this: 
    (ID: d359cd00-b06d-5cc6-94ee-93e6975295ff, client: "GS Attach Excel on issue event")
    The "ID" is the identifier of the execution, while "client" is the name of the PDF export rule that called this callback. Using these pieces of information you can easily find the PDF export rule to fix!

If you can't fix the problem after studying the troubleshooting item, open a support ticket with the problem details.

Typical problems and their solutions

After you investigated the problem details and, most importantly, you have the error message, see the matching item below for the explanation of the problem and for the instructions to fix it.

In most cases the app gives a clear explanation on what went wrong. Therefore, even if your particular error message is not 100% identical with the ones below, it is worth to have a look at the "similar" items.

My rule failed with the "Better PDF Exporter for Jira Cloud app is not installed!" message.

Problem: Better PDF Automation for Jira can not work alone. It relies on the Better PDF Exporter for Jira app for generating the PDF file that will be processed by the automation rules.

Solution: Install the Better PDF Exporter for Jira Cloud app to your Jira Cloud site.

My rule failed with the "Better PDF Automation for Jira Cloud app is not installed!" message.

Problem: The successful execution of automation rules requires Better PDF Automation for Jira to be installed.

Solution: Install the Better PDF Automation for Jira Cloud app to your Jira Cloud site.

My rule failed with the "{header name} header must be defined and not be blank!" message.

Problem: The Send web request action requires a few request headers to successfully call the PDF Automation API.

Solution: Configure the required request headers with correct values.

My rule failed with the "Content-Type header must be defined with value application/x-yaml!" message.

Problem: Send web request action sets the "Content-Type" request header to the default value "application/json", but the PDF Automation API expects YAML format request bodies.

Solution: Configure the Content-Type request header with the "application/x-yaml" value.

My rule failed with the "Invalid credentials provided!" message.

Problem: The Send web request action requires authentication credentials to allow connecting to the Jira Cloud site.

Solution: Configure all required request headers with correct values.

My rule failed with the "{field name} must be defined and not be blank!" message.

Problem: You forgot to add a required field or set its value in the request body YAML.

Solution: Add the missing field with a valid value to the request body YAML.

My rule failed with the "actions[n].type must be defined and be one of ATTACH or CALL or SEND!" message.

Problem: You forgot to add the type field for an action, or it has an invalid value.

Solution: Check the actions list and make sure that the item with the mentioned index has a type field with a valid value. (Note that indexing starts from 0, therefore actions[0] is actually the first item in the list.)

My rule failed with the "actions[n].to must be a list!" message.

Problem: The to, cc and bcc fields of a SEND action must be a valid list if they contain multiple email addresses.

Solution: Check the actions list and make sure that the mentioned field's value is a proper YAML list. (Note that indexing starts from 0, therefore actions[0] is actually the first item in the list.)

My rule failed with the '"actions[n].body" must not exceed the limit of 500 characters!' message.

Problem: You are most likely to get this error if you are trying to send an email with an overly long body, but the length of the value is limited for many other fields as well.

Solution: Check the actions list and make sure that the mentioned field's value contains fewer characters than the limit. (Note that indexing starts from 0, therefore actions[0] is actually the first item in the list.)

My rule failed with the "Malformed YAML request" message.

Problem: The YAML has to be properly formatted otherwise the PDF Automation API won't accept it.

Solution: Validate the YAML with an online validator, fix the problems found and try running the rule again.

My rule failed with the "A low-level technical problem has occurred, most likely a timeout." message.

Problem: You may get this error if you are trying to export too many issues at a time. In the Cloud version of Better PDF Exporter, all exports must complete within 10 minutes, otherwise the process will be terminated in order to save resources. As the execution of an automation rule starts with exporting the PDF file, this limitation inherently applies to automation rules, too.

Solution: Set the export.jql field to a JQL query or the export.filterId field to a saved filter that returns fewer issues. If the problem persists, open a support ticket and we will be there to help.

Note that although several factors affect the number of issues that fit in the 10 minutes duration, generally speaking, you can export 1000 issues without any problems.

My rule failed with the "Failed to execute action with the PDF document" message.

Problem: These types of errors occur during the phase when the exported PDF file is being processed by the actions.

Solution: To understand the problem more, check the text inside the curly brackets. Example: "{type=ATTACH, name=Attach PDF to issue, successful=false, message=Issue does not exist with key SCRUM-23}"

Let's break it up and analyze it!

  • "type=ATTACH" means that the failed action is an ATTACH type one.
  • "name=Attach PDF to issue" shows the precise name of the action.
  • "successful=false" just means that the action failed.
  • "message=Issue does not exist with key FOO-123" clearly explains that you tried to attach the PDF file to a non-existing issue.

Fix: in this particular example, configure the toIssueKey field for the ATTACH action with an existing issue key. Obviously, different messages require different fixes, but the messages themselves should be very intuitive.

My PDF export rule succeeded but the PDF callback rule was not triggered.

Problem: The URL you provided for the CALL action is well-formed, but it isn't actually valid.

Solution: Make sure that the url field of the CALL action is the same as the Webhook URL in the PDF callback rule's trigger (which is Incoming webhook type).

My rule succeeded, but recipients haven't received any emails.

Problem: The most likely root cause is that there is a typo in one or more email addresses. The app validates whether the email addresses are formally correct, but it can't validate if they actually exist.

Solution: Double-check the email addresses in the SEND action's to, cc and bcc fields.

My rule failed, but the message is different from the items above.

If your rule failed with a message that's different from the ones above and you can't find the solution, open a support ticket and we will help.