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:

Property	Description
Type	Only HTTP is supported.
Authentication	All 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.
ProxyType	Supported 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:

Property	Description
HTML5.ForwardAuthToken	This 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.Timeout	Positive 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.PreserveHostHeader	his 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.DynamicDestination	If true, the managed application router allows this destination to be used dynamically on the host or path level.
HTML5.SetXForwardedHeaders	If true, the managed application router adds X-Forwarded-(Host, Path, Proto) headers to the back-end request. The default value is true.
sap-client	This 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_KEY	Use additional static headers.
URL.queries.QUERY_KEY	Use 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.

Property	Description
apiKey	No meaning for Authentication type `NoAuthentication` or `BasicAuthentication`.
URL.headers.authorization	If 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 Name	Component Description
BC-CP-DEST-CF	Support component for this service

Destination ​

Configuration ​

Mandatory Properties ​

Additional Properties ​

Hidden from UI ​

Create Destinations using the MTA Descriptor ​

Cross-MTA CAP service api consumption ​

mta.yaml ​

xs-app.json ​

manifest.json ​

Support ​