Skip to content

Commit 1b005a3

Browse files
committed
docs(km): fix back-end hyphenation and heading sentence case
- misc/destinations/README.md: "Environment Check Report" → "Environment Check report" (H4 sentence case) - misc/onpremise/connectivity.md: two instances of "back end" → "back-end" (KM terminology)
1 parent e91dde4 commit 1b005a3

File tree

2 files changed

+110
-23
lines changed

2 files changed

+110
-23
lines changed

misc/destinations/README.md

Lines changed: 79 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22

33
## Overview
44

5-
SAP BTP destinations are used to connect to different services and systems in the cloud, on-premise or any publicly available endpoints. They are used to define the connection parameters for the service you want to consume. The destination is a logical representation of the service and contains all the information required to connect to it.
5+
SAP BTP destinations are used to connect to different services and systems in the cloud, on-premise, or any publicly available endpoints. They are used to define the connection parameters for the service you want to consume. The destination is a logical representation of the service and contains all the information required to connect to it.
66

77
When using `WebIDEUsage=odata_gen`, there are two ways to configure the destination URL:
88

9-
- **Partial destination** The destination URL contains only the base host (for example, `https://services.odata.org`). SAP tooling automatically appends the OData service path at runtime. Use this when your back-end exposes multiple services and you want to specify the service path during consumption.
10-
- **Full destination** The destination URL contains the complete path to a specific OData service (for example, `https://services.odata.org/v2/northwind/northwind.svc/`), indicated by setting `WebIDEAdditionalData=full_url`. SAP tooling uses the URL exactly as configured without appending any additional paths. Use this when you are targeting a single, fixed service endpoint.
9+
- **Partial destination**: The destination URL contains only the base host (for example, `https://services.odata.org`). SAP tooling automatically appends the OData service path at runtime. Use this when your back-end exposes multiple services and you want to specify the service path during consumption.
10+
- **Full destination**: The destination URL contains the complete path to a specific OData service (for example, `https://services.odata.org/v2/northwind/northwind.svc/`), indicated by setting `WebIDEAdditionalData=full_url`. SAP tooling uses the URL exactly as configured without appending any additional paths. Use this when you are targeting a single, fixed service endpoint.
1111

1212
When using `WebIDEUsage=odata_abap`, the partial/full distinction does not apply. The destination URL must always be the base host only, and SAP tooling appends the ABAP catalog paths automatically.
1313

@@ -116,7 +116,7 @@ The SAP BTP destination `WebIDEUsage` property is used to define the purpose of
116116

117117
### Understanding `WebIDEAdditionalData`
118118

119-
The `WebIDEAdditionalData` property is an optional configuration flag that instructs SAP tooling how to interpret the destination URL. It is only relevant when `WebIDEUsage=odata_gen`it has no effect when using `odata_abap`, which always treats the destination URL as a base host.
119+
The `WebIDEAdditionalData` property is an optional configuration flag that instructs SAP tooling how to interpret the destination URL. It is only relevant when `WebIDEUsage=odata_gen`it has no effect when using `odata_abap`, which always treats the destination URL as a base host.
120120

121121
When set to `full_url`, it tells SAP tooling that the destination URL represents the complete, final service URL, and no additional OData service paths should be appended. When this property is not set, SAP tooling treats the destination URL as a base host and automatically appends the required OData service paths (such as `/sap/opu/odata/...` or `/odata/v2/...`).
122122

@@ -138,6 +138,67 @@ https://api.successfactors.eu/odata/v2/EmpJob
138138

