General

Smart Document allow you to pull external resources (images, pdf files or others) from a secured repository to work with our Image, Merge Document and Attach Files functions. These functions are respectively inserting an image, merging a PDF document into a generated PDF, attaching a file into a generated Word document.

As a reminder for those three functions, the quote cell(s) or field(s) used to pull external resource must be of type URL.

URL API are not supposed to be displayed in the UI and should only be used for document generation. If you would need your user to access the document from the Quote UI another URL column should be set up with a Viewer link / Public URL.

OAuth 2.0 Authentication

To access those secured external resource when generating a document, an authentication mechanism must be setup in the PROS Cloud as well as some access right on the external file repository.

SharePoint resources

CERTIFICATE-BASED AUTHENTICATION (JWT BEARER TOKEN AUTHENTICATION)

The Microsoft recommended way for authentication with SharePoint is OAuth 2.0 Client Credentials Flow with Certificate-based Authentication. Microsoft calls this "Certificate credentials" or "Client assertion with certificate" in their documentation. It's also known as JWT Bearer Token Authentication.

Azure AD Setup & Configuration

Step 1: Create Azure AD App Registration

In Azure Portal > Azure Active Directory (Entra Id) > App registrations

1. Click "New registration".
2. Name: "SharePoint Certificate Auth App".
3. Supported account types: "Single tenant".
4. Redirect URI: Leave empty (not needed for client credentials).
5. Click "Register".

Step 2: Note Application Details

Save these values from the Overview page:

• Application (client) ID: df15de9b-49ea-4d22-b974-68c08a312cbf
• Directory (tenant) ID: e3c40aa4-4fc8-4430-80e0-ff02ed844ecb
• Tenant Name: YourTenantName Image Added
  
  

Step 3: Upload Certificate

In App Registration > Certificates & secrets > Certificates

1. Click "Upload certificate".
2. Select your .cer or .pem certificate file (public key only).
3. Add description: For example "SharePoint Authentication Certificate".
4. Click "Add".
5. Note the Thumbprint: [matches SHA-1 from your certificate].

Image Added Image Added

Step 4: Configure API Permissions

In App Registration > API permissions

1. Click "Add a permission".
2. Select "SharePoint". This is mandatory, we currently only support SharePoint REST API V1.
3. Choose "Application permissions".
4. Select required permissions:
   1. Sites.Read.All (or Sites.FullControl.All)
   2. Files.Read.All (or Files.ReadWrite.All)
5. Click "Grant admin consent for [tenant]".

Authentication

The authentication for SharePoint is richer than the standard OAuth 2.0 authentication. You will need to provide the support team with the following information via a Support Ticket:

AUTHENTICATION WITH CLIENT CREDENTIALS (AZURE COMMUNICATION SERVICES: ACS)

This method of authentication will be deprecated by Microsoft in April 2026 as announced by Microsoft.

Extract of Microsoft Announcement below:

"Azure ACS will stop working for new tenants as of November 1st, 2024 and it will stop working for existing tenants and will be fully retired as of April 2nd, 2026. "

Full announcement available here: https://learn.microsoft.com/en-gb/sharepoint/dev/sp-add-ins/retirement-announcement-for-azure-acs

Prerequisite: SharePoint setup

Some SharePoint Setup is necessary before being able to work with Smart Document. Some of these actions will be taken by your SharePoint administrator.

Activate App-Only via Powershell

• Open SharePoint Online Management Shell
• Open PowerShell
• Execute the following commands in PowerShell to connect to your sharepoint site and activate sharepoint app-only
  • Install -Module -Name Microsoft.Online.PowerShell
  • $adminUPN="<the full email address of a SharePoint administrator account, example: [email protected]>"
  • $orgName="<name of your Office 365 organization, example: contosotoycompany>"
  • $userCredential = Get-Credential -UserName $adminUPN -Message "Type the password."
  • Connect-SPOService -Url https://$orgName-admin.sharepoint.com -Credential $userCredential
  • set-spotenant -DisableCustomAppAuthentication $false

Enable & Configure App-Only

Step 1: Set up an app-only principal with tenant permissions

https://docs.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azureacs

Navigate to a site in your tenant https://MyCompany.sharepoint.com/ Call the appregnew.aspx page https://MyCompany.sharepoint.com/_layouts/15/appregnew.aspx Click on the Generate button to generate a client id/app id and client secret and fill the remaining info For example Title: DocGenPROS AppDomain: www.MyCompany.com Redirect URL: http://www.MyCompany.com/default.aspx

Step 2: Grant permissions to the newly created principal

Possible scopes for the permission request:

Below are the various App permission level that are available in SharePoint

Step 3: Retrieve the TenantID and ClientID

As you will need to give this information to Conga, this is how you can retrieve your TenantID and ClientID.

Use a Postman GET Method

AUTHENTICATION

The authentication for SharePoint is richer than the standard OAuth 2.0 authentication. You will

need to provide the following information via a Support Ticket:

COMPLIANT URL FORMAT

URL used in the Document Generation are stored in the CPQ Quote. Performance Quoting has trict URL validation process. You cannot use URLs with '(' or ')'.

SharePoint Rest API URL may contain some of those forbidden characters. '(' or ')' must be encoded as follow when used in the quote.

USEFUL LINKS

Get started with SharePoint Online Management Shell

Granting access using SharePoint App-Only

Types of add-in permissions and permission scopes

Differences between add-in permission rights and user rights

Only Salesforce organizations where the Smart CPQ managed package has been installed can be the repository for the files used as external resources.

Prerequisite: Salesforce setup

STORAGE

Only documents and images stored in the Files entities in Salesforce can be used as external resources during the document generation process. Documents and images stored in the Salesforce Notes & Attachments entities are not eligible for merge, attach and insertion in document generation.

PERMISSIONS

The user launching the document generation must have access to the Salesforce-stored resources. If not, the document generation process will not be able to merge, attach or insert the file.

To learn more about Salesforce Permission read: Who Can See My File?

Authentication

There is no additional setup to perform for authentication as the managed package will take care of it.

Nevertheless, on PROS Cloud side we need to enable the capability, you will need to reach out to create a Support ticket for the team to enable the feature.

Compliant URL Format

URL used in the Document Generation are stored in the CPQ Quote. Performance Quoting has a strict URL validation process. You cannot use URLs with '(' or ')'.

This is how the URL should be built and stored in the Quote:

WHAT IS THE SALESFORCE INSTANCE URL? (SALESFORCE_INSTANCE_URL)

The Salesforce instance URL must be the domain URL. How to find it?

• Log in to your Salesforce org as an Admin
• Navigate to ‘My Domain’ in Setup
• Look for Current My Domain URL

HOW TO FIND MY SALESFORCE REST API VERSION NUMBER? (SALESFORCE_REST_API_VERSION)

• Log in to your Salesforce org as an Admin
• Navigate to ‘Apex Classes’ in Setup
• Click on the ‘New’ button
• Click ‘Version Settings’ tab

  There you can see which API version your Salesforce instance is on.

  
  
  
  
  
  
  

WHERE TO FIND THE IDENTIFIER OF THE FILE ? (FILE_ID)

The file ID can be found in the URL when opening the "View file details" page.