Close

Install Outlook Integration

Outlook Integration is an extension to Content Services and Microsoft Outlook that allows you to save and file your emails to Alfresco from within Microsoft Outlook, in a centralized and structured way.

You can drag and drop emails in and out of the repository, and add metadata automatically when an email is filed. Other features include leveraging Alfresco’s in-built workflow processing and filtered search capabilities.

Advanced metadata support includes:

  • Full support for custom models
  • A configurable and dynamic metadata dialog
  • The ability to map metadata configuration to a path, folder type, or aspect
  • The ability to assign the same metadata to a set of emails in Microsoft Outlook, or a set of files in your file system

You can apply a sorted view to the Alfresco repository (from within Microsoft Outlook), and page through a folder or site if it contains a large number of files.

You can also create new versions of existing documents, review the version history of a versioned document, and revert back to previous versions.

This information helps system administrators to install, configure, and manage Outlook Integration.

The software you need to install Outlook Integration is as follows:

  • AMP files that are applied to Alfresco and provide the administration tooling in Alfresco Share
  • A server license that is applied in Alfresco Share
  • Client licenses that can be applied in Alfresco Share or in Microsoft Outlook
  • A zip file that provides an addition to the Microsoft Outlook toolbar, which you unzip and install before you start up Microsoft Outlook

If you plan to enable the transformation of MSG and EML files into PDF format, you need to install and configure Alfresco Transform Service.

You can download the Outlook Integration software from Hyland Community.

Prerequisites

There are a number of software requirements for installing Outlook Integration. See Supported Platforms for more information.

You need one of each of the following components:

Operating system requirements

You can use one of the following operating systems:

  • Microsoft Windows 11 with latest updates
  • Microsoft Windows 10 with latest updates

Software requirements

You can use one of the following Outlook releases:

  • Microsoft Outlook for Office 365 (x86/x64) with latest updates
  • Microsoft Outlook 2019 (x86/x64)
  • Microsoft Outlook 2016 (x86/x64)
  • Visual Studio Tools for Office 4.0 Runtime
  • Microsoft .NET Framework 4.7.2 or above

Alfresco requirements

  • Alfresco Content Services 23.x.

See the Supported platforms for more.

Alfresco Search Services 2.0 and above

If you’re using Alfresco Search Services or Alfresco Search and Insight Engine 2.0 and above in combination with Outlook Integration 2.10 and above, you must add the messageId property to the shared.properties file for SOLR. See the Indexing recommendations (Cross locale section) for the product you’re using to locate this file:

Add the following lines to the configuration:

alfresco.cross.locale.property.#={http://www.alfresco.org/model/imap/1.0}messageId
alfresco.cross.locale.property.#={http://www.westernacher.com/alfresco/models/wpsmail-v2}messageId

where # is an ascending index number that hasn’t been used.

Starting from Outlook Integration 2.10, you must also enable cross-locale data types in Alfresco Search Services or Alfresco Search and Insight Engine 2.0 and above.

Follow the steps in the Indexing recommendations (Cross locale section) for the product you’re using to enable this configuration. This applies for both the messageId property addition and enabling cross-locale data types:

Note: These changes require a SOLR restart, but no reindex.

Alfresco Search Enterprise

If you’re using Alfresco Search Enterprise in combination with Outlook Integration, you must add the messageId property to the shared.properties file for Elasticsearch configuration in Alfresco Content Services. See the recommendations in the Exact Term Search section to locate this file:

Add the following lines to the configuration:

alfresco.cross.locale.property.#={http://www.alfresco.org/model/imap/1.0}messageId
alfresco.cross.locale.property.#={http://www.westernacher.com/alfresco/models/wpsmail-v2}messageId

where # is an ascending index number that hasn’t been used.

You must also enable cross-locale data types in Search Enterprise.

Follow the steps in the Exact Term Search (Cross locale section) to enable this configuration. This applies for both the messageId property addition and enabling cross-locale data types:

Java requirements

  • Java: OpenJDK 17 is recommended. This needs to be installed on the server only (i.e. not the Outlook clients). See the Content Services Supported Platforms for more information.

Access to Docker image

The Docker image that you can use for the Outlook Integration T-Engine is uploaded to a private registry, Quay.io. You’ll need access to the following image:

transform-outlook
  • A Quay.io account is needed to pull Docker images that are needed for Outlook Integration.

Note: Alfresco customers can request Quay.io credentials by logging a ticket at Alfresco Support. These credentials are required to pull private (Enterprise-only) Docker images from Quay.io.

