Article

Configuring the Outlook add-in component for Pega applications

Use the Outlook Office add-in to integrate your application with multiple client types depending on Exchange server versions.

The Outlook Office add-in is supported only on the web with Office Outlook 365. It is not supported on the web with on-premises Office Outlook 2013 or 2016 Exchange servers. Also, if you have the Mimecast application in the Outlook client, the compose view will be disabled.

The Outlook Office add-in synchronizes emails and appointments with Pega applications. 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 – You can leave the add-in taskpane open in your mailbox when you switch between messages.
Pinnable taskpane is supported only by Outlook 2016 for Windows and Outlook Online. For more information, see Pinnable taskpane.

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. The pinnable taskpane is supported in an email or appointment reply as well.

Prerequisites

  1. Verify that your server is SSL enabled (HTTPS).
  2. Verify that third-party cookies are enabled for your browser. To learn how to enable them, see your browser's online documentation.
  3. Optional: If you are using Microsoft Edge to access a private server, add https://outlook.office.com to your list of trusted websites.
  4. Optional: 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:

  1. Configuring the Outlook component
  2. Configuring the Web server
  3. Configuring the manifest file
  4. Configuring settings for the Pega for Outlook Office add-in
  5. Authenticating the Pega for Outlook Office add-in using a custom single sign-on (SSO)
  6. Optional: Publishing the add-in as an organizer
  7. Optional: Publishing the add-in as an individual mailbox user

Additional information:

Configuring the Outlook component

  1. Install the Exchange Outlook Integration component from Pega Exchange.
  2. Add the Exchange Outlook Integration component to your application stack as a component application in the Enabled Component section in the Application rule.
  3. Open all the access groups corresponding to the application and add the OutlookAddIn portal.
  4. Update the Browser RequestorType to your application unauthenticated access group.
  5. Create a new guest role, provide the following access level privileges and then update above access group with this role:
    1. @baseClass – ReadInstances – level 5, Read rules – level 5, Execute activities - level 5
    2. Data-Admin-Operator-ID – ReadInstance – level 5, WriteInstances – level 5, Execute activities - level 5
    3. Data-Admin-Security-Token – ReadInstance – level 5, WriteInstandes – level 5, ReadRules – level 5, Execute activities - level 5
  6. Update your application skin by adding the Outlook-style-helper style sheet to additional style sheets.
  7. Update the ExchangeInt service package with corresponding application access group.
  8. Update the OfficeAdmin Operator ID access group to your application access group, which will point to your application.
  9. Update the Office365 keystore to your exchange server keystore URL.
  10. Optimize the OMsexchuid property in your operator table.
  11. Optional: If you want to use calendar synchronization, optimize the IsEnabledBiSync property in the operator table.
  12. Update the LoadEWSConfigurationExt extension according to the implementation application.
  13. Update the CreateItemURL Dynamic System Setting for Exchange server URL configuration.
  14. Update ExchangeVersion to get the Exchange server version.
  15. Optional: If you want to see the sync email and appointments in your portal, check Calendar and Email menu items in pyCaseManager and pyCaseWorker navigation rules.

Configuring the Web server

Configure your application 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 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. Optional: 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

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

If you are authenticating the Pega for Outlook Office add-in by using a custom single sign-on (SSO), follow the instructions for Authenticating the Pega for Outlook Office add-in using a custom single sign-on (SSO).
  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"/>

<IconUrl DefaultValue="https://10.60.215.243:8443/AddIn/Images/Icon64.png"/>

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/OutlookAddIn?pyActivity=@baseclass.OutlookShowLoad&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/OutlookAddIn?pyActivity=@baseclass.OutlookShowLoad&amp;pzAuth=guest"/>

</bt:Urls>

Configuring settings for the Pega for Outlook Office add-in

  1. Enter the certificate location to validate the JWT token which is used to establish SSO across devices.
    1. Optional: 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/.
  2. Configure an Email Listener account by clicking Dev Studio > Records > Integration Resources > Email Listener > OfficeAddInCompose > OfficeAddInCompose 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).
  3. Optional: If the synchronization is not automatic, configure the Email Listener account with the IMAP option (send event invitations in iCalendar format) in Exchange Server.
  4. Optional: If you are using Office 365 mailbox, configure the Email Listener in Mail settings. Open Mail Settings > POP/IMAP settings and make sure to check Send Event Invitations in iCalendar format.
  5. Start the OfficeAddInCompose Email Listener from the Listener landing pages. By default, it is blocked, so you must clear the Email Listener check box from Dev Studio to enable it.
  6. Start the OfficeAddInCompose Email Listener.

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 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 forpyActivity=@baseclass.OutlookShowLoad&amp;pzAuth=guestand 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. 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:

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

  1. 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

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

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

  1. Log in to Microsoft Office 365 as an administrator 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 Application 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. By default, the Optional field is disabled, which means that your users must manually enable the add-in.

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

If you want to publish the Pega for Outlook Office add-in to only one mailbox user, perform 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.

Limitations

If you synchronize appointments in the Explorer view and edit from the Organizer view until you add the Listener Email ID, that appointment will not be synchronized to PRPC layer. (You need to add this Listener Email ID manually in To (or) CC (or) BCC).

Extension points

Customize your Outlook add-in using the following extension points:

  • LoadEWSConfigurationExt – Extend it for DCR related changes in your implementation layer.
  • AddInObjLinkExt – Extend it in your implementation layer to associate your work object to appointment or email work object.
  • AssociateEmailPostExt – Extend it in the implementation layer to associate your work object to email work object.
  • AssociateObjApptExt – Extend it in the implementation layer to associate your work object to appointment work object.
  • AssociateObjExt – Extend it in the implementation layer to associate your work object to email work object.
  • OutlookPortal_TopNavigation – Use it to create work objects from Office add-in.
  • RetrieveOutlookData – Use to make the added objects to appear in the panel.
  • OutlookViewInBrowser – Use it to open a specific work object from Office add-in.

Dynamic system settings

Configure the following dynamic system settings in your Pega Application:

  • CreateItemURL – Use it to configure an Exchange server URL.
  • ExchangeVersion- Use it to provide an Exchange server version.
  • IncludEmailTemplates – Use it to define if Email templates in Outlook add-in are displayed or not.
  • InternalDomainsEnter 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.
  • ProcessAttachments – Set to true to process attachments, create attachments in your application, and associate to email or appointment when synchronizing emails and appointments.

Published December 17, 2018 — Updated April 1, 2019

Related Content

Have a question? Get answers now.

Visit the Pega Support Community to ask questions, engage in discussions, and help others.