Integrating with Microsoft Outlook by using the Pega for Outlook Office add-in
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.
- For a list of limitations on the Pega for Outlook Office add-in, see Pega for Outlook add-in and Pega for Outlook VSTO add-in comparison.
- Pega Sales Automation does not support Internet Explorer. To use the Pega for Outlook Office add-in, use the Microsoft Edge browser.
- To display the add-in in Outlook, the add-in uses the browser. The browser that is used is determined by the operating system, the Office version, and whether the Edge WebView2 (Chromium-based) is installed. For more info, see Browsers used by Office Add-ins on the Microsoft documentation site.
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
OutlookAddIn.js script files in your implementation layer.
Email and appointment replies also support Pinnable taskpane.
- Verify that your server is SSL enabled (HTTPS).
- Verify that third-party cookies are enabled for your browser. To learn how to enable cookies, see your browser's online documentation.
- If you are using Microsoft Edge to access a private server, add
https://outlook.office.comto your list of trusted websites.
- To configure the Outlook add-in on iPhone in Safari, you must first allow cross-site tracking in Safari.
Configuring the Web server
Configure your Sales Automation server for the Pega for Outlook Office add-in user by
AddIn folder and entering your authentication
AddInfolder contains the required images for your Pega for Outlook Office add-in integration.
- You can replace the Pega-provided icons in the
AddIn/Imagesfolder with your own images. However, you must use the Pega-provided icon names for your images because these names are referenced in the manifest URLs.
- If you have a Pega Cloud services installation, do not perform this procedure and go to the "Configuring the Web server for Pega cloud" procedure, instead.
- Download the following AddIn folder: AddIn folder.
- Open the WinSCP Login dialog box and log in to your server.
- Add the
AddInfolder to the
- If you are using Tomcat 7 or later, to designate the Pipe symbol (|) as a valid
character in your query parameters, in the
- Authenticate the Pega for Office Outlook add-in user. To do it, in the
/opt/tomcat/webapps/prweb/WEB-INFfolder, open the
web.xmlfile 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 Web server for Pega Cloud services
Configure the Web server when have a Pega Cloud services installation. Web server configuration for Pega Cloud installations is different than the configuration without Pega Cloud.
- Do not manually add servlets to the
web.xmlfile, because Pega Cloud already adds the servlet.
- To find the servlets, in the header of Dev Studio, click .
- Do not add
- To customize the add-in images, replace the binary files
Icon16with your own images.
- If you want to change the names of the binary files, you must replace them in
Configuring the manifest file
To provide your URLs for the Pega for Outlook Office add-in, configure the manifest file.
- In the navigation pane of App Studio, click .
- Open the Microsoft Exchange tab.
- In the Office add-in only section, click Configure Manifest.
- Configure the manifest file the following way:
- In the Display Name field, enter the Outlook Office add-in display name.
- In the Instance details field, enter the Pega instance URL with port (if applicable).
- In the Application name field, enter the name of your application. (This is used only to identify the manifest file).
- In the Icon label field, enter a label that you want to add for the Outlook header bar of the Outlook add-in.
- In the Group label field, enter a label that you want to add for the Outlook header bar of the Outlook add-in group.
- Select either the Default or Custom authentication type.
- Click Download.
- In the dialog box that is displayed after the system downloads the file, copy
the Outlook Office add-in manifest’s unique identifier (GUID).The Add-in manifest’s unique identifier is used when the Outlook Office add-in is published by an administrator at the organizational level, and if clients are Mac Outlook client users.
- 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.
- Click Save.
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 the settings in Pega Sales Automation. Configuration is divided into App Studio settings and Developer settings.
- In the explorer pane of App Studio, click .
- In the Outlook add-in settings section, complete the
- 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.
- 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.
- Optional: 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.
- Click Save.
the certificate location to validate the JWT token, which is used to establish
SSO across devices. To do this, in Dev Studio, click .
- If you have Office 365, no action is needed.
- If you are using an on-premises Exchange 2013 or 2016 server, change the KeyStore URL to reflect your Exchange URL. 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/.
an Email Listener account by clicking 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).
- Optional: If the synchronization is not automatic, configure the Email Listener account to use the IMAP option (send event invitations in iCalendar format) in Exchange Server.
- Optional: If you are using Office 365 mailbox, configure the Mail settings. Open and select the Send Event Invitations in iCalendar format. chcek box
- 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.
- Open the
- Search for the OutlookAddIn servlet and replace it with your SSO servlet.
- Search for
[email protected]&pzAuth=guestand replace it with
Result: The URL should now appear as: https://pegadevap.murex.com/prweb/sso?pyActivity=Data-Portal.OutlookLogin.
- Log in to Dev Studio.
- In the Records explorer, click .
- Select your SSO and copy your identity provider (idP) domain name. Make sure the domain is https.
- In the manifest file, add your idP domain under the
- Import the manifest file for your mailbox user account and verify the add-in.
- In the Dev Studio header search text field, search for and select the
- Find the following two lines in the
var snapstartURL = prpcURL.concat("/prweb").concat("?pyActivity=").concat("Data-Portal.OutlookViewInBrowser"); var clientURL = prpcURL.concat("/prweb").concat("?pyActivity=").concat("Data-Portal.OutlookViewInBrowser&outlookWO=" +insHandle);
- Add your SSO servlet after
prwebin each line ("/prweb/SSO").
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.
- Log in to Microsoft Office 365 as an admin user and open the Microsoft Exchange Admin center.
- Click .
- Click .
- Upload and install the
OAddinManifest.xmlfile that you configured for your Pega for Outlook Office add-in.
- Log in to Pega Sales Automation as an administrator.
- In the header of Dev Studio, in thesearch box, search for and select
- Click Download file.
- Open the file and change the Pega-provided URLs to match the URLs for your implementation.
- Double-click the application to open the Edit Add-in
settings window and review the default settings. If you select Optional (disabled by default), 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.
- In your Microsoft Office 365 inbox, in the top right-hand corner of the screen, click the gear icon.
- In the Settings pane, click Manage add-ins.
- Click Click here to add a custom add-in.
- Click Add from file and upload the
OAddinManifest.xmlfile that you configured for your Pega for Outlook Office add-in.
Calendar items update from Sales Automation portal
The order in which you configure the Pega Sales Automation to Microsoft Exchange calendar integration and the Pega for Outlook Office add-in impacts your ability to update calendar items from the 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 cannot be updated in the portal until you run the MigrateOfficeAddinAppointment activity.
Previous topic Configuring Pega for Outlook VSTO and Pega for Outlook Office Next topic Manage email and calendar