Note: Make sure that you request credentials for Alfresco Content Services and Alfresco Outlook Integration, so that you can use the additional transform-outlook-1.2.x Docker image.

Note: It is recommended that you familiarize yourself with the concepts of containerized deployment before working with Docker.

Install AMPs

There are three steps to installing Outlook Integration:

  • Install the Alfresco AMP files (the Alfresco Outlook Server software)
  • Apply the licenses
  • Install the Microsoft Outlook zip file (the Alfresco Outlook Client software)

Make sure you are running the correct versions of operating system and software before you install the AMP files.

  1. Stop the Alfresco server.

  2. Browse to Hyland Community, download and unzip the Outlook Integration zip package:

    alfresco-outlook-integration-3.0.x.zip

  3. Copy the provided AMP files to the Alfresco amps and amps_share directories.

    Copy this file to the amps directory:

    alfresco-outlook-repository-3.0.x.amp

    and this file to the amps_share directory:

    alfresco-outlook-share-3.0.x.amp

  4. To install the AMP files, run the apply_amps.bat file from the Alfresco bin directory.

    Check the output from the script to ensure that the AMP files have installed successfully.

  5. Restart the Alfresco server.

  6. Open Alfresco Share, and click Admin Tools on the Alfresco toolbar to see the Outlook configuration section.

    The URL is: http://localhost:8080/share/page/console/admin-console/mail-customization-config

    where localhost:8080 is your Alfresco server and port number.

If you plan to transform MSG and EML files into PDF format, you need to install and configure the Transform Service, and then select an installation method under Install Transform Engine for more information.

Install server and client licenses in Alfresco Share

Use Alfresco Share Admin Tools to install your Outlook Integration server and client licenses.

Ensure that you have applied the Alfresco Outlook Server AMP files (see Install Outlook Integration AMPs).

  1. Open Alfresco Share, and click Admin Tools on the Alfresco toolbar.

    The URL is: http://localhost:8080/share/page/console/admin-console/mail-customization-config

    where localhost:8080 is your Alfresco server and port number.

  2. Select Licenses and click Edit.

  3. Open the server license file in a text editor, and copy and paste the contents into the Server License field.

  4. (Optional) Open the client license file in a text editor, and copy and paste the contents into the Outlook Client License field.

    Alternatively, specify the client license in Microsoft Outlook in Alfresco Client > Configure > License.

    Note: There is no Lotus Notes capability, so you do not need to add information in Lotus Notes Client License.

  5. Click Save.

    The server license status, number of current users, maximum users, product version and other information is displayed. Check that the license status is valid.

    Note: If you added a client license, the license key is displayed, with a message to check the Alfresco Client > Configure > License tab in Microsoft Outlook (do this check after you have installed Alfresco Outlook Client).

    Note: The server and client licenses are stored in a system folder in Alfresco, and will persist after a restart in containerized environments. The folder location is: /sys:system/cm:wps_alfresco_mail_integration/cm:license/cm:mail.

Install Transform Engine

The Outlook Integration Transform Engine (or T-Engine) enables transformation of MSG and EML files into PDF format when used with the Transform Service. The Outlook Integration T-Engine is available both as a Docker image and as a Web Archive (WAR) file.

Install T-Engine on Tomcat

If you wish to use a Tomcat application server, you can use the WAR bundle to install the Outlook Integration T-Engine.

Note: Check the supported Tomcat version based on your version of the Content Services documentation before continuing.

  1. Install the latest required version of Tomcat, for example, Tomcat 10 to run as a service.

    See the Tomcat documentation for more information about configuring and using a Tomcat server.

    For information about securing Tomcat, see Tomcat security considerations.

  2. Rename the WAR file from transform-outlook-webapp-${version}.war to transform-outlook.war.

    You’ll find the file, transform-outlook-webapp-2.0.0.war, in the distribution zip.

  3. Copy the WAR file into your <TOMCAT_HOME>/webapps folder.

  4. To enable ActiveMQ in the Outlook T-Engine, set the following URL property in JAVA_OPTS:

    -DACTIVEMQ_URL=${activemq.url}

  5. To enable the shared file store in the Outlook T-Engine, set the following URL property in JAVA_OPTS:

    -DFILE_STORE_URL=${shared.file.store.url}

  6. Start the Tomcat service.

  7. Test that the T-Engine is running:

    1. Open your browser and access http(s)://${SERVER}:{PORT}/transform-outlook to load the T-Engine test page.

    2. Add the following configuration property in alfresco-global.properties:

       localTransform.transform-outlook.url=http(s)://${SERVER}:{PORT}/transform-outlook
      

