Setting up DocuWare for Outlook on-premises

DocuWare for Outlook on-premises links a local DocuWare installation with Microsoft Outlook.

To install the add-in, first register an OAuth application in Microsoft Entra ID, assign the required Graph permissions, and note the tenant, client ID, and secret. Next, add these values to the DocuWare server (dwmachine.config) and ensure the DocuWare site is accessible via HTTPS. Finally, customise the Outlook manifest with your DocuWare URL and the client ID, then deploy the manifest to the desired Outlook clients.

When these steps are complete, users can file e-mails and attachments directly to their on-premises DocuWare trays or file cabinets.

Prerequisites and limitations

Prerequisites:

A DocuWare Connect to Outlook license is required to access and use the add-in.
DocuWare setup was installed without any errors.
HTTPS Certificate is created and assigned to the website in IIS, so that the entire DocuWare is accessible via https://{{YOUR_DOMAIN}}/DocuWare

Make sure call to https://{{YOUR_DOMAIN}}/DocuWare/Outlook succeeds

Limitations:

Storing emails from a shared mailbox is not supported in the desktop (classic) version of Microsoft Outlook.
The in-app feedback feature is unavailable, as DocuWare for Outlook on-premises cannot connect to DocuWare Cloud to submit feedback.

Entra OAuth app registration

To use DocuWare for Outlook on-premises with your Outlook clients, an OAuth app registration must be created in Microsoft Entra.

Go to Microsoft Entra App registration and create a new app, for example:

Now the app is created. In the next steps, you configure the app.

1. Expose an API

First, open Expose an API to add a new application ID Uri here.

In the right panel add your DocuWare URL to the application ID URI and Save.

Next, add the access_as_user scope and fill the data in the right pane, for example:
- Scope name: access_as_user
- Who can consent: Admins and users
- Admin consent display name: Read-only access to user emails and profiles.
- Admin consent description: Allow DocuWare for Outlook to have read-only access to users’ emails and profiles.
- User consent display name: Read-only access to your emails and profile.
- User consent description: Allow DocuWare for Outlook to have read-only access to your emails and profiles.
- State: Enabled

4. Click Add a client application and enter the following ID to pre-authorize all Microsoft Office application endpoint.

ea5a67f6-b6f3-4338-b240-c655ddc3cc8e

This ID is valid for all Microsoft application endpoints.

2. Authentication

Redirect Uris

Switch to the Authentication tab and add the following redirect URIs to the OAuth application registration:

https://YOUR_DOCUWARE_URL/DocuWare/Outlook-Frontend/
https://YOUR_DOCUWARE_URL/DocuWare/Outlook-Frontend/auth
https://YOUR_DOCUWARE_URL/DocuWare/Outlook-Frontend/login
https://YOUR_DOCUWARE_URL/DocuWare/Outlook-Frontend/adminConsentResult.html
brk-multihub://YOUR_DOCUWARE_URL

Note: entering a link without HTTPS
Depending on the administrator’s Microsoft version and region, the Authentication tab in Azure might show a different view. In the new default view it's not possible to add the brk-multihub://<Your_DocuWare_URL>. In this case, use the link To switch to the old experience, please click here to enter the brk-multihub://<Your_DocuWare_URL> URL in the previous interface.

Implicit grant and hybrid flows

On the same page, make sure that Access Tokens and ID Tokens are activated.

3. Create a client secret

DocuWare for Outlook also requires a secret to connect securely to the user's Office 365 account.

This secret is required in a later step.

4. API Scopes

4.1 Microsoft APIs

Switch to the API permissions tab to define the API permissions required by DocuWare for Outlook. Those are all to be added as Microsoft Graph API permissions.

email
offline_access
openid
profile
Contacts.Read
Contacts.Read.Shared
MailboxSettings.Read
MailboxSettings.ReadWrite
Mail.Read
Mail.ReadWrite
Mail.ReadWrite.Shared
User.Read

4.2 APIs your organization uses

