Setting Up Retarus Cloud Fax App for Salesforce

The Retarus Cloud Fax App for Salesforce lets you send fax campaigns and single faxes directly in Salesforce. Setup includes installing the package, activating the app, configuring authentication and credentials, assigning permissions, and setting up fax features for your users.

Prerequisites

Before you begin, make sure you have:

• Salesforce administrator access

• Retarus Fax-for-Applications API credentials, including Reporting WebPush OAuth credentials

• Lightning Web Security (LWS) enabled in Salesforce
  If LWS is not enabled, creating and sending faxes through the single fax component may not work.

Installing the app

1. Open the installation link provided by Retarus.

2. Log in with your Salesforce credentials.

3. Choose the installation scope, such as Install for Admins Only or Install for All Users.

4. Select this option:
   I acknowledge that I’m installing a Non-Salesforce Application that is not authorized for distribution as part of Salesforce’s AppExchange Partner Program.

5. Complete the installation and wait for it to finish.

Activating the app

1. Go to Setup - Lightning App Builder.

2. Find Fax Campaign Management and click Edit.

3. Click Activation.

4. Choose whether to activate the app for administrators only or for all users, based on your rollout plan.

5. Save your changes.

5. Verify that the app appears in the App Launcher.

Creating the External Client App

Create an External Client App in Salesforce so Retarus can send fax status updates back to your Salesforce organization.

During setup, assign an integration user to this app. Retarus uses this user identity when it updates fax jobs and fax campaigns in Salesforce. Assign the Cloud Fax Integration User permission set to the integration user before you continue.

Create and configure the app

1. Go to Setup - External Client App Manager, then select New External Client App.

2. Enter the basic app details:

   • External Client App Name
     Enter a name that helps you identify the app.

   • API Name
     Salesforce generates this automatically from the app name.

   • Contact Email
     Enter any valid email address.

   • Distribution State
     Select Local.

3. Leave the other basic fields unchanged unless your organization requires different values.

4. In API (Enable OAuth Settings), select Enable OAuth.

5. Enter a Callback URL that starts with https://.

   Salesforce requires this value, but the Retarus integration does not use it.

6. In OAuth Scopes, select Manage user data via APIs (api).

7. In Flow Enablement, enable Client Credentials Flow and confirm the prompt.

8. Leave all remaining settings unchanged.

9. Select Create.

Assign the integration user

1. Open the Policies tab of the new app.

2. Select Edit.

3. Expand OAuth Policies.

4. Make sure Enable Client Credentials Flow is selected.

5. In Run As, enter the username of the integration user.

6. Save your changes.

Get the client ID and client secret

1. Open the Settings tab.

2. Expand OAuth Settings.

3. Select Consumer Key and Secret.

4. Confirm your identity if prompted.
   -> Salesforce then displays the Consumer Key and Consumer Secret, which you use later as the client ID and client secret.

Information to provide to Retarus

During implementation, provide the following information to the Retarus implementation team so they can set up Push Reporting for fax status updates.

Configuring Retarus credentials

To allow Salesforce to send fax data to Retarus, store your Retarus Fax API credentials in Salesforce.

Update the named credential

1. Go to Setup - Named Credentials.

2. Open Retarus API Credentials and select Edit.

3. In the URL field, replace CUSTOMERNUMBER with your Retarus customer number.

4. Save your changes.

Update the external credential

1. Go to Setup - Named Credentials - External Credentials.

2. Open Retarus Integration.

3. In the Principals list, open Auth and select Edit.

4. Add these parameters exactly as shown:

   • username
     Your Retarus API username.

   • password
     Your Retarus API password.

   • clientID
     The client ID from the External Client App setup.

   • clientSecret
     The client secret from the External Client App setup.

5. Save your changes.

Assigning permissions to users

To use Cloud Fax features in Salesforce, assign the Cloud Fax User permission set to each user who should send fax campaigns or single faxes.

1. Go to Setup - Permission Sets.

2. Open Cloud Fax User.

3. Select Manage Assignments.

4. Add the users who should use Cloud Fax features.

Additional permissions for fax campaigns

Users who send fax campaigns also need these additional Salesforce permissions. Salesforce does not allow managed packages to include these permissions in a packaged permission set.

Without these permissions, fax campaign sending may not work as expected.

Single fax setup

You can use the single fax feature on any Lightning Record Page for standard or custom Salesforce objects.

Add the single fax component to a record page

1. Open a Lightning Record Page in Lightning App Builder.

2. In the component list, find Retarus Cloud Fax Management under Custom - Managed.

3. Drag the component to the page.

4. Save and activate the page as needed.

Configure default values

After you add the component, you can configure default values to simplify fax creation:

• Whether a cover page is selected by default.

• Which value prefills the recipient fax number.

• Which values prefill the cover page fields.

Prefilling is optional.

Supported prefill methods

You can prefill fields in these ways:

You can also reference custom relationship fields. Use the relationship API name with __r where required.

Prefill behavior

• The value used to prefill the recipient fax number also prefills Cover Page - To Fax.

• If a user does not have access to a referenced field, Salesforce does not prefill it.

• If a referenced field does not exist or the reference is entered incorrectly, Salesforce does not prefill it.

• If you need more advanced logic, create a custom formula field and use that value for prefilling.

Related lists

Cloud Fax Job includes lookup fields for:

• Account

• Contact

• Lead

• Case

• Opportunity

When you use the Retarus Cloud Fax Management component on a Lightning Record Page for one of these objects, Salesforce automatically fills the matching source lookup field when it creates a Cloud Fax Job. This lets you add related lists for Cloud Fax Jobs to those record pages.

Data model overview

The Retarus Cloud Fax App for Salesforce uses two custom objects:

This data model applies to all faxes, including single faxes. For a single fax, the campaign usually includes only one related Cloud Fax Job.

When Salesforce sends fax data to Retarus:

• It sends a Cloud Fax Campaign with attached documents.

• It includes all related Cloud Fax Jobs in Draft status.

• The status changes to In Progress after sending starts.

After sending, users should generally not change the related records. This helps prevent inconsistencies between Salesforce and Retarus. Validation rules protect Cloud Fax Jobs in particular.

Sending through Flows or Apex

You can send a Cloud Fax Campaign by using the invocable action Send Cloud Fax Campaign from Salesforce Flows or Apex.

Input and output

What the action does

When Send Cloud Fax Campaign runs, Salesforce:

1. Validates the campaign data.

2. Builds and sends the request to the Retarus Fax API.

3. Updates statuses if successful.

4. Stores the Retarus Job ID on the campaign record.

Validation rules

Before Salesforce sends a Cloud Fax Campaign to Retarus, these conditions must be met:

• At least one supported document is attached.

• At least one related Cloud Fax Job is in Draft status. Only Draft Cloud Fax Jobs are sent.

Supported file types:

Limitations

Create records outside the user interface

If you create Cloud Fax Campaign or Cloud Fax Job records outside the packaged UI, make sure they follow the expected data model. This applies to custom Flows, Apex, data imports, and other custom integrations.

Required setup for new records

• A Cloud Fax Campaign must have at least one supported document attached.

• A Cloud Fax Job must be related to a parent Cloud Fax Campaign.

• A Cloud Fax Job must contain the required recipient data.

• New Cloud Fax Job records must be created with Draft status.

• Attach the documents to the Cloud Fax Campaign before sending.

Cloud Fax Campaign fields

Source values for Cloud Fax Campaign

Cloud Fax Job fields

Cover page fields can usually contain any text values. Avoid HTML tags in these fields, because they can cause unexpected formatting on the generated cover page.

Source lookup fields on Cloud Fax Job

Cloud Fax Job also includes lookup fields for Account, Contact, Lead, Case, and Opportunity. Use these fields when you want related Cloud Fax Jobs to appear in related lists on those standard object record pages.

Error handling when sending fax campaigns

If a fax campaign stays in In Progress for an extended period, an error likely occurred while Salesforce was sending data to Retarus.

Common causes

• The user who selected Send Fax Jobs does not have the Cloud Fax User permission set.

• Credentials in the Named Credential or External Credential are incorrect.

After you correct the issue, reset the campaign status to Draft before sending again.

Further troubleshooting

1. Open the Developer Console, or enable debug logs for the affected user.

2. Reset the fax campaign status to Draft and resend it.

3. Review logs in the Developer Console or under Setup → Debug Logs.

4. Look for entries related to the FutureHandler operation.