SAP Joule is SAP's generative AI, designed to help users accomplish tasks through natural language interaction within SAP applications. This guide will provide a step by step walkthrough to enable joule in SAP Fiori.

The guide is primarily written for SAP S/4HANA Cloud, Private Edition (PCE).
PS: Also covers steps that differ for On-Premise S/4HANA (for a Proof-of-Concept environment).

Before starting, it is important to understand the key components involved and the role each plays.

Component	What It Is	Role in This Integration
SAP Joule	SAP's generative AI copilot. A cloud service on SAP BTP.	The AI assistant end users interact with. Loaded in FLP header as a Shell Plugin.
SAP BTP	SAP Business Technology Platform  the cloud foundation.	Hosts Joule, Work Zone, Identity Services, and destinations connecting to S/4HANA.
SAP Build Work Zone, standard edition	SAP's digital workplace platform. Can serve as launchpad or content bridge.	Acts as the technical bridge between Joule and S/4HANA. Required in the Joule Formation.
SAP Cloud Identity Services (IAS)	SAP's Identity Authentication Service. Manages user identity and SSO.	Provides the SSO layer. All BTP services require IAS authentication.
SAP Cloud Connector (SCC)	An on-premise agent creating a secure tunnel from BTP to on-premise systems.	Enables Work Zone and Joule on BTP to securely reach S/4HANA.
SAP Fiori Launchpad (FLP)	The S/4HANA web UI hub where users launch Fiori apps.	The surface where the Joule icon appears via a Shell Plugin target mapping.
Formation	A BTP System Landscape construct grouping systems for a specific integration.	Tells Joule which Work Zone, IAS tenant, and S/4HANA belong together.
CDM3	Common Data Model v3 . SAP Fiori's content model (catalogs, tiles, groups).	Used to expose S/4HANA Fiori content to BTP so Work Zone can sync it.

The following describes the end-to-end integration flow:

• End User opens S/4HANA Fiori Launchpad in browser
• FLP authenticates via IAS (after SSO is configured)
• FLP loads the Joule Shell Plugin from the Joule Web Client (sapdas.cloud.sap)
• Joule on BTP connects to Work Zone via the Joule Formation
• Work Zone reaches S/4HANA via BTP Destinations → Cloud Connector → ABAP Server(S/4 system)
• Joule icon appears in FLP header. Users interact with Joule through natural language.

Requirement	Details
SAP BTP Global Account	Admin access. Subaccount in the same region as your IAS tenant.
SAP Cloud Identity Services (IAS)	IAS tenant associated with your BTP Global Account.
SAP S/4HANA System	PCE or On-Premise (for PoC). FLP accessible via browser.
SAP Cloud Connector	Installed and running. Registered to your BTP subaccount.
S/4HANA Technical User	User with access to CDM3 service (/sap/bc/ui2/cdm3) and FLP admin roles.
BTP Entitlements	Joule (foundation), SAP Build Work Zone standard edition, SAP Cloud Identity Services.
Regional Alignment	BTP subaccount, IAS tenant, and Work Zone must be in the same region.

Note: PCE vs On-Premise: PCE uses token-based registration via Communication Arrangements. On-Premise uses Cloud Connector and manual destinations. Each step calls out differences.

Step 1: Enable Cloud Foundry in BTP Subaccount

Why: Cloud Foundry is the runtime where BTP service instances (Work Zone, Joule) are deployed. Without it, subscriptions and the Joule booster cannot run.

1. Open SAP BTP Cockpit → navigate to your target Subaccount → Overview.
2. Click Enable Cloud Foundry. Accept defaults (Plan: standard). Click Create.
3. Once enabled, click Create Space → name it e.g. ‘dev'. Assign yourself Space Developer + Space Manager roles.

Validation: Subaccount Overview shows CF Enabled, Org Name, API Endpoint, and space ‘dev' listed.

On-Premise PoC: No difference. This step is identical for both PCE and On-Premise.

 

Step 2: Add Entitlements

Why: Entitlements grant your subaccount the right to use specific BTP services. Without them, the services cannot be subscribed to or instantiated.