Click again on Add a permission, switch to APIs my organization uses, type in the name of the OAuth app you are currently creating (e.g., DocuWare for Outlook on-premises), and click on the entry in the result list.

Finally, check access_as_user and click on Add permission.

5. Grant admin consent to the OAuth app

Make sure to record the following values, which you will need in the next steps:

Microsoft Tenant ID (tenantid)
Application Client ID (clientid)
Application Client Secret

Completing this action finalizes the admin-consent process. After granting consent, you should see a confirmation screen like the one shown below.

This step has to be made by the Microsoft Azure AD Global Admin

On the DocuWare Server

1. Extend dwmachine.config

Switch to the server where DocuWare is installed and open a PowerShell terminal with administrative rights on the folder where DocuWare.Setup.Server.Cmd.exe is located (i.e., C:\Program Files (x86)\DocuWare\Setup Components).

Execute these commands to add required values to your server’s dwmachine.config file.

./DocuWare.Setup.Server.Cmd.exe configureMachine --key="D4O.TenantId" --value="theTenantGuid"

./DocuWare.Setup.Server.Cmd.exe configureMachine --key="D4O.OfficeClientId" --value="theClientId"

./DocuWare.Setup.Server.Cmd.exe configureMachine --key="D4O.OfficeClientSecret" --value="theClientSecret" --encrypted

2. Enable HTTPS for LocalWebServices and AuthorityAddress

As Outlook requires having your application hosted via https, it's crucial to have the URL working & stated as HTTPS.

<Setting Key="LocalWebServices" Value="<https://{{YOUR_DOCUWARE_URL}}/DocuWare/>" Encrypted="false" />

<Setting Key="AuthorityAddress" Value="<https://{{YOUR_DOCUWARE_URL}}/DocuWare/>" Encrypted="false" />

3. Create Outlook Manifest.xml file

Access the Outlook manifest.xml file (available in the expandable section below) and copy the XML text into a local file on your desktop. In the next step, you should replace some placeholder values and prepare the XML for later upload.

Replace the placeholder values in the Outlook manifest.xml file with the actual values from your DocuWare system. More specifically, you should search for:

{{GENERATE_A_UNIQUE_ID}} and replace it with any GUID as the application GUID
{{YOUR_DOCUWARE_URL}} and replace it with the URL of your DocuWare system
{{YOUR_CLIENTID}} and replace it with your OAuth application client ID

Find instructions to create a new GUID using PowerShell
If you need to generate a unique GUID, you can find step-by-step instructions on the Microsoft documentation portal.

Expand this option to access the Outlook manifest.xml file.

<?xml version="1.0" encoding="UTF-8"?>

