CRMService Web Guide

1. Basic information

CRMService is a service that runs in the background of the Windows operating system and monitors employee e-mail communication with customers. It is installed as an add-on to the NET Genium ERP application and requires a technology mailbox to which incoming e-mails of all employees are automatically forwarded. It automatically creates activities from e-mail messages delivered to the technology mailbox and assigns them to specific business relationships or contacts in the address book.

CRMService further synchronizes activities with the Office 365 calendar.

2. Required files

For CRMService to work, it is necessary to have the following files in its directory:

• CRMService.exe
• NETGeniumConnection.dll

+ configuration XML file for each technology box.

For calendar synchronization to work with Office 365, you must have the following additional files in its address book:

• Microsoft.Graph.dll
• Microsoft.Graph.Auth.dll
• Microsoft.Graph.Core.dll
• Microsoft.Identity.Client.dll
• Newtonsoft.Json.dll
• System.Buffers.dll
• System.Diagnostics.DiagnosticSource.dll
• System.Memory.dll
• System.Numerics.Vectors.dll
• System.Runtime.CompilerServices.Unsafe.dll

3. Technology box

A necessary condition for the CRMService service is the existence of a technology mailbox to which incoming e-mails of all employees are automatically forwarded. The usual name is, for example, “crm@firma.cz” resp. “Crm” in front of the at sign and with the domain of the company. The name of the technology box will often be used by the employees themselves, so the simplest and most memorable name is recommended.

In order to be able to monitor outgoing e-mails sent from e-mail clients other than NET Genium itself, employees need to add a technology mailbox to a copy or blind copy of the e-mail when sending an e-mail to the customer. This ensures that the outgoing e-mail reaches the technology mailbox, and its contents are analyzed and then stored in the activity. All e-mails sent directly from NET Genium do not need to be forwarded in a copy to the technology inbox, NET Genium will automatically ensure that activity is created from the content of the e-mail.

The redirection of incoming e-mails from all employee e-mail boxes must be performed manually in the application provided by the e-mail service provider.

4. Calendar synchronization

CRMService mutually synchronizes the activities of all users who match the e-mail address entered in the user table (“susers”) with the e-mail address on the Microsoft portal.

• CRMService cannot handle recurring events. In NET Genium, when you synchronize such an event, an activity is created with the deadline set to the start date of the recurring event.

5. Azure Active Directory configuration

CRMService requires additional manual configuration of Azure Active Directory or Microsoft Entra ID if

