Acrolinx Sidebar

Note: Acrolinx: This functionality has been deprecated and is no longer supported and/or available for new installations. This documentation is retained as a reference only for customers already using the functionality and for whom it remains available in the current state. The functionality will be removed in the future so customers using this should make plans to transition away from their implementation of it.

Acrolinx is a third-party content standardization tool that, when integrated with STEP, is used to check and improve the quality of text-based content authored in the Web UI. The Acrolinx platform uses an advanced linguistic analysis engine that 'reads' content and guides writers to make it better. Through artificial intelligence technology, Acrolinx enables users to create accurate, consistent, and impactful copy.

The integration between Acrolinx and STEP is achieved through the Acrolinx Sidebar, a product of Acrolinx that works with text fields in the Web UI and, with the click of a button, gives users guidance and feedback on their content. Acrolinx checks content for issues such as spelling, grammar, style, valid terminology, and tone of voice, then returns an Acrolinx Score that grades the overall quality of the content. Content with a higher Acrolinx Score is considered to be of greater quality, taking much of the guesswork out of content improvement.

Prerequisites

  • To use the Acrolinx functionality, the applicable license must be in place and the installation recipe applied. Additionally, users must have established an account with Acrolinx. Contact Stibo Systems for details.
  • It should be determined which users need access to the Acrolinx Sidebar prior to its configuration in the Web UI. Privileges to view the Acrolinx sidebar are controlled by configurations within the Web UI designer and not through User Actions applied in the workbench. However, users must be granted the required privileges (from within the workbench) to view and edit attribute values.

Configuration

When a Global Navigation Panel component is configured, the Acrolinx Sidebar can be installed as a button on a Product Summary Card, as shown below:

Configuring the Acrolinx Sidebar for Product Summary Cards

To configure the Acrolinx Sidebar on a Product Summary Card, first follow steps one through three in the Below Title Product Summary Card topic in the Web User Interfaces documentation here. This will allow you to determine which information should display in the primary Product Summary Card.

  1. On the Product Summary Card Properties page in the designer, a dropdown field is accessible for the 'Secondary Summary Card Section' parameter. Provided the required components and licenses have been properly applied, clicking the dropdown will show 'Acrolinx' as a selectable option.

  1. When selected, an 'Edit component' window displays that allows you to configure the Acrolinx Sidebar. There are three parameters to enable configuration:
  • Acrolinx Server URL: This property is required. Enter the URL to the sidebar on the Acrolinx Server (for example, <SERVER_ADDRESS>[:<PORT>]/). The server address is determined by the user's agreement with Acrolinx.
  • Acrolinx User Groups: The list of user groups for which the Acrolinx Sidebar is valid. If user groups are added, only members of these groups will be able to view the Acrolinx Sidebar. If left empty, the sidebar will be visible to all users.

Click 'Add...' to browse to or search for the relevant user group(s). Click 'Remove' to remove a selected user group. Click 'Up' or 'Down' to reorder a selected user group.

  • Allow checking of inherited values: Check this box to allow the sidebar to check inherited values as well as local values. This applies to both normal tree inheritance and dimension inheritance.
  1. Click Save, then Close on the designer to save the configurations and exit the designer.

For information on how to access and use the Acrolinx functionality via the Acrolinx Sidebar component, refer to the Accessing the Acrolinx Sidebar and Using the Acrolinx Sidebar sections later in this topic.

Accessing the Acrolinx Sidebar

To access the Acrolinx Sidebar configured on a Below Title Product Summary Card, follow the steps below.

  1. As shown in the screenshot below, click the Acrolinx toggle button on the far right of the Product Summary Card to open the Acrolinx Sidebar. On first launch, the sidebar will display a sign-in prompt. The 'Server address' field will be prepopulated with the sidebar URL (either server or cloud) that was provided when configuring the component in the Web UI designer.

  1. At the top of the panel is a pin button, and an 'X' button. Clicking this pin changes its color from gray (disengaged) to blue (engaged). When engaged, regardless of where a user navigates in the Web UI, display of the Acrolinx Sidebar will persist. To disengage the pin, click the pin again. When disengaged, the panel will retract when the user navigates elsewhere in the Web UI. Clicking the 'X' causes the panel to retract immediately.
  2. Click SIGN IN to open the Acrolinx sign-in page. The page will open in your browser.
  3. On the sign-in page, enter your Acrolinx username and password, then click SIGN IN.

Note: This login information is not the same as your STEP login.

  1. After logging in, the Acrolinx website displays a prompt to provide access to 'Acrolinx for STEP.' Click CONFIRM.

  1. Close the page after receiving the 'You've successfully signed in' message.

  1. The enabled Acrolinx Sidebar now displays on the right side of the screen. When first opened, the sidebar may display a list of options such as Spelling, Grammar, Style, Valid terms, and Tone of voice, as shown in the below screenshot.

Note: The actual options displayed are driven by users' business needs and configured on the Acrolinx Server side. These options are not determined by Stibo Systems or controlled through configurations in the Web UI.

Using the Acrolinx Sidebar

