Import from Microsoft 365 (advanced)
Import is able to import emails from Microsoft 365 without any complex configurations. You only need to use advanced configuration mode in the following cases:
- You are running an on-premises version of Ultimate Forms
- You are running a standalone version of Ultimate Forms
- You are running a Salesforce app version of Ultimate Forms
- You want to import from a tenant that is not your current one
- You want to configure your own custom permission settings
Normally, Ultimate Forms will use an Azure AD enterprise app provided by us that will grant it access to Exchange Online in your tenant via Microsoft Graph API. This app, named Infowise Ultimate Forms: Import, is granted access to read and write emails in all mailboxes of your tenant. A global administrator in your organization can grant this permission either beforehand in Ultimate Forms via Global Settings -> Import or upon creation of first import profile that uses Microsoft 365 email provider. The administrator can then also limit which specific email accounts will be allowed to import from, for an additional level of security.
When you configure access in the advanced mode, you are required to create your own enterprise application and provide its settings to the import profile. The enterprise app is created on the tenant from which you are planning to import. It can be any tenant, not necessarily your own, as long as you have administrative access to it.
Creating Enterprise App
- Log into the Azure AD administration site. You can access it from the general admin page or directly via URL: https://aad.portal.azure.com/.
- In the left menu, click on Azure Active Directory, then on App registrations.
- In the toolbar, click on New registration.
- Enter a meaningful name and click Register.
- Click on API permissions, then Add permission.
- Click on Microsoft Graph, then Application permissions.
- Scroll down to Mail section and expand it.
- Check Mail.Read permission. If you are planning to allow Import to delete messages from the server, check Mail.ReadWrite instead (optional).
- Click on Add permissions at the bottom.
- Click on Grant admin consent to approve the permissions for the tenant. Application permissions are granted once and allow an application to gain access at any time, without user interaction.
- Click on Certificates and secrets to configure how the application is going to be accessed by Ultimate Forms. You can choose from two options:
- Certificates (recommended) - upload a certificate, which will then be configured in the import profile. Read more regarding configuring certificates in the next section below.
- Client secrets - similar to passwords, secrets are simpler to configure, but not as secure and will expire after a certain time period. Only recommended to use when the import needs to be run for up to 2 years. Make sure to store the secrets in a safe place and renew as required. Secrets will be shown only once upon creation.
- Your enterprise app is now configured. Switch to Overview page and take a note of client and tenant IDs, we will use them later for configuring the import profile:
Creating Self-signed Certificate
NOTE: authenticating via a certificate is the recommended approach as, unlike secrets, certificate are not short-lived and need not to be frequently renewed.
You can use both self-signed and commercial certificates. Make sure your certificate contains both public and private key and is password-protected.
To create a self-signed certificate on Windows, search for PowerShell, right click and select Run as administrator. Enter the following lines, substituting the bold values with your own:
$date_now = Get-Date
$extended_date = $date_now.AddYears(25)
$cert = New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -dnsname infowise_test -notafter $extended_date
$pwd = ConvertTo-SecureString -String 'samplepwd' -Force -AsPlainText
$path = 'cert:\localMachine\my\' + $cert.thumbprint
Export-PfxCertificate -cert $path -FilePath c:\infowise_test.pfx -Password $pwd
- 25 - number of years the certificate will remain valid
- infowise_test - name of the certicate
- samplepwd - certificate password, up to 30 characters
- c:\infowise_test.pfx - export path
Note: When creating a self-signed certificate for usage on-premises, you might need to add the -KeySpec Signature parameter to the New-SelfSignedCertificate command to specify that the private key can be used for signing.
IMPORTANT: make sure you store the certificate and its password in a safe place.
Next open the export folder and double-click the newly-created certificate. It will start the import wizard. You can use the default values, except for the password:
Once the certificate is imported, you need to export it in .cer format. For that, search Windows for Manage user certificates, expand Personal, then Certificates. You should be able to find it here:
Right-click on the certificate, then All Tasks -> Export. It will start the export wizard. Leave all default values, only specifying the export location at the end. It will create a .cer file, containing the public key of the certificate.
Now we can upload the certificate to our enterprise app.
- On Certificate and client secrets page of the enterprise app, make sure to switch to Certificates tab, then click on Upload certificate.
- Select the .cer file we just exported and provide a meaningful name
Once the certificate is uploaded to the enterprise app, it can be used by import profiles.
Configuring Import Profile
- Open Ultimate Forms and select list, form or object where you want to set up an import profile.
- Click on Import to switch to import settings.
- Click on Add new profile, then enter a name for the new profile.
- Switch to Data provider tab.
- Select Microsoft 365 (advanced) protocol.
- Enter the email address you want to import from (by default, your own email is already entered).
- Enter tenant and client ID of the enterprise app. Unless the mailbox is located on GCC High government cloud, leave Public checked.
- Choose to either use a certificate or a client secret.
- When using a certificate, upload the .pfx file and specify the certificate password.
- When using a client secret, provide it.
- Click on Connect. If you provided correct values, Actions tab will become visible. Otherwise an error will be shown.
- Delete messages from server option can only be used when you previously granted Mail.ReadWrite permission to the enterprise app.
- Enter at least one action and save the profile.
NOTE: Certificates and password are stored encrypted in our system and are never visible after being entered. You do not need to re-enter them again, unless you want to make changes to those credentials themselves.