Technical Articles
How to create destination in SAP Cloud Platform Cockpit and types we support in SAP Leonardo IoT Action
In this blog post, I would like to share how to create destinations in SAP Cloud Platform and examples of different types that we support in SAP Leonardo IoT actions in detail.
Actions of type Service Integration and In-App Notification in SAP Leonardo IoT uses destinations defined in the SAP Cloud Platform cockpit.
- For actions of type Service Integration, destinations contain the URL and credentials of (backend) systems which are the targets of these actions.
- For actions of type In-App Notification, destinations contain URL and credentials of 3rd party notification servers (e.g. the notification server of a SAP S/4 HANA on-premise system). Having destinations for this kind of action are optional since the built-in notification server is the default notification server and can be used without having any destination.
How to create destinations
Destinations can be created in two different ways:
- In the SAP cloud platform cockpit, within the menu on the left, Connectivity→ Destinations → New Destination (certain roles / permissions are needed to create a destination from the UI)
or via
- SAP cloud platform Destination Service API via HTTP POST request to https://destination-configuration.cfapps.sap.hana.ondemand.com/destination-configuration/v1/subaccountDestinations (a bearer token is required as authentication)
Supported Destination Type and Authentication mechanisms
Destinations have to be of type HTTP and following Authentication types are supported:
- NoAuthentication
- BasicAuthentication
- OAuth2ClientCredentials (Client Credentialsand Password grant types are supported)
- OAuth2UserTokenExchange (Client Credentialsgrant is used, token is not exchanged as of 4/1/2019)
Supported Destination Proxy Types
Destinations can describe Cloud systems (reached via public internet) or On-Premise systems (reached via cloud connector). Depending on the location of the destination the proxy type has to defined accordingly:
- Internet
- OnPremise
Supported Destination URLs
Destinations of type HTTP need to have a URL. The URL can have tokens which are being replaced with actual values during the execution of an action. Those tokens are optional. Since destinations are defined outside of the Action Modeler UI, there is no value help available for those tokens. The token format is still the same however as what you would see in Action UI: ${token.name}. An example with the thing id, name and type tokens in an URL may look like this:
https://www.sap.com/do/${thing.type}/something?thingid=${thing.id}&thingname=${thing.name}
Supported Destination Names
The destination name shall not contain any whitespace of special characters except underscores “_” and dashes “–“. This restrictions is enforced in the destination service UI but not in the API. However, refrain from using those unsupported characters (e.g. spaces ” ” via API).
Destinations with HTTP headers
HTTP Headers can be defined using (additional) destination properties. In the destination service UI a property can be added by clicking the New Property button. The left field being the property name, the right being the property value.
Properties can also be defined via the destination service API.
To be used as a HTTP Header, the property has to have the prefix sap.iot.header. (including the last dot) followed by the name of the actual header variable. Examples would be sap.iot.header.X-Client-Version or sap.iot.header.X-Client-ID
Destinations for endpoints which require a CRSF token
SAP backend systems are often requiring a CRSF token, that’s true for ERP systems but also for CPI. This protection can (often) be disabled but in case this is not appropriate or possible, the destination definition can be enhanced to indicate to the Action execution framework that CRSF need retrieved and added.
Following property is needed to enable CRSF Token:
- sap.iot.XcsrfURL with the value of the URL which returns the CRSF token. This is often the same URL as the actual URL of the endpoint
Destinations for endpoints which require a ETAG token
In addition to CRSF token, Action execution framework also supports ETAG.
Following property is needed to enable ETAG Token:
- sap.iot.etagURL with the value of the URL which returns the ETAG token. This is often the same URL as the actual URL of the endpoint
Destinations for endpoints with a self-signed certificate
Although not considered secure, there might be a need to use the action framework to connect to systems which are using self-signed certificates (e.g. demo or development systems).
The property sap.iot.certificationEnabled with the value false can used in a destination to indicate that the certificate check should not apply for this destination.
Destinations defining a 3rd party notification server
Although of type HTTP destination, the destinations will not appear and cannot be used for Actions of type HTTP but are rather be used for Actions of type In-App Notifications and represent another choice of notification server. Those destinations will probably rarely be used.
An (additional) destination property with the name sap.notification_server with the value true indicates that the destination is used for a notification server instead of being an endpoint of a (backend) system.
Examples for destinations
Destination with OAuth 2.0 Password grant + two HTTP Header variables:
Destination with Basic Authentication (e.g. for use with CPI):
Destination for on-premise 3rd party Notification Server:
Destination with OAuth 2.0 Client Credentials grant (e.g. used for calling SAP Leonardo IoT APIs):
Destination with OAuth 2.0 Client Credentials grant and URL tokens:
Destination with No Authentication (or payload based authentication):
Destination with CRSF token support:
Summary
As you can see from examples of destinations outlined in this blog post, SAP Leonardo IoT support multiple types of authentication method as well as tokens for robust service integration.
Hi Kim,
It's nice sharing. Would you kindly share the sample destination configuration for Ariba open api?
I noticed that in Cloud Platform help portal in "Extension of Ariba" guide, it's referring to use apiKey when creating the http destination on cloud platform, however, I don't see this input field on Cloud Platform neo environment.
Using Sandbox Environment
https://help.sap.com/viewer/f4204795aea64e909c53dc85a8030fdc/Cloud/en-US/81ddfa57e10247899bd49db49b12c9a4.html
Above is the URL of the CP help portal I was referring.
BR
Yanbing
Hi Yanbing,
I don't think apiKey is a standard field in a Cloud Platform destination. Did you try to add apiKey as property to the destination?
Should this not work, please send feedback about the documentation or open a support ticket.
Regards,
Frank
Hi there Daniel,
I have been trying to trigger an ODATA call on an S/4Hana system using an action.
I created a destination with the following settings
i know that the endpoint works because i can acces it with my approuter and i get data i am also able to post do that endpoint.
However whenever i try to post data using an action i get the error (iot.actions.error.121 - Call to external endpoint failed).
I then tryed to make a call to a system that is available over the internet (no Cloud connector) and that works fine.
So...
Proxy type "Internet" works
Proxy type "On-premise" does NOT
(i even deactivated the x-csrf-token check in order to make sure that was not the problem.)
I then went on to activate the payload trace in my cloud connector. And the requests (when triggered my the iot actions) where not arriving in the cloud connector.
The requests (using the very same destination) where being sent to the cloud connector and do my SAP system.
All that to say the iot actions service intergration seems to have issues with On-Premise systems. Or i am doing something wrong. I would be very greatful for any help.
King Regards
David Sooter