Skip to main content
 

How can we help?

Search

Admin Guide

  • Updated

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:

Acrolinx for Salesforce Knowledge 3.6

1. Prepare Your Instance

Prepare Your Instance

Acrolinx Platform Configurations
Enable Cross-Origin Resource Sharing (CORS)

Enable Cross-Origin Resource Sharing (CORS) between Salesforce and your Acrolinx Platform. See our article on how to enable CORS.

Set Up SSO

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

Salesforce Permissions

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.

Assign Permissions to Your Writers

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:

  1. From Setup, enter “Users” in the Quick Find box. Select Users.

  2. Click the name of the user that you want to assign permissions to. This will open the user's profile.

  3. Navigate to the Permission Set Assignments section of the user profile and click Edit Assignments.

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

  5. Click Save.

Generate Private Key and Server Certificate

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.

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

  2. 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. The server.key is your RSA private key.

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

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

2. Set Up Acrolinx

Set Up Acrolinx

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.

1. Create the Connected App
Salesforce_CreateConnectedApp.png

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.

2. Set Permissions
Salesforce_SetPermissions.png

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.
3. Provide the Consumer Key and Private Key
Salesforce_ProvideConsumerKeyPrivateKey.png

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.

4. Connect to the Acrolinx Platform
Salesforce_ConnecttoAcrolinx.png

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.

5. Add Fields
Salesforce_AddFields.png

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.
6. Edit the Record Page
Salesforce_EditRecordPage.png

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.

7. Set Up Batch Checking (Optional)
Salesforce_SetUpBatchChecking.png

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.

8. Set Up Automated Checking (Optional)
Salesforce_SetUpAutomatedChecking.png

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.

Acrolinx for Salesforce Knowledge 3.4

1. Prepare Your Instance

Prepare Your Instance

Acrolinx Platform Configurations
Enable Cross-Origin Resource Sharing (CORS)

Enable Cross-Origin Resource Sharing (CORS) between Salesforce and your Acrolinx Platform. See our article on how to enable CORS.

Set Up SSO

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

Salesforce Permissions

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.

Assign Permissions to Your Writers

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:

  1. From Setup, enter “Users” in the Quick Find box. Select Users.

  2. Click the name of the user that you want to assign permissions to. This will open the user's profile.

  3. Navigate to the Permission Set Assignments section of the user profile and click Edit Assignments.

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

  5. Click Save.

Generate Private Key and Server Certificate

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.

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

  2. 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. The server.key is your RSA private key.

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

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

Set Up Connected App in Salesforce

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:

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

  2. Click Save.

Set Up Policy for Connected App

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 Set

To create an unmanaged permission set, do the following:

  1. Go to Setup > Users > Permission Sets.

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

  3. Click Save.

  4. Go to Manage Assignments > Add Assignment in the Acrolinx Sidebar permission set.Select the users that should be able to use the Sidebar.

  5. Click Next and then Assign.

Change the Policy and Add the Permission Set

To change the policy for the connected app, do the following:

  1. Go to Setup > Apps > App Manager > AcrolinxUserConnectedApp > Manage > Edit Policies.

  2. Go to Connected App Edit | OAuth Policies >Permitted Users, and select Admin approved users are pre-authorized from the dropdown.

  3. Scroll to Permission Sets, and click Manage Permission Sets on the App Manager page for the AcrolinxUserConnectedApp.

  4. Select theAcrolinx Sidebar permission set, and click Save.

2. Set the Acrolinx URL and Create a Score Field

Set the Acrolinx URL and Create a Score Field

Set the Acrolinx URL

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:

  1. From the Salesforce Setup, enter “Remote Site Settings” in the Quick Find box. Select Remote Site Settings.

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

  3. Click Save.

  4. Open the Acrolinx App Configuration and add your Remote Site URL to the field labeled Acrolinx URL.

Create an Acrolinx Score Field

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:

  1. Go to Setup > Object Manager > Knowledge.

  2. Select Fields & Relationships > New to add a new field. Select the radio button next to Number and click Next.

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

  4. Select the user profiles that should have edit access for this field, and click Next.

  5. Uncheck the Add Field box next to Knowledge Layout and click Save.

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

