Knowledge Center
  1. Home
  2. Documentation
  3. Cloud Fax Platform
  4. Fax Tutorials
  5. Building a custom Retarus Cloud Fax connector on SAP® BTP Integration Suite

Building a custom Retarus Cloud Fax connector on SAP® BTP Integration Suite

Creating a custom Retarus Cloud Fax connector on SAP BTP Integration Suite brings a multitude of benefits to fax communication automation and simplification. This connector seamlessly integrates into the SAP environment, enabling centralized administration of fax-related operations. In addition to improving operational efficiency, it guarantees increased data security, scalability, and flexibility. This solution ensures regulatory compliance, synchronizes fax data in real time, and provides extensive reporting.

Overview

To incorporate Retarus Enterprise Cloud products into the SAP BTP tenant environment, two key components are required:

  • Access to Retarus Cloud Fax
    To gain access, create and instantiate a custom connector for Retarus Cloud Fax. As a result, an SAP-native cloud URL will be provisioned, enabling access to Retarus Cloud Fax directly from within SAP. This tutorial provides step-by-step instructions on how to set up the connector.

  • Integration of web service methods
    The main purpose of the integration is to transform SAP content into the required Retarus Cloud Fax REST API request headers, properties, and JSON payload for job transmission. This tutorial does not go into detail on the integration process.

Tip: To become familiar with the Retarus Cloud Fax REST API, launch the Swagger UI and run some tests (the login ID, username, and password for Retarus Cloud Fax are required).

Prerequisites

SAP BTP

  • The SAP BTP cloud tenant ID and the password (also referred to as cloud secret) are available. When gaining access to an active instance of the integration solution, they are required to set up basic authentication. The essential information can be found in the API documentation’s curl statements. The service instance can be accessed using the unique SAP cloud URL provisioned within the operating service instance.

  • SAP BTP (Business Technology Platform) is operational.

  • SAP BTP Integration Suite is operational and has the following enabled capabilities:

    • Open Connectors
    • Cloud Integration (optional)
    • API Management (optional)

Retarus

  • For Retarus Cloud Fax, an active Retarus test agreement, proof of concept (PoC), or contract must already be in place and activated through a customer or developer account.
    If a test agreement is required, fill out the contact form or speak with a Retarus representative.

  • Account credentials (also known as “Login ID”) with a username and password.

Each Retarus customer typically has a single primary identifier for all booked services - the customer number. Multiple login IDs can be created for the same customer number (or tenant). This makes it possible to create different processing configurations to accommodate different people, departments, or purposes.

Building a custom Retarus Cloud Fax connector 

Importing an API specification

The required actions are described “from scratch,” but SAP may provide pre-built packages or artifacts that include the connector and the integration flow for download.

  1. Open the SAP Integration Suite Home page, and scroll down to the Capabilities section.

  2. Under Extend Non-SAP Connectivity, select Discover Connectors.

     

  3. Navigate to the Connectors page, and select Build New Connector.

     

  4. Select Import.
    Retarus Cloud Fax (REST) comes with a defined Swagger/OpenAPI specification. This specification can be used to make the service and its methods available within SAP easily and with minimal effort.

     

  5. Select Swagger:

     

  6. Go to the Faxolution for Application REST API page and copy the URL of the JSON file located just below the headline.

     

  7. Navigate to the Import from URL field, enter the copied URL, and select Continue import in the upper right corner.

     

  8. Select Continue import in the upper right corner.

  9. The REST resource selector is displayed. Select all resources that you want to be accessible using the connector. This option can be used to hide ‘out of scope’ REST resources from SAP users, without modifying the service itself.

 

  1. Select the Import button in the lower right corner.
    The connector configuration page with the Setup tab opens.

     

  2. If the base URL for Retarus Cloud Fax isn’t automatically imported from the API definition, enter it manually - https://faxws.retarus.com/rest/v1 .
    Keep the other fields in the Properties section at their default settings.

  3. Select basic as the authentication method.
    Two new fields for entering a user name and a password appear. It is not necessary to provide the username and password in this step. These details can be entered while starting a running instance of the connector, which is described in the following section.

     

  4. Select Save.

