Configure Acrolinx for your needs in Salesforce.
Note
To set up Acrolinx for Salesforce Knowledge, you'll need admin privileges in Salesforce.
To set up Acrolinx for Salesforce Knowledge, do the following:
Enable Cross-Origin Resource Sharing (CORS) between Salesforce and your Acrolinx Platform. See our article on how to enable CORS.
Set Up SSOSSO lets you skip the browser-based sign-in process for the Acrolinx Sidebar. Learn how to set up Acrolinx for SSO.
Once you’ve enabled SSO, click the toggle switch next to Use SSO in the Acrolinx Setup. Enter your password in the Password field.
To use Acrolinx for Salesforce, writers need to have access to the knowledge base and one of two permission sets:
-
Acrolinx User - has access to the features that come with Acrolinx for Salesforce.
-
Acrolinx Administrator - has access to the Acrolinx User and can access the administrative page. There, you can see logs, batch check results, and other options set up by a system administrator.
To use Acrolinx for Salesforce, writers need knowledge-base access and the Acrolinx User or Acrolinx Administrator permission set.
To assign one or both of the Acrolinx permissions, do the following:
-
From Setup, enter “Users” in the Quick Find box. Select Users.
-
Click the name of the user that you want to assign permissions to. This will open the user's profile.
-
Navigate to the Permission Set Assignments section of the user profile and click Edit Assignments.
-
Select a permission in the Available Permission Sets column, and click Add to move it to the Enabled Permission Sets column.
Note
If you want a user to run batch checks, you'll also need to add the “Run Flows” permission to the Enabled Permission Sets column.
-
Click Save.
To generate the private key and server certificate using the OpenSSL library, do the following:
Tip
Don't have OpenSSL? Learn how to install it.
-
Run the command below to generate a private key. It will return your
server.pass.key
file.openssl genrsa -des3 -passout pass:x -out server.pass.key 2048
-
Use the
server.pass.key
file to create another key file via the command below:openssl rsa -passin pass:x -in server.pass.key -out server.key
It will return your
server.key
file. Theserver.key
is your RSA private key. -
Request and generate the certificate with the following command:
openssl req -new -key server.key -out server.csr
Once you run the command, you'll need to provide some information:
-
Country Name: <your country>
-
State or Province Name: <your state>
-
Locality Name (city): <your city>
-
Organization Name: <your company>
-
Organization Unit Name: <your company>
-
Common Name: <optional>
-
Email Address: <your email address>
-
-
Generate the SSL certificate with the following command:
openssl x509 -req -sha256 -days 365 -in server.csr -signkey server.key -out server.crt
It will return your
Server.Crt
file.Server.Crt
is your digital signature certificate.
Tip
Keep the keys that you generate in a safe place – especially the keys from steps 2 and 4.
When you open Acrolinx in Salesforce Knowledge, you'll see a tab for the Acrolinx Setup Guide. This walks you through the steps needed to configure Acrolinx and connect to the Acrolinx Platform.
To get started, open Acrolinx in Salesforce and click Acrolinx Setup Guide.
Notice
Before you start, be sure to complete the step “Generate Private Key and Server Certificate” in Prepare Your Instance.
Connected apps let you integrate external applications into Salesforce.
Add a new connected app via the app manager and enter the required information:
Field |
Description |
---|---|
Connected App Name |
The unique name displayed in the App Manager and on the app's launcher tile. Don't reuse this name within your org. |
API Name |
The API name used when referring to your app from a program. By default, this name won't include spaces. You can only enter letters, numbers, and underscores. |
Contact Email |
The contact email for you or your support team. |
Enable OAuth Settings |
Grant access to Salesforce data on behalf of an external application (Acrolinx, in this case). |
Callback URL |
The endpoint that Salesforce calls back to your application during OAuth. It’s the same as the OAuth redirect URI. Depending on which OAuth flow you use, the URL is typically the one that a user’s browser is redirected to after successful authorization. Make sure the URL uses secure HTTPS or a custom URI scheme. |
Use digital signatures |
Select if you’re using the JWT OAuth flow. Add the certificate on your system to upload for the JWT OAuth flow. The certificate size is limited to 4 KB. |
Selected OAuth Scopes |
OAuth scopes define permissions for the connected app. These are granted as tokens after the app is authorized. Manage user data via APIs (api) - Gives access to the current, signed-in user’s account using APIs. Perform requests at any time (refresh_token, offline_access) - Allows a refresh token to be returned when the requesting client is eligible to receive one. With a refresh token, the app can interact with the user’s data while the user is offline. This token is synonymous with requesting offline_access. |
Once you've added this information, be sure to mark the steps as Done in the setup guide.
In this step, you'll create a new permission set for the Acrolinx Sidebar and assign it to your users.
Enter the required information:
Field |
Description |
---|---|
Label |
The permission set label, which corresponds to Label in the user interface. Limit: 80 characters. |
API Name |
The unique name of the object in the API. This name can contain only underscores and alphanumeric characters, and must be unique in your organization. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. |
Click Edit to add the consumer key from the connected app and the private key that you generated in the Prepare Your Instance section of the Acrolinx for Salesforce Knowledge Admin Guide.
Enter the required information:
Field |
Description |
---|---|
Consumer Key |
Identifies the customer to Salesforce and a consumer secret establishes the ownership of the consumer key. |
Private Key |
Used in the encryption/decryption of data sent between your server and Salesforce. You create this when you request your certificate with a Certificate Signing Request (CSR). |
Once you've added this information, be sure to mark the step as Done in the setup guide.
Connect to the Acrolinx Platform via Salesforce.
In this step, you'll provide your unique Acrolinx URL, add it to the Remote Site Settings, and set up SSO.
Click Edit and paste your Acrolinx URL into the Acrolinx URL field.
Click Add next to Add the Acrolinx URL to the Remote Site Settings.
After that, click Edit to turn on SSO and enter your SSO password in the Password field.
This step lets you add Acrolinx-specific fields to the Knowledge object so that important checking information appears where you need it. This step is optional for Sidebar checks. If your license includes automated checking, the fields are required.
You can name the fields whatever you'd like, but you might choose something like the following:
Tip
To display a field, be sure to add it to the record page layout.
Field label |
Description |
---|---|
Acrolinx Score |
Field to store the Acrolinx Score. |
Acrolinx Scorecard |
Field to store a link to the Acrolinx Scorecard. |
Embed Scorecard |
Field to embed the Acrolinx Scorecard link below the Acrolinx Score. |
Last Checked |
Add a field to store the article’s last checked date. |
Score Status |
Add a field to store the “Score Status” color value. |
Score Color |
Add a field to display the “Score Status” color. |
In this step, you'll add components to the record page in Salesforce so you can check articles with Acrolinx and view the Acrolinx Score.
You'll only complete this step if your license includes batch checking.
Set the maximum number of parallel checks and click Add to enable batch checking from the list view.
After you add a button to the List View Button Layout, mark the step as Done in the setup guide.
You'll only complete this step if your license includes automated checking.
Click Apply to create a flow that starts an automatic Acrolinx check when you save or update an article.
Note
If want to update to Acrolinx for Salesforce Knowledge version 3.6, be sure to deactivate the trigger that you set up in earlier versions of Acrolinx for Salesforce Knolwedge before you click Apply.
Review the flow logic and mark the step as Done.
Tip
If you decide not to use batch or automated checking later on, they're easy to turn off. Learn how to turn off batch and automated checking.
Enable Cross-Origin Resource Sharing (CORS) between Salesforce and your Acrolinx Platform. See our article on how to enable CORS.
Set Up SSOSSO lets you skip the browser-based sign-in process for the Acrolinx Sidebar. Learn how to set up Acrolinx for SSO.
Once you’ve enabled SSO, click the toggle switch next to Use SSO in the Acrolinx Setup. Enter your password in the Password field.
To use Acrolinx for Salesforce, writers need to have access to the knowledge base and one of two permission sets:
-
Acrolinx User - has access to the features that come with Acrolinx for Salesforce.
-
Acrolinx Administrator - has access to the Acrolinx User and can access the administrative page. There, you can see logs, batch check results, and other options set up by a system administrator.
To use Acrolinx for Salesforce, writers need knowledge-base access and the Acrolinx User or Acrolinx Administrator permission set.
To assign one or both of the Acrolinx permissions, do the following:
-
From Setup, enter “Users” in the Quick Find box. Select Users.
-
Click the name of the user that you want to assign permissions to. This will open the user's profile.
-
Navigate to the Permission Set Assignments section of the user profile and click Edit Assignments.
-
Select a permission in the Available Permission Sets column, and click Add to move it to the Enabled Permission Sets column.
Note
If you want a user to run batch checks, you'll also need to add the “Run Flows” permission to the Enabled Permission Sets column.
-
Click Save.
To generate the private key and server certificate using the OpenSSL library, do the following:
Tip
Don't have OpenSSL? Learn how to install it.
-
Run the command below to generate a private key. It will return your
server.pass.key
file.openssl genrsa -des3 -passout pass:x -out server.pass.key 2048
-
Use the
server.pass.key
file to create another key file via the command below:openssl rsa -passin pass:x -in server.pass.key -out server.key
It will return your
server.key
file. Theserver.key
is your RSA private key. -
Request and generate the certificate with the following command:
openssl req -new -key server.key -out server.csr
Once you run the command, you'll need to provide some information:
-
Country Name: <your country>
-
State or Province Name: <your state>
-
Locality Name (city): <your city>
-
Organization Name: <your company>
-
Organization Unit Name: <your company>
-
Common Name: <optional>
-
Email Address: <your email address>
-
-
Generate the SSL certificate with the following command:
openssl x509 -req -sha256 -days 365 -in server.csr -signkey server.key -out server.crt
It will return your
Server.Crt
file.Server.Crt
is your digital signature certificate.
Tip
Keep the keys that you generate in a safe place – especially the keys from steps 2 and 4.
For security reasons, you'll need to set up the AcrolinxConnectedApp before your writers start to use Acrolinx. That way, you can more closely monitor Acrolinx and how it's used in your knowledge base. After you generate your private key and server certificate, you'll need to set up the connected app and provide the credential data.
To set up the connected app, do the following:
-
Go to Setup > Apps > App Manager > New Connected App.Fill in the following information:
-
Under Basic Information, add the following:
-
Connected App Name: AcrolinxUserConnectedApp
-
API Name: AcrolinxUserConnectedApp
-
Contact Email: <Provide your email>
-
-
Under API (Enable OAuth Settings), add the following:
-
Select Enable OAuth Settings.
-
Callback URL: https://login.salesforce.com/
-
Select Use digital signatures. Click Browse and select the certificate you generated (.crt) in the section Generate Private Key and Server Certificate.
-
Selected OAuth Scopes:
-
Select Manage user data via APIs (api).
-
Select Perform requests at any time (refresh_token, offline_access).
-
-
-
-
Click Save.
To set up the policy for the connected app, you'll first need to add an unmanaged permission set. After that, you can add your new permission set.
Create an Unmanaged Permission SetTo create an unmanaged permission set, do the following:
-
Go to Setup > Users > Permission Sets.
-
Click New in the top left of the table, and add the following:
-
Name: Acrolinx Sidebar
-
API Name: <unique name that you want the API to use>
-
-
Click Save.
-
Go to Manage Assignments > Add Assignment in the Acrolinx Sidebar permission set.Select the users that should be able to use the Sidebar.
-
Click Next and then Assign.
To change the policy for the connected app, do the following:
-
Go to Setup > Apps > App Manager > AcrolinxUserConnectedApp > Manage > Edit Policies.
-
Go to Connected App Edit | OAuth Policies >Permitted Users, and select Admin approved users are pre-authorized from the dropdown.
-
Scroll to Permission Sets, and click Manage Permission Sets on the App Manager page for the AcrolinxUserConnectedApp.
-
Select theAcrolinx Sidebar permission set, and click Save.
You'll need to connect Salesforce to your Acrolinx instance. To do this, add your Acrolinx URL to the Salesforce Remote Site Settings.
To add your Acrolinx URL to Salesforce, do the following:
-
From the Salesforce Setup, enter “Remote Site Settings” in the Quick Find box. Select Remote Site Settings.
-
Click the New Remote Site button to open the Remote Site Edit window. Enter the following information:
-
Remote Site Name: <For example, Acrolinx>
-
Remote Site URL: <Your instance URL>
-
Active: true
-
-
Click Save.
-
Open the Acrolinx App Configuration and add your Remote Site URL to the field labeled Acrolinx URL.
It's also possible to save the Acrolinx Score for each of your articles. To get started, you'll need to create a field to store the score. After you create this field, you can choose to display the score for an article directly in Salesforce. Learn how in Add Components to the Record Page.
To create a field to store the score, do the following:
-
Go to Setup > Object Manager > Knowledge.
-
Select Fields & Relationships > New to add a new field. Select the radio button next to Number and click Next.
-
Add the following information under Step 2. Enter the details:
-
Label your field in the Field Label box. We recommend "Acrolinx Score."
-
Name your field in the Field Name box. We recommend “AcrolinxScore” with “__c” at the end. For example, “AcrolinxScore__c.”
-
Enter a description about what the field does, for example: "This field will store the Acrolinx Score that gets saved after an automated check."
Click Next.
-
-
Select the user profiles that should have edit access for this field, and click Next.
-
Uncheck the Add Field box next to Knowledge Layout and click Save.
-
Open the Acrolinx App Configuration and search for the name of your field in Field to store Acrolinx Score.
Note
If you don’t add this field to field-level security, Salesforce Knowledge will hide the field from all profiles.
To get a quick overview of how your content scores, you can add the Acrolinx Score component to your record page.
Note
For your writers to access the Edit with Acrolinx page, you may need to add Salesforce IP addresses to your allow list.
Do this if:
-
The setting "Enforce login IP ranges on every request" under Session Settings is selected.
-
IP ranges are set for a user's profile
If that's the case, you'll need to add additional Salesforce IP addresses to the IP ranges for the selected user profiles. Learn which addresses you need to add.
To add components to the record page, do the following:
-
Go to Setup > Object Manager > Knowledge.
-
Select Lightning Record Pages. Click on the name of your record page (for example, "Knowledge Record Page") under Label and click Edit.
-
When the Lightning App Builder page opens, search "Acrolinx" under Components. Drag and drop the Acrolinx Score and Edit with Acrolinx components to your page.
-
Click Save.
Tip
You may also need to activate the page to make it available to users.
If you don’t see the Lightning Record Page for Knowledge, you might need to create it.
To create this page, do the following:
-
Go to Setup > Object Manager > Knowledge.
-
Select Lightning Record Pages. Click New and select Record Page, then click Next.
-
Next to Label, provide any label (for example, Knowledge Record Page). Next to Object, select Knowledge. Click Next.
-
Click the Clone Salesforce Default Page tab or select your preferred template in the Choose Page Template tab. Click Finish.
-
Search "Acrolinx" under Components when the Lightning App Builder page opens. Drag and drop the Acrolinx Score and Edit with Acrolinx components to your page. Click Save and Activate.
-
Choose where you want to assign the page layout and click Save.
Note
This field is required for batch checking.
If you want Acrolinx to check multiple draft articles at the same time, add a number next to Max. Number of Parallel Checks in the Acrolinx Setup. This sets the maximum number of articles checked at the same time. It can be any full number between 1 and 23. We suggest 5 as a default value.
The batch check option in Salesforce lets you check multiple draft articles directly in the Salesforce Knowledge list view. You won't have to open the Sidebar for each file, so it's easy to determine how your content scores.
To enable batch checking, add a Quick Action button that starts score checking for unsaved draft articles.
-
Go to Setup > Object Manager > Knowledge.
-
Select Buttons, Links, and Actions > New Button or Link.
-
Enter the following information:
-
Label: Check with Acrolinx
-
Name: Added automatically based on Label value – must be unique
-
Display Type: List Button
-
Behavior: Display in an existing window without sidebar or header
-
Content Source: URL
-
In the text box below, enter:
{!URLFOR('/flow/AcrolinxApp/ScheduleBatchAcrolinxEvaluation')}
-
-
Click Save.
-
Go to Setup > Object Manager > Knowledge.
-
Select List View Button Layout > Edit. Click Add to move your newly created buttons to the Selected Buttons list in the Custom Buttons section.
-
Click Save. You’ll see the Check with Acrolinx button on the Knowledge list view page.
-
Go to Setup > Object Manager > Acrolinx Batch Check > Page Layouts > Acrolinx Job Layout.
-
Select Mobile & Lightning Actions.
-
Drag and drop Cancel to the Salesforce Mobile and Lightning Experience Actions section.
-
Click Save. You’ll see the Cancel button on the Acrolinx Batch Check page.
When you use Acrolinx for Salesforce, it's possible to turn on automated checking. This starts an automatic Acrolinx check when you save an article in the Acrolinx editor. If you've added an Acrolinx Score field to lightning knowledge, you'll see the score from your automated check directly in your article.
If your Salesforce version supports Apex triggers, you can create a trigger to calculate the Acrolinx Score when you save or update an article.
In your sandbox org, create an Apex trigger for your Knowledge object (usually Knowledge__kav) and paste in the following code:
trigger AcrolinxOnSave on Knowledge__kav (after insert, after update) { (new AcrolinxApp.KnowledgeObj()).onTrigger(); }
If you already have a trigger for your Knowledge object, you can add just one line. Make sure that the trigger is running after insert and update:
(new AcrolinxApp.Knowledge()).onTrigger()
Your Knowledge object may have a different name. If that's the case, replace “Knowledge__kav” with the correct name.
In your sandbox org, create a test class and paste in the following code:
@IsTest private class AcrolinxTestClass { @IsTest private static void insertArticle() { AcrolinxApp__AcrolinxConfigurationSettings__c settings = AcrolinxApp__AcrolinxConfigurationSettings__c.getOrgDefaults(); settings.AcrolinxApp__ScoreCalculationTriggerDisabled__c = true; upsert settings; Knowledge__kav article = new Knowledge__kav( Title = 'Test title', UrlName = 'Test-title' ); Test.startTest(); insert article; Test.stopTest(); System.assert(String.isNotBlank(article.Id), 'Article should be inserted'); } }
In the test class, create an article record that you can insert into the database. Depending on the customizations in your org, you may need to define values for a few other fields. For example, "Language" if you enable translations.
-
From Setup, enter “Deployment” in the Quick Find box. Select Deployment Settings, and click Continue.
-
Click Edit next to the Sandbox org name and select Allow Inbound Changes.
-
Click Save.
-
From Setup, enter “Outbound Change Sets” in the Quick Find box. Select Outbound Change Sets, and click Continue.
-
Click New and enter a Name and Description. Click Save.
-
Click the name of a change set in the Change Sets list. Click Add under Change Set Components.
-
Select Apex Trigger from the Component Type dropdown. Select the trigger that you've created and click Add to Change Set.
-
Select Apex Class from the Component Type dropdown. Select the test class that you’ve created and click on Add to Change Set.
-
-
Click Upload in the Change Set detail section.
-
Select Target Organization (production org) and click Upload.
-
From Setup, enter “Inbound Change Sets” in the Quick Find box. Select Inbound Change Sets, and click Continue.
-
Click Validate next to Change Set Name. In the Validate Change Set section, select Default under Choose a Test Option.
-
Click Validate next to Choose a Test Option and then click OK.
-
Once validation is successful, go to the Inbound Change Sets page. Click Deploy next to the change set you want to use.
Tip
You can track the status of deployments that are in progress in the Deployment Status page. To open it, go to Setup, enter Deployment Status in the Quick Find box, then select Deployment Status. The page also shows completed deployments.
If you need to upload a large dataset, you can change your custom settings to turn off automated checks.
To turn off automated checking, do the following:
-
From Setup, enter “Custom Settings” in the Quick Find box. Select Custom Settings.
-
Click on Manage next to Acrolinx Configuration Settings.
-
Disable the trigger for everyone - Click New below Acrolinx Configuration Settings.
-
Disable the trigger for a specific user - Click New at the top of the table below Default Organization Level Value. Select User from the Location dropdown, and add the user's name.
-
-
Select Score Calculation Trigger Disabled and click Save.
To add the secure credentials that you've generated for use in the Setup Wizard, do the following:
-
Go to Setup > App Manager > AcrolinxUserConnectedApp > View > Manage Consumer Details > Copy Consumer Key.
-
In the Acrolinx Setup:
-
Enter the copied consumer key next to Client ID.
-
Enter the
server.key
that you generated in the section Prepare Your Instance. Add this next to Private Key.
-