Leveraging the changes in eConnect for Microsoft Dynamics GP 2010

Article
09/22/2011

In this post I will talk about the changes made to the API for eConnect for Microsoft Dynamics GP 2010 and how developers can take advantage of these changes to affect their custom application. If you have been using eConnect 2010 you have already realized that there is a new Windows service running called the eConnect for Microsoft Dynamics GP 2010 Integration Service. This is a change from the version 9 and 10 days where there was a COM+ application for eConnect that appeared under Component Services. Like the eConnect COM+ application, the eConnect 2010 service runs under a Windows user that requires DYNGRP role access in the DYNAMICS and company databases. I will breakdown some of the other changes in the following sections.

eConnectMethods Class

There are several new methods added to this class and they are discussed in the eConnect Programmers guide in MSDN here. These methods provide the functionality for reading and writing to the Dynamics GP databases. One of the more interesting changes is that the CreateTransactionEntity method returns a string value. This string is the XML that is passed to the eConnect API and it includes the generated Document Number of the transaction. So if you are integrating Sales Transactions and do not pass the SOPNUMBE value in the XML, the eConnect API retrieves the next number internally and you will then be able to see the SOPNUMBE in the string value returned by the CreateTransactionEntity method.

The CreateEntity, CreateTransactionEntity, DeleteEntity, DeleteTransactionEntity, UpdateEntity, and UpdateTransactionEntity may have different names but they all go down the same road. In other words, right now they have been named this way for readability but have no real big differences. For instance, it is possible to create a GL Transaction by passing a GL Transaction Type XML document to the DeleteEntity method. The only difference between these methods is that the CreateTransactionEntity returns a string and the others return a bool! An advantage to having different naming conventions would be for readability of your code. If you have an application that does multiple operations like creating new transactions, updating existing customers, and deleting addresses, you could pass the specific XML documents to the desired methods so the code would be easier to understand from a developer perspective. For example, you would pass your XML document that updates a customer record to the UpdateEntity method and you would pass a new Sales Invoice transaction XML document to the CreateTransactionEntity method.

RequireProxyService

You can bypass using the new eConnect Windows service so your application calls the eConnect stored procedures under the context of the user running the application. Thus the eConnect service does not even need to be running and the user(s) running the application will need to have access in SQL server. You can give them DYNGRP role access or something more granular like spefic access to eConnect stored procedures and tables. You can take advantage of this option in a couple ways where you will set the RequireProxyService configuration property to false. The default value for this setting is true so by default the eConnect service needs to be running. If it is not, you will receive a "There was no endpoint listening at net.pipe://localhost/Microsoft/Dynamics/GP/eConnect/EntityOperations that could accept the message" error when the eConnect API attempts to intialize the service proxy.

There are two ways to use this configuration setting:

1. Add a key for this setting in your application config file like below:

<?xml version="1.0"?>
<configuration>
<appSettings>
<add key="RequireProxyService" value="false"/>
</appSettings>
</configuration>

2. In your application code, set the RequireProxyService property of the eConnectMethods class to false:

// Add reference to Microsoft.Dynamics.GP.eConnect.dll in Visual Studio Project

// Add using statement to Microsoft.Dynamics.GP.eConnect namespace
using Microsoft.Dynamics.GP.eConnect;

// Instantiate eConnectMethods class to use RequireProxyService
eConnectMethods eConnect = new eConnectMethods();
eConnect.RequireProxyService = false;

An interesting related tidbit is that the Web Services for Microsoft Dynamics GP 2010 takes advantage of this setting. If you have the Microsoft Dynamics GP Web Services installed, take a peek at the WSServiceAppSettings.config file under the C:\Program Files\Microsoft Dynamics\GPWebServices\ServiceConfigs folder. You will see a line at the bottom of the file that sets the RequireProxyService to false. You can even go ahead and stop the eConnect Integration Service and attempt a call to a method in the Microsoft Dynamics GP 2010 Web Services and it will be successful. Go ahead I know you want to try! The web services call will be successful because the eConnect service proxy is bypassed and the call to the eConnect SQL objects is made under the context of the user running the Microsoft Dynamics GP Service Host service that is used by the Microsoft Dynamics GP 2010 Web Services.

ReuseBaseTransaction

When using multiple transaction types in a single XML document, a change to the API for eConnect 2010 was made in regards to the way transactions are processed. If you use the eConnectProcessInfo node for each transaction type in the XML document, then each transaction type will run as a seperate transaction. This is fairly signficant because the entire XML document is not treated as one transaction. So transaction types that are successful will not rollback if an error is hit with a transaction type that runs later in the XML. Take for example the following XML:

