Configure Mobility Access

This topic provides details on how to configure Mobility Access.

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.

Note: If your PPM instance supports multiple languages, note that Micro Focus 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.

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

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 Micro Focus 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.

Back to top

See also: