Skip to main content

Salesforce AppExchange Installation

This guide walks Salesforce administrators through setting up the Barid AppExchange app for sending Letters and Invoices.

Prerequisites​

  • Salesforce org (Sandbox or Production)
  • System Administrator profile or equivalent permissions
  • Barid API credentials (API Key and Secret)

Step 1: Install the Package​

  1. Navigate to the Barid listing on AppExchange
  2. Click Get It Now
  3. Select your org and follow the installation wizard
  4. Choose "Install for Admins Only" initially (you can grant access later)

Step 2: Configure API Credentials (External Credentials)​

API credentials are stored securely using Salesforce External Credentials. This ensures your API Key and Secret are hidden in the UI and never exposed in metadata.

The package includes two External Credentials - one for production and one for test. Configure the one matching your environment:

  1. Go to Setup → Named Credentials

  2. Click the External Credentials tab

  3. Find Barid API (Production) or Barid API (Test) and click on it

  4. Under Principals, find Barid_User and click on it (not Edit)

  5. Click Edit on the principal detail page

  6. Under Authentication Parameters, click Add and create two parameters:

    • Name: X_Api_Client_Id, Value: Your Barid API Key
    • Name: X_Api_Client_Secret, Value: Your Barid API Secret (will be masked after saving)
    Important

    Use underscores (_) in parameter names, NOT hyphens. Hyphens cause formula errors.

  7. Click Save

note

The Custom Headers on the Named Credential are pre-configured by the package to automatically inject these credentials as HTTP headers. No additional Named Credential configuration is required.

Configure Barid Settings​

  1. Go to Setup → Custom Metadata Types
  2. Click Manage Records next to Barid Settings
  3. Click New or edit the existing record
  4. Configure the following fields:
FieldDescriptionDefault / Example
API EnvironmentSelect Test, QA, or ProductionTest (default)
Timeout (s)API timeout in seconds120
Auto Send InvoicesEnable automatic invoice sendingUnchecked
Cron ExpressionSchedule for batch job (leave blank to disable)0 0 * * * ? (hourly)
Invoice Trigger StatusInvoice status that triggers automatic sendingPosted
Emirates ID Field(Optional) API name of custom field containing Emirates IDEmirates_ID__c
Invoice Reference Field(Optional) API name of Invoice field to use as referenceCustom_Reference__c
Order Reference Field(Optional) API name of Order field to use as referencePO_Number__c
note

The API Environment setting determines which External Credential is used. Select "Production" when you're ready to go live.

Emirates ID Field Configuration (Optional)​

If your org has a custom field on Account to store Emirates ID, you can configure Barid to use it for more accurate customer lookup:

  1. Enter the API name of the field (e.g., Emirates_ID__c)
  2. The field must be on the Account object
  3. Leave blank to use phone/email lookup only

Emirates ID lookup is preferred over phone/email as it provides more accurate customer matching in the Barid system.

Invoice/Order Reference Field Configuration (Optional)​

By default, the Invoice Sender component uses:

  • Invoice: DocumentNumber field
  • Order: OrderNumber field

To use a different field as the reference number sent to Barid:

  1. Enter the API name of the field (e.g., Custom_Reference__c or PO_Number__c)
  2. The field must exist on the respective object (Invoice or Order)
  3. Leave blank to use the default field

Step 3: Configure Remote Site Settings​

  1. Go to Setup → Remote Site Settings
  2. Click New Remote Site
  3. Add the Barid API endpoint:
FieldValue
Remote Site NameBaridAPI
Remote Site URLhttps://sender.api.barid.ae or https://test.sender.api.barid.ae
ActiveChecked

Step 4: Grant User Access​

The package includes a Barid User permission set that grants access to Barid features.

Assign Permission Set to Users​

  1. Go to Setup → Permission Sets
  2. Click Barid User
  3. Click Manage Assignments → Add Assignment
  4. Select the users who need to send documents via Barid
  5. Click Assign

The permission set grants:

  • Access to all Barid Apex classes
  • Read/Create/Edit access to Document__c (for tracking sent documents)
  • External Credential Principal Access for both Test and Production APIs

Users will also need access to relevant standard objects (Account, Contact, Order, etc.) through their profile or other permission sets.

Step 5: Add Components to Page Layouts​

Add Letter Sender to Record Pages​

  1. Go to Setup → Object Manager
  2. Select the object (e.g., Account, Contact, ContentDocument)
  3. Click Lightning Record Pages
  4. Edit the page or create a new one
  5. Drag Send Letter via Barid component onto the page
  6. Click Save → Activate

Add Quick Action to Page Layout​

The package includes a Send via Barid Quick Action for Account. After deployment, add it to the page layout:

  1. Go to Setup → Object Manager → Account
  2. Click Page Layouts
  3. Edit the layout
  4. In the palette, find Send via Barid under "Mobile & Lightning Actions"
  5. Drag the action to Salesforce Mobile and Lightning Experience Actions
  6. Click Save

When users click this action on an Account, they can select from any PDF files attached to that Account and send them via Barid.

Quick Actions for Other Objects​

The package includes Quick Actions for Account, Contact, Contract, and Order. To add them to page layouts:

  1. Go to Setup → Object Manager → Select the object (Account, Contact, Contract, or Order)
  2. Click Page Layouts
  3. Edit the layout
  4. Find Send via Barid or Send To Barid under "Mobile & Lightning Actions"
  5. Drag the action to Salesforce Mobile and Lightning Experience Actions
  6. Click Save

Create Quick Actions for Additional Objects (Opportunity, Case, etc.)​

To add Quick Actions on objects not included in the package:

  1. Go to Setup → Object Manager → Select the object → Buttons, Links, and Actions
  2. Click New Action
  3. Configure:
    • Action Type: Lightning Web Component
    • Lightning Web Component: c:baridLetterSender
    • Label: Send via Barid
    • Name: Send_via_Barid
  4. Click Save
  5. Add to page layout as described above

Add Invoice Sender to Order Records​

The base Barid package includes a Send To Barid Quick Action for Order objects:

  1. Go to Setup → Object Manager → Order
  2. Click Page Layouts
  3. Edit the layout
  4. In the palette, find Send To Barid under "Mobile & Lightning Actions"
  5. Drag the action to Salesforce Mobile and Lightning Experience Actions
  6. Click Save

Alternatively, add the component directly to the Lightning Record Page:

  1. Go to Setup → Object Manager → Order
  2. Click Lightning Record Pages
  3. Edit the page
  4. Drag Barid Invoice Sender component onto the page
  5. Click Save → Activate

Invoice Quick Action (Salesforce Billing)​

For orgs with Salesforce Billing, a separate Barid for Billing extension package is available on AppExchange. This extension adds a pre-configured Send Invoice to Barid Quick Action on the Invoice object.

  1. Install the Barid for Billing package from AppExchange (requires the base Barid package)
  2. Go to Setup → Object Manager → Invoice
  3. Click Page Layouts
  4. Edit the layout
  5. Find Send Invoice to Barid under "Mobile & Lightning Actions"
  6. Drag the action to Salesforce Mobile and Lightning Experience Actions
  7. Click Save
note

The base Barid package already contains all invoice functionality. The extension simply provides a ready-to-use Quick Action on the Invoice object.

Step 6: Configure Automatic Invoice Sending (Optional)​

If you want invoices to be automatically sent to Barid when they reach a specific status (e.g., "Posted"), follow these steps:

6a. Enable Auto-Send in Settings​

  1. Go to Setup → Custom Metadata Types
  2. Click Manage Records next to Barid Settings
  3. Edit your settings record
  4. Check Auto Send Invoices
  5. Set Cron Expression for the schedule frequency (see examples below)
  6. Set Invoice Trigger Status to the status that should trigger sending (default: Posted)
  7. Click Save

Cron Expression Examples:

ScheduleCron Expression
Every hour0 0 * * * ?
Every 30 minutes0 0,30 * * * ?
Daily at midnight0 0 0 * * ?
Daily at 8 AM0 0 8 * * ?

6b. Activate the Schedule​

After configuring settings, run this Apex command once to activate the schedule:

BaridInvoiceScheduler.syncSchedule();

This reads your Barid Settings and creates (or removes) the scheduled job accordingly. Run this command again whenever you change the Auto Send Invoices or Cron Expression settings.

6c. Verify the Schedule​

To check if the job is scheduled:

System.debug(BaridInvoiceScheduler.isScheduled());

To see schedule details:

System.debug(BaridInvoiceScheduler.getScheduleDetails());

To manually remove the scheduled job:

BaridInvoiceScheduler.unschedule();

How It Works​

  1. The scheduler runs at your configured interval
  2. It queries Invoices with the trigger status (e.g., "Posted")
  3. Invoices that haven't been processed are sent to Barid
  4. Each invoice creates a Document__c record to track status
  5. Already-processed invoices are skipped (prevents duplicates)
note

This feature requires the Salesforce Billing Invoice object. If your org doesn't have Salesforce Billing, the scheduler will skip processing automatically. The app can still be installed and used for manual letter sending.

Step 7: Verify Installation​

Test API Connection​

  1. Open an Account record
  2. Look for the Send Letter via Barid component
  3. The component should load without errors

Send a Test Letter​

  1. Upload a PDF file to an Account record
  2. Click Send via Barid (Quick Action) or use the component
  3. Enter a title and verify the recipient is auto-detected
  4. Click Send Letter
  5. Check the Barid Documents related list for status

Custom Object: Barid Document​

The app creates Document__c records to track sent documents:

FieldDescription
NameAuto-generated ID (BD-0001, etc.)
StatusPending, Sent, Delivered, or Failed
Document TypeLetter or Invoice
File NameOriginal filename
Sent DateWhen successfully sent
Document IdBarid system reference ID
Error MessageDetails if sending failed

Add Related List to Page Layouts​

  1. Go to Object Manager → Account (or other objects)
  2. Click Page Layouts
  3. Edit the layout
  4. Drag Barid Documents related list onto the page
  5. Click Save

Platform Cache (Optional)​

For better performance, enable Platform Cache:

  1. Go to Setup → Platform Cache
  2. Create a partition named BaridCache
  3. Allocate at least 1 MB to the session cache

The app uses Platform Cache to store API sessions (~30 minute TTL), reducing authentication calls.

Troubleshooting​

"Recipient not found in Barid"​

The Account holder must be registered in the Barid system. The app uses standard Salesforce fields to look up customers:

For Person Accounts:

  • PersonEmail field
  • Phone or PersonMobilePhone field

For Business Accounts:

  • Phone field on the Account
  • Email from the primary Contact

Ensure at least one of these fields has a value that matches the customer's Barid registration.

"No PDF files attached"​

The component only shows PDF files. Ensure:

  • Files are uploaded as Salesforce Files (not Attachments)
  • File extension is .pdf

API Connection Errors​

  1. Verify Remote Site Settings include the Barid API URL
  2. Check that External Credential has X_Api_Client_Id and X_Api_Client_Secret parameters configured (Setup → Named Credentials → External Credentials tab → click on the principal)
  3. Ensure the user has the Barid User permission set assigned (this grants access to the External Credential)
  4. Test the API credentials in Barid's dashboard

Permission Errors / Button Not Visible​

If the "Send To Barid" button doesn't appear or users get permission errors:

  1. Assign the Barid User permission set to the user (Setup → Permission Sets → Barid User → Manage Assignments)
  2. Ensure the Quick Action has been added to the page layout (see Step 5)
  3. Verify users have access to Salesforce Files (ContentDocument, ContentVersion) through their profile

Support​

For issues or questions:

Developer Notes (Scratch Orgs)​

When developing with scratch orgs, the project uses the Barid namespace defined in sfdx-project.json. This means:

  • External Credentials are deployed with the Barid__ namespace prefix
  • Named Credential formulas reference {!$Credential.API_Test.X_Api_Client_Id} (without namespace prefix - Salesforce resolves this automatically)
  • Permission Set includes External Credential Principal Access automatically

No manual configuration is required for scratch orgs created from this project.