<eConnect>
<SOPTransactionType>
<eConnectProcessInfo>
<ConnectionString>Server=SQLSVR;Database=TWO;integrated security=SSPI;persist security info=False;Trusted_Connection=Yes</ConnectionString>
</eConnectProcessInfo>
<taSopLineIvcInsert_Items>
<taSopLineIvcInsert>
<SOPTYPE>2</SOPTYPE>
<SOPNUMBE>ORDNJ00069168</SOPNUMBE>
<CUSTNMBR>AARONFIT0001</CUSTNMBR>
<DOCDATE>3/16/2011 12:00:00 AM</DOCDATE>
<LOCNCODE>WAREHOUSE</LOCNCODE>
<ITEMNMBR>256 SDRAM</ITEMNMBR>
<AutoAssignBin>0</AutoAssignBin>
<UNITPRCE>15.00</UNITPRCE>
<QUANTITY>48.00</QUANTITY>
<DOCID>STDORD</DOCID>
<UOFM>EACH</UOFM>
<DEFEXTPRICE>1</DEFEXTPRICE>
</taSopLineIvcInsert>
</taSopLineIvcInsert_Items>
<taSopHdrIvcInsert>
<SOPTYPE>2</SOPTYPE>
<DOCID>STDORD</DOCID>
<SOPNUMBE>ORDNJ00069168</SOPNUMBE>
<LOCNCODE>WAREHOUSE</LOCNCODE>
<DOCDATE>3/16/2011 12:00:00 AM</DOCDATE>
<CUSTNMBR>AARONFIT0001</CUSTNMBR>
<CREATECOMM>1</CREATECOMM>
<CREATETAXES>1</CREATETAXES>
<DEFTAXSCHDS>1</DEFTAXSCHDS>
<DEFPRICING>1</DEFPRICING>
<BACHNUMB>CPR 66</BACHNUMB>
</taSopHdrIvcInsert>
</SOPTransactionType>
<POPTransactionType>
<eConnectProcessInfo>
<ConnectionString>Server=SQLSVR;Database=TWO;integrated security=SSPI;persist security info=False;Trusted_Connection=Yes</ConnectionString>
</eConnectProcessInfo>
<taPoLine_Items>
<taPoLine>
<PONUMBER>A-0001</PONUMBER>
<DOCDATE>2011-05-02</DOCDATE>
<VENDORID>ACETRAVE0001</VENDORID>
<LOCNCODE>WAREHOUSE</LOCNCODE>
<VNDITNUM>256 SDRAM</VNDITNUM>
<ITEMNMBR>256 SDRAM</ITEMNMBR>
<QUANTITY>1</QUANTITY>
<REQDATE>2011-05-09</REQDATE>
<RELEASEBYDATE>2011-05-02</RELEASEBYDATE>
<PRMDATE>2011-05-09</PRMDATE>
<PRMSHPDTE>2011-05-02</PRMSHPDTE>
<UNITCOST>3164</UNITCOST>
<UOFM>Each</UOFM>
<ORD>16384</ORD>
</taPoLine>
</taPoLine_Items>
<taPoHdr>
<PONUMBER>A-0001</PONUMBER>
<VENDORID>ACETRAVE0001</VENDORID>
<VENDNAME>IRIDIUM SATELLITE LLC</VENDNAME>
<DOCDATE>2011-05-02</DOCDATE>
<PRMDATE>2011-05-09</PRMDATE>
<PRMSHPDTE>2011-05-02</PRMSHPDTE>
<REQDATE>2011-05-09</REQDATE>
</taPoHdr>
</POPTransactionType>
</eConnect>

If the SOP transaction is successful but the POP transaction fails for some reason, the SOP transaction will not rollback. This is a change when compared to how this worked in previous versions of eConnect. However, there is a configuration setting called ReuseBaseTransaction that can be used to make sure that each transaction type will use the same SQL connection so everything would rollback in the XML document. You can set ReuseBaseTransaction to true by adding it to your application config file or the Microsoft.Dynamics.GP.eConnect.Service.exe.config file depending on if you are using the service proxy (RequireProxyService).

<?xml version="1.0"?>
<configuration>
<appSettings>
<add key="ReuseBaseTransaction" value="true"/>
</appSettings>
</configuration>

Keep in mind this behavior change only happens when using multiple transaction types in your XML document AND using a eConnectProcessInfo node in the transaction type. If you do not use eConnectProcessInfo, then the same transaction is used by default for the entire XML document.

Using the eConnect WCF Service