Additional information, such as a specific name for the new connector, can be included in the Information tab. To apply any updates, select Save & Next in the upper right corner.

 

Starting a connector instance

Now, the new connector should be turned into a working instance. As a result, it will become available via a SAP-native cloud URL with REST resource suffixes.

  1. On the Integration Suite - Connectors page, select Create Instance.

     

    The connector search widget opens.

  2. Search for and select the previously created connector.

     

    After choosing the connector, an instance initialization dialog appears.

     

  3. Enter the following information:

    • Name: The name of the currently running instance, which will be displayed in the instance overview later.

    • Username and Password: The Retarus Cloud Fax login ID credentials obtained from Retarus.

  4. Select Create Instance at the bottom of the page.

    The connector should now be instantiated and running.

     

  5. Select Test in the API docs to test the connector instance.
    The blue box indicates the currently selected and authenticated instance.

     

Verifying the connector’s connection

  1. Click on the POST method to open it.

     

  2. Select Try it out.

     

    Upon clicking, the body field will become editable, indicated by its background color changing to white.

  3. Enter the customer number provided by Retarus.

 

  1. For a quick and straightforward functional test, clear everything from the body field and paste the following code.

    Make sure to replace the personalization parameters inside <…> with your specific details, and remove the <>.

    {
    "reference": {
        "customerDefinedId": "<Your Company Name>",
        "billingCode": "<Your Billing Code>",
        "billingInfo": "<Your Billing Info>"
    },
    "recipients": [
        {
            "number": "<Your Destination Number>",
            "properties": [
                {
                    "key": "string",
                    "value": "string"
                }
            ]
        }
    ],
    "documents": [
        {
            "name": "attachment.txt",
            "charset": "UTF-8",
            "data": "UmV0YXJ1cyBDbG91ZCBGYXggU2VydmljZS4gDQpUZXN0IGF0dGFjaG1lbnQuDQoNCkhhdmUgYSBuaWNlIGRheQ=="
        }
    ],
    "meta": {
        "customerReference": "<Your Customer Number>",
        "jobValid": {
            "start": null,
            "end": null
        }
    },
    "renderingOptions": {
        "paperFormat": "A4",
        "resolution": "HIGH",
        "header": "%tz=CEST Testfax: CSID: %C Recipient Number: %# Date: %d.%m.%Y"
    },
    "transportOptions": {
        "csid": "<Your CSID>"
    },
    "statusReportOptions": {
        "reportPurgeTs": "2023-11-03T20:14:37.098+02:00",
        "reportMail": {
            "successAddress": "<Your email address>",
            "failureAddress": "<Your email address>",
            "attachedFaxImageMode": "SUCCESS_ONLY",
            "attachedFaxImageFormat": "TIFF"
        }
    }
}

  2. Select Execute to send the job to Retarus Cloud Fax.

     

    If the operation is successful, an OK/200 response is shown, along with the Retarus Cloud Fax job ID. Additionally, an email is sent to the specified mailbox.

  3. Select Cancel to end the test.

The connector is now up and running and can be used by other integration consumers.

Tips

Tip 1

In the response area, pay attention to the Curl section:

 

It displays the complete curl command that can be used in a DOS shell to send the job to Retarus. This section contains information valuable for future integrations. It is highly recommended to copy and safely store the following information:

  • SAP endpoint right after the POST command. It looks similar to https://api.openconnectors.eu10.ext.hana.ondemand.com/…. This endpoint is designated for SAP users who have permission to use this instance of the Retarus Cloud Fax connector. Any jobs that are sent in the correct format to this endpoint are directly forwarded through the Fax connector to Retarus Cloud Fax.

  • User, Organization, and Element strings, as these are required to create the SAP credentials for using this connector in other SAP integrations (e.g., integration flows).

Note: Copy the jobId from the response body to retrieve the report for this job using the /{cuNo}/fax/reports/{jobId} resource.

Tip 2

All Fax features and options available in the default body during the test can be found in the corresponding Retarus documentation in the EAS portal.

If any concerns or issues arise, contact Retarus support and request assistance from an integration expert.

← Developer Documentation
Cloud Fax - How to receive faxes in a Microsoft Teams channel →