Install T-Engine using Docker Compose

To deploy the Outlook Integration T-Engine with the Transform Service, you’ll need to update your Docker Compose file to include the Outlook T-Engine.

Note: While Docker Compose is often used for production deployments, the Docker Compose file provided is recommended for development and test environments only. Customers are expected to adapt this file to their own requirements, if they intend to use Docker Compose to deploy a production environment.

  1. Add Outlook Integration T-Engine container to your docker-compose.yaml file:

     transform-outlook:
         image: quay.io/alfresco/transform-outlook:2.0.0
         mem_limit: 2g
         environment:
             JAVA_OPTS: " -Xms256m -Xmx512m"
             ACTIVEMQ_URL: "nio://activemq:61616"
             ACTIVEMQ_USER: "admin"
             ACTIVEMQ_PASSWORD: "admin"
             FILE_STORE_URL: "http://shared-file-store:8099/alfresco/api/-default-/private/sfs/versions/1/file"
         ports:
             - 8091:8090
         links:
             - activemq
    
  2. Add the following JAVA_OPTS property to the alfresco container:

     -DlocalTransform.transform-outlook.url=http://transform-outlook:8090/
    

See the Content Services documentation - T-Engine configuration for more details. For further development, see Content Transformers and Renditions Extension Points.

Install Alfresco Outlook Client in Microsoft Outlook

Inside the Outlook Integration zip is another zip file that installs the Alfresco Outlook Client into Microsoft Outlook.

You might need local administrator rights to install .NET and Microsoft VS Tools for Office Runtime. Ensure you have already installed the required AMP files in your Alfresco instance (see Install Outlook Integration AMPs).

Note: If you are distributing Alfresco Outlook Client across an organization, see Install the Alfresco Outlook Client in unattended mode for guidance on installing in unattended mode.

  1. Extract the contents of the alfresco-outlook-client-3.0.x.zip file using a standard unzip tool.

  2. Navigate to the directory containing the unzipped content and double click the install.bat file.

    The Alfresco Outlook Client installer checks whether the required components already exist on the system. The required files are installed and the Alfresco Outlook Client installer wizard opens.

  3. Read the copyright information and click Next.

  4. Specify the folder where you would like the Outlook Client to be installed and click Next.

    Alternatively, accept the default path specified.

  5. Click Next to confirm that the installation can start.

  6. Select your preferred language, and click Continue.

    Microsoft Office Primary Interop Assemblies are also installed, if they do not already exist in your version of Microsoft Office.

  7. Click Close to complete the installation.

  8. Open Microsoft Outlook.

    You will see an Alfresco Client tab on the toolbar. Click this tab to view options for configuring the Alfresco Outlook Client.

    If you did not enter a client license key in Alfresco Share, you must enter one when you open Microsoft Outlook. Navigate to Alfresco Client > Configure > License to enter your key.

Install Alfresco Outlook Client in unattended mode

You can automate the Alfresco Outlook Client installation by using the msiexec command.

