Integrate Acrolinx with a Third-Party Terminology Solution

If you use a third-party terminology solution, you can configure Acrolinx so that you can use both systems together. For example, suppose that you want to use Acrolinx to check your content, but use a third-party solution to manage your terminology workflow. You can configure Acrolinx so that while writers check their content with Acrolinx, they’re redirected to the third-party solution when they click the links for the term help or term contribution.

To integrate Acrolinx with your external terminology solution, you must configure the URL templates for the term help and term contribution in the core server properties file. Also, your third-party terminology solution must accept data sent through these URL templates. In most cases, this requires a customized solution.

Use a Third-Party System for Term Help

You can configure Acrolinx so that when writers open the term help, they'll see the help from your third-party terminology management solution instead of Acrolinx.

You do this by defining a template for how the URL should be constructed. The template syntax is the same as the syntax that is defined in the RFC 6570 standard. You don't need to know all about this standard to configure the template, but if you're interested, you can read the template specifications on the Internet Engineering Task Force (IETF) website.

For example, the default template for the term help URL has the following structure:

{+baseUrl}{+termHelpContext}{?termUniversalId}

This template would resolve to a URL that resembles the following example:

https://acrolinx.demo-inc.com/termhelp/?termUniversalId=690bfacb-bc26-4f8a-b63e-9c795873b2a2&locale=en
Here's how the default template is resolved:

  • {+baseUrl} resolves to https://acrolinx.example.com
  • {+termHelpContext} resolves to /termHelp/
  • {?termUniversalId} resolves to ?termUniversalId=690bfacb-bc26-4f8a-b63e-9c795873b2a2&locale=en .

However, lets say you use the quickTerm V5 tool produced by Kaleidoscope. You would configure the template to look something like this:

termHelpUrl.template=http://acme-intranet.com/qtweb/Pages/Main/Search.aspx?tuuid={termUniversalId}&euuid{entryUniversalId}&showOnly=true

For quickTerm V6, the syntax looks something like this:

termHelpUrl.template=http://acme-intranet.com/terminology/search?entryUUID={entryUniversalId}&termbaseId=[Termbank-ID]

This would configure Acrolinx to call the help from quickTerm while passing the Acrolinx universal ID for the term and the head term (also known as "term entry" or "concept" in other systems).


To configure a custom term help URL, follow these steps:

  1. Open your overlay of the core server properties file.

    You find the overlay for the core server properties file in the following location:

    %ACROLINX_CONFIGURATION_ROOT%\server\bin\coreserver.properties
  2. Add the following property: 

    termHelpUrl.template=<URL_TEMPLATE>

    As mentioned previously, a quickTerm help URL might look something like this:

    termHelpUrl.template=http://acme-intranet.com/qtweb/Pages/Main/Search.aspx?tuuid={termUniversalId}&euuid{entryUniversalId}&showOnly=true


    You can use the following parameters for the URL template:

    ParameterDetails
    baseUrlThe base URL of your Core Platform. Use {+baseURL} to use your Core Platform or enter the address of your third-party solution.
    termHelpContextThe term help page of your terminology solution. Use{+termHelpContext} to use the Acrolinx term help page or enter the path to the term help page in your third-party solution.
    termIdA custom term identifier that you can use to retain identifiers generated by another system.

    If you've imported your custom identifiers into Acrolinx, you can pass them back to your third-party solution.

    entryIdA custom term entry identifier that you can use to retain identifiers generated by another system.

    If you've imported your custom identifiers into Acrolinx, you can pass them back to your third-party solution.

    termSurfaceThe name of the term.
    termDatabaseIdThe database ID of the term.
    termUniversalIdThe universal ID of the term.
    entryUniversalIdThe universal ID of the term entry.
  3. Save your changes and restart the core server.

Contribute Terms to a Third-Party System

You can use Acrolinx to discover terms in your content and give people the option to contribute terms to a terminology database. As a reminder, the default workflow for contributing terms looks like this:

  • You check that your content and all discovered terms are listed on the Scorecard and in the Acrolinx Sidebar.
  • In the Sidebar, you can click a "Contribute Term" button that is available for each discovered term.
  • This button opens up a form within the Sidebar where you can add a comment about your contribution before you submit it to the Acrolinx terminology database.

However, if you use another terminology solution you'll want to bypass parts of this workflow. Instead, when you click "Contribute Term", you can have Acrolinx open a third-party term contribution form. To enable this feature, you need to disable the default behavior and configure a custom term contribution URL.

To disable the default behavior and configure a custom term contribution URL, follow these steps:

  1. Open your overlay of the core server properties file.

    You find the overlay for the core server properties file in the following location:

    %ACROLINX_CONFIGURATION_ROOT%\server\bin\coreserver.properties
  2. Add the following properties: 

    termContribution.disableInternalTermContribution=true
    termContributionUrl.template=<URL_TEMPLATE>

    The template must be specified according to RFC 6570. The default value of the template is {+baseUrl}{+termContributionContext}{?locale} #surface={+escapedSurface}{&language}{&userid}&{contextFieldName}={+escapedContext}

    For example, if you use quickTerm, your term contribution URL might look something like this:

    termContributionUrl.template=http://acme-intranet.com/qtweb/Pages/Main/TermRequest.aspx?term={surface}&tbname=%3CAcrolinx%3E&sourceLang={language}&customUserName={userid}&contextField={contextFieldName}&contextValue={context}

    If you use quickTerm V5 with SDL MultiTerm, your term contribution URL might look something like this:

    termContributionUrl.template=http://acme-intranet.com/qtweb/Pages/Main/TermRequest.aspx?term={surface}&tbname=my_multiterm_db&sourceLang={language}&customUserName={userid}&contextField={contextFieldName}&contextValue={context}

    For quickTerm V6 with SDL MultiTerm, your term contribution URL might look something like this:

    termContributionUrl.template=http://acme-intranet.com/terminology/search?new-term-request&term{surface}&sourceLangName={language}&tbid=[Termbank-ID]&customUserName={userid}


    Of course, you should replace sample values acme-intranet.com with the address of your quickTerm server and my_multiterm_db with the name of your MultiTerm terminology database.

    You can use the following parameters for the URL template:

    ParameterDetails
    baseUrlThe base URL of your server. Use {+baseURL} to use your Core Platform or enter the address of your third-party solution server.
    termContributionContextThe term contribution page of your terminology solution. Use {+termContributionContext} to use the Acrolinx term contribution page or enter the address of the term contribution page your third-party solution.
    localeThe locale of the user interface.
    surfaceThe plain text version of the contributed term.
    escapedSurfaceThe Acrolinx-escaped and optionally Base64-encoded version of the contributed term.
    languageThe language of the term.
    useridThe user ID of the contributing user.
    contextFieldNameThe name of the context field.
    contextThe plain text context of the contributed term.
    escapedContextThe Acrolinx-escaped and optionally Base64-encoded context of the contributed term.
  3. (Optional) Add the following property: termContributionUrl.enableBase64Encoding=true 

    This property enables the Base64 encoding of the term and the context in the term contribution URL.

  4. Save your changes and restart the core server.