Configure Mobility Access

This topic provides details on how to configure Mobility Access.

In this topic:

Set up an email account

You must set up an email account that is used to fetch and process user response email. The Mobility Access Service periodically connects to this email account to read user response emails, parses the emails, and then applies to the selected action to the workflow step.

The email account must meet the following requirements:

• The account must not be shared with any other process or used for any other purpose.

• The account must not be configured as the email address for a PPM user.

• The account must be configured to receive notification response email messages no larger than 1 MB.

  Note: If an email message sent to the account is not a notification response email for the Mobility Access Service, the email is considered SPAM email and is deleted.

Back to top

Configure the email server

This section describes how to configure the email server for Mobility Access.

Overview

For the Mobility Access Service to connect to email account to read user response email, you must configure the email server for the Mobility Access Service in the mobility_access.xml file. The mobility_access.xml file is added to the <PPM_Home>/conf directory after you install the Mobility Access add-on.

The Mobility Access Service supports the password authentication to email servers, or the OAuth authentication for Microsoft Exchange Online.

Set up Mobility Access as an Azure AD application

If the email account dedicated for Mobility Access is hosted on Microsoft Exchange Online, you need to register the Mobility Access as an Azure Active Directory (AD) application.

To set up Mobility Access as an Azure AD application:

1. Register the Mobility Access as an application with Azure AD. For details, see the Register an application section in the Microsoft Documentation.

   Note down the Application (client) ID and Directory (tenant) ID. You can find the information from the Overview tab after you register the application.

   

2. Add a client secret for the application. For details, see the Add a client secret section in the Microsoft Documentation. Note down the secret's Value.

   

3. Enable the application (Mobility Access) to access the Exchange mailbox via client credentials flow with the POP and IMAP protocols, as follows:

   • Add the POP and IMAP permissions to your AAD application. For details, see the Add the POP and IMAP permissions to your AAD application section in the Microsoft Documentation.
   • Get tenant admin consent. For details, see the Get tenant admin consent section in the Microsoft Documentation.
   • Register service principals in Exchange. For details, see the Register service principals in Exchange section in the Microsoft Documentation.

Configure the email server

To configure the email server for Mobility Access Service:

1. Navigate to the <PPM_Home>/conf directory and open the mobility_access.xml file in a text editor.