You might need local administrator rights to install .NET and Microsoft VS Tools for Office Runtime. Ensure you have already installed the required AMP files in your Alfresco instance (see Install Outlook Integration AMPs).

  1. Extract the contents of the alfresco-outlook-client-3.0.x.zip file using a standard unzip tool.

  2. Locate x64/AlfrescoOutlookClient_x64_3.0.x.msi or x86/AlfrescoOutlookClient_x86_3.0.x.msi, depending on whether you are running a 64-bit or 32-bit version of Windows.

  3. From a command line, navigate to the x64 or x86 directory, and run the msiexec command. For example:

    For an interactive installation:

     msiexec /i AlfrescoOutlookClient_x86_3.0.x.msi HOST=127.0.0.1:8080 AUTH=basic
    

    For a non-interactive installation:

     msiexec /i AlfrescoOutlookClient_x86_3.0.x.msi HOST=127.0.0.1:8080 AUTH=basic /quiet
    

    For a non-interactive installation with OpenId Connect enabled:

     msiexec /i AlfrescoOutlookClient_x86_3.0.x.msi HOST=127.0.0.1:8080 AUTH=oidc /quiet
    

    Note: Microsoft Office Primary Interop Assemblies are also installed, if they do not already exist in your version of Microsoft Office.

    Here is a full list of parameters that can be used with the msiexec command:

    Parameter Values Description
    HOST Format: <http|https>://<hostname>:<port> Sets the Alfresco server URL. Port is optional.
    SHARE Default: share Sets context to Alfresco Share.
    ALFRESCO Default: alfresco Sets context to the Alfresco repository.
    CULTURE en|de|es|it|fr|ja|ru|zh-cn|pt-br|nl|nb-no|cs|da|fi|pl|sv Default: en Sets language for Alfresco Outlook Client.
    SHAREALT No default Sets alternative URL for Alfresco Share.
    AUTH basic|windows|oidc Sets authentication type.
    APPTITLE Default: Alfresco Outlook Plugin Sets a custom title for Alfresco Outlook Client. Format: "My Custom Title"
    LANGS No default Sets the available languages for the Alfresco Outlook Client. Format: "en,de,fr". See CULTURE parameter for available language codes.

    Added in Outlook Integration 2.9.2.
    OIDCHOST Format: https://<idsHost>:<port> Sets the URL for the Identity Service that is used for OpenId Connect.

    Added in Outlook Integration 2.10.
    OIDCCID Default: alfresco Sets the OpenID Connect Client that is used in the Identity Service.

    Added in Outlook Integration 2.10.
    OIDCREALM Default: alfresco Sets the realm that is used in the Identity Service.

    Added in Outlook Integration 2.10.
    OIDCURL Default: https://127.0.0.1:6543/OutlookCallback Sets local redirect callback URL that is used in the Outlook Client to do the token exchange with the Identity Service.

    Added in Outlook Integration 2.10.
  4. Verify that Alfresco Outlook Client has installed in Microsoft Outlook.

    You will see an Alfresco Client tab on the toolbar. Click this tab to view options for configuring the Alfresco Outlook Client.

    If you did not enter a client license key in Alfresco Share, you must enter one when you open Microsoft Outlook. Navigate to Alfresco Client > Configure > License to enter your key.

Uninstall

This section walks through how to uninstall Outlook Integration.

Uninstall Outlook Integration

To uninstall the Alfresco Outlook files, use the Module Management Tool (MMT). To completely remove Outlook Integration, you must uninstall the Outlook package from Alfresco, as well as from Microsoft Outlook on all Windows clients.

This information provides uninstall directions for Alfresco Content Services.

Note: See Uninstall Outlook Client to uninstall the Alfresco Outlook Client.

  1. Stop the Alfresco server.

  2. Use the information in Uninstall an Amp file to uninstall each AMP file.

    For example, from the Alfresco root directory, you need two commands:

     java -jar bin/alfresco-mmt.jar uninstall com.westernacher.wps.AlfrescoMailIntegrationRepository tomcat/webapps/alfresco.war
    
     java -jar bin/alfresco-mmt.jar uninstall com.westernacher.wps.AlfrescoMailIntegrationShare tomcat/webapps/share.war
    

    Use these commands to check whether the AMP files were removed:

     java -jar bin/alfresco-mmt.jar list tomcat/webapps/alfresco.war
                   java -jar bin/alfresco-mmt.jar list tomcat/webapps/share.war
    
  3. Delete the tomcat/webapps/alfresco and tomcat/webapps/share folders in the Alfresco installation directory.

    Deleting these directories forces Tomcat to read the edited WAR files when Alfresco is restarted.

  4. Restart the Alfresco server.

Uninstall Outlook Client

Learn how to uninstall the Alfresco Outlook Client.

Note: You can uninstall the Outlook client from your Microsoft Windows machines. Using the standard Programs > Uninstall Program feature in Windows. Look for Alfresco Outlook Client and uninstall it.

There are two different ways to uninstall the Alfresco Outlook Client for enterprise installations:

  1. Use the original .msi file to uninstall the client by running a single command.

     msiexec /x <Path_to_msi_file> /q
    

    where /x = uninstall, /q = silent.

  2. Use the identifying number.

    The identifying number is tied to a specific version of your Outlook Integration. If your users have different versions installed, you need to find out the product IDs for each version.

    1. Install the Outlook plugin version that was distributed to the machines of your end users.

    2. Run the PowerShell command:

       get-wmiobject Win32_Product | Format-Table IdentifyingNumber, Name, LocalPackage -AutoSize
      
    3. Search for Alfresco Outlook Client and copy the identifying number from the first column of the output (including the brackets).

    4. Run the msiexec command with administration permissions on the end user machine using the identifying number. For example:

       msiexec /x  {723B7FFD-3B53-4786-9741-D845BC1796A3} /q
      

      where /x = uninstall, /q = silent.

      Note: For more Microsoft msiexec documentation, see Command-Line Options.

Edit this page

Suggest an edit on GitHub
This website uses cookies in order to offer you the most relevant information. Please accept cookies for optimal performance. This documentation is subject to the Documentation Notice.