Using the eConnect Incoming and Outgoing Services With MSMQ

The eConnect Incoming and Outgoing services provide an easy method for sending and consuming eConnect XML messages with external applications.  Both services utilize Microsoft Message Queueing (MSMQ), which enables applications running at different times to communicate across networks and systems that may be temporarily offline. Applications send messages to queues and read messages from queues.

The following guide will aid in configuring and troubleshooting both services and their integrations with MSMQ.

Configuring the eConnect Incoming service:

First off, ensure that you are using the eConnect for Microsoft Dynamics GP 2018 version of the eConnect Incoming service, as previous versions have been known to have issues causing slowness or the service to not transfer the documents to the MSMQ Queue.

In order to utilize the service, you will need to edit the “eConnect_Incoming.exe.config” configuration file located at

C:\Program Files\Microsoft Dynamics\eConnect 18.0\Service\Incoming Service

and point it to the correct location, so that the service knows where the send the documents to. Here is an example of what this would look like:

<?xml version="1.0"?>

<configuration>

<appSettings>

   <!--   eConnect.BackOffice.ConnectionString should point to your SQL server and company DB. -->

   <!--   Leave the eConnect.Incoming_Queue value="" if you want the eConnect Incoming Service to create the Queue for you. The default queue name will be Machinename\Private$\eConnect_Incoming. The format for public queues: MachineName\QueueName -->

 <!--   Public Queue example: -->

   <!--   <add key="eConnect.Incoming_Queue" value="MyQueueServer\eConnect_Incoming" /> -->

   <!--   Private Queue example: -->

   <!--   <add key="eConnect.Incoming_Queue" value="MyQueueServer\Private$\eConnect_Incoming" /> -->

   <!--   <add key="eConnect.Transactional_deadletter_Queue" value="0" />   0=System Transaction deadletter Queue(Defualt). 1=Queue defined in eConnect.Incoming_Queue key, plus _deadletter. -->

   <!--   eConnect.Schema.Type key refers to the type of schema that you would like to validate against "", XSD, or XDR. "" means that no validation will take place agianst your xml doc. -->

   <!--   example: <add key="eConnect.Schema.Type" value="XSD" /> -->

   <!--   eConnect.Schema tells the services where to find an eConnect XSD or XDR schema to validate the xml against. If its value is blank then the xml will not be validated against a schema. -->

   <!--   example: <add key="eConnect.Schema" value="C:\Documents and Settings\Myuser\My Documents\Visual Studio Projects\eConnect_API\bin\eConnect.xsd" /> -->

   <!--   example: <add key="eConnect.LogALL" If this value is set to 0 then no erros will be sent to the event log, 1 = Log Only Errors, and 2 then all message successfull or unsuccessull will be logged in the eConnect eventlog. /> -->

   <!--   <add key="eConnect.Threads" value="0" /> -->

   <add key="eConnect.BackOffice.ConnectionString" value="data source=127.0.0.1;initial catalog=TWO;integrated security=SSPI;persist security info=False;packet size=4096" />

   <add key="eConnect.Incoming_Queue" value="dax2012r3\private$\econnect_incoming" />

   <add key="eConnect.Transactional_deadletter_Queue" value="0" />

   <add key="eConnect.Schema.Type" value="" />

   <add key="eConnect.Schema" value="" />

   <add key="eConnect.LogAll" value="1" />

   <add key="eConnect.Threads" value="0" />

</appSettings>

</configuration>

I have highlighted the most important changes needed for the file: The data source (SQL server name or IP address), initial catalog (default GP company used), and the eConnect Incoming Queue, which can be found via Computer Management -> Services and Applications -> Message Queueing and then right-clicking on the queue name and selecting Properties

Note: The queue will need to be “Transactional” in order to work with eConnect. You will also want to confirm that the account(s) used to run the eConnect services have the appropriate permissions on the Security tab of the queue properties window.

Once you have installed the service and updated the configuration file, you can then test the service by using the “Queue Client” application, which is available at

C:\Program Files (x86)\Microsoft Dynamics\eConnect 18.0\eConnect Samples\VB DOT NET Queue Client

In order to use the tool, you will need to open the “QueueClientForDotNet.vbproj” project file from the above location in Visual Studio, and either Start it (at a minimum) or Build it for continued use.

For our test, we will be using the private “econnect_incoming” queue. You can simply select the queue from the “Local Private Queues” drop-down as shown below:

The tool includes a “msmqtest.xml” sample XML file to use, located at C:\Program Files (x86)\Microsoft Dynamics\eConnect 18.0\eConnect Samples\VB DOT NET Queue Client\bin which I have also selected in the “XML Document Path” field.

After clicking the Sent to Queue button, we now see a “Message successfully sent” message in the tool and the test message is visible in the queue:

This confirms that the queue is functioning correctly and is able to receive messages. Now after starting the eConnect Incoming service, the message will be removed from the queue and pushed into the company database:

Configuring the eConnect Outgoing Service:

Similar to the Incoming service, for the Outgoing service you will need to edit the “eConnect_Outgoing.exe.config” configuration file located at

C:\Program Files\Microsoft Dynamics\eConnect 18.0\Service\Outgoing Service

and point it to the correct location so that the service knows which company database to use when it checks the “eConnect_Out” table, which is what the eConnect Outgoing service periodically reads from to determine what to send to MSMQ. Here is an example of what this would look like:

<?xml version="1.0"?>

<configuration>

<configSections>

                                <section name="DatabaseNames" type="System.Configuration.SingleTagSectionHandler" />

</configSections>

