The Recommended Issue Resolution Workflow
The following workflow provides a systematic approach to resolving Joule issues. It is divided into two phases: Initial triage (performed by the user or first-level support) and Diagnostic Investigation (performed by the Joule administrator).
Phase 1: Initial Triage
Step 1: Identify the Symptom
Before diving into troubleshooting, take a moment to classify the issue. The fastest path to a fix starts with asking: what kind of problem is it? Match the reported symptom to one of these common categories:
Symptom (Most Common) | Likely Category |
Joule icon not visible | UX / Icon Issue |
Blank/white screen after clicking icon | SAP Cloud Identity Services – Identity Authentication (IAS) / Identity Provisioning (IPS) |
“Refused to connect” error | Trusted Domains / Connectivity |
“Digital Assistant not found” | Formation / SAP BTP Provisioning |
Joule only provides SAP Help documentation | Content / Roles / Capabilities |
“I'm having trouble connecting” | Connectivity / Principal Propagation |
Joule not greeting with user's name | Identity / Global User ID |
Booster execution fails | Joule Booster / Activation |
Step 2: Download Traces
A quick but important step before escalating any Joule issue: collect your diagnostic data upfront. Fortunately, Joule makes this straightforward. Head to Settings > About > Download Traces, decide whether to include message history, and save the .zip file. This single package contains a wealth of troubleshooting information, including: Joule version and environment details, UI logs and recent HTTP requests, Correlation IDs for the last 5-10 messages, Message history (if consented).
Step 3: Determine the Response Type and Classify the Issue Layer
Per SAP Note 3679363 How to recognize a Joule response's type?, Joule has three response types:
Response Type | How to Recognize | Meaning |
Direct Response | Generic content, exclamation mark on hover (Response Insights) | Joule could not match any capability or knowledge source |
Information Retrieval | Response includes SAP Help documentation links or custom document sources | Joule matched knowledge content but not a transactional capability |
Transactional / Navigational | Response returns business data or app navigation buttons | Capability was successfully selected and executed |
A mismatch between the expected and actual response type is a telltale sign of a deeper issue. If you're expecting a transactional or navigational response but Joule returns an informational or direct answer instead, this points to a content, role, or configuration problem that warrants a closer look by your administrator.
Tips:
Joule Response Types (SAP Note 3679363 How to recognize a Joule response's type?)
Direct Response: Generic “I cannot…” + exclamation icon on hover Information Retrieval: Response includes SAP Help doc links Transactional/Navigational: Returns business data or app button
If expected Transactional but got Informational/Direct: -> Follow Path D below (Content/Roles)
The fastest way to get to the bottom of a Joule issue is to match the symptom to the right architecture layer. Use the table from the github repository ([Github] leee03/SAP_Joule_Issue_Catalog) as your starting point — it maps common symptoms to the layer most likely responsible, so you know exactly where to focus your investigation, a simplified view as below:
Symptom | Diagnostic Path | Architecture Layer |
Joule icon not visible in SAP Fiori Launchpad | Path F: UX / Icon Appearance | Layer 1: Client/UX |
“Refused to connect”https://community.sap.com/”I'm having trouble connecting” | Path E: Connectivity / Principal Propagation | Layer 5: Connectivity |
Joule returns SAP Help content / generic instructions only | Path D : Content Exposure & Roles | Layer 3: SAP Build Work Zone + Layer 6: Backend |
“Digital Assistant not found” | Path E: Connectivity / (Formation) | Layer 5: Connectivity |
Joule not greeting with user name / blank screen | Path C: SAP Cloud Identity Services | Layer 2: SAP Cloud Identity Services |
Booster execution fails / formation errors | Path B: Joule Booster / Activation | Layer 4: Joule Service |
Entitlements missing / systems not in landscape | Path A: SAP BTP Provisioning | Layer 7: SAP Business Technology Platform |
Content Provider sync fails / unauthorized | Path D : Content Exposure & Roles | Layer 3: SAP Build Work Zone |
The diagnostic path detailed will be mentioned in below chapter in part3.
Let us continue to part 3!
