Pega Sales Automation provides a Pega for Outlook Office add-in that you can use to integrate your application with multiple client types depending on Exchange server versions.

With the Pega for Outlook Office add-in, you can perform the following actions:

• Search, open, and display Pega Sales Automation leads, contacts, opportunities, organizations, and accounts.
• Synchronize emails and appointments.
• Associate emails or appointments with contacts, leads, opportunities, organizations, and accounts.
• Create contacts, leads, opportunities, activities, and tasks.

The Pega for Outlook Office add-in supports the following features:

• Single sign-on (SSO) – after you log in to the add-in for the first time, you can access it from any device, without reentering your login credentials.
• Pinnable taskpane – leave the add-in taskpane open in your mailbox when you switch between messages.

If you customize your URL pattern by replacing prweb in your URL with a custom value, you must override the OutlookLogin.js and OutlookAddIn.js script files in your implementation layer. Pinnable taskpane is supported in an email or appointment reply as well.

Prerequisites

• Verify that your server is SSL enabled (HTTPS).
• Verify that third-party cookies are enabled for your browser. To learn how to enable them, see your browser's online documentation.
• If you are using Microsoft Edge to access a private server, add https://outlook.office.com to your list of trusted websites.
• To configure Outlook add-in on iPhone in Safari, allow cross-site tracking in Safari.

To install the Pega for Outlook Office add-in, complete the following steps:

• Configuring the Web server
• Configuring the manifest file (for 8.4)
• Configuring the manifest file (for 8.3)
• Configuring the manifest file (for 8.2 and 8.1)
• Configuring settings for the Pega for Outlook Office add-in
• Authenticating the Pega for Outlook Office add-in using a custom single-sign-on (SSO)
• Publishing the add-in as an organizer
• Publishing the add-in as an individual mailbox user
• (Optional): Updating calendar items from Sales Automation portal

Configuring the Web server

Configure your Sales Automation server for the Pega for Outlook Office add-in user by adding the AddIn folder and entering your authentication credentials.The AddIn folder contains the required images for your Pega for Outlook Office add-in integration.

1. Download the following AddIn folder: AddIn folder.
2. Open the WinSCP Login dialog and log in to your server.
3. Add the AddIn folder to the /opt/tomcat/webapps directory.
4. If you are using Tomcat 7 or later, to designate the Pipe symbol '|' as a valid character in your query parameters, in the /opt/tomcat/conf directory, add tomcat.util.http.parser.HttpParser.requestTargetAllow=|{} to catalina.properties.
5. In the /opt/tomcat/webapps/prweb/WEB-INF folder, to authenticate the Pega for Office Outlook add-in user, open the web.xml file and add the following servlet and servlet mappings:

<servlet>