<OfficeApp
	xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0"
	xmlns:mailappor="http://schemas.microsoft.com/office/mailappversionoverrides/1.0"
	xsi:type="MailApp">
	<Id>{{GENERATE_A_UNIQUE_ID}}</Id>

	<Version>3.0</Version>
	<ProviderName>DocuWare</ProviderName>
	<DefaultLocale>en-US</DefaultLocale>
	<DisplayName DefaultValue="DocuWare" />
	<Description DefaultValue="DocuWare for Outlook" />
	<IconUrl DefaultValue="https://{{YOUR_DOCUWARE_URL}}/DocuWare/Outlook-Frontend/assets/docuware-64.png" />
	<HighResolutionIconUrl DefaultValue="https://{{YOUR_DOCUWARE_URL}}/DocuWare/Outlook-Frontend/assets/docuware-128.png" />
	<SupportUrl DefaultValue="https://support.docuware.com/en-US/" />

	<AppDomains>
		<AppDomain>https://{{YOUR_DOCUWARE_URL}}/DocuWare/Outlook-Frontend</AppDomain>
		<AppDomain>https://login.microsoftonline.com</AppDomain>
	</AppDomains>

	<Hosts>
		<Host Name="Mailbox" />
	</Hosts>
	<Requirements>
		<Sets>
			<Set Name="Mailbox" MinVersion="1.1" />
		</Sets>
	</Requirements>
	<FormSettings>
		<Form xsi:type="ItemRead">
			<DesktopSettings>
				<SourceLocation DefaultValue="https://{{YOUR_DOCUWARE_URL}}/DocuWare/Outlook-Frontend/" />
				<RequestedHeight>250</RequestedHeight>
			</DesktopSettings>
		</Form>
	</FormSettings>

	<Permissions>ReadWriteMailbox</Permissions>
	<Rule xsi:type="RuleCollection" Mode="Or">
		<Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />
	</Rule>
	<DisableEntityHighlighting>false</DisableEntityHighlighting>

	<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
		<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1"
		                  xsi:type="VersionOverridesV1_1">
			<Requirements>
				<bt:Sets DefaultMinVersion="1.5">
					<bt:Set Name="Mailbox" />
				</bt:Sets>
			</Requirements>

			<Hosts>
				<Host xsi:type="MailHost">
					<Runtimes>
						<Runtime resid="LaunchEventMainPage">
							<Override type="javascript" resid="ClassicRuntimeScript"/>
						</Runtime>
					</Runtimes>
					<DesktopFormFactor>
						<SupportsSharedFolders>true</SupportsSharedFolders>
						<FunctionFile resid="MainPage" />
						<ExtensionPoint xsi:type="MessageReadCommandSurface">
							<OfficeTab id="TabDefault">
								<Group id="docuwareGroupId">
									<Label resid="paneTitle" />
									<Control xsi:type="Button" id="msgReadOpenPaneButton">
										<Label resid="paneTitle" />
										<Supertip>
											<Title resid="paneTitle" />
											<Description resid="paneDescription" />
										</Supertip>
										<Icon>
											<bt:Image size="16" resid="icon16" />
											<bt:Image size="32" resid="icon32" />
											<bt:Image size="80" resid="icon80" />
										</Icon>
										<Action xsi:type="ShowTaskpane">
											<SourceLocation resid="MainPage" />
											<SupportsPinning>true</SupportsPinning>
										</Action>
									</Control>
								</Group>
							</OfficeTab>
						</ExtensionPoint>
						<ExtensionPoint xsi:type="MessageComposeCommandSurface">
							<OfficeTab id="TabDefault2">
								<Group id="composeGroup">
									<Label resid="paneTitle" />
									<Control xsi:type="Button" id="msgComposeOpenPaneButton">
										<Label resid="paneTitle" />
										<Supertip>
											<Title resid="paneTitle" />
											<Description resid="paneDescription" />
										</Supertip>
										<Icon>
											<bt:Image size="16" resid="icon16" />
											<bt:Image size="32" resid="icon32" />
											<bt:Image size="80" resid="icon80" />
										</Icon>
										<Action xsi:type="ShowTaskpane">
											<SourceLocation resid="MainPage" />
											<SupportsPinning>true</SupportsPinning>
										</Action>
									</Control>
								</Group>
							</OfficeTab>
						</ExtensionPoint>
						<ExtensionPoint xsi:type="LaunchEvent">
							<LaunchEvents>
								<LaunchEvent Type="OnNewMessageCompose" FunctionName="onNewMessageCompose"/>
								<LaunchEvent Type="OnMessageSend" FunctionName="onMessageSendHandler" SendMode="SoftBlock" />
							</LaunchEvents>
							<SourceLocation resid="LaunchEventMainPage"/>
						</ExtensionPoint>
					</DesktopFormFactor>
					<MobileFormFactor>
						<ExtensionPoint xsi:type="MobileMessageReadCommandSurface">
							<Group id="mobileMsgRead">
								<Label resid="paneTitle" />
								<Control xsi:type="MobileButton" id="mblRestPaneButton">
									<Label resid="paneTitle" />
									<Icon xsi:type="bt:MobileIconList">
										<bt:Image size="25" resid="icon16" scale="1"/>
										<bt:Image size="32" resid="icon32" scale="1"/>
										<bt:Image size="48" resid="icon80" scale="1"/>
										<bt:Image size="25" resid="icon16" scale="2"/>
										<bt:Image size="32" resid="icon32" scale="2"/>
										<bt:Image size="48" resid="icon80" scale="2"/>
										<bt:Image size="25" resid="icon16" scale="3"/>
										<bt:Image size="32" resid="icon32" scale="3"/>
										<bt:Image size="48" resid="icon80" scale="3"/>
									</Icon>
									<Action xsi:type="ShowTaskpane">
										<SourceLocation resid="MainPage" />
									</Action>
								</Control>
							</Group>
						</ExtensionPoint>
					</MobileFormFactor>
				</Host>
			</Hosts>

			<Resources>
				<bt:Images>
					<bt:Image id="icon16" DefaultValue="https://{{YOUR_DOCUWARE_URL}}/DocuWare/Outlook-Frontend/assets/docuware-16.png" />
					<bt:Image id="icon32" DefaultValue="https://{{YOUR_DOCUWARE_URL}}/DocuWare/Outlook-Frontend/assets/docuware-32.png" />
					<bt:Image id="icon80" DefaultValue="https://{{YOUR_DOCUWARE_URL}}/DocuWare/Outlook-Frontend/assets/docuware-80.png" />
				</bt:Images>
				<bt:Urls>
					<bt:Url id="MainPage" DefaultValue="https://{{YOUR_DOCUWARE_URL}}/DocuWare/Outlook-Frontend/" />
					<bt:Url id="LaunchEventMainPage" DefaultValue="https://{{YOUR_DOCUWARE_URL}}/DocuWare/Outlook-Frontend/" />
					<bt:Url id="ClassicRuntimeScript" DefaultValue="https://{{YOUR_DOCUWARE_URL}}/DocuWare/Outlook-Frontend/classic-outlook.runtime.js" />
				</bt:Urls>
				<bt:ShortStrings>
					<bt:String id="paneTitle" DefaultValue="DocuWare" />
				</bt:ShortStrings>
				<bt:LongStrings>
					<bt:String id="paneDescription" DefaultValue="DocuWare - the ultimate add-in for integrating emails and their attachment into business processes.">
						<bt:Override Locale="de" Value="DocuWare - Das ultimative Add-In zur Integration von E-Mails und ihren Anhängen in Geschäftsprozesse." />
						<bt:Override Locale="fr" Value="DocuWare - Le module idéal pour intégrer des e-mails et de leurs pièces jointes dans les processus opérationnel." />
						<bt:Override Locale="es" Value="DocuWare - El complemento definitivo para integrar correos electrónicos y sus archivos adjuntos en los procesos." />
						<bt:Override Locale="ja" Value="DocuWare - 電子メールとその添付ファイルをビジネスプロセスに統合するための高度なアドイン。" />
					</bt:String>
				</bt:LongStrings>
			</Resources>
			<WebApplicationInfo>
				<Id>{{YOUR_CLIENTID}}</Id>
				<Resource>api://{{YOUR_DOCUWARE_URL}}/DocuWare/Outlook-Frontend/{{YOUR_CLIENTID}}</Resource>
				<Scopes>
					<Scope>openid</Scope>
					<Scope>profile</Scope>
					<Scope>offline_access</Scope>
					<Scope>email</Scope>
					<Scope>User.Read</Scope>
					<Scope>Mail.ReadWrite</Scope>
					<Scope>Mail.ReadWrite.Shared</Scope>
					<Scope>MailboxSettings.ReadWrite</Scope>
				</Scopes>
			</WebApplicationInfo>
		</VersionOverrides>
	</VersionOverrides>
</OfficeApp>

Rollout of Add-In for Office 365 users

Now that all requirements are set, the manifest file with your DocuWare system values can be used to be rolled out to Office 365 users.

Just follow the step-by-step description of the setup and roll-out process.