How-to: Troubleshooting Exact Lightweight Integration Server (ELIS)
Introduction
Exact Lightweight Integration Server (ELIS) is a composite solution that involves several
services and communication through the network. Furthermore, ELIS is
designed to host the external solutions that are developed by Exact or third
parties. Thus, it is prone to errors and finding issues are difficult. The ELIS
infrastructure provides different information to the administrators so that it
will be easier for them to look for the issues and solve them as soon as
possible. This reduces the maintenance and down time of the services.
The ELIS engine works based on the
offline messaging model whereby the communication to ELIS is done by
sending messages to ELIS. Offline means there is no immediate
communication. If there is an issue or problem with the network, all the
messages will be stored and ELIS will process them when the
communication is restored. The messages will not be lost or discarded. If there
is no communication problem, the messages will be sent to ELIS and
processed immediately.
The following diagram displays the message
flow from the product to ELIS. Every section works differently and the
way to troubleshoot each section is different. Some of the operations are done
by different processes.
Scope
This document describes the various ways to
troubleshoot ELIS-related solutions based on the operation of the engine,
assuming the solutions have been deployed successfully to the products.
Deployment and configuration issues are not explained in this document, and all
the settings and services are assumed to have been configured properly.
All the functionalities explained in this
document are available only for Exact Synergy Enterprise product update 253
onwards and Exact Globe Next product update 408 onwards. The version numbers
will be mentioned only if there are differences in the functionality for the
version.
Disclaimer
The information in this document is only
for troubleshooting. Some of the steps might differ for different products. The
information provided is applicable only for Exact Synergy Enterprise product
update 253 onwards and Exact Globe Next product update 408 onwards. The third
party add-ons might handle the errors differently and the ELIS
infrastructure might not be able to handle all the errors. All the solutions
and add-ons developed by Exact are supported by the troubleshooting steps,
unless stated otherwise.
Manual modification of the files or
settings might change the way the software works and must be performed with
caution. Changing some of the settings or files might require rebooting the IIS
server or other services which might affect the users and cause errors if they
try to access those services. The working solutions might also be affected.
Thus, it is advisable to contact Exact before making any changes.
Message flow
It is easier to find the issues and solve
them if you have an understanding of how messages travel to each of the
component. In this document, Exact Integrator (Exact Integrator
synchronizes information between Exact Synergy Enterprise and Exact Globe Next)
is used as an example.
- If there is a change of data in Exact Synergy
Enterprise or Exact Globe Next, the ELIS solution must inform ELIS
about the changes. Every solution has a different logic on how and when to
inform the server on the changes. Each solution deploys Subscribers to
the client products. The subscriber will be notified by Exact Synergy
Enterprise or Exact Globe Next when the data is changed. The subscriber will
create a message and put it into elisOutgoingQueue in MSMQ.
- The dispatcher service will pick up the message
and based on the destination, send the message to ELIS by calling the
web services.
- From the other side, the ELIS listener
will receive the message, check the message structure, and put it in the elis.main
queue in MSMQ. The listener service runs under the system user. If the system
user has access to Microsoft SQL Server, the listener service will create a
monitor record in ELIS to track the message. However, if the system user
does not have access to Microsoft SQL Server, the listener service will skip
this step. The status of the record will be “Received”.
- The resolver service will pick up the message
from the main queue and check the monitoring component to determine whether
there is a record for the message in the database. If there is a record in the
database, the resolver will update the status of the message. Otherwise, the
resolver will create the monitor record for the message.
Note: If the message reaches this stage, you can check the status of the
message in the ELIS management console (go to Monitoring ? Integration
status). If you cannot find any record under the monitor section, this means
the issue is in the previous steps.
If
the status of the record is “Pending”:
- The resolver will prioritize the message based
on the solution information and send the message into one of the priority
queues. The status of the record will be “Pending” and the destination queue
will be displayed under the monitor section.
- The resolver will then receive the message and
start to process it. The status of the record will be “Processing”.
- There will also be two results from the
processed message, which are “Successful” or “Failed”. If the processing has
failed, the error message will be recorded.
- If the processing has failed, you can try to
process the failed message again after the issue is solved by going to the Integration
status in the ELIS management console. Find the failed message and
click Retry. The status of the record will be “Retrying” and you will be
able to view the number of tries.
Troubleshooting
Once the message is in ELIS, it will
be recorded and you can easily track the status of the message. Troubleshooting
manually most often occurs when messages are not displayed under the monitor
section. This means something is wrong with the client or dispatcher. However,
if the ELIS services cannot access the database, there will be no record
of the message. Thus, you have to start from the source where the message was
created.
Firstly, check the statuses of the services
for the client and server. Make sure the Exact Integration Dispatcher
service is running on the client, and Exact Integration Listener and Exact
Integration Resolver services are running on the server. By default, each
of the service has a different way of preventing the down time.
Exact Synergy Enterprise
In Exact Synergy Enterprise, if any error
occurs when the messages are created or sent to MSMQ, the error log will
display the error messages (go to Setup ? Reports ? Log ? Errors). You
can filter the error messages based on the user or date and time, or search based
on the word “notification” (allows you to view all the notification errors).
If there is an error with the notification,
the error message will not be created. Check the error message because the
error might be due to the configuration, for example, a wrong division number
has been used, some of the data do not exist anymore, or the data have been changed.
You can solve the issue based on the description of the error. To prevent more
error messages from being created, you can remove the activation from the ELIS
management console. For more information, see How-to: Activating and deactivating solutions for Exact Lightweight
Integration Server (ELIS). However, if the activation
involves more than one product such as another Exact Synergy Enterprise or
Exact Globe Next, deactivating the add-on will also deactivate the clients.
If no error messages are displayed, the
error notification might not be working properly. To make sure the error
notification is working, refer to the Exact Integration Dispatcher
section.
Exact Globe Next
In Exact Globe Next, if an error occurs
when the message is created or sent to MSMQ, an error log will be created. You
are required to check the database for the error messages. In the Exact Globe
Next database, execute the following SQL query in the Microsoft SQL server
management studio. You can filter the error messages based on the “LogDate” for
the time of the error message or “HumresID” for the user.
The following results will be displayed
after executing the SQL query.
If there is an error with the notification,
no message will be created. Sometimes, the error occurs due to the
configuration, for example, a wrong division number has been used, some of the
data do not exist, or the data have been changed. You will be able to solve the
issue based on the description of the error. If you do not want the error
messages to be created, remove the activation from the ELIS management
console. For more information, see How-to: Activating and deactivating solutions for Exact
Lightweight Integration Server (ELIS). However, if the activation involves
more than one product, for example, another Exact Synergy Enterprise or Exact
Globe Next, deactivating the add-on will also deactivate the clients.
If no error messages are displayed, the
error notification might not be working properly. To ensure the error
notification is working properly, refer to the Exact Integration Dispatcher
section.
Exact Integration Dispatcher
Once the message is created and placed in
the “elisOutgoingQueue” dispatcher, the “elisOutgoingQueue” dispatcher will
take the message. Exact Integration Dispatcher is a Microsoft Windows
service that can be shared by all the ELIS clients on the same machine.
To prevent any down time for this service,
once the service is installed by the product updater, the recovery option of
the dispatcher will restart the service if the service fails.
You can stop the dispatcher service to
check whether the error notification is working by opening the Microsoft
Windows services, select Exact Integration Dispatcher, and stop the
service. Change the relevant data in Exact Synergy Enterprise or Exact Globe
Next. For example, if you are testing Exact Integrator, you can change
the account, item, item unit, or any supported entity. Check MSMQ to determine whether
the message has been created in MSMQ. To check MSMQ, go to Start ? Control
Panel ? Administrative Tools ? Computer Management. In the Computer
Management screen, click Services and Applications, click Message
Queuing, and then click Private Queues. Always refresh this screen
because the screen will not be refreshed automatically. The “elisOutgoingQueue”
service will display the number of messages.
The notification is working properly if
there are messages in the queue.
Note: Before
you test the dispatcher, check the queue before performing any operation to
create messages because the queue might already contain messages from other
solutions or there might be messages pending for processing.
If there is a problem with the dispatcher,
this service will log the problem in the Microsoft Windows Event Log. To access
the event log, go to Start ? Control Panel ? Administrative Tools ? Computer Management. In the Computer
Management screen, click Event Viewer, click Applications and
Service Logs, and then click Exact Integration Dispatcher. The
errors and warnings will be displayed.
If there is an error in the dispatcher or
message, the dispatcher will log the error message, ignore the message in the
queue, and continue the operation.
There is also a possibility the message is
correct due to external reasons (for example, network failure) or the
dispatcher cannot connect to ELIS. If this occurs, the dispatcher will
try to process the message a few times based on the internal configuration. If
the message cannot be processed, a warning message with the full description
will be logged, the message will be ignored, and the operation will continue.
To check the message in the event log, click the Details tab. The error
message will be displayed after the warning message to indicate what went wrong
before the dispatcher ignores the message.
If the message is created successfully and
the dispatcher has processed the message, this means the message is in ELIS
(refer to ELIS section).
Note: Exact
Integration Dispatcher is a shared service. Exact Synergy Enterprise and
Exact Globe Next are using the same dispatcher service.
ELIS
There are several components in ELIS.
These components all work together but not independently.
The listener will be the first component
that will receive the messages and put the messages in the main queue. This
process helps ELIS to keep the messages in a safe location before the
messages are processed. If ELIS is busy or not working properly, the
messages will remain in the listener. The listener runs under the system
account. If the account has access to the database, a monitor entry will be
created immediately for the messages and you can view the progress of the
messages in the ELIS management console. If an error has occurred in the
component, the error will be logged in the ELIS database. However, if
the database cannot be accessed, the error will be logged in the event log.
To check whether the listener is sending
the messages to the “elis.main” queue, stop the ExactIntegrationResolver
service, select MSMQ (refer to the Exact Integration Dispatcher
section), and view the number of messages in the queue. The listener is working
if the number of messages in the queue changes after changing the data in Exact
Synergy Enterprise or Exact Globe Next.
The resolver will then pick up the messages
from the “elis.main” queue and process the messages. The ExactIntegrationResolver
service will run under a fixed user. Thus, the service will have access to the
database. The messages will be available in the Integration Monitor in
the ELIS management console and you will be able to check the progress
of the messages. All the error messages will be logged in the Server Log
and if the resolver finds any issues that will prevent the messages from being
processed, the status will be changed to “Failed” and the error messages will
be logged in the system.
For each failed message, a log record will
be created to display the error message and stack trace that caused the error. Stack
trace is used for debugging and it is not included in the ELIS
management console but it is available in the Logs table in the ELIS
database.
Note:
- Since every solution has its own way of handling
the error messages, it is possible to have a successful status in the Monitor
section without the actual data being processed. If this occurs, you have to
ask the solution developers to look for the problem.
- If multiple messages are sent to ELIS at
the same time (for example, when creating an account, Exact Synergy Enterprise
or Exact Globe Next will send multiple messages for the account, contact, and
address at the same time), and one of the messages fails in the resolver, this
component will stop processing the messages and the following error will be
displayed:
Tracing
You can trace the execution of the codes
and process the messages through the system and different components. By
default, the tracing is turned off. To turn on the tracing, open the ELIS
installation directory, click the XMD folder, and open the Exact.MacroManager.Trace.Config
file with any text editor. Find the TraceEnabled value and change it
from “0” to “1”. You can define the location of the trace file by modifying the
TraceStorageFolder value. After changing the value, restart the ELIS
services for the change to take effect.
Once the trace is turned on, ELIS
will create a trace file in the location of the configuration and store the
records of the trace in the ExactIntegrationTracelog.xml file. All the
trace data will be placed in this file. Thus, the size of the file will grow
very fast. The contents in the file can only be read by the Service Trace
Viewer tool (SvcTraceViewer.exe). This is a development tool and it is not
available for download. You have to send the trace file to the Exact support
for further action.
Note: Tracing
is used mainly for debugging and troubleshooting purposes. Therefore, tracing
should not be turned on in an active environment because it can affect the
performance of the execution codes.
Tracing can also be turned on for the
client and dispatcher by copying Exact.MacroManager.Trace.config to the XMD
folder in Exact Globe Next, Exact Synergy Enterprise, or Exact Integration
Dispatcher. After the file has been copied, restart the product:
- Exact Synergy Enterprise — Restart the IIS
service.
- Exact Globe Next — Close and reopen the
application.
- Exact Integration Dispatcher — Restart the ExactIntegrationDispatcher
Windows service.
Once
the message has passed through the different components, the trace will log the
information and error messages if anything goes wrong.
Note: Always turn off the trace after you have saved the trace file. Make
sure the trace file is turned off when a lot of users are using the system.
Related documents
| Main Category: |
Support Product Know How |
Document Type: |
Online help main |
| Category: |
On-line help files |
Security level: |
All - 0 |
| Sub category: |
Details |
Document ID: |
26.179.481 |
| Assortment: |
Exact Synergy Enterprise
|
Date: |
20-03-2015 |
| Release: |
|
Attachment: |
|
| Disclaimer |