You may choose to use the eConnect Integration Service by making a service reference in your Visual Studio project. The programming reference and techniques for doing so are discussed in MSDN here. The eConnect Integration Service is a new WCF service available in the 2010 version of eConnect. So if you are developer with experience around WCF programming techniques or want to do more with WCF, this is one strategy to use with an upcoming eConnect project. When using the eConnect Integration Service as a Service Reference, you do not need to make a reference to the Microsoft.Dynamics.GP.eConnect assembly since all the classes are available with your service reference. You would still need to make a reference to the Microsoft.Dynamics.GP.eConnect.Serialization assembly to help in constructing eConnect XML documents if necessary.

One advantage I have seen in a few cases so far is the ability to call into eConnect with a specified Windows account. This may come into play when you have a web application that supports Anonymous or Forms based authentication and the web application needs to call the eConnect API to interact with Dynamics GP. If you are using the Service Reference, you have access to a DynamicsGPClient object which gives you access to a ClientCredential property. In the below code example, I use the System.Net namespace to use a NetworkCredential object that I can pass to the ClientCredential.

// 1. Make a Service Reference to net.pipe://<computername>/Microsoft/Dynamics/GP/eConnect/mex in Visual Studio project.
// 2. Add a using statement to the System.Net namespace.
// 3. Add a using statement to the Service Reference (Ex: using eConnectWebApplications.eConnectService;)

protected void Button3_Click(object sender, EventArgs e)
        {
            // Initialize a new instance of the eConnectClient
            eConnectClient eConnectObject2 = new eConnectClient();

eConnectObject2.ClientCredentials.Windows.ClientCredential = new NetworkCredential("eConuser", "()Redrabbit", "croehric1");

            eConnectObject2.CreateTransactionEntity("blah blah","blah blah");

        }

Using the above pattern I can pass a specific Windows user credential to the eConnect API that will have access to the eConnect Integration Service because it is a valid Windows user. Depending on the web site security and configuration, if I do not do this then I may receive a message that says something like:

The pipe name could not be obtained for the pipe URI: Access is denied. (5, 0x5)

Tracing Steps

On version 9 and 10 of eConnect it was possible to do tracing of the eConnect API but you could only do it by modifying the .Net Framework machine.config file and then give the COM+ user account for eConnect Full Control to the root of the C drive. That was not always ideal. Things have changed for the better when it comes to tracing in eConnect 2010!

In addition to tracing the eConnect API which gives you insight into the XML string passed and connection string info, you can also initialize tracing the WCF layer. So any type of exception in the WCF layer can be traced. You can add tracing information to either your application config file if you are setting RequireProxyService="false" or you can add tracing information to the Microsoft.Dynamics.GP.eConnect.Service.exe.config file if RequireProxyService="true". Remember the latter setting is the default and right now the most common usage we see. I always use the below tracing information so to make things easy I will just copy my entire Microsoft.Dynamics.GP.eConnect.Service.exe.config file which you can copy into your Microsoft.Dynamics.GP.eConnect.Service.exe.config file or simply replace it:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<system.diagnostics>
<sources>
<source name="eConnectTraceSource" switchValue="Verbose">
<listeners>
<add name="eConnectTextTracelistener">
<filter type="" />
</add>
</listeners>
</source>
<source name="eConnectServiceTraceSource" switchValue="Verbose">
<listeners>
<add name="eConnectSvcTextTracelistener">
<filter type="" />
</add>
</listeners>
</source>
<source name="System.ServiceModel" switchValue="Verbose" propagateActivity="true">

<listeners>
<add name="wcfListener"/>
</listeners>
</source>
<source name="System.IO.Log" switchValue="Verbose" propagateActivity="true">
<listeners>
<add name="wcfListener"/>
</listeners>
</source>
<source name="System.Runtime.Serialization" switchValue="Verbose" propagateActivity="true">
<listeners>
<add name="wcfListener"/>
</listeners>
</source>
<source name="System.IdentityModel" switchValue="Verbose" propagateActivity="true">
<listeners>
<add name="wcfListener"/>
</listeners>
</source>
</sources>
<sharedListeners>
<add initializeData="C:\Program Files\Microsoft Dynamics\eConnect 11.0\eConnectSvc.log" type="System.Diagnostics.TextWriterTraceListener, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
name="eConnectSvcTextTracelistener">
<filter type="" />
</add>
<add initializeData="C:\Program Files\Microsoft Dynamics\eConnect 11.0\eConnectSvcLog.xml" type="System.Diagnostics.XmlWriterTraceListener, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
name="eConnectSvcXmlTracelistener">
<filter type="" />
</add>
<add initializeData="C:\Program Files\Microsoft Dynamics\eConnect 11.0\eConnect.log" type="System.Diagnostics.TextWriterTraceListener, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
name="eConnectTextTracelistener">
<filter type="" />
</add>
<add initializeData="C:\Program Files\Microsoft Dynamics\eConnect 11.0\eConnectLog.xml" type="System.Diagnostics.XmlWriterTraceListener, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
name="eConnectXmlTracelistener">
<filter type="" />
</add>
<add name="wcfListener" type="System.Diagnostics.XmlWriterTraceListener" initializeData="C:\Program Files\Microsoft Dynamics\eConnect 11.0\WCFTracing.svclog"/>
</sharedListeners>
<trace autoflush="true" />
</system.diagnostics>
<system.web>
<compilation debug="true" />
</system.web>
<system.serviceModel>
<diagnostics wmiProviderEnabled="true">
<messageLogging logMalformedMessages="true" logMessagesAtServiceLevel="true"
logMessagesAtTransportLevel="true" />
</diagnostics>
<bindings>
<netNamedPipeBinding>