2. Provide values for the Mobility Access Service configuration parameters as described in the table below:

   Parameter	Description
   hostname	Required. Hostname of the email server. Example: imap.mail.microfocus.com You can also specify an IP address for this parameter.
   enabled	Required. Set this parameter to true to enable the email server to process emails. Emails are fetched and processed only from the servers for which this parameter is set to true. By default, this parameter is set to true.
   auth_class	Required if the email account is hosted on Microsoft Exchange Online. Indicates that the OAuth authentication is used for the email server. Set this parameter to the following: com.kintana.wf.mobilityaccess.auth.MobilityAccessMSOAuth
   protocol	Required. Mail protocol of the email server. Only IMAP and POP3 protocols are supported. The default value is imap. Valid values include the following: imap pop3 imaps pop3s Note: Use imaps if your email server supports the IMAPS protocol in order to prevent login failure.
   email_address	Required. Email address from which to fetch and process the emails. Example: ppm800_email_service@microfocus.com Note: Make sure that no PPM user account specifies this address as the user email address.
   email_account	Required. Email account from which to fetch and process the emails. The value you specify depends on your server and could be just the account name (with domain name) or the email address. Examples: ppm800_email_service AMERICAS\ppm800_email_service ppm800_email_service@microfocus.com
   password	Required only for email servers that use the password authentication. The password of the email account used to fetch and process the emails. Provide the password in plain text or encrypt it using kEncrypt.sh. To escape special characters, enclose the password between the <![CDATA[ and ]]> tags. Note: You must enclose all the encrypted passwords between #!#. Plain text password example: <password><![CDATA[Welcome123]]> </password> Encrypted password example: <password><![CDATA[#!#3E7i:C/Vp}lhSN41)L~YLhFk-:w5tzJpR1ua~q `ekTD^ChnJ<>4UNxc51x7ip`6x~4`qZlx^3_18EAhzJtZ(b9O/RE&+{A, 68156ApEcFqQpv9Kg{Rfx^&~ep_VtLPC(:nkk=:<A85x91v(A*(mk3 {$kJcbrjlk@k)L{`|8$)<KPLxI@ 2R13^sL1p)i7#!#]]></password>
   tenant_id	Required only for email account that is hosted on Microsoft Exchange Online. The Directory (tenant) ID in Azure AD. You must register Mobility Access as an Azure AD application to obtain the information. For details, see Set up Mobility Access as an Azure AD application.
   client_id	Required only for email account that is hosted on Microsoft Exchange Online. The Application (client) ID in Azure AD. You must register Mobility Access as an Azure AD application to obtain the information. For details, see Set up Mobility Access as an Azure AD application.
   client_secret	Required only for email account that is hosted on Microsoft Exchange Online. The secret value obtained from Azure AD. You must register Mobility Access as an Azure AD application and add a client secret for the application. For details, see Set up Mobility Access as an Azure AD application. Provide the secret in plain text or encrypt it using kEncrypt.sh. To escape special characters, enclose the secret between the <![CDATA[ and ]]> tags.
   mail_archive_folder	Applicable only to email servers that support IMAP protocols. The name of the folder in which incoming mails are stored after processing. Example: PPM_PROCESSED_MAILS Note: If a folder does not exist, the Mobility Access Service creates the folder.
   archive_messages	Require for email servers that use the IMAP protocol. If set to Y, all the incoming emails and outgoing feedback emails are logged into the PPM_EMAIL_PROCESSED_MSGS table. The default value is Y. If the email server supports the IMAP protocol, and if the mail_archive_folder parameter is set to a valid value, all the incoming emails are moved to the archive folder after processing.
   days_to_retain_messages	Required for email servers that use the IMAP protocol. The number of days from the mail received date that email messages remain in the PPM_EMAIL_PROCESSED_MSGS table and the mail_archive_folder. The default value is 180.
   action_processor	Required. Intended for possible future use, this parameter is set to the following value and must NEVER be changed: com.kintana.wf.mobilityaccess.server.WorkflowActionProcessor
   Action Processor Configurations
   notes_logging	Specifies what are saved in the notes for requests and packages. The value can be either of the following: ONLY_EMAIL_MESSAGE. Default value. Only the email message is saved in the notes. HEADERS_AND_EMAIL_MESSAGE. Email message and headers are saved in the notes.
   send_success_feedback	Required. Specifies whether to send a feedback message to the user if the selected workflow action is completed successfully. The default value is N.
   send_failure_feedback	Required. Specifies whether to send a feedback message to the user if the selected workflow action fails. The default value is Y.
   send_not_applicable_feedback	Required. Specifies whether to send a feedback message to the user if the selected workflow action is not applicable. The default value is N.
   mobility_access_hide_initial_message	Specifies whether to hide or display the initial text in an Mobility Access email notification. The default value is false.

3. Save, and then close the mobility_access.xml file.

Back to top

Configure user-defined markers

Any markers that PPM Center users define in email responses are added to the mobility_access.properties file, which is located in the <PPM_Home>/conf/custom_resources/mobility_access directory. You can edit this file to customize these markers.

Back to top

Configure Mobility Access Service logging

The Mobility Access Service writes to the mobility_access_log.txt file, which is located in the <PPM_Home>/server/<PPM_ServerName>/log directory. If you encounter problems related to Mobility Access, you can use this log file to help you troubleshoot the problems.

Mobility Access Service logging is defined in the logging.conf file, which is located in the <PPM_Home>/conf directory. The file specifies that any error related to Mobility Access Service is logged in the mobility_access_log.txt file.

To turn on debugging, open the logging.conf file and change only the first line in the Mobility Access Service Logging configuration to the following:

# Mobility Access logging
log4j.logger.com.kintana.wf.emailprocessor=DEBUG, MOBILITY_ACCESS_LOG

Back to top

See also:

• Deploy Mobility Access