How to setup an SMS Connector with SAP BTP Open Connectors
About this document
This document outlines the prerequisites and necessary steps to connect Retarus Enterprise SMS with SAP BTP – Business Technology Platform. The connection allows further integration of customer SAP application and processes with retarus cloud messaging services. The integration process is demonstrated by using the transactional retarus service SMS4Applications (REST) - in general the approach is also applicable for other retarus services, like Retarus Cloud Fax or Transactional Email which offer also REST APIs.
This document describes a REST-based service connection, while SOAP, SMTP and other protocol bridges are also possible.
While the SAP ecosystem as a whole offers a multitude of options for solution integration, this document will focus on using the SAP Business Technology Platform (BTP) - Integration Suite, utilizing the contained “Cloud Integration” and “Open Connector” capabilities eventually.
Background
To integrate a retarus enterprise cloud service like Enterprise SMS (SMS4Applications, REST API) with the SAP BTP tenant environment, two main things have to established:
Make the SMS4Applications service available. For this, we will create and instanciating a custom ‘OpenConnector’ against the retarus service. The result of this step is the provisioning of an SAP-native cloud URL, to access the service from within SAP. To guide through the steps to setup this connector is the scope of this document.
The integration of the provided webservice methods. As result, sending SMS jobs and retrieving status data becomes very easy and standardized. The main function of the integration is to convert SAP-originated content into the required SMS4Application-REST request headers, properties and JSON payload for the actual job transmission. The integration part is out of scope in this document and is part of a subsequent document
Just as a tip, to become familiar with the service, open the swagger UI at https://developers.retarus.com and try out the service right away (in case SMS4Application Login-ID username and password credentials were available).
Prerequisites
SAP
To start building the outlined solution, following SAP-sided prerequisites are required:
- SAP BTP - Business Technology Platform up and running
- SAP BTP - Integration Suite up and running, with enabled capabilities
- Open Connectors
- Cloud Integration (optional)
- API Management (optional)
The service instance is reachable via the unique SAP cloud URI, which is provisioned (and can be found) at the instantiated running service instance.
Retarus
- A Retarus testagreement, PoC or contract is already in place for SMS4Application and activated though a customer account. If you need a testagreement please contact your retarus representative or fill out the contact sheet.
- Account credentials already provided (also called “Login-ID”) with username and password..
- Service account credentials (also called Login-ID) with Username and password are provisioned and available.
Please Note: usually each retarus customer operates all booked services under one main identifier, the customer number. Inside each customer number, an arbitrary numbers of Login-IDs for each booked service can be created, to allow different processing configurations for different personas, departments or purposes.
SAP BTP OpenConnector setup for SMS for Applications (REST)
Import API Specification
Note: We explain the necessary steps with a “from scratch” perspective, but readily assembled artefacts or packages for the OpenConnector and the Integration flow may be available for download from retarus or SAP.
To start, we access the SAP BTP Integration Suite home and select “Open Connectors”
On the OpenConnector page, select “Build new connector”
The SMS for Applications (REST) service comes with a defined swagger/OpenAPI definition, so we will use this option to make the service and its methods available in SAP with almost no effort.
To do so, select ‘Import’:
Select „Swagger“
IMPORTANT NOTE: As of time of last update of this document, the SAP OpenConnector specification importer on one hand supports the OAS3 standard semantically, but on the other hand (still) expects JSON as spec format for the import, instead of the YAML format, which is more typical for OAS specs.
It can be assumed that SAP will close this gap and support OAS3/YAML spec imports as well rather soon, but until then, an equivalent JSON-file of the OAS3-spec is required.
This file can be provided by retarus on demand, or can be generated using the public available swagger.io tools to load the regular Faxolution YAML spec, and export back to JSON.
As consequence of the afore mentioned, for now, we will upload the converted OAS JSON-file file manually, instead of using an URL reference.
The latest retarus YAML OAS3 spec for Faxolution for Applications (REST) can be found here .
Please select CONTINUE IMPORT in the upper right corner.
If anything works fine, a REST resource selector is displayed. Select all resources which shall be available in the OpenConnector. This selection option is very helpful to hide ‘out of scope’ REST resources for the SAP users, without the need to touch the service itself.
- We will proceed with all provided methods, so check Select All Resources
- Select the “Import” button in the lower right corner. You will get directed to the Connector configuration page, starting in tab “Setup”
- Enter the Base URL for the retarus service, in this case https://sms4a.retarus.com/
- Choose ‘basic’ as authentication method. This authentication expects the username (also called Login-ID in retarus wording) and password.
- Select “SAVE”
Note: You don’t have to provide username and password at this point. This can be done when starting an actually running instance of the connector. We will cover this in the next chapter.
Starting a service instance
We will instantiate our new connector into a running service, i.e. a service that is accessible by using an SAP-native cloud URL plus the REST service resource suffixes.
One way to instantiate the connector is to choose Create Instances in the main menu of the Integration Suite – Connectors page:
A search widget is opened. Search and select your previously created connector
After selection, an instance initializing dialogue is displayed.
Here, the following information have to be provided:
- “Name” – the name of the running instance, to be displayed as such in the instance overview later on
- “Username” / “Password”: the retarus SMS4A Login-ID credentials, which you have obtained from retarus in advance.
Please select “Create Instance”
Your connector is now instantiated and running.
An overview page is shown, where you can, for instance, select “Test in the API docs” and try your (now authenticated) connector instance. The currently selected and authenticated instance is indicated in the blue box:
Verify the OpenConnector connectivity
At first, visit the API-DOCs and go to the GET /rest/v1/version-resource.
Select Try it out and then Execute. You should receive a successful (code 200) response with service version details as response payload.
Then go to the POST /rest/v1/jobs resource. Select “Try it out”.
In the Edit Value-Field, paste in a minimalistic test job like the one below, using a test mobile phone number, and select “Execute”
{"messages":[{"text": "Hello World!", "recipients":[{"dst": "+49160xxxxxxxxxx"}]}]}
If anything works as expected, you should..
- receive an OK/200 response with the retarus SMS Job-ID
- receive the actual SMS on your phone.
Congrats, now the OpenConnector is up and running, and ready to be utilized by other integration consumers!
TIP: All options which are available in the API Docs provided with the SMS for Applications REST service are also explained in the related retarus documentation in the EAS portal.
In case of questions or problems please get in touch with your retarus representative. Our integration experts will happily assist on your integration journey.