139139
For detailed information about configuring and using `full_url`, see [Using `WebIDEAdditionalData=full_url` for Complete Service URLs](#using-webideadditionaldatafull_url-for-complete-service-urls).
140140

141+
## Authentication Types
142+
143+
The `Authentication` property in an SAP BTP destination controls how the destination service authenticates requests to the back-end system. The value you choose determines what credentials, if any, SAP BTP sends on behalf of the caller.
144+
145+
The most common authentication types for OData services are:
146+
147+
| Authentication Type | What SAP BTP sends | Typical use case |
148+
|---|---|---|
149+
| `NoAuthentication` | Nothing—no credentials attached | Public or open endpoints that do not require caller identity |
150+
| `BasicAuthentication` | A fixed username and password | Systems that accept a shared technical user |
151+
| `PrincipalPropagation` | A short-lived certificate representing the logged-in user | On-premise systems where end-user identity must be forwarded |
152+
| `OAuth2ClientCredentials` | A client ID and secret exchanged for an access token | Cloud APIs using OAuth2 machine-to-machine flows |
153+
| `SAMLAssertion` | A SAML assertion representing the logged-in user | Cloud systems requiring federated identity |
154+
155+
For a full list of supported authentication types, see [HTTP Destinations](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/http-destinations).
156+
157+
### NoAuthentication
158+
159+
`Authentication=NoAuthentication` tells the SAP BTP destination service to forward requests to the back-end system without attaching any credentials. SAP BTP does not add an `Authorization` header, does not exchange tokens, and does not present certificates.
160+
161+
#### When to use NoAuthentication
162+
163+
Use `NoAuthentication` only for endpoints that are intentionally open and do not require caller identity, for example:
164+
165+
- Publicly available OData services (such as the Microsoft Northwind demo service).
166+
- Internal sandbox or mock servers that do not enforce access control.
167+
- Systems where access is controlled entirely at the network layer (for example, IP allowlisting, firewall rules, or VPN) rather than at the application layer.
168+
169+
#### When not to use NoAuthentication
170+
171+
Do not use `NoAuthentication` for:
172+
173+
- Any endpoint that returns user-specific or sensitive data.
174+
- Systems where access should be restricted to authenticated users or specific technical accounts.
175+
- Productive back-end systems: even if the back-end currently accepts unauthenticated requests, using `NoAuthentication` in production removes the ability to audit which caller made a request and makes it trivially easy for any authorized BTP user to query the service without restriction.
176+
177+
#### Security nuance
178+
179+
`NoAuthentication` means **SAP BTP sends no credentials**—it does not mean the back-end system is unprotected. The back-end may still enforce its own access controls:
180+
181+
- Network-level controls: IP allowlists, firewall rules, or Cloud Connector virtual host mappings that restrict which source IPs can reach the service.
182+
- Application-level controls: The back-end system itself may still return HTTP 401 or HTTP 403 if it enforces its own access policy independent of the SAP BTP destination configuration.
183+
184+
If you are receiving unexpected HTTP 401 or HTTP 403 responses when using `NoAuthentication`, the back-end system is enforcing authentication independently of the destination configuration. Switch to the appropriate authentication type (`BasicAuthentication`, `OAuth2ClientCredentials`, or `PrincipalPropagation`) to supply credentials.
185+
186+
#### Destination configuration example
187+
188+
```ini
189+
Type=HTTP
190+
Authentication=NoAuthentication
191+
ProxyType=Internet
192+
URL=https://services.odata.org
193+
Name=northwind
194+
WebIDEEnabled=true
195+
WebIDEUsage=odata_gen
196+
HTML5.DynamicDestination=true
197+
HTML5.Timeout=60000
198+
```
199+
200+
For on-premise destinations using `ProxyType=OnPremise`, see [Choosing an Authentication Type](../onpremise/connectivity.md#choosing-an-authentication-type) for guidance on when `NoAuthentication` is and is not appropriate through the Cloud Connector.
201+
141202
## Using WebIDEAdditionalData=full_url for Complete Service URLs
142203

143204
### Overview
@@ -186,7 +247,7 @@ When using a destination with `full_url`, the service path is already included i
186247

187248
### Use Case Examples
188249

189-
#### Use Case 1: Third-Party OData Service
250+
#### Use case 1: Third-party OData service
190251

191252
You're consuming a specific OData service from an external provider with a fixed endpoint:
192253

@@ -196,7 +257,7 @@ WebIDEAdditionalData=full_url
196257
WebIDEUsage=odata_gen
197258
```
198259

199-
#### Use Case 2: Custom SAP Gateway Service
260+
#### Use case 2: Custom SAP Gateway service
200261

201262
You have a custom OData service deployed on SAP Gateway with a specific path that should not be modified:
202263

@@ -217,7 +278,7 @@ WebIDEUsage=odata_gen
217278

218279
### Overview
219280

220-
When a destination is configured with `WebIDEUsage=odata_abap`, SAP tooling uses the ABAP service catalogs (OData V2 and OData V4) to discover available services. However, there are situations where a required service exists on the back-end system but is not listed in either catalogfor example, because it has not been registered in the catalog, has not been activated in `/IWFND/MAINT_SERVICE`, or requires a Communication Arrangement that has not been set up.
281+
When a destination is configured with `WebIDEUsage=odata_abap`, SAP tooling uses the ABAP service catalogs (OData V2 and OData V4) to discover available services. However, there are situations where a required service exists on the back-end system but is not listed in either catalogfor example, because it has not been registered in the catalog, has not been activated in `/IWFND/MAINT_SERVICE`, or requires a Communication Arrangement that has not been set up.
221282

222283
In these cases, you can bypass catalog discovery entirely and call the service directly by entering the `<destination-name>.dest` URL pattern in the SAP Fiori tools generator or Service Centre:
223284

@@ -236,7 +297,7 @@ Use the `<destination-name>.dest` URL pattern when:
236297
- You want to avoid creating a separate `odata_gen` destination for a single service.
237298
- The service is reachable through the existing destination (authentication and proxy settings are already correct).
238299

239-
This approach works with any destination proxy type`Internet` or `OnPremise`as long as the destination is reachable and the service path is accessible.
300+
This approach works with any destination proxy type`Internet` or `OnPremise`as long as the destination is reachable and the service path is accessible.
240301

241302
### Example: Northwind Destination
242303

@@ -248,7 +309,7 @@ In the SAP Fiori tools generator, select **Connect to an OData Service** as the
248309
https://northwind.dest/V2/Northwind/Northwind.svc/
249310
```
250311

251-
The following screenshot shows the generator with the URL entered. The warning beneath the field"No backend annotations associated with this service were retrieved and may result in an invalid application being created"is expected for services that do not expose OData annotations and does not prevent the application from being generated.
312+
The following screenshot shows the generator with the URL entered. The warning beneath the field"No backend annotations associated with this service were retrieved and may result in an invalid application being created"is expected for services that do not expose OData annotations and does not prevent the application from being generated.
252313

253314
![SAP Fiori tools generator with Connect to an OData Service selected and https://northwind.dest/V2/Northwind/Northwind.svc/ entered in the OData service URL field](odata-service-url.png?raw=true "OData Service URL Field — .dest Pattern")
254315

@@ -270,18 +331,18 @@ The following table summarizes how each part of the URL is handled:
270331
### Important Notes
271332

272333
- The destination must have `HTML5.DynamicDestination=true` set so that the application router can resolve it at runtime.
273-
- The service path you enter must match the exact path the back-end system exposes including case sensitivity.
334+
- The service path you enter must match the exact path the back-end system exposes, including case sensitivity.
274335
- If the service requires authentication, the destination's authentication configuration (for example, `BasicAuthentication`, `SAMLAssertion`, or `PrincipalPropagation`) is applied to the request automatically.
275336
- This approach does not change how the destination is configured in the SAP BTP cockpit. The existing `odata_abap` destination is reused; you are simply addressing the service directly rather than going through catalog discovery.
276337

277338
### Cloning the Destination with `odata_gen`
278339

279340
If you prefer a more permanent solution, you can clone your existing `odata_abap` destination in the SAP BTP cockpit and update `WebIDEUsage` to `odata_gen`. This creates a dedicated destination that bypasses catalog discovery for all services, without affecting your original `odata_abap` destination.
280341

281-
1. In the SAP BTP cockpit, open your subaccount and navigate to **Connectivity** -> **Destinations**.
342+
1. In the SAP BTP cockpit, open your subaccount and navigate to **Connectivity** > **Destinations**.
282343
2. Select your existing `odata_abap` destination and click **Clone**.
283344
3. Give the cloned destination a new name (for example, `mys4hc-destination-gen`).
284-
4. Change `WebIDEUsage` from `odata_abap` to `odata_gen`. Ensure `odata_abap` is fully removed if both values are present, SAP Fiori tools defaults to `odata_abap` and catalog discovery is used instead.
345+
4. Change `WebIDEUsage` from `odata_abap` to `odata_gen`. Ensure `odata_abap` is fully removed: if both values are present, SAP Fiori tools defaults to `odata_abap` and catalog discovery is used instead.
285346
5. Save the destination.
286347

287348
With `WebIDEUsage=odata_gen` and no `odata_abap` present, the SAP Fiori tools generator shows **Connect to a System** as the data source option. Selecting the destination exposes a **Service Path** field where you enter the service path directly. The following screenshot shows the `northwind` destination selected with an empty **Service Path** field ready for input:
@@ -315,7 +376,7 @@ Environment check is a tool used to validate the destination configuration and e
315376
Even if your destination is configured with `odata_gen`, it's still a valid tool to ensure that the destination is reachable and all the required parameters are set correctly. However, if your target system is not an ABAP system, then the OData V2 and OData V4 catalog endpoints fail.
316377

317378
1. Open SAP Business Application Studio.
318-
1. Open the Command Palette (View -> Find Command).
379+
1. Open the Command Palette (**View** > **Find Command**).
319380
1. Enter `Fiori: Open Environment Check`.
320381
1. Click `Check Destination` and choose your destination.
321382
1. Enter credentials, if prompted.
@@ -344,7 +405,7 @@ This typically leads to errors such as:
344405
- **HTTP 404 Not Found** (most common)
345406
- **HTTP 401 and HTTP 403** (when authentication is attempted against an invalid path)
346407

347-
#### Example of an Incorrect Destination URL
408+
#### Example of an incorrect destination URL
348409

349410
If the destination URL is configured as shown in the following URL then SAP Fiori tools or the Service Center automatically appends the required service path for the operation:
350411

@@ -376,7 +437,7 @@ You can use `Dynamic Destinations` to validate your destination configuration ou
376437

377438
**Ensure you are subscribed to [SAP Build Work Zone](https://developers.sap.com/tutorials/cp-portal-cloud-foundry-getting-started.html) to ensure the `dynamic_dest` path is exposed on your SAP BTP subaccount.**
378439

379-
#### Steps to Use Dynamic Destinations
440+
#### Steps to use dynamic destinations
380441

381442
1. Get the name of your SAP BTP subaccount destination configured using SAMLAssertion such as `mys4hc-destination`.
382443
2. Ensure the SAP BTP destination `Additional Properties` contains `HTML5.DynamicDestination: true` and `WebIDEEnabled: true`.
@@ -410,7 +471,7 @@ https://mytrial-account.launchpad.cfapps.us10.hana.ondemand.com/dynamic_dest/mys
410471

411472
When reporting issues or opening support tickets, you must provide diagnostic information to help support teams understand and resolve the issue. The artifacts you need to include depend on the destination configuration:
412473

413-
#### Option 1: Environment Check Report
474+
#### Option 1: Environment Check report
414475

415476
Run the Environment Check tool (as described in the [Environment Check](#environment-check) section above) and **review the generated output carefully**. The Environment Check report can reveal misconfigurations or issues with calling the respective catalog requests (OData V2/V4 catalogs), which may help you identify and resolve the problem without needing to open a support ticket.
416477

@@ -423,7 +484,7 @@ When opening a support ticket, attach the generated zip file. This file includes
423484

424485
The entire zip file must be attached as it provides comprehensive information to diagnose connectivity and configuration issues.
425486

426-
#### Option 2: Network Trace (HAR File)
487+
#### Option 2: Network trace (HAR file)
427488

428489
Include a full network trace (`.har` file) with all requests in the scenario after it was reproduced. This is essential for support teams to understand the flow of API calls and identify the root cause of browser-based issues.
429490

@@ -438,7 +499,7 @@ The `.har` file should be exported from your browser (Chrome, Edge, Firefox, or
438499

439500
This comprehensive trace allows support teams to analyze the complete flow of API calls, identify failed requests, and diagnose connectivity or configuration issues.
440501

441-
#### Option 3: On-Premise Destinations (ProxyType=OnPremise)
502+
#### Option 3: On-premise destinations (ProxyType=OnPremise)
442503

443504
If your destination uses `ProxyType=OnPremise` (Cloud Connector), additional artifacts are required beyond the Environment Check report and HAR file. The Cloud Connector adds another layer between SAP BTP and your back-end system, requiring specific configuration details and logs for proper troubleshooting.
444505

0 commit comments

Comments
 (0)