Addovation Sync - Case - Configuration Document
Last Updated: 2025-03-12
Functionality of Sync Case
Introduction
The Sync Case system is designed to seamlessly integrate email communication into case management processes. This service automatically monitors a user’s inbox, focusing on emails sent to a specifically defined address. Upon receiving an email, the system processes it and creates a corresponding case, assigning a unique Case ID. An auto-reply is then sent to the sender, including the Case ID in the subject line for easy reference. Additionally, all relevant email content and attachments are systematically linked to the created case within the IFS system, enabling efficient tracking and management through the IFS admin login.
Sync Case supports multiple channels and can process emails directed to different "To" addresses. However, each "To" address is linked exclusively to a single channel.
Check-in Steps
1. Process Email: Create a Case ID for the email.
2. Upload Email File: Set the email subject as the file name.
3. Check-in Attachments Individually: Each attachment is checked in separately.
4. Process Auto-Reply: Handle the automated response.
5. Delete/Archived Email: Remove the processed email from the inbox, or if the incoming customer has an IMAP incoming server, move the email to the configured archive folder.
Updating the Case
When a customer replies to the auto-generated email, the service checks the email subject for the Case ID. If the Case ID is found, the service updates the existing case with the new information. To ensure the email is correctly associated with an existing case, the Case ID must be included in the email subject.
Configuration Overview
When setting up an Email2Case subscription through the cloud portal, various configuration options are available. These configurations are managed by a dedicated service. The client is identified using the tenant ID and environment name, which then determines the appropriate configurations.
Multiple Tenants and Environments Support
- Sync Case support multiple tenants per customer, and each tenant can have multiple environments by defining an environment name.
- For each environment, channels are created, with each channel considered a subscription.
- All configurations are linked to a specific channel.
- Multiple emails can be configured per channel, but all emails within a channel must be linked to the same IFS environment. If the email addresses need to be directed to different environments, separate subscriptions should be created. Each email can only be configured for one specific channel.
- Users can configure multiple channels under one environment, but a single channel can only support one IFS environment.
- If multiple users need to be created for the same environment, a separate subscription must be created for each user.
- It's not recommended to configure more than four channels, as it may affect data load management.
Managing Iterations
- The function app operates on a loop with a 20-seconds gap between iterations. This interval can be adjusted through the “Timer Schedule” configuration in the Azure environment variables.
- If there's a large volume of emails, the function app will need time to process them. Any new emails received during this period will have to wait until the current batch is processed, as the app only considers the emails present in its inbox at the start of each iteration.
- When there are four channels, the inboxes of all four channels are read sequentially during each iteration, with priority determined by database configuration.
- Each iteration is limited to 10 minutes. After 10 minutes, the process pauses and then restarts from where it left off.
- Due to this limitation, more than four channels are not recommended.
- To mitigate this, users have the option to create four separate function apps linked to different environments, allowing each to run in parallel for its respective channel.
Function App User Authentication
- For function apps, using SSO authentication, which requires a pop-up for user identification each time they log in, or basic authentication, can be challenging. Therefore, user authentication for function apps should be handled through a token generation process.
- To generate tokens, Sync Case needs to create a “Service User” in IFS with the necessary permissions. Then, an IAMClient environment is created to generate tokens for the service user.
- When setting up the IAMClient environment, a Client ID should be provided, and the “Service Account” option must be selected. The corresponding Service User is then chosen.
- Once the IAMClient environment is created, a Client Secret is generated alongside the Client ID. This Client ID and Client Secret are used when generating tokens for the Service User.
Email2Case Configurations
Channel Configurations
A few configurations are required to identify the channel.
ChannelId: A unique ID for the channel should be given. Currently there is no specific format for the channel ID.
ChannelName: Name of the channel to be given.
EnvironmentName: Environment name should be given.
TenantId: Customer’s tenant ID should be given.
TenantName: Relevant tenant name to be entered.
IFS Configurations
The IFS configurations related to Sync Case need to be set up here.
IFSConfigurations: The section next to the “realms” in IFS URL is given here.
IFsExtServer: IFS environment URL
IFsPassword: Client Secret provided by the customer, copied from IAM Client Details.
IFsUserName: Client ID provided by the customer, assigned during IAM Client creation
IFsTokenEndpont: IFS endpoint which supports generating the token.
IsIfsCloudVersion: The value should be 'true' for all IFS 10 and later versions
Channel Email Configuration
This section contains the configurations for the "to" email address associated with the specific channel.
Sync Case supports basic authentication, OAuth2 authentication and Multi-Factor authentication (MFA) for email addresses.
Basic Authentication: With an email ID and password, email addresses using basic authentication can be easily accessed, allowing the inbox to be read.
OAuth2 Authentication: For OAuth2 users, a Client ID and Client Secret are generated through Azure App Registration. These credentials ensure that the logged-in user is authorized for the relevant tenant.
Multi-Factor Authentication (MFA): To support MFA, an Azure App Registration is required with a client ID and an uploaded certificate, which should be linked to the Email Address Tenant. Moreover, Azure Key Vault is needed to verify the certificate, along with another Azure App Registration to access the Key Vault.
To complete the setup, the necessary permissions must be granted to the user through Azure API permissions, and the appropriate scope should be defined in the configurations.
AccountMode: SyncCase supports only the Scheduled function at the moment.
Scheduled: This account will continue support on scheduled functions. Addovation supports only scheduled at the moment. Scheduled function supports the service to run at specified times. We set that time under the function app configurations. (Refer the Sync Case Setup guide for customer for more information)
UserName: Username of the given email Id.
EmailId: This defines the Email address for the support channel.
Password: This defines the password of above-mentioned email account. Password must be set to never expire.
SendAsEmailId: While the EmailId represents the user account from which email2case reads the inbox, the “SendAsEmailId” is the address to which customers send their emails. Each EmailId is associated with a SendAsEmailId, and in some cases, these two may be the same.
TenantId: The tenant ID associated with the specified email address in “Channel Email Configurations”.
ClientId: This is the client id of the email account. We need the client ID, if only the OAuth is used.
RedirectUrl: When a token is generated from the app registration, it will be redirected to this URL. The list of redirect URLs should be defined in App Registration, and one of them must be specified here in the configurations.
During app registration, it is defined the access permissions for the emails received from a specified tenant. Multiple access levels can be defined, such as permissions to create an APIM, initiate services, create databases, or read emails. The specific permissions available through each app registration are defined at the time of setup. Here, the permissions (scopes) are required by the Sync Case.
Scopes: Permissions (scopes) required by the Sync Case system to read emails by logging into pop3 or imap servers or via GraphAPI are specified here.
ReplyScopes: Permissions (scopes) required by the Sync Case system to send emails by logging into pop3 or imap servers or via GraphAPI are specified here
MailProtocol: Pop3 or imap protocol or for MFA defined protocol as ‘GraphAPI’.
HostName: Incoming server details.
MailPort: This will be 995 for Pop3 and it will be 993 for imap.
ReplyMailHostName: Outgoing server details.
ReplyMailPort: This is 587 mostly.
MailFormat: This is the format in which the email is saved, and it can be either EML or MSG.
UseOauth: This should be “true” if user token authentication is used, and “false” if basic authentication is used.
UseSSL: This should be “true” if user token authentication is used, and “false” if basic authentication is used.
ReplyMailUseSSL: This defines, whether to use SSL or not when replying to the sender’s mail.
system to send replies by logging into SMTP server are specified. These requested scopes must align with the permissions granted in the app registration to ensure successful operation.
SMTPAuth: Whether the user needs to be re-authorized when sending a reply is defined here. The token generated when the inbox is read can also be used for the reply, or a new token can be generated specifically when the reply is sent.
DeactivatedFolder (only supports to IMAP Servers): While processing an email, if something goes wrong, SyncCase will deactivate the email from further processing and move it to the defined folder. If no folder name is defined, the email will be moved to the default deactivate folder. The folder will be systematically created as a subfolder of the inbox.
ArchivedFolder (only supports to IMAP Servers): Once the email processing is complete, the email will be moved to the specified folder. If no folder name is defined, the email will be deleted from the inbox. The folder will be systematically created as a subfolder of the inbox
Email Map Fields
A channel can have multiple "To" email addresses, each with its own set of configurations. The Email Map field values help identify the specific configurations for each "To" address when a case is created and placed in the queue. The most crucial map value is the MapID, which must match the UserName assigned to the corresponding "To" address under the Channel Email Configurations. The other values also required to map the Sync Case fields with IFS fields.
MapID: This should match the UserName in the Channel Email Configurations.
DefaultValue: The value to be used if no field value is received.
FieldName: The name of the field in the Sync Case application.
FieldValue: A specific value that can be assigned to the mapped field, which will always be passed.
IfsFieldName: The corresponding IFS field name that should be mapped to the Sync Case field.
IsKeyField: Indicates whether this field is mandatory.
IsUseDefault: Determines whether the DefaultValue should be used. If true, the default value will be passed even if a FieldValue is received.
Attachment Config
These configurations define how email attachments should be managed within IFS when a case is created from a received email.
CheckInAttachments: Defines how email attachments should be checked in when an email is received. If this configuration is set to true, the attachments will be checked in separately along with the message file; otherwise, only the message file will be checked into IFS.
CheckinMsg: Specifies that the email message file itself should be checked in.
ClassFormat: The class format in which the message file and attachments should be checked in. This is optional.
ClassName: The class name under which the message file and attachments should be checked in.
KeyRef and LuName: These define the object to which the checked-in document should be linked, which in this case is the created or updated case. Each case is treated as a new object, and the attached document revisions can be viewed under the object’s attachments. The details required for creating this object, such as KeyRef and LuName, can vary depending on the customer.
IsAttachToMainCase: Attachments can be linked to a created or updated case, or they can be linked to case contact notes. If the configuration value is set to 'True,' the attachments will be linked to the case.
ContentEncodes: Certain special characters, such as Big5, may be supported by client systems but are unrecognized by the Sync Case system. While general standard character types are typically supported, any additional encoding required for unidentified characters should be specified here to ensure compatibility.
Attachment Map Fields
These configurations assist in mapping fields between the projection/script and the Sync Case system. No specific values are provided here; only the fields are mapped. Various mapping fields are available for different categories, such as ‘DocType’ and ‘FileExtOriginal’.
The following mappings should currently be passed by default.
{
"DefaultValue": "",
"FieldName": "DocFormat",
"FieldValue": "",
"IfsFieldName": "DocumentFormat",
"IsKeyField": false,
"IsUseDefault": false
},
{
"DefaultValue": "",
"FieldName": "DocType",
"FieldValue": "",
"IfsFieldName": "DocumentType",
"IsKeyField": false,
"IsUseDefault": false
},
{
"DefaultValue": "",
"FieldName": "ErrorMessage",
"FieldValue": "",
"IfsFieldName": "ErrMsg",
"IsKeyField": false,
"IsUseDefault": false
},
{
"DefaultValue": "",
"FieldName": "FileExtOriginal",
"FieldValue": "",
"IfsFieldName": "FileExt",
"IsKeyField": false,
"IsUseDefault": false
}
Attachment Service
These configurations are related to the service that manages the document check-in process (document management service).
ServiceEndpoint: Specifies the endpoint to be accessed for checking in documents.
ServiceUrl: The URL of the document management service.
TimeoutSeconds: Defines the timeout duration in seconds. A longer timeout is set here to accommodate the check-in of larger documents, which may take more time.
Checkin Attachment Backend
These configurations define the IFS projection details that should be invoked during the document check-in process.
ProjectionEndpoint: Specifies the URL endpoint for the projection. Only the portion of the URL related to the projection is required; the initial part of the IFS URL can be omitted.
FieldNames: Lists the field names that need to be passed by the Sync Case system. These field names should be correctly identified to ensure the values are passed properly, and they should be separated by commas. These field names can be found in the IFS API documentation.
MessageSetting
These configurations define the handling of message processing and auto replies.
AutoReplyEnabled: When set to True, the sender will receive an automatic reply from the Email2Case system once a case is created.
AutoReplyMessage: Defines the structure of the auto-reply email. The email body will include variables that change dynamically based on each email.
AutoReplySubject: Specifies how the subject line of the auto-reply is formatted. For example:
[#GLB#{CaseID}] {Subject}
\[\]
: Specify static string.
#GLB#
: A fixed identifier.
{CaseID}
: The case ID appears within curly brackets after the fixed identifier.
{Subject}
: The original email subject appears within curly brackets after the case ID.
When the user replies to the auto-reply without changing the subject, the system will recognize it as part of the same case and update the existing record. However, if the user removes the fixed identifier from the subject before replying, the system will not recognize it as an existing case, and a new case will be created.
This behavior occurs because the auto-reply format is clearly defined in the configuration. Any emails related to an existing case must have the same subject as the original auto-reply in order for the system to associate them with the correct case.
- KeyIdentifierPriority: If the fixed identifier is removed from the subject but a hashtag is placed at the beginning and end of the case ID (e.g., #{CaseID}#), the system will still recognize the existing case and update it. This is because an alternative identifier format can also be defined for case recognition.
The system gives priority to the auto-reply subject format defined in "AutoReplySubject", and the second priority goes to this alternative identifier.
For example: [#GLB#{CaseID}], #{CaseID}#
If both formats are present in the subject, priority is given to the one with the fixed identifier. The highest priority format should always be listed first, before any commas. Formats listed later have lower priority.
AcceptNoSubject: If this is false, emails without a subject will be ignored.
DefaultSubject: If an email is received without a subject and is not ignored, a default subject can be set here. Any string value can be defined for this purpose.
SubjectFilter: Emails can be filtered by configuring SubjectFilter. This allows processing only emails whose subjects match the specified filters, while the rest will be deleted or moved to the archive folder.
There are several ways to configure filters:
Support%
– Filters emails where the subject starts with the keyword "support" (not case-sensitive).
%Case
– Filters emails where the subject ends with the keyword "case" (not case-sensitive).
%Priority%
or Priority
– Filters emails where the subject contains the keyword "priority" (not case-sensitive).
\[SUPPORT%\]
– To filter subjects with case-sensitive keywords, enclose the filter in square brackets ([ ]).
Empty
– Leave the filter blank if all emails should be processed without filtering
ToEnabled: When set to True, the auto-reply will be sent to both the email sender and all recipients listed in the "To" section.
BccEnabled: When set to True, the auto-reply will be sent to the email sender and all recipients in the "Bcc" section.
CcEnabled: When set to True, the auto-reply will be sent to the email sender and all recipients in the "Cc" section.
FontFamily: Specifies the font family used for the auto-reply.
FontSize: Defines the font size for the auto-reply.
FirstMailConditions
A request raised by some customers that they want an identifier to identify the first email of a email thread.
DefaultValue: The value to be used if no field value is received.
FieldName: Field name in which a value will be passed to identify the first email.
FieldValue: In IFS, the value set here will be displayed against the first email attachment. For example, if the value is set as “Y”, it will be displayed against the first email.
IfsFieldName: IFS field name to which the value will be passed to identify first email.
IsKeyFields: Indicates whether this field is mandatory.
IsUseDefault: Determines whether the DefaultValue should be used. If true, the default value will be passed even if a FieldValue is received.
ReplyConditions
This defines under which conditions the service should send an auto reply if the auto reply is enabled in message settings.
User can define whether the auto-reply should be sent only to the first email or to all case-related emails. In that case, the system checks the value of the field used to identify the first email, and based on that value, the auto-reply is triggered.
If no values are specified here, the auto-reply will not be sent, as the conditions for sending it are not set.
DefaultValue: The value to be used if no field value is received.
FieldName: The name of the email2case field used to determine whether an email is the first in a series.
FieldValue: Indicates the action for sending an auto-reply. If set to "Y," an auto-reply is sent only to the first email. If set to "N," the auto-reply will be sent to all subsequent emails except the first.
IfsFieldName: The IFS field name that maps to the email2case field, used to identify whether an email is the first in the series.
IsKeyFields: Specifies whether the field defined above is considered a key field.
IsUseDefault: Determines whether the DefaultValue should be used. If true, the default value will be passed even if a FieldValue is received.
BackendService
The service which is used when creating a case is defined here.
These configurations are related to the service that is used when creating a case.
ServiceEndpoint: Specifies the endpoint to be accessed for creating a case.
ServiceUrl: The URL of the service.
TimeoutSeconds: Defines the timeout duration in seconds. This is typically the same for all customers but can be changed if the version is updated for a specific customer.
UpdateCaseBackend
The projection which is used to update a case is defined here.
ProjectionEndpoint: Specifies the URL endpoint for the projection.
FieldNames: Lists the field names that need to be passed by the Email2Case system. These field names should be correctly identified to ensure the values are passed properly, and they should be separated by commas.
ChannelMapFields
This section defines the mapping configuration for fields associated with "UpdatedCaseBackend."
Each one needs to be discussed further in detail.
“FieldName”: “CaseId”, “IfsFieldName”: “” - Specifies the IFS field that should be mapped to the "CaseId" field in the email2case system.
“FieldName”: “Objkey”, “IfsFieldName”: “” and “FieldName”: “Seq”, “IfsFieldName”: “” -
When an email is checked in, it can either be attached directly to the case, making it accessible in the IFS attachment panel, or it can be attached to a specific line, requiring the user to select the line to view the attachment.
The Object Key and Sequence ID fields aid in identifying the specific line to which the attachment belongs. This section specifies the relevant IFS fields to map with the "Object key" and "Seq" fields in the email2case system.
Under “KeyRef” in the Attachment Configurations, the Sequence ID is mapped to the Case ID to facilitate attaching the correct attachment to the case.
If only the Case ID is being used for checking in attachments, mapping the Sequence ID is unnecessary. Additionally, if any other field (such as Line ID or a similar identifier) is received from IFS in place of Seq, it should be mapped to the corresponding Sync Case field and specified in the attachment configurations.
“FieldName”: “CaseId” – Specifies the IFS field (Title) that should be mapped to the "Subject" field in the Sync Case system.
“FieldName”: “SentFrom”, “IfsFieldName”: “” - Specifies the IFS field that should be mapped to the "SentFrom" field in the Sync Case system.
“FieldName”: “DisplayName”, “IfsFieldName”: “” - Specifies the IFS field that should be mapped to the "DisplayName" field in the Sync Case system.
“FieldName”: “Description”, “IfsFieldName”: “” - Specifies the IFS field that should be mapped to the "Description" field in the Sync Case system.
“FieldName”: “Attachment”, “IfsFieldName”: “” - Specifies the IFS field that should be mapped to the "Attachment" field in the Sync Case system.
This attachment field is used to identify whether there is an attachment included in the email or not.
- “FieldName”: “DefaultCustomer”, “IfsFieldName”: “” - Specifies the IFS field that should be mapped to the "DefaultCustomer" field in the Sync Case system.
If a sender is registered under multiple customers, the record will be created under the first customer listed, with a warning message logged. If the sender is not registered under any of the available customers, the record will be created under the default customer specified here.
“FieldName”: “CustomerName”, “IfsFieldName”: “” - Specifies the IFS field that should be mapped to the "CustomerName" field in the Sync Case system.
“FieldName”: “IsMultipleCustomer”, “IfsFieldName”: “” - Specifies the IFS field that should be mapped to the "IsMultipleCustomer" field in the Sync Case system.
This field indicates whether the sender is linked to multiple customers. Based on the Boolean value received from IFS, the Sync Case system will proceed with the appropriate actions.
“FieldName”: “KeyRef”, “IfsFieldName”: “” and “FieldName”: “LuName”, “IfsFieldName”: “” – Specifies the IFS fields that should be mapped to the "KeyRef" and “LuName” fields in the Sync Case system.
“FieldName”: “ExcludeStates”, “IfsFieldName”: “” - Specifies the IFS field that should be mapped to the "ExcludeStatus" field in the Sync Case system. As previously explained in this document, cases with statuses that should not be updated when an email is received are specified under "ExcludeStatus".
VerifyCaseBackend
When an email is received, the Sync Case service first checks if the email is related to an existing case by analyzing the email subject. If the email is related, the relevant case ID must be included in the subject. To verify whether the case ID is valid, this configuration is used.
When an email is related to an existing case, one of the following criteria will be applied:
- If the email is related to a closed, completed, or canceled case:
The previous case will not be updated, and a new case will be created. - Regardless of the case status:
The case will be updated.
Users can select their preferred criteria, and this will be checked along with the case ID verification.
FieldNames: Specifies the field names that should be verified (Ex: Case ID) and the statuses that should be excluded.
ProjectionEndpoint: Specifies the URL endpoint for the projection.
RollbackService
Typically, attachments are checked in after a case is created. However, if the check-in process for the attachments fails, the case will be created without any attachments, and the related email will be deleted or moved from the inbox after the case is created.
In such situations, where the attachments cannot be successfully checked in, the created case should either be canceled or closed. The service (API endpoint) used to handle this rollback process is defined within the RollbackService.
ServiceEndpoint: Specifies the service endpoint to be accessed to rollback a created case.
ServiceUrl: The URL of the service.
TimeoutSeconds: Defines the timeout duration in seconds.
RollBackBackend
The backend (IFS projection) responsible for handling the rollback process is defined here in RollBackBackend.
Note: The distinction between the service and the backend is as follows:
The service
refers to the email-to-case API endpoint that should be accessed.
The backend
refers to the IFS projection that must be accessed for the rollback process.
ProjectionEndpoint: Specifies the projection endpoint to be accessed to rollback a created case.
FieldNames: Lists the field names that need to be passed to endpoint.
BlackList
Email IDs that should not be processed can be specified here. Users can define any number of email IDs, and any emails from these addresses will be deleted from the inbox.
EmailFilters
Users can define specific email content here. If this content is found in either the email body or subject, the email will not be processed and will be deleted from the inbox.
CacheDuration
In the database channel logs, both error details and successfully processed email details (even if they are deleted from the inbox) are cached for system reference. The duration for retaining this cache is defined here.
Please note that logs of emails still present in the inbox will not be deleted from the cache. Only the logs related to emails deleted or moved from the inbox will be removed when the cache is cleared.
CachedLogHour: Specifies how many hours the error logs will be retained.
MaximumRetry: Defines the maximum number of retry attempts for errors that are either not covered under LogCategoryActions or do not fall under any defined error category. Once this limit is reached, the case will be deactivated.
ProcessedMailHour: Specifies the number of hours the logs of processed emails will be retained.
LogCategoryActions
As described in the RollBackService, if an attachment check-in fails, the email-to-case process will attempt the check-in a few more times. When an error occurs during an iteration, the service will continue processing other emails in that iteration and attempt to check the failed one again in the next iteration.
For each error category, the number of allowed failures (attempts) is defined here. Until the final attempt, the status of the email remains “Active.” Once the maximum number of allowed failures is reached, the case will be rolled back and canceled. In the next iteration, a message will indicate that the specific email will no longer be processed. Users can manually delete emails from the inbox that were not processed due to errors.
Actions for handling these failed emails can also be defined here, either as “Deactivate” or “Suspend”:
Deactivate:
The email will no longer be processed but will remain in the inbox.Suspend:
The email will be deleted from the inbox in the next iteration.
These error logs can be viewed in the email-to-case channel logs with the corresponding status.
ActionType: Specifies whether the action for the case is set to "Deactivate" or "Suspend."
LogCategoryName: Specifies the error category.
NoOfFailuredAllowed: Specifies the number of attempts allowed before the case is rolled back.
Available error categories are as follows.
IFS Error
Error Name | Description |
---|---|
IFSError | Error returned from IFS when attempting to create a case |
IFSDocumentError | Error returned from IFS when attempting to check in a document |
IFSUnauthorized | The token is unauthorized from the IFS |
IFSServerError | The IFS server is unresponsive |
IFSResponseFailed | No response received from IFS after sending a request |
Email Related Error
Error Name | Description |
---|---|
BlockMessages | Triggered when incoming messages are blocked |
MailContentError | Error received when unable to read the email content |
AccountUnauthorized | Received when user credentials are incorrect |
AccountAccessDenied | Received when access is denied despite correct credentials, possibly due to permissions or scope issues |
AutoReplyError | Error encountered when sending an auto-reply |
Server-Side Error
Error Name | Description |
---|---|
InternalServerError | Error encountered while accessing either the email2case or IFS server |
SystemError | Default error category for unidentified issues |
ServiceUnauthorized | The token is unauthorized from the service |
ServiceAccessDenied | Access denied by the service |
Channel Error
Error Name | Description |
---|---|
InvalidConfiguration | Displays if channel configurations are invalid when validated by the email2case service |
LogTraceStatus
More details on the logs can be accessed in debug mode. However, some customers have requested that certain information be hidden in debug mode as well. The content that needs to be displayed or hidden is defined here.
LogFieldName: Specifies the name of the field.
LogTraceEnable: Indicates whether the field should be displayed (True) or hidden (False).