<binding name="eConnectNamedPipeConfig" closeTimeout="00:10:00"
sendTimeout="00:10:00" receiveTimeout ="infinite" transferMode="Buffered" hostNameComparisonMode="StrongWildcard"
maxBufferPoolSize="2147483647" maxBufferSize="2147483647" maxReceivedMessageSize="2147483647">
<readerQuotas maxDepth="60" maxStringContentLength="2147483647"
maxArrayLength="2147483647" maxBytesPerRead="2147483647" maxNameTableCharCount="2147483647" />
<security mode="Transport">
<transport protectionLevel="EncryptAndSign" />
</security>
</binding>
</netNamedPipeBinding>
</bindings>
<services>
<service behaviorConfiguration="eConnectServiceBehavior" name="Microsoft.Dynamics.GP.eConnect.Service">
<endpoint address="EntityOperations" binding="netNamedPipeBinding" bindingConfiguration="eConnectNamedPipeConfig"
name="eConnectServiceEndpoint" contract="Microsoft.Dynamics.GP.eConnect.IEconnect">
<identity>
<dns value="localhost" />
</identity>
</endpoint>
<endpoint address="GetDocumentNumbers" binding="netNamedPipeBinding" bindingConfiguration="eConnectNamedPipeConfig"
name="eConnectDocNumberEndPoint" contract="Microsoft.Dynamics.GP.eConnect.ITransactionRecordIds">
<identity>
<dns value="localhost" />
</identity>
</endpoint>
<endpoint address="RollBackDocuments" binding="netNamedPipeBinding" bindingConfiguration="eConnectNamedPipeConfig"
name="eConnectRollBackDocuments" contract="Microsoft.Dynamics.GP.eConnect.IDocumentNumberRollback">
<identity>
<dns value="localhost" />
</identity>
</endpoint>
<endpoint address="mex" binding="mexNamedPipeBinding" name="http" contract="IMetadataExchange" />
<host>
<baseAddresses>

<add baseAddress="net.pipe://localhost/Microsoft/Dynamics/GP/eConnect/" />
</baseAddresses>
</host>
</service>
</services>
<behaviors>
<serviceBehaviors>
<behavior name="eConnectServiceBehavior">

<serviceDebug includeExceptionDetailInFaults="true" />

<serviceMetadata httpGetEnabled="true" httpGetUrl="https://localhost/Microsoft/Dynamics/GP/eConnect/mex"/>
</behavior>
</serviceBehaviors>
</behaviors>
</system.serviceModel>
</configuration>

The tracing output will create files in the C:\Program Files\Microsoft Dynamics\eConnect 11.0 folder. The Windows user running the eConnect Integration Service will need Full Control to this location to make sure all the files are written to it. The settings I used above are set to "Verbose" so the files can grow to a large size quickly if this is left on and you have a heavy integration. I would advise to use tracing only in troubleshooting issues with eConnect. An example would be when you use the Web Services for Microsoft Dynamics GP 2010 since tracing will give you access to the generated eConnect XML document serialized by the Web Services.

When using the above tracing information that I provided, the eConnect.log file can be viewed to see the generated eConnect XML passed to the API along with the connection string. The files that end with .svclog are WCF trace files and can be viewed with Notepad but they are difficult to read. If you have the Windows SDK installed from Visual Studio, you may have the Service Trace Viewer application (C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Bin\NETFX 4.0 Tools\SvcTraceViewer.exe) which is great for loading up .svclog files and finding information about exceptions easier.

I know there has been a number of changes with the eConnect 2010 release and unfortunately I can't cover all of them here but hopefully this will be helpful for you.

Chris

Leveraging the changes in eConnect for Microsoft Dynamics GP 2010

Additional resources