<appSettings>

   <!--   BackOffice.ConnectionString should point to your SQL server where the requester services are installed-->

   <!--   The eConnect.OutGoing_Queue value is no longer used. Please specific the queue names in the eConnect Requester Setup tool. -->

   <!--   "Queue.Type": 0 = Private, 1 = Public -->

   <!--   "Requester.ACTION" 0 = All Documents, 1 = inserts, 2 = updates, 3 = deletes 4 = inserts and updates 5 = inserts and updates combined into 1 doc-->

   <!--   "Requester.OutputType" 0 = list, 1 = master document 2 = complete document-->

   <!--   "Requester.Remove" Remove should always be set to 1, this flag removes the record from eConnect_Out Shadow Table-->

   <!--   "Timer1.Interval" Timer Interval is used to determine the interval in milliseconds for the service to check the eConnect_Out Shadow Table for new records -->

   <!--   "Delay.Interval" Delay Interval is used to determine the age in seconds of the records in the eConnect_Out Shadow Table for processing. -->

   <!--                                                                    ex. delay.interval default setting is 5 seconds, this states that any record in the shadow table older than 5 seconds will be processed -->

   <!--   "DatabaseNames" DatabaseNames section is used to determine the databases that you want the outgoing service to request data from. -->

   <!--                                                                    The service follows the order the databases are listed. ex. the requesting order will be database1,database2,database3,etc. -->

   <!--                                                                    To add databases you need to following the naming convention of database1 = "databasename" database2="databasename" database3="databasename" etc.-->

   <!--    "ByteOrderMark" Used to specify if a byte order mark (BOM) should be added to the xml output(ByteOrderMark=1). Useful with BizTalk 2004 and the BizTalk Server 2004 Adapter for MSMQ v2.0. -->

                <!--                                                                        If you are using BizTalk 2004 MSMQT in some situations the BOM may not be needed(so the configured value should be set to ByteOrderMark=0, KB=840715). -->

   <add key="BackOfficeConnString.ConnectionString" value="packet size=4096;integrated security=SSPI;data source=127.1.0.0;persist security info=False;initial catalog=TWO" />

   <add key="Queue.Type" value="0" />

   <add key="Requester.ACTION" value="0" />

   <add key="Requester.OutputType" value="2" />

   <add key="Requester.Remove" value="1" />

   <add key="Timer1.Interval" value="1000" />

   <add key="Delay.Interval" value="5" />

   <add key="ByteOrderMark" value="0" />

</appSettings>

<DatabaseNames database1="DYNAMICS" database2="TWO" />

</configuration>

I have highlighted the most important changes needed for the file: The data source (SQL server name or IP address), initial catalog (default GP company used), and the System and Company databases in the “DatabaseNames” node. The other settings are explained in the “Outgoing Service” section of the eConnect Installation and Administration Guide.

After updating the configuration file and restarting the eConnect Outgoing Service to apply the settings, we now need to specify which actions in Dynamics GP will trigger entries into the “eConnect_Out” table in the company database.

This is accomplished via the Requester Setup Tool, which is available at C:\Program Files\Microsoft Dynamics\eConnect 18.0\Requester Setup\RequesterSetup.exe

After launching the Requester Setup tool, you will first need to enter the connection information via the “Connection Settings” button. Enter your SQL server instance name in the “SQL Instance” field and the name of the Dynamics GP company database in the “Database Name” field, then click Save. Then back on the main window for the Requester Setup Tool, click the Connect button and a list of the various options will appear as shown below:

For this demonstration, we are telling the Requester to add an entry to the eConnect_Out table when a new account is added to Dynamics GP – hence, selecting the GL_Accounts option on the Insert tab.

If you would like to override the default MSMQ Queue specified in the configuration file for this specific condition, you can do so on the “Message Queues” tab as shown here:

Once the desired conditions and queues are selected, click the Update button to update the settings in the eConnect_Out_Setup table in the company database.

Now when we create a new account in GP

An entry appears in the “eConnect_Out” table

and is then picked up by the eConnect Outgoing service, which sends the message to our queue in MSMQ:

Using Target Journaling To Log Messages

You can store copies of messages received by a MSMQ Queue via Target Journaling, for troubleshooting purposes. See the following article for the steps to enable Target Journaling:

https://technet.microsoft.com/en-us/library/cc732962(v=ws.10).aspx

You can review the XML in the message on the “Body” tab of the message in MSMQ.

See the following article for more information about Target Journaling:

https://technet.microsoft.com/en-us/library/cc772529(v=ws.10).aspx

It is important to note that we do not recommend keeping Journaling enabled for a long period of time, nor do we recommend having too many messages in the journal queue. This can degrade the performance of your MSMQ service.

Also, the MSMQ computer management console will only show you 1,000 messages inside any queue at a particular moment of time. There is no scrolling mechanism so that you can scroll through the messages. However, you can monitor the current number of messages in the MSMQ journal queue by using the following performance counter in the Performance Monitor tool:

Lastly, you can write custom code to read messages out of MSMQ journal queues and save them as text/log files. Please refer to the following whitepaper for more details:

https://msdn.microsoft.com/en-us/library/ms973860.aspx

Monitoring with the eConnect MSMQ Control tool

The eConnect installation also provides a utility that you can use to monitor queues and messages. The eConnect MSMQ Control tool allows you to open a queue, see the list of messages in the queue, and view the contents of individual messages.

Use the utility during development to ensure messages are getting delivered and that they contain the expected XML data. You can view, edit, and resend messages and use the tool for debugging purposes. For additional information about using the eConnect MSMQ Control utility, refer to the Utilities chapter in the eConnect Installation and Administration Guide.