Share this page

# 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 email, parses the email, and then applies 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.

## 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, refer to 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, refer to 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, refer to the Microsoft documentation.
   - Get tenant admin consent. For details, refer to the Microsoft documentation.
   - Register service principals in Exchange. For details, refer to 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.

Example of the mobility_access.xml file for email servers that use the password authentication

Copy code

    <email_service_config>
       <email_servers>
       <inbound_email_server>
           <hostname>imap.mail.ppm.com</hostname>
           <enabled>true</enabled>
           <protocol>imap</protocol>
           <email_address>ppm750_email_service@ppm.com</email_address>
           <email_account>ppm750_email_service </email_account>
           <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>
           <default_folder>INBOX</default_folder>
           <mail_archive_folder>PPM_PROCESSED_MAILS</mail_archive_folder>
           <archive_messages>Y</archive_messages>
           <send_success_feedback>N</send_success_feedback>
           <send_failure_feedback>Y</send_failure_feedback>
           <send_not_applicable_feedback>N</send_not_applicable_feedback>
           <days_to_retain_messages>2</days_to_retain_messages>
        <action_processor><value>com.kintana.sops.emailprocessor .server.WorkflowActionProcessor</value></action_processor>
           <notes_logging>ONLY_EMAIL_MESSAGE</notes_logging>
        <package_lines_bulk_approval>Y</package_lines_bulk_approval>
        </inbound_email_server>
        </email_servers>
    <email_service_config>

Example of the mobility_access.xml file for Microsoft Exchange Online

Copy code

    <email_service_config>
        <email_servers>
           <inbound_email_server>
                 <hostname>outlook.office365.com</hostname>
                 <enabled>true</enabled>
                 <auth_class>com.kintana.wf.mobilityaccess.auth.MobilityAccessMSOAuth</auth_class>
                 <protocol>imap</protocol>
                 <email_address><![CDATA[XXXXX@XXXX.onmicrosoft.com]]></email_address>
                 <email_account><![CDATA[XXXXX@XXXX.onmicrosoft.com]]></email_account>
                 <tenant_id>099xxxxxx-xxxx-xxxx-xxxx-xxxxxxaa767e</tenant_id>
                 <client_id>c60xxxxx-xxxx-xxxx-xxxx-xxxxxxxx982c</client_id>
                 <client_secret><![CDATA[#!#2RaO^xxxxx...vGcjg6J#!#]]></client_secret>
                 <default_folder>INBOX</default_folder>
                 <mail_archive_folder>PROCESSED_PPM_MAILS</mail_archive_folder>
                 <archive_messages>Y</archive_messages>
                 <send_success_feedback>N</send_success_feedback>
                 <send_failure_feedback>Y</send_failure_feedback>
                 <send_not_applicable_feedback>N</send_not_applicable_feedback>
                 <days_to_retain_messages>3</days_to_retain_messages>
                 <action_processor><value>com.kintana.wf.mobilityaccess.server.WorkflowActionProcessor</value></action_processor>
                 <action_processor_properties>
                         <notes_logging>ONLY_EMAIL_MESSAGE</notes_logging>
                 </action_processor_properties>
           </inbound_email_server>
       </email_servers>
    </email_service_config>

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

Note: If your PPM instance supports multiple languages, note that PPM supplies translations only for the message content markers it delivers. If you change these marker definitions, you must create and maintain the translations for them.

Example of the mobility_access.properties file

Copy code

    #A customer-updatable resource file for Mobility Access markers
    ###########################################
    ### Non-Translatable Resources ###
    ###########################################
    subjectResponseBeginSuffix=:
    subjectResponseEnd=;
    notesMarkerPrefix=<
    notesMarkerSuffix=>
    controlDataResponseBeginSuffix=:
    controlDataResponseEnd=~~~
    ###########################################
    ### Translatable Resources ###
    ###########################################
    subjectResponseBegin=User Action
    userNotesResponseBegin=Notes Begin
    userNotesResponseEnd=Notes End
    controlDataResponseBegin=PPM Reference

## 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

Caution: To ensure that only valid actions are taken based on email responses, each email approval message contains a system-generated key that PPM uses to validate the response. Any user who responds to a PPM email approval message must include this key in the response.

However, note that OpenText does not guarantee non-repudiation for email approvals, and recommends that you check for compliance with internal and other applicable policies for non-repudiation in approval processes within your enterprise before you enable this feature in PPM.

To reduce the risk of accepting approval messages from unauthorized users, make sure that email messages are encrypted both in transit and at rest. To further reduce the risk of exposing the system-generated keys in PPM center email approval messages, make sure that the user accounts of potential approvers are on an internal enterprise mail server, and that only these email accounts are associated with the corresponding PPM users. These messages must not be forwarded to external mail servers, and any mobile devices used by potential approvers must directly exchange messages with the enterprise mail server using secure channels. These risk mitigation suggestions still cannot guarantee non-repudiation of approvers.

## See also

- Deploy Mobility Access

https://admhelp.microfocus.com PPM 8942
Tips to improve your search results... OpenText™ Project and Portfolio Management Help Center PPM Help 26.2-26.3 All View Local Help Center View Online Help Center Version: