SAP: Cloud Fax connector on BTP Integration Suite

→ Open the SAP Integration Suite Home page and scroll to the Capabilities section.

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

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

→ Select Import.

→ Select Swagger.

→ Specify the path to the OpenAPI specification file:

• Go to the Fax-for-Applications REST API page and copy the JSON file URL below the headline.
  

  

• Go back to SAP Integration Suite, navigate to the Import from URL field, and paste the copied URL.

• Select Continue Import.

→ Choose resources for the connector:

• Use this option to hide ‘out of scope’ REST resources from SAP users, without modifying the service itself.

• In this example, select the Select All Resources checkbox.

• Select Import in the lower right corner.

  

• Enter the Base URL: https://faxws.retarus.com/rest/v1.

• Choose basic as the authentication method. This authentication requires the username (also known as login ID) and password.

• Select Save.

• The username and password are not necessary in this step. These details can be entered while starting a running instance of the connector, as described below.

• The connector can be enhanced in the Information tab by giving it a meaningful name, such as the raw service name and protocol, and adding a brief description of the service.

→ On the Connectors page, select Create Instance to open the connector search widget.

→ Search for and select the previously created connector.

→ In the instance initialization dialog:

• Type the name of the currently running instance that will be displayed in the instance overview later.

• Enter the Retarus Cloud Fax login ID credentials obtained from Retarus.

• Select Create Instance.

The connector is now instantiated and running.

→ Select Test in the API docs to test the connector instance.

→ Click on the POST method to open it.

→ Select Try it out.

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

→ Enter the customer number provided by Retarus.

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

{
    "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"
        }
    }
}

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

→ 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.

→ Select Cancel to end the test.

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).

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

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.