• it downloads emails from a technology mailbox operated using Microsoft cloud services (https://docs.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth) or
• synchronizes the calendar or user activities.

Configuring Azure Active Directory or Microsoft Entra ID consists of the following steps:

• NET Genium configuration on the “https://portal.azure.com” portal:
  • Application registration “NET Genium” on webside https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps
    • portal.azure.com / App registrations
    • NET Genium as the application name
    • Finding Application (client) ID which is automatically created when the application is registered
      • Application ID (client)
    • Finding Directory (tenant) ID which is automatically created when the application is registered
      • Directory ID (tenant)
    • Creation client secret code
      • portal.azure.com / App registrations / NET Genium / Certificates & secrets / New client secret
    • Setting API permissions for Office 365 Online
      • portal.azure.com / App registrations / NET Genium / API permissions / Add a permission / APIs my organization uses / Office 365 Exchange Online
      • API name ““POP.AccessAsApp”, type “Application”
      • API name ““IMAP.AccessAsApp””, type “Application”
    • Setting API permissions for Microsoft Graph
      • portal.azure.com / App registrations / NET Genium / API permissions / Add a permission / Microsoft Graph
      • API name “Microsoft Graph – Calendars.ReadWrite”, type “Application”
      • API name “Microsoft Graph – Group.ReadWrite.All”, type “Application”
      • API name “Microsoft Graph – User.Read.All”, type “Application”
  • Creating a configuration file “MicrosoftOAuth.json” in the “Config” directory of the NET Genium whose activities are to be synchronized
    • Set the contents of the file to: “{"web":{"client_id":"Application ID (client)","tenant_id":"Directory ID (tenant)","auth_uri":"https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize","token_uri" :"https://login.microsoftonline.com/organizations/oauth2/v2.0/token","client_secret":"client secret code"}}”
• Connecting NET Genium to the technology box (https://www.youtube.com/watch?v=bMYA-146dmM) in PowerShell using the following script:
  • Set-ExecutionPolicy -Scope Process -ExecutionPolicy Unrestricted
  • Install-Module -Name ExchangeOnlineManagement
  • Install-Module Microsoft.Graph
  • Install-Module -Name AzureAD
  • Import-Module AzureAD
  • Import-Module ExchangeOnlineManagement
  • Connect-AzureAD -Tenant Directory (tenant) ID
  • Connect-ExchangeOnline -Organization Directory (tenant) ID
  • $myapp = Get-AzureADServicePrincipal -SearchString "NET Genium"
  • New-ServicePrincipal -AppId $myapp.AppId -ServiceId $myapp.ObjectId -DisplayName "Service Principal for POP3/IMAP Services"
  • Add-MailboxPermission -Identity "crm@firma.cz" -User $myapp.ObjectId -AccessRights FullAccess
• Creating rules for automatic forwarding of incoming and outgoing mail to the technology mailbox

6. Import e-mail messages

CRMService can import existing “eml” files, which are e-mail messages stored in their original format. For this purpose, it is necessary to create an import directory and set its absolute path on the disk to the configuration file under the “emlDir” attribute. CRMService reads the files in this directory, processes them in the standard way like other downloaded e-mail messages from the mail server, and then deletes the processed files from the import directory.

7. Configuration file

• It is necessary to create a configuration XML file for each technology box and place it in the same directory as “CRMService.exe”. Example configuration file:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
	
    <add key="rootPath" value="C:\inetpub\wwwroot\netgenium" />

    <add key="stopFrom" value="00:00" />
    <add key="stopTo" value="06:00" />

    <add key="smtpServer" value="localhost" />

    <add key="errorFrom" value="crmservice@firma.cz" />
    <add key="errorTo" value="support@firma.cz" />

    <add key="pop3Url" value="pop3.firma.cz" />
    <add key="pop3Email" value="crm@firma.cz" />
    <add key="pop3Name" value="crm@firma.cz" />
    <add key="pop3Password" value="pop3heslo" />
    <add key="pop3OAuth" value="true" />

    <add key="emlDir" value="D:\Services\CRMService\eml" />

    <add key="saveOriginalsFrom" value="abc@firma.cz" />
    <add key="saveIncomingAsPending" value="false" />

  </appSettings>
</configuration>

• rootPath – absolute disk path to the NET Genium directory
• stopFrom – start time of the technology pause in the format “HH:mm”, during which the CRMService service will not connect to the technology box
• stopTo – end time of the technology pause in the format “HH:mm”, during which the CRMService service will not connect to the technology box
• smtpServer – the address of the outgoing mail server
• errorFrom – e-mail address from which notifications of possible errors in the CRMService service are sent
• errorTo – e-mail address to which notifications of possible errors in the CRMService service are sent
• pop3Url – incoming mail server address (for SSL security it is possible to use the syntax “server name:port number”)
• pop3Email – e-mail address of the technology box
• pop3Name – login name to the technology box
• pop3Password – password for the technology box
• pop3OAuth – a flag indicating whether to use OAuth2 enhanced security for login
• emlDir – the absolute path on the disk to the directory from which the CRMService service reads and processes “eml” files
• saveOriginalsFrom – e-mail address, from which when the e-mail arrives, the file “Original.eml” will be automatically created in the activity attachment. Any number of “saveOriginalsFrom” parameters can be specified in the configuration file.
• saveIncomingAsPending – a flag indicating whether the “Due date” field should be filled in for the incoming e-mail message in the newly created activity.

All e-mail messages that arrive in the technology mailbox are deleted after processing.

8. Service installation

• CRMService is a service that runs in the background of the Windows operating system and automatically activates and downloads e-mails every 5 minutes. It is not enough to simply run the “CRMService.exe” program, but it is necessary to install the service using the “CRMService.exe – user.lnk” file. The file “CRMService.exe – user.lnk” is created automatically by running the program “CRMService.exe”.
• After running the “CRMService.exe” program, check the dialog settings. Set the startup mode to “Automatic” and select “LocalSystem” for the Account. Click the “Install” button to complete the installation of the service.

• You can also uninstall the program by running the “CRMService.exe” program and clicking on the “Uninstall” button.

9. Backup of downloaded e-mail messages

Copies of all e-mail messages delivered to the technology mailbox are automatically saved in the “POP3Downloads\yyyy-MM-dd” subdirectory, which is located in the same directory as “CRMService.exe”. E-mail messages are stored under a random name (GUID.eml), and are placed in a subdirectory whose name identifies the day on which the e-mail message was downloaded.

Example:

D:\Services\CRMService\POP3Downloads\2013-05-28\154c463d-386a-4b61-bf0d-6b2cd91a1bcb.eml

10. Assignment to an order, order, or task

E-mail messages delivered to the technology mailbox search for text strings, the occurrence of which in the subject or body of the e-mail will ensure the correct assignment of the created activity to an existing order, order or task. When writing these strings in an e-mail message, it is possible to:

• arbitrarily combine lowercase and uppercase letters,
• use strings with or without diacritics,
• a space may or may not be specified after the colon.

To assign to a contract:

• “Contract:number”
• “Contract:number type”
• “Contract:number p-”
• “Contract:number type p-”
• “Project:number”
• “Project:number type”
• “Project:number p-”
• “Project:number type p-”

To assign to an order:

• “Order:number”
• “Order:number type”
• “Order:number p-”
• “Order:number type p-”

To assign to a task:

• “Task:number”
• “Task:number type”
• “Task:number p-”
• “Task:number type p-”

To assign to an opportunity:

• “Opo:number”

Where:

• “number” is the contract / order / task number
• “type” is the type of activity that will be used when creating the activity (if not specified, the type “E-mail” will be used)
• “p-”, “p1”, “p2”, “p3”, “p4”, etc. is the scope setting (see next chapter)

11. Setting the scope of the activity

Newly created activities can be set scope – visibility of activities for individual user roles. The scope of activities is set when searching for text strings, the occurrence of which ensures the correct assignment of the created activity to an existing order, order or task.

When inserting text strings into the subject or body of an e-mail, the following methods are available for setting the scope of the newly created activity:

Failure to specify key chain “p-” (“p1”, “p2”, “p3”, etc.) for scope setting

Failure to find the “px” key string means that the scope of the activity will be set to the user role to which the sender (for outgoing messages) or recipient (for incoming messages) is assigned. This means that the activity will be visible to all users who

• are assigned to the same user role as the recipient or sender of the e-mail,
• are assigned to user roles with the same authority or
• they are in a user role with higher privileges than the user role of the recipient or sender.

Specify the “p-” key string to set the scope

The string “p-” means that the created activity will not have the scope set, which will cause:

• is visible only to the responsible person of the activity, if it is not assigned to the contract,
• is visible to the responsible person of the activity, and also to all members of the engagement work team, if assigned to the engagement.

Indication of the key string “p1”, “p2”, “p3”, etc. to set the scope

String “p1”, “p2”, “p3” etc. indicates that the created activity will have the scope applied to all user roles that have an immersion level equal to the specified number, as well as to all user roles that are superior to these.

The following rules must be observed for the correct setting of the required scope by the CRMService service:

• the length of the text string to be examined must be equal to two,
• the first character of the string must be equal to “p” or “P” and
• the second character of the string must be a number.

12. Activity type setting

The activity type is set when searching for text strings, the occurrence of which ensures the correct assignment of the created activity to an existing order, order or task. For example, you can set the type of activity in the following ways:

• “Contract:number Documentation”
• “Order:number Documentation”
• “Task:number Documentation”

The specified type of activity in the subject or body of the e-mail message must correspond to the already existing type of activity in NET Genium. If no match is found, the activity type is always set to “E-mail”. You can only set the type of activity in the subject or body of an e-mail for outgoing e-mails. For incoming e-mails, the activity type is always set to “E-mail”

13. Banned email addresses for Campaigns

CRMService also handles the analysis of e-mails that contain a request to immediately stop sending e-mail messages to the given customer.

If the e-mail arrives in the technology box with the subject line “do not send” or “I do not want” (it is possible to combine lowercase and uppercase letters and use strings with or without diacritics), all contacts and business relationships searched by e-mail will be marked. Sender's e-mail addresses – Specifically, the “Allow e-mails” and “Allow bulk e-mails” checkboxes for the contact or business relationship will be deselected. If no contact or business relationship is found based on the sender's e-mail address, the sender's e-mail will be recorded in the “Campaigns” application in the “Forbidden e-mail” table with the type set to “Do not send e-mails”.

If an e-mail whose subject contains the string arrives in the technology mailbox:

• “Undeliverable Mail” and the text of this e-mail contains the string “The following mail failed to be delivered...” and the string “To:” or
• “Undelivered Mail” and at the same time the string “message could not” and the string “be delivered to one or more recipients” are found in the text of this e-mail,

all contacts and business relationships searched for by e-mail addresses listed in the body of the e-mail message will be marked – specifically, the “Non-functional e-mail” check box will be marked for the relevant contact or business relationship. If no contact or business relationship is found based on the e-mail address in the body of the e-mail message, this e-mail will be recorded in the “Campaigns” application in the “Forbidden e-mail” table with the type set to “Broken e-mail”. “. At the same time, the created activity will be set as not fulfilled (the field “Completion date” will not be filled in).

Rules for unwanted or non-functional e-mails are implemented in the CRMService service mainly due to the “Campaigns” application. This application allows you to send bulk e-mails to e-mail addresses obtained from contacts or business relationships stored in the NET Genium database, as well as to e-mail addresses obtained from other databases. By clicking the “Remove invalid addresses” button in the campaign form, you can easily delete from the list of recipients' email addresses the addresses that were recorded in the “Forbidden e-mail” table as described above.

14. Invitations

CRMService automatically creates or updates invitations that are part of e-mail messages. Therefore, if an invitation is attached to the e-mail message, an invitation record is automatically created or updated in the “Activities” application for each of the recipients of the message, which was found in the NET Genium user table by e-mail address. All these recipients will see the invitation on the NET Genium main page, where they have the option to further process the invitation.

15. Rules for processing e-mail messages

Each e-mail message that is delivered to the technology mailbox is evaluated according to the rules of the CRMService service. The following list lists all the rules that are applied in CRMService and outlines the CRMService workflow.

15.1. Duplicate email messages

In the first step, the identification key of the e-mail message is composed of the general information of the e-mail message (date of the message, e-mail address of the sender, e-mail addresses of all recipients of the message and subject of the message). It then verifies that the email with the same key has not already been processed. If so, it is the same report that has already been processed and will therefore not be processed again. “DUPLICATE KEY” and “DELETED” will be written to the log file, and the message will be deleted without being processed.

An example is when one NET Genium user sends an e-mail message to three other NET Genium users, for example. Because all employees are set to forward incoming e-mail messages to the same technology inbox, the same e-mail message appears in the technology inbox three times. In terms of rules, which will be explained below, outbound activity will be generated when the first of these three messages is processed. However, when the next two are processed, the identification key is matched, so these messages will be deleted without being processed.

15.2. Problem solving

If the subject of the e-mail starts with the words “Description Problem No.”, “Commentary Problem No.”, “Status Problem No.”, “New Issue No.” or “Problem No.”, then it is an automatic e-mail, which the “Troubleshooting” application sends.

The CRMService service analyzes the body of the e-mail message. As part of this analysis, CRMService tries to determine if the body of the e-mail message includes information such as the order number, problem ID, problem subject, and problem status.

The order number is set in the “Area” form in the customer application “Troubleshooting”. The body of the e-mail message looks like “Contract:” and CRMService tries to find such a connection. The problem ID is determined by analyzing the individual links. If the link “&id =” appears in the link, the number after “=” is taken as the problem ID. Problem status represents the current status of the problem. In the e-mail message, CRMService detects the presence of the problem status and the subject of the problem by examining whether the table row contains the keywords “Status” or “Subject” or “Subject”, respectively.

If all four of these attributes are discovered in the body of the e-mail message, the e-mail message will be processed into a task. The task will either be created or updated if it already exists. The log file contains the “Task application” and a message about what was done with the task (eg NEW TASK CREATED, TASK ID UPDATED).

If one of the key attributes has not been discovered in the body of the message, the e-mail is not processed at all and “INVALID TASK” is written to the log file.

15.3. Invalid e-mail addresses or the same sender and recipient

If the sender's e-mail address is not valid or the message has only one recipient and his e-mail address is the same as the sender's address, the e-mail message is not processed as an activity and “SPAM” is written to the log file.

15.4. NET Genium

If the sender's e-mail address is set to “license@netgenium.com” or “error@netgenium.com”, the e-mail message is not processed as an activity and “NET Genium” is written to the log file.

15.5. Inform other users

If the subject of the e-mail starts with “Info about” and the body of the e-mail contains the sentence “This is an automatically generated e-mail”, the e-mail is not processed as an activity and “Inform other users…” is written to the log file.

The same rule applies to the English version. If the subject of the e-mail message contains the word “Details” or “details” and at the same time the body of the e-mail message contains the sentence “This is an automatically generated e-mail”, the e-mail message is not processed as an activity and is written to the log file. “Notify other users…”.

15.6. New task

If the subject of the e-mail starts with “New task:”, the e-mail message is processed as an activity according to the rules below, but a new one is also created. a task where the recipient of the e-mail message is listed as the solver and the sender of the e-mail message as the approver.

E.g. one employee receives an e-mail from a customer and needs to create a task for another employee as described in that e-mail. In this case, it is enough to forward the e-mail to another employee and insert one of the above-mentioned variants into the subject. CRMService automatically creates a new task with a subject matching the subject of the email (all after the colon). This task will be solved by all recipients of the e-mail message who were found in the NET Genium users table according to the e-mail address, the task approver will be the sender of the e-mail message, again found in the NET Genium users table by e-mail address.

“NEW TASK CREATED” is written to the log file if the sender was found in the NET Genium user table, or “UNKNOWN USER” otherwise.

15.7. Email forwarding and email replies

If the subject of the e-mail starts with “Re:”, “RE:” or “Fwd:”, the e-mail is processed as an activity according to the rules below (see chapters 13.10 and 13.11).

15.8. Exceptions for e-mail messages that are not processed

Any number of “ignoreSubject” attributes can be defined in the CRMService configuration file. If the configuration file contains “ignoreSubject” attributes, it verifies that the subject of the e-mail message contains at least one of the values stored under this attribute. If a match is found, the email is not processed as an activity and will be skipped. In most cases, these are service e-mails (eg “Service out of service”) for which it is not important to create new activities.

15.9. The direction of the e-mail message

CRMService handles incoming and outgoing e-mail messages differently. By default, the e-mail message is considered incoming.

15.9.1. The “pop3Email” attribute in the configuration file

The configuration file contains the mandatory attribute “pop3Email”, which defines the e-mail address of the technology mailbox. If CRMService detects that one of the recipients of the e-mail message is the technology mailbox, it automatically marks the e-mail message as outgoing.

15.9.2. The domain of the sender and the domain of the technology box

If CRMService detects that the sender's domain is the same as the mailbox domain, and it is not an e-mail message that has only one recipient with the same domain as the mailbox domain, it automatically marks the e-mail message as outgoing.

15.10. Processing of incoming e-mail messages

If one of the two conditions above is met and the e-mail is marked as outgoing, please skip to the next chapter!

For the evaluation of an e-mail message as incoming, it is a basic condition that at least one of the recipients is found in the NET Genium user table according to their e-mail address. If this condition is met, as many incoming activities will be created as the users (recipients of the e-mail message) have been found, and the respective recipient of the message will be set as the “responsible person” for each of these incoming activities. These activities will be identical in content, only each of them will have a different person in charge. “PROCESSED” is then written to the log file.

If none of the recipients of the e-mail message is found in the NET Genium users table according to their e-mail address, the message will be marked as outgoing and CRMService will try to process this message as outgoing.

15.11. Outgoing e-mail processing

If the e-mail message has been marked as outgoing, in order for the message to be processed successfully, the sender of the message must be found in the NET Genium users table by the sender's e-mail address. In this case, an outgoing activity will be created that has the username of the sender of the e-mail message set in the “responsible person”. “PROCESSED” is then written to the log file.

All e-mail messages that have not been processed as activities have “DELETED” in the log file.