Add Components to the Record Page

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:

  1. Go to Setup > Object Manager > Knowledge.

  2. Select Lightning Record Pages. Click on the name of your record page (for example, "Knowledge Record Page") under Label and click Edit.

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

  4. Click Save.

Tip

You may also need to activate the page to make it available to users.

Don't See a Lightning Record Page for Knowledge?

If you don’t see the Lightning Record Page for Knowledge, you might need to create it.

To create this page, do the following:

  1. Go to Setup > Object Manager > Knowledge.

  2. Select Lightning Record Pages. Click New and select Record Page, then click Next.

  3. Next to Label, provide any label (for example, Knowledge Record Page). Next to Object, select Knowledge. Click Next.

  4. Click the Clone Salesforce Default Page tab or select your preferred template in the Choose Page Template tab. Click Finish.

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

  6. Choose where you want to assign the page layout and click Save.

3. Set Up Batch Checking

Set Up Batch Checking

Set Maximum Parallel Checks

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.

Enable Batch Checking

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.

Create a List View Button

  1. Go to Setup > Object Manager > Knowledge.

  2. Select Buttons, Links, and Actions > New Button or Link.

  3. 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')}

  4. Click Save.

Add Button to the List View Button Layout

  1. Go to Setup > Object Manager > Knowledge.

  2. Select List View Button Layout > Edit. Click Add to move your newly created buttons to the Selected Buttons list in the Custom Buttons section.

  3. Click Save. You’ll see the Check with Acrolinx button on the Knowledge list view page.

Add Cancel Button to Batch Check Page Layout

  1. Go to Setup > Object Manager > Acrolinx Batch Check > Page Layouts > Acrolinx Job Layout.

  2. Select Mobile & Lightning Actions.

  3. Drag and drop Cancel to the Salesforce Mobile and Lightning Experience Actions section.

  4. Click Save. You’ll see the Cancel button on the Acrolinx Batch Check page.

Logs and Check History

When you open the the Acrolinx App in Salesforce, you'll see the Check History and Logs tabs next to the Acrolinx Setup. You can use these to troubleshoot if you run into any checking issues.

4. Set Up Automated Checking

Set Up Automated Checking

Turn On Automated Checks

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.

Create an Apex Trigger

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.

Create a Test Class

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.

Connect Sandbox and Production Orgs

  1. From Setup, enter “Deployment” in the Quick Find box. Select Deployment Settings, and click Continue.

  2. Click Edit next to the Sandbox org name and select Allow Inbound Changes.

  3. Click Save.

Create an Outbound Change Set

  1. From Setup, enter “Outbound Change Sets” in the Quick Find box. Select Outbound Change Sets, and click Continue.

  2. Click New and enter a Name and Description. Click Save.

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

  4. Click Upload in the Change Set detail section.

  5. Select Target Organization (production org) and click Upload.

Deploy Your Inbound Change Set

  1. From Setup, enter “Inbound Change Sets” in the Quick Find box. Select Inbound Change Sets, and click Continue.

  2. Click Validate next to Change Set Name. In the Validate Change Set section, select Default under Choose a Test Option.

  3. Click Validate next to Choose a Test Option and then click OK.

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

Turn Off Automated Checks

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:

  1. From Setup, enter “Custom Settings” in the Quick Find box. Select Custom Settings.

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

  3. Select Score Calculation Trigger Disabled and click Save.

5. Add Security Credentials (3.4 only)

Add Security Credentials in Salesforce Knowledge

To add the secure credentials that you've generated for use in the Setup Wizard, do the following:

  1. Go to Setup > App Manager > AcrolinxUserConnectedApp > View > Manage Consumer Details > Copy Consumer Key.

  2. In the Acrolinx Setup:

    1. Enter the copied consumer key next to Client ID.

    2. Enter the server.key that you generated in the section Prepare Your Instance. Add this next to Private Key.