Note: The functionality of the Acrolinx Sidebar itself is controlled by Acrolinx, and the specific criteria checked by the sidebar is determined by users, not by Stibo Systems. For more information on configuring Acrolinx functionality within the Acrolinx Sidebar, refer to the Acrolinx documentation (https://docs.acrolinx.com/doc/en).

  1. Navigate to the object containing the content that you want to check. This typically will be a product object, and content will typically be on a Node Details screen.
  2. To begin a check, click on the Acrolinx icon at the top of the sidebar.

  1. Next, click on the CHECK button. Clicking CHECK sends data to Acrolinx for inspection.

  1. Once the check completes, Acrolinx returns a list of issues (contained in 'cards') along with an overall Acrolinx Score in the upper right-hand corner of the Sidebar. The Acrolinx Score indicates the overall quality of the content. The identified issues display as black text in their respective cards.
  2. Click on the black text (or any blank area) in the card to highlight the problematic content in the text field on the Node Details screen. To automatically correct the issue, click on the green text in the card. Click on MORE INFORMATION to go to an Acrolinx page in your browser that provides more information on the error.

The below screenshot shows an example of an Acrolinx check run on product attribute values on a Node Details Page. The highlighted error is a prompt to add a comma. An Acrolinx Score of 86 is displayed in the upper right corner of the sidebar, with the number of located errors (3) beneath it.

Note: If the problematic text is within a rich text field and you open the rich text editor, the text will not be highlighted within the rich text editor.

  1. Click on the Acrolinx Score to view to the Acrolinx Scorecard, which opens in a new browser tab (or window, depending on your browser settings).

Filtering Attributes and Inline References From Acrolinx Checks

It is possible to filter out which STEP attributes are checked by the Acrolinx Sidebar and also prevent the content of inline references from being included in the checks. This is done by setting up the relevant rules (for example, exclusion_elements and inclusion_elements) in a context segmentation definition (CSD) file on the Acrolinx Server. The below subsections give a brief overview of how to set this up, but does not go into extensive detail. For more information about configuring the server-side extraction, refer to the Acrolinx documentation (https://docs.acrolinx.com/doc/en).

Note: Each customer will most likely need a CSD file that is specific to them to define which attributes to include in the check and which to exclude (not all editable content will need to be checked).

Filtering Attributes From Checks

One method to filter out attributes from Acrolinx Sidebar checks is to configure the Web UI to have a specific 'Acrolinx page' (which could be a tab page on a screen) that only contains specific attributes that should be checked. This is fully configured in the Web UI and not on the Acrolinx server.

Another method is to set up rules on the Acrolinx Server that govern which fields to check and which to ignore by using a CSD file.

The following is an example of the text that is sent to the Acrolinx Server. The ID of the attribute is stored in the data-step-component-id attribute.

<div class="FormFieldWidget" lang="fr-FR" data-element-id="Description" data-step-component-id="Description" id="acrolinx_integration0">This is some content</div>

It is possible to exclude the attribute reference by setting the following in the relevant CSD file on the Acrolinx Server:

exclusion_elements=<div data-step-component-id="Description">,<div data-step-component-id="AnotherAttributeID">

Filtering Resolved Inline References From Checks

Resolved inline reference values will be checked if they are not set up as exclusion_elements in the CSD file on the Acrolinx Server. If not configured for exclusion, the resolved values will be checked and errors will appear in the sidebar. But even if the errors are corrected, the changes will be discarded upon save and the original values will return. As such, it is useful to have the sidebar avoid checking the values of inline references in the first place.

This is an example of the text that is sent to the Acrolinx Server when the content contains an inline reference:

<div class="FormFieldWidget" lang="fr-FR" data-element-id="Description" data-step-component-id="Description" id="acrolinx_integration0"><p>This <span class="step-rt-fmt-bolditalic">has</span> a spellling mistake.</p><p>And a second paragraph.</p><p>And a reference to another object <span attrid="" class="step-rt-fmt-non_editable step-rt-fmt-ref" contenteditable="false" equalsign="=" includeattrname="false" objecturl="step://product?id=22359" resolveto="objname" separator=";" stibotag="ref">Edgar Allan Poe - The Pit and The Pendulum</span></p><p>is 6 <span class="step-rt-fmt-non_editable step-rt-fmt-lt" contenteditable="false" stibotag="lt">&lt;</span> 5?</p></div>

Specifically, the inline reference is defined as:

<span attrid="" class="step-rt-fmt-non_editable step-rt-fmt-ref" contenteditable="false" equalsign="=" includeattrname="false" objecturl="step://product?id=22359" resolveto="objname" separator=";" stibotag="ref">Edgar Allan Poe - The Pit and The Pendulum</span>

It is possible to exclude the inline reference by setting the following in the relevant CSD file on the Acrolinx Server:

exclusion_elements=<span contenteditable="false">

Considerations and Limitations

Acrolinx Sidebar Functionality

  • The Acrolinx Sidebar analyzes content on a per-product basis and does not handle batch or multi-node processing of products. However, since direct user interaction is key to content improvement, this hands-on approach ensures that data is of the highest possible quality.
  • All editable fields that are visible on the Web UI screen being checked by the Acrolinx Sidebar are passed to Acrolinx. Only attribute value fields are checked; name fields are not checked. Read-only fields are not checked, nor are they recognized as text by the sidebar.

Note: If the Web UI screen contains multiple tabs, the Acrolinx Sidebar only operates on the tab that is currently selected. Also, some attributes may not be visible due to vertical scrolling, but they will still be checked.

Acrolinx Updates

  • For customers running the Acrolinx Sidebar, refer to the Acrolinx support / help center website for information on major updates to the Acrolinx core platform: https://support.acrolinx.com/hc/en-us/.
  • Before updating to a new version of Acrolinx, contact Stibo Systems for advice on compatibility between STEP and Acrolinx.