<servlet-name>OutlookAddIn</servlet-name>
                    <display-name>OutlookAddIn</display-name>

                    <description>Internet Application Composer, using custom authentication techniques</description>

                    <servlet-class>com.pega.pegarules.internal.web.servlet.WebStandardBoot</servlet-class>

                    <init-param>
 <param-name>PegaEtierClass</param-name>

                                           <!--  COMPONENTS: This was previously com.pega.pegarules.services.HttpAPI -->

                                                <param-value>com.pega.pegarules.session.internal.engineinterface.service.HttpAPI</param-value>

                              </init-param>

                               <init-param>

                                             <param-name>AuthenticationType</param-name>

                                              <param-value>PRCustom</param-value>

                               </init-param>

                                <init-param>

                                               <param-name>RuntimeServletName</param-name>

                                                <param-value>OutlookAddIn</param-value>

                               </init-param>

                                <init-param>

                                      <param-name>AuthService</param-name>

                                                <param-value>OutlookAddinService</param-value>

                                </init-param>

                </servlet>

               <servlet-mapping>

                                <servlet-name>OutlookAddIn</servlet-name>

                                <url-pattern>/OutlookAddIn</url-pattern>

                </servlet-mapping>

                <servlet-mapping>

                                <servlet-name>OutlookAddIn</servlet-name>

                              <url-pattern>/OutlookAddIn/*</url-pattern>

                </servlet-mapping>

Configuring the manifest file (for 8.4)

To provide your URLs for the Pega for Outlook Office add-in, configure the manifest file.

1. In the navigation pane of App Studio, click Settings > Application Settings.
2. Open the Microsoft Exchange tab.
3. In the Office add-in only section, click Configure Manifest.
4. Configure the manifest file the following way:
   1. In the Display Name field, enter the Office add-in display name.
   2. In the Instance details field, enter the Pega instance URL with port (if applicable).
   3. In the Application name field, enter the name of your application (needed only to identify the manifest file).
   4. In the Icon label field, enter a label that you want to add for the Outlook header bar of the Outlook add-in.
   5. In the Group label field, enter a label that you want to add for the Outlook header bar of the Outlook add-in group.
5. Click Download.
6. Copy the Outlook add-in manifest unique identifier (GUID) displayed in the dialog box appearing after download.

   The Addin manifest unique identifier is applicable when Outlook add-in is published by an administrator at the organizational level and if clients are Mac Outlook client users.

7. In App Studio, on the Microsoft Exchange tab, in the Configure manifest files section, paste the GUID into the Addin manifest unique identifier(GUID) field.
8. Click Save.

Configuring the manifest file (for 8.3)

To provide your URLs for the Pega for Outlook Office add-in, configure the manifest file.

1. In the navigation pane of App Studio, click Settings > Application Settings.
2. Open the Microsoft Exchange tab.
3. In the Office add-in only section, click Configure Manifest.
4. Configure the manifest file the following way:
   1. In the Display Name field, enter the Office add-in display name.
   2. In the Instance details field, enter the Pega instance URL with port (if applicable).
   3. In the Application name field, enter the name of your application (needed only to identify the manifest file).
   4. In the Icon label field, enter a label that you want to add for the Outlook header bar of the Outlook add-in.
   5. In the Group label field, enter a label that you want to add for the Outlook header bar of the Outlook add-in group.
5. Click DownloadManifest.

Configuring the manifest file (for 8.2 and 8.1)

To provide your URLs for the Pega for Outlook Office add-in, configure the manifest file.

1. In the Dev Studio header search text field, search for and download the OAddinManifest.xml file.
2. Open the OAddinManifest.xml file.
3. Configure the manifest file elements as shown in the following table:

   Manifest file element	Manifest file element required data	Sample input
   <Id>String</Id>	Enter the unique ID of your Office Addin-in as a GUID.	<Id>6ac7a924-6039-42e5-8d0c-63a0b9c31417</Id>
   <IconUrl DefaultVAlue=" " />	Enter the URL of the image that is used to represent your Pega for Outlook Office add-in.	<IconUrl DefaultValue="https://10.60.215.243:8443/AddIn/Images/Icon64.png"/>
   <SourceLocation DefaltValue=" "/>	Enter the source file locations for your Pega for Outlook Office add-in as a URL between 1 and 2,018 characters long. The source location must be an HTTPS address, not a file path.	<SourceLocation DefaultValue="https://10.60.215.243:8443/prweb/[email protected]&amp;pzAuth=guest"/>
   <bt:Images> <bt:Image id="icon16" DefaultValue=""/> <bt:Image id="icon32" DefaultValue=""/> <bt:Image id="icon80" DefaultValue=""/> </bt:Images>	Enter the URL of the images that are used to represent your Pega for Outlook Office add-in. Microsoft recommends using three images: 16px, 32px, and 80px.	<bt:Images> <bt:Image id="icon16" DefaultValue="https://10.60.215.243:8443/AddIn/Images/Icon16.png"/> <bt:Image id="icon32" DefaultValue="https://10.60.215.243:8443/AddIn/Images/Icon64.png"/> <bt:Image id="icon80" DefaultValue="https://10.60.215.243:8443/AddIn/Images/Icon80.png"/> </bt:Images>
   <bt:Urls> <bt:Url id="messageReadTaskPanelUrl" DefaultValue=""/> </bt:Urls>		<bt:Urls> <bt:Url id="messageReadTaskPanelUrl" DefaultValue="https://10.60.215.243:8443/prweb/[email protected]&amp;pzAuth=guest"/> </bt:Urls>

Configuring settings for the Pega for Outlook Office add-in

To determine how the Pega for Outlook Office add-in handles attachments and to specify the internal domains to filter out from the Add a Person list for emails and appointments, configure settings in Pega Sales Automation. Configuration is divided into the following parts: App Studio settings and Developer settings.

1. In the explorer panel of App Studio, click Settings > Application Settings.
2. Click the Microsoft Exchange tab.
3. In the Outlook add-in settings section, complete the following steps:
   1. If you want to process attachments when synchronizing emails and appointments, select the Process attachments check box. For more information, see Configuring Pega Sales Automation to Microsoft Exchange calendar integration.
   2. Enter the Internal domains that you want to filter out when populating the Add a Person list for emails and appointments. For example, if you enter, in.pega.com, any email or appointment recipients that have the domain @in.pega.com do not display in the Add a Person list. If you enter multiple domains, enter the domain names as comma-separated values. For example, pega.com, in.pega.com.
   3. In the Configure manifest files section, paste the GUID generated as part of the Configuring the manifest file task into the Addin manifest unique identifier(GUID) field.
4. Click Save.
5. Enter the certificate location to validate the JWT token which is used to establish SSO across devices.
   1. In Dev Studio, click Records > Security > Keystore > Office365.
      1. If you are using Office 365, no action is needed.
      2. If you are using an on-premises Exchange 2013 or 2016 server, change the KeyStore URL to reflect that. For example, if you are using an Exchange 2013 server with the URL, mail.in.company.com, then your KeyStore URL is: https://mail.in.company.com /autodiscover/metadata/json/1/.
6. Configure an Email Listener account by clicking Dev Studio > Records > Integration Resources > Email Listener > OfficeAddInComposeView > Email Account and make sure that the listener address is correct. It is recommended not to have multiple listeners configured with the same email account (within or across systems).
   1. If the synchronization is not automatic, configure the Email Listener account with IMAP option (send event invitations in iCalendar format) in Exchange Server.
   2. In Office 365 mailbox, configure the Mail settings. Open Mail Settings > POP/IMAP settings and make sure to check Send Event Invitations in iCalendar format.
7. Enable sync in the compose view.

Authenticating the Pega for Outlook Office add-in by using a custom single-sign-on (SSO)

The Pega for Outlook Office add-in includes an authentication service called OutllookAddInService (servlet name:OutlookAddIn) that enables you to use a single-sign-on (SSO) functionality. The authentication service uses Pega Sales Automation operator credentials and a Microsoft Exchange Server JWT token to validate users.

If you want to use your organization's SSO service to allow authentication by using network credentials, rather than the Microsoft Exchange Server JWT token, complete the following steps:

1. Open the OAddinManifest.xml file.
   1. Search for the OutlookAddIn servlet and replace it with your SSO servlet.
   2. Search for [email protected]&pzAuth=guest and replace it with pyActivity=Data-Portal.OutlookLogin.The URL should now appear as: https://pegadevap.murex.com/prweb/sso?pyActivity=Data-Portal.OutlookLogin.
2. Log in to Dev Studio.
3. In the Records explorer, click SysAdmin > Authentication Service.
4. Select your SSO and copy your identity provider (idP) domain name. Make sure the domain is https.
5. In the manifest file, add your idP domain under the <AppDomains> element.
6. Import the manifest file for your mailbox user account and verify the add-in.
7. In the Dev Studio header search text field, search for and select the Outlookaddin.js file.
8. Find the following two lines in the Outlookaddin.js file:

var snapstartURL = prpcURL.concat("/prweb").concat("?pyActivity=").concat("Data-Portal.OutlookViewInBrowser");

var clientURL = prpcURL.concat("/prweb").concat("?pyActivity=").concat("Data-Portal.OutlookViewInBrowser&outlookWO=" +insHandle);

10. Add your SSO servlet after prweb in each line ("/prweb/SSO").

For example:

var snapstartURL = prpcURL.concat("/prweb/SSO").concat("?pyActivity=").concat("Data-Portal.OutlookViewInBrowser");

var clientURL = prpcURL.concat("/prweb/SSO").concat("?pyActivity=").concat("Data-Portal.OutlookViewInBrowser&outlookWO=" +insHandle

Publishing the Pega for Outlook Office add-in as an organizer to all mailbox users

If you need to publish the Pega for Outlook Office add-in to all mailbox users, complete the following steps:

1. Log in to Microsoft Office 365 as an admin user and open the Microsoft Exchange Admin center.
2. Click Admin > Exchange > Organization > Add-ins.
3. Click Add > Add from File.
4. Upload and install the OAddinManifest.xml file that you configured for your Pega for Outlook Office add-in.
   1. Log in to Pega Sales Automation as an administrator.
   2. In the Dev Studio header search text field, search for and select the OAddinManifest.xml file.
   3. Click Download file.
   4. Open the file and change the Pega-provided URLs to match the URLs for your implementation.
5. Double-click the application to open the Edit Add-in settings window and review the default settings. If you select the Optional, disabled by default option, your users must manually enable the add-in.

Publishing the Pega for Outlook Office add-in to an individual mailbox user

If you need to publish the Pega for Outlook Office add-in to only one mailbox user, complete the following steps:

1. From your Microsoft Office 365 inbox, in the top-right corner of the screen, click the Gear icon.
2. In the Settings pane, click Manage add-ins.
3. Click Click here to add a custom add-in.
4. Click Add from file and upload the OAddinManifest.xml file that you configured for your Pega for Outlook Office add-in.

Optional: Updating calendar items from Sales Automation portal

If you configure the Pega Sales Automation to Microsoft Exchange calendar integration after enabling the Pega for Outlook Office add-in you will not be able to update the calendar items from the Sales Automation portal. Meetings synchronized using the Outlook add-in can not be updated in the portal until running the MigrateOfficeAddinAppointment activity.