1. Go to Global Account → Entitlements → Entity Assignments.
2. Select your subaccount → Configure Entitlements → Add Service Plans.
3. Add: Joule (also search as ‘das-application') — plan: foundation
4. Add: SAP Build Work Zone, standard edition — plan: standard
5. Add: SAP Cloud Identity Services — plan: connectivity
6. Click Save.

Validation: All three services appear in Entitlements list with quota assigned.

Step 3: Establish Trust to IAS

Why: All BTP services (including Joule) authenticate via IAS. Establishing trust allows your subaccount to delegate authentication to IAS, enabling SSO across all connected services.

1. Go to BTP Subaccount → Security → Trust Configuration.
2. Click Establish Trust.
3. Select your IAS tenant (e.g., yourtenantid.accounts.ondemand.com).
4. Click Next through the wizard → Finish.

Validation: Trust Configuration shows your IAS tenant with status Active.

Step 4: Configure Trusted Domains in BTP

Why: BTP Trusted Domains control which browser origins can interact with your subaccount's services via iFrames and cross-origin calls. Without this, the Joule panel cannot be embedded in your FLP.

1. Go to BTP Subaccount → Security → Settings → Trusted Domains.
2. Click Add for each of the following origins (scheme + host + port if non-standard):

• Your FLP origin: e.g. https://your-s4-host:44301
• Your Joule Web Client: https://..sapdas.cloud.sap
• Your Work Zone site: https://.launchpad.cfapps..hana.ondemand.com

1. Click Save.

Note: Your Joule URL is found in System Landscape → Formations → your Joule formation → URL column of the Joule system entry.(You can maintain it later once Joule is activated via booster etc.)

Validation: All required origins appear in the Trusted Domains list.

Step 5: Configure Trusted Domains in IAS

Why: IAS maintains its own trusted domain allowlist. Cross-domain authentication requires IAS to trust the same origins as BTP.

1. Open IAS Admin Console: https://.accounts.ondemand.com/admin
2. Go to Applications & Resources → Tenant Settings → Customization → Trusted Domains.
3. Click Add — enter hostname only (no scheme or port) for each host.
4. Click Save.

Note: Format difference: BTP accepts full origins (https://host:44301). IAS accepts hostname only (host.example.com).

Validation: IAS shows ‘Trusted Domains updated' confirmation.

Step 6: Expose SAP Fiori Launchpad Content (CDM3)

Why: Work Zone needs to know what Fiori apps and catalogs exist in S/4HANA. The CDM3 export makes this content discoverable so Work Zone can sync it.

Pre-requisite: Activate CDM3 ICF Service

1. In S/4HANA, run transaction SICF.
2. Navigate to /sap/bc/ui2/cdm3. If inactive, right-click → Activate Service.

Expose Content

1. Run transaction /n/UI2/CDM3_EXP_SCOPE.
2. Select Version 1.
3. Choose All roles (first-time setup) or select specific roles.
4. Click Expose Content in the toolbar. Wait for completion.
5. Click View Log to verify results.

Note: Warnings in the CDM3 log are normal. Red errors should be investigated but typically do not block the integration.

Validation: Log shows entities exposed (e.g., ‘14,663 out of 14,671 entities exposed'). Click View Exposed Content to confirm.

Step 7: Set Up SAP Cloud Connector

Why: Cloud Connector creates a secure outbound-only tunnel from your on-premise/PCE network to BTP. Work Zone and Joule use this tunnel to reach S/4HANA without inbound firewall rules.

Please setup cloud connector first.

7.1 Register BTP Subaccount

1. Open SCC Admin UI (e.g. https://localhost:8443).
2. Add your BTP subaccount using Download Authentication Data from BTP → Connectivity → Cloud Connectors.
3. Confirm status shows Connected (green).

7.2 Create Back-End Mapping

1. Go to Cloud to On-Premises → + Add:

• Protocol: HTTPS (preferred) or HTTP (PoC)
• Internal Host/Port: e.g. S/4HANA internal hostname + HTTPS port 44301 or HTTP port 8001
• Virtual Host: a clean alias (e.g., s4hana-virtual)
• Back-End Type: ABAP System

1. Add Resources: /sap/bc/ui2/cdm3, /sap/bc/ui2/flp, /sap/bc/ui5_ui5 — all with ‘Path and All Sub-Paths'.

Validation: Mapping shows green ‘Reachable' status. BTP Cockpit → Connectivity → Cloud Connectors shows ‘Available'.

On-Premise PoC: If HTTPS port 44301 is blocked between SCC and ABAP server, use HTTP port 8001 for PoC. In SICF, navigate to /sap/bc/ui2/cdm3 → Logon Data tab → check ‘Use all logon procedures' to allow Basic Authentication.

Step 8: Activate Subscriptions and Instances

Why: Subscriptions activate the actual services in your subaccount. Without subscribing to Work Zone and Joule, neither the Joule icon nor the content bridge can function.

1. Go to BTP Subaccount → Instances and Subscriptions → Create.
2. Subscribe to SAP Build Work Zone, standard edition — plan: standard.
3. Subscribe to Joule (das-application) — plan: foundation.
4. For Work Zone: also create a Service Instance (name: BuildZone) and a Service Key.
5. Launch Work Zone from Instances & Subscriptions at least once — this registers it in System Landscape.

Note: The Joule Booster (next step) looks for the Work Zone subscription in its dropdown. It only appears after you launch Work Zone at least once.

Validation: Subscriptions show ‘Subscribed'. Service Key created. System Landscape → Systems shows Work Zone auto-registered.

Step 9: Configure the Joule Formation

Why: A Formation is a logical grouping that tells Joule which Work Zone, IAS tenant, and S/4HANA belong together. Without a formation, Joule has no context about which systems to connect to.

Option A — Run the Joule Booster (Recommended for PCE)

1. Go to Global Account → Boosters → search ‘Setting Up Joule' → click Start.
2. Wizard: Select subaccount and CF space (dev).
3. Step 3 — Select Integrations: choose SAP Build Work Zone, standard edition.
4. Step 4 — Select Capabilities: SAP S/4HANA Cloud Private Edition + SAP Build Work Zone, standard edition.
5. Step 5 — Select your Work Zone system and S/4HANA system.
6. Click Execute and wait for completion.

Option B — Add Systems to Existing Formation

1. Go to Global Account → System Landscape → Formations.
2. Find the formation of type ‘Integration with Joule' with status Ready.
3. Click Include Systems → add your Work Zone instance and S/4HANA system.
4. Confirm integration options (Enable Capability Deployment, Enable Joule Icon).

Validation: Formation shows status Ready (green). Includes IAS, Work Zone, and Joule systems. Note the Joule URL — needed for Trusted Domains and shell plugin.

On-Premise PoC: On-Premise systems cannot complete Communication Arrangement token registration.

Recommended approach:

(1) Run the booster selecting only Work Zone as the integration (not S/4HANA).
(2) Register S/4HANA manually in System Landscape → Systems → Add → Type: SAP S/4HANA Cloud. (Not needed for POC)

Step 10: Configure BTP Destinations

Why: BTP Destinations define how Work Zone and Joule connect to S/4HANA. Without correct destinations, Work Zone cannot read content and Joule cannot reach the backend.

Create the following destination (Design-Time and Runtime can be the same for PoC):

Property	Value
Name	e.g, jouletc  (lowercase, no underscores)
Type	HTTP
URL	http://:/sap/bc/ui2/cdm3
Proxy Type	OnPremise
Authentication	BasicAuthentication
User / Password	S/4HANA technical user with CDM3 access
sap-client	Your S/4HANA client (e.g., 100)
HTML5.DynamicDestination	true
WebIDEEnabled	true
WebIDEUsage	odata_abap

 

Critical: Work Zone Destination Naming: Work Zone only accepts destination names that are lowercase with no underscores. Names like MCF_TC will cause an error. Use names like jouletc or s4hana.

Critical: URL Path: The destination URL must include the CDM3 path: /sap/bc/ui2/cdm3. Without this, Work Zone receives an HTML login page instead of JSON, resulting in an authorization error.

Validation: Check Connection returns HTTP 200. e.g. SWZ_JOULE destination is auto-created and visible in the destinations list.

 

Step 11: Configure Work Zone Channel Manager

Why: The Channel Manager connects Work Zone to S/4HANA as a Content Provider. This sync imports S/4HANA's Fiori catalogs and makes the app landscape available to Joule.

1. Launch SAP Build Work Zone, standard edition from Instances & Subscriptions.
2. Go to Channel Manager → + New.
3. Fill in:

• Title: your system name (e.g., S4H_UIB)
• Design-Time Destination: your lowercase destination (e.g., jouletc)
• Runtime Destination: same
• Content Scope: Roles and related content
• Automatically add all content items: ON

1. Click Save, then click the sync icon.

Wait 5-15 minutes for first sync

On-Premise PoC: The channel may show ‘Updated' with a ‘Connectivity Error' in the Report. This error is for real-time change notification callbacks, which on-premise systems do not support. The content sync itself succeeds. Re-sync manually when S/4HANA content changes.

Validation: Channel shows Updated status. Content Manager → Explore confirms S/4HANA catalogs are visible.

Step 12: Configure Joule Shell Plugin in S/4HANA FLP

Why: The Joule icon in FLP is delivered via a SAPUI5 Shell Plugin configured as a Target Mapping in an FLP catalog. Without this step, users will not see the Joule icon regardless of BTP configuration.

12.1 Create Technical Catalog

1. In S/4HANA, run transaction /n/UI2/FLPD_CUST (Launchpad Content Manager: Cross-Client).
2. In the Catalogs tab, create a new catalog: ID = Z_JOULE_TECH, Title=”Joule Technical Catalog”. Package: $TMP (PoC).

12.2 Create Shell Plugin Target Mapping

1. Open catalog Z_JOULE_TECH in the Launchpad Designer (opens in browser).
2. Click Target Map… tab → Create Target Mapping.
3. Fill in:

• Semantic Object: Shell
• Action: plugin  (type manually — not in dropdown)
• Application Type: SAPUI5 Fiori App
• URL: https://..sapdas.cloud.sap/resources/public/webclient/s4  (NO trailing slash)
• Title: Joule
• ID: sap.das.webclientplugin.s4
• Save.

Critical: No Trailing Slash: The Joule Web Client URL must NOT end with a slash. Use …/webclient/s4 not …/webclient/s4/. A trailing slash causes ‘File not found' and the icon will not appear.

Note: How to find your Joule URL: Go to System Landscape → Formations → your Joule formation. The Joule system shows a URL like https://.eu10.sapdas.cloud.sap. Append /resources/public/webclient/s4 to this base URL.

12.3 Create Role and Assign Catalog

1. Run transaction PFCG → create single role Z_JOULE_S4HANA.
2. Menu tab → click Launchpad Catalog → assign Z_JOULE_TECH (Local Front-End Server).
3. Authorizations tab → Change Authorization Data → Do not select templates → Generate → Save.
4. User tab → assign role to target users → User Comparison → Full Comparison → OK.

Validation: Log in to FLP. The Joule icon (sparkle/diamond) appears in the FLP header. Clicking it opens the Joule panel.

Step 13: Configure IAS SSO for S/4HANA FLP (Recommended)

Why: Joule is secured by IAS. If FLP uses ABAP local login, users must log in again when Joule opens. Configuring IAS SSO for FLP gives a seamless single login experience.

13.1 Download IAS Metadata

1. Open IAS Admin Console → Applications & Resources → Tenant Settings → SAML 2.0 Configuration.
2. Click Download Metadata File. Save the XML.

13.2 Configure SAML2 in S/4HANA

1. Run transaction SAML2 in S/4HANA.
2. Enable SAML 2.0 and create a Local Provider Name.
3. Trusted Providers tab → Add → Upload Metadata File → upload IAS metadata.
4. Set NameID format (Login Name recommended — maps to ABAP user ID).
5. Download S/4HANA SP metadata.

13.3 Register S/4HANA as Application in IAS

1. IAS Admin Console → Applications → + Add.
2. Upload S/4HANA SP metadata under Trust → SAML 2.0 Configuration.
3. Set Subject Name Identifier to match your ABAP user attribute (Login Name).
4. Save.

Validation: Opening FLP URL redirects to IAS login. After login, FLP opens without ABAP credential prompts. Joule opens without a separate login.

Symptom	Likely Cause	Fix
Joule icon not visible in FLP	Shell plugin not loaded or role not assigned	Verify role Z_JOULE_S4HANA is assigned. Hard-reload FLP (Ctrl+Shift+R). Check browser console for plugin errors.
‘File not found' when Joule loads	Trailing slash in plugin URL	Remove trailing slash: use …/webclient/s4 not …/webclient/s4/.
‘Refused to frame/connect' error	Missing Trusted Domain entry	Add the exact blocked origin (shown in browser console) to BTP and IAS Trusted Domains.
Work Zone Channel: Connectivity Error	Real-time callbacks not supported (on-premise)	If status shows ‘Updated' with Connectivity Error — content synced. Re-sync manually as needed.
Work Zone ‘authorization error' on fetch	Destination URL missing CDM3 path	Ensure destination URL is http://:/sap/bc/ui2/cdm3.
Booster fails: ‘System already part of formation'	IAS can only be in one Joule formation	Find the existing Joule formation and add your systems to it instead.
SCC mapping ‘Not Reachable'	Firewall blocking the port	Ask network team to open the port between SCC and ABAP server. Try internal IP instead of hostname.
Joule opens but prompts for login	IAS SSO not configured for FLP	Complete Step 13 — configure SAML2 trust between S/4HANA and IAS.
Work Zone destination name error	Name has uppercase or underscores	Rename destination to lowercase with no underscores (e.g., jouletc).
Wrong Joule URL after S/4HANA 2025 upgrade	DAS_WEBCLIENT_PLUGIN set to pilot URL	Update /UI2/FLP_SYS_CONF (SM30) with your tenant URL, or remove the parameter.

• Joule provisioned on SAP BTP and linked to IAS and Work Zone via a Formation
• SAP Cloud Connector established as the secure bridge between BTP and S/4HANA
• Work Zone Channel Manager syncing S/4HANA Fiori catalogs to BTP
• BTP Destinations correctly routing Work Zone to S/4HANA via Cloud Connector
• Joule Shell Plugin configured in S/4HANA FLP via a Technical Catalog and PFCG role
• Joule icon visible and functional in the S/4HANA Fiori Launchpad