Skip to content

Destination

Retrieve information about destinations in the Cloud Foundry environment.

The Destination service lets you retrieve the backend destination details you need to configure applications in the Cloud Foundry environment.

How to get started?

Read relevant SAP BTP Connectivity Help or find additional information inside the SAP Cloud SDK Connectivity Destination.

Configuration

A destination defines the back-end connectivity. In its simplest form, a destination is a URL to which requests are forwarded. There must be a destination for every single app (microservice) that is a part of the business application.

Destination configuration is provided by destination service.

Mandatory Properties

When you configure the mandatory properties of a destination, note the following guidelines:

PropertyDescription
TypeOnly HTTP is supported.
AuthenticationAll authentication types are supported.
  • When using basic authentication, User and Password are mandatory.
  • When using principal propagation, the proxy type is on-premise.
  • When using OAuth2SAMLBearerAssertion, the uaa.user scope in the xs-security.json file is required.
ProxyTypeSupported types:
  • on-premise (if set, binding to SAP BTP connectivity service is required)
  • internet

Additional Properties

When you configure additional properties of a destination, note the following guidelines:

PropertyDescription
HTML5.ForwardAuthTokenThis token contains the user identity, scopes, and other attributes. It’s signed by the UAA so it can be used for user authentication and authorization with back-end services.

If true, the OAuth token is sent to the destination. The default value is false.
  • If the ProxyType is set to on-premise, don’t set the ForwardAuthToken property to true.
  • If the Authentication is other than NoAuthentication, don’t set the ForwardAuthToken property to true.
HTML5.TimeoutPositive integer representing the maximum time to wait for a response (in milliseconds) from the destination. The default value is 30000 ms. If you have a backend application that performs complex and time consuming processing, it is recommended to configure a destination timeout of at least 120000 ms to avoid potential timeouts in case of network slowness.
HTML5.PreserveHostHeaderhis is expected by some back-end systems like AS ABAP, which don’t process x-forwarded-* headers.

If true, the managed application router preserves the host header in the back-end request.
HTML5.DynamicDestinationIf true, the managed application router allows this destination to be used dynamically on the host or path level.
HTML5.SetXForwardedHeadersIf true, the managed application router adds X-Forwarded-(Host, Path, Proto) headers to the back-end request.

The default value is true.
sap-clientThis is expected by ABAP back-end systems.

If true, the managed application router propagates the sap-client and its value as a header in the back-end request.
URL.headers.HEADER_KEYUse additional static headers.
URL.queries.QUERY_KEYUse additional static query parameters.

Hidden from UI

Some properties have a special meaning and are hidden in the UI and only displayed by an asterisk *****, furthermore these properties are not included in the destination export.

Therefore, these properties can also be used to store sensitive information that should not be accessible through the user interface, but only through the destination service. In some cases these can be used as an alternative to environment variables.

PropertyDescription
apiKeyNo meaning for Authentication type NoAuthentication or BasicAuthentication.
URL.headers.authorizationIf declared, this property will always be added to the request as a header field!

This is not intended to be a replacement for the SAP Credential Store!

SAP Credential Store service provides a repository for passwords, keys and keyrings for applications that are running on SAP BTP. It enables the applications to retrieve credentials and use them for authentication to external services.

Create Destinations using the MTA Descriptor

When modeling a Multitarget Application (MTA), you are able to create and update destinations from your MTA descriptor.

Using it this way, you can configure Content Deployment to automate and deploying content to services without the need for an application-specific deployer.

Cross-MTA CAP service api consumption

If you want to decouple and split huge MTAs in multiple modules, you can use Cross-MTA Dependencies.

Another possibility is to create a destination for your CAP service API, that can be used from a custom SAPUI5 app.

While deploying your CAP app, a destination will be automatically created pointing out to the CAP service API.

mta.yaml

yaml
modules:
  - name: YOUR_CAP_SERVICE
    type: nodejs
    path: gen/srv
    parameters:
      buildpack: nodejs_buildpack      
    requires:
      - name: YOUR_SERVICE_xsuaa
      - name: YOUR_SERVICE_destination
#     - name: YOUR_SERVICE_connectivity # if you need on-premise support
    provides:
      - name: srv-api # required by consumers of CAP services (e.g. approuter)
        properties:
          srv-url: ${default-url}
# ... additional modules like a custom HTML5 app
resources:
  - name: YOUR_SERVICE_xsuaa    
    # reference existing service instance from approuter
    type: org.cloudfoundry.existing-service 
    parameters:
      service-plan: application
      service: xsuaa
  - name: YOUR_SERVICE_destination
    # reference existing service instance from approuter
    type: org.cloudfoundry.existing-service  
    requires: 
      - name: srv-api
    parameters:
      service: destination
      service-plan: lite
      config:
        init_data:
          subaccount:
            existing_destinations_policy: update
            destinations:
              - Name: YOUR_CAP_SERVICE_DEST_NAME
                Description: Authenticated CAP service with forwarded JWT
                Authentication: NoAuthentication
                ProxyType: Internet
                Type: HTTP
                URL: ~{srv-api/srv-url}
                HTML5.DynamicDestination: true
                HTML5.ForwardAuthToken: true
# - name: YOUR_SERVICE_connectivity # if you need on-premise support

xs-app.json

Usage of the CAP destination inside SAPUI5 route config:

json
{
    "welcomeFile": "index.html",
    "authenticationMethod": "route",
    "routes": [
		{
			"source": "^/cap/(.*)$",
			"target": "$1",
			"destination": "YOUR_CAP_SERVICE_DEST_NAME",
			"csrfProtection": true
		},
        {
            "source": "^(.*)",
            "target": "$1",
            "service": "html5-apps-repo-rt"
        }
    ]
}

Using AppRouter

This example uses the CAP service behind the HTML5-APP-REPO.

If you want to make the CAP service public available, you can also add the route to the xs-app.json config of your approuter!

manifest.json

Usage of the CAP destination inside SAPUI5 component:

json
{
    "sap.app": {
        "dataSources": {
            "mainService": {
                ...
                "uri": "cap/my-service/",
                "type": "OData",
                "settings": {
                    "odataVersion": "2.0"
                }
            }
        }
    }
}

Relative Usage

This example uses the CAP service behind the HTML5-APP-REPO, so the uri must be service relative and will be called behind html5-apps-repo-rt.

If you want to use the AppRouter instead, use an absolute uri: "/cap/my-service/"

Support

Component NameComponent Description
BC-CP-DEST-CFSupport component for this service