Microsoft Dynamics GP. econnect Installation and Administration Guide Release 9.0

(1)

Microsoft Dynamics

™

GP

eConnect Installation and Administration Guide

Release 9.0

(2)

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical,

photocopying, recording, or otherwise), or for any purpose, without the express written

permission of Microsoft Corporation. Notwithstanding the foregoing, the licensee of the software with which this document was provided may make a reasonable number of copies of this document solely for internal use.

Trademarks Microsoft, Microsoft Dynamics, Visual Basic, Visual Studio, BizTalk Server, Windows, and Windows Server are either registered trademarks or trademarks of Microsoft Corporation or its affiliates in the United States and/or other countries.

The names of actual companies and products mentioned herein may be trademarks or registered marks - in the United States and/or other countries - of their respective owners.

Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred.

Intellectual property Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Warranty disclaimer Microsoft Corporation disclaims any warranty regarding the sample code contained in this documentation, including the warranties of merchantability and fitness for a particular purpose.

Limitation of liability The content of this document is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Microsoft Corporation. Microsoft Corporation assumes no responsibility or liability for any errors or inaccuracies that may appear in this manual. Neither Microsoft Corporation nor anyone else who has been involved in the creation, production or delivery of this documentation shall be liable for any indirect, incidental, special, exemplary or consequential damages, including but not limited to any loss of anticipated profit or benefits, resulting from the use of this documentation or sample code.

License agreement Use of this product is covered by a license agreement provided with the software product. If you have any questions, please call the Microsoft Dynamics GP Customer Assistance Department at 800-456-0025 (in the U.S. or Canada) or +1-701-281-6500.

(3)

E C O N N E C T I N S T A L L A T I O N A N D A D M I N I S T R A T I O N G U I D E i

Introduction

...2

What’s in this manual...2

Symbols and conventions ...2

Product support ...3

Part 1: eConnect Basics

...6

Chapter 1: eConnect Overview

...

7

What is eConnect?...7

What eConnect can do ...7

Getting started...8

Chapter 2: eConnect Architecture

...

11

Architecture diagram ... 11

Configurations...12

Business objects ...13

eConnect API ...14

BizTalk ...15

Transaction Requester ...15

Replication Service...16

Part 2: Installation

...

20 Chapter 3: Prerequisites

...

21

Operating system ...21

Microsoft .NET 1.1 Framework...21

COM+ user account...21

Distributed Transaction Coordinator (DTC)...22

Functional currency ...24

Microsoft Message Queueing (MSMQ) ...25

Chapter 4: eConnect Installation

...

27

Installation types...27

Installation procedure ...27

Chapter 5: BizTalk Adapter Installation

...

33

Overview...33

Installing the eConnect Adapter for BizTalk 2004...33

Installing the eConnect Adapter for BizTalk 2006...34

Part 3: Administration...

38 Chapter 6: Configuring eConnect Services

...

39

Overview...39

Incoming Service...39

(4)

C O N T E N T S

Replication Service...45

Transaction Requester ...48

BizTalk adapter...51

Chapter 7: Maintenance

...

57

Installing additional companies ...57

Modifying an eConnect installation...59

Completing a repair...60

Removing eConnect...61

Chapter 8: Utilities

...

63

eConnect Requester Setup ...63

eConnect MSMQ Control ...63

eConnect Release Information ...65

Chapter 9: Troubleshooting

...

67

Functional currency ...67

Connection string problems ...67

Login problems ...68

Incoming or Outgoing Services ...68

BizTalk server ...68

eConnect event log...69

Incoming Service problems ...69

COM+ object...70

Glossary...

71

(5)

(6)

Introduction

Welcome to eConnect for Microsoft Dynamics™ GP. This documentation explains how to install and administer eConnect. An eConnect installation includes files, tools, and services that allow applications to integrate with Microsoft Dynamics GP. Before you begin installing and using eConnect, take a few moments to review the information presented here.

What’s in this manual

The Microsoft Dynamics GP eConnect Installation and Administration Guide is designed to give you an in-depth understanding of how to install and administer eConnect. Information is divided into the following parts:

• Part 1, eConnect Basics, provides an overview of eConnect and the components it supplies to help other applications integrate with Microsoft Dynamics GP. • Part 2, Installation, describes how to install eConnect or the eConnect runtime. • Part 3, Administration, explains how to configure and maintain eConnect. To learn about creating applications that use eConnect for Microsoft Dynamics GP, refer to the eConnect Programmer’s Guide and Reference document.

Symbols and conventions

To help you use this documentation more effectively, we’ve included the following symbols and conventions within the text to make specific types of information stand out.

Symbol Description

The light bulb symbol indicates helpful tips, shortcuts, and suggestions.

Warnings indicate situations you should be aware of when completing tasks.

Margin notes summarize important information.

Margin notes call attention to critical information and direct you to other areas of the documentation where a topic is explained.

Convention Description

Part 1, eConnect Basics Bold type indicates a part name.

Chapter 1, “Overview” Quotation marks indicate a chapter name.

(7)

E C O N N E C T I N S T A L L A T I O N A N D A D M I N I S T R A T I O N G U I D E 3

I N T R O D U C T I O N

Product support

Microsoft Dynamics GP technical support can be accessed online or by telephone. Go to www.microsoft.com/Dynamics and click the CustomerSource or PartnerSource link, or call 888-477-7877 (in the US and Canada) or 701-281-0555.

(8)

(9)

(10)

Part 1: eConnect Basics

This portion of the documentation contains introductory information you should know before deploying eConnect for Microsoft Dynamics GP. The following information is discussed:

• Chapter 1, “eConnect Overview,” introduces eConnect and the types of integration interfaces and tools it provides.

• Chapter 2, “eConnect Architecture,” discusses the underlying components that are part of an eConnect installation.

(11)

Chapter 1:

eConnect Overview

Microsoft Dynamics GP eConnect allows you to integrate your business applications with Microsoft Dynamics GP. The following topics introduce Microsoft Dynamics GP eConnect:

• What is eConnect?

• What eConnect can do

• Getting started

What is eConnect?

eConnect is a collection of tools, components, and interfaces that allow applications to programmatically exchange data with Microsoft Dynamics GP. The key eConnect components and interfaces include:

• A .NET managed code assembly

• A Microsoft BizTalk® Application Integration Component (AIC) • Microsoft Message Queuing (MSMQ) services

These eConnect interfaces allow external applications like web storefronts, web services, point-of-sale systems, or legacy applications to integrate with Microsoft Dynamics GP. The external applications can perform actions like creating, updating, retrieving, and deleting back office documents and transactions.

Throughout the documentation, the terms front office and back office are used. The term back office refers to the financial management system, in this case, Microsoft Dynamics GP. The term front office refers to customer relationship management systems, data warehouses, web sites, or other applications that communicate with the back office.

eConnect allows you to leverage the existing transaction-based business logic of Microsoft Dynamics GP. This allows you to focus your time and energy on creating or enhancing custom applications for the front office.

What eConnect can do

eConnect allows you to enhance your applications in the following ways:

1. Add real-time access to Dynamics GP data.

eConnect provides real-time access to back office data. It offers a way to add up-to-date back office information to existing front office applications like web storefronts or service applications.

2. Share financial management data across applications.

eConnect allows multiple applications to share financial management data. The eConnect interfaces can support multiple independent applications. Changes to financial data in Dynamics GP are simultaneously available to all applications that use eConnect to access that data in Dynamics GP.

Application developers who use eConnect obtain the following benefits:

1. Reduce development time.

eConnect has a large number of integration points for Microsoft Dynamics GP. Software developers can quickly add back office integrations to an application. This simplifies the development effort, while providing fast access to Microsoft

(12)

P A R T 1 E C O N N E C T B A S I C S

Dynamics GP data. eConnect also reduces development time when the business logic contained in the back office is reused by new custom applications.

An eConnect integration also reduces data re-entry. An automated eConnect integration between Microsoft Dynamics GP and a new or existing online storefront, web service, or other data source eliminates the time and cost of manually copying data.

2. Use existing development tools.

eConnect allows software developers to select their tool of choice when working with eConnect. Developers can use Microsoft .NET, Microsoft SQL Server stored procedures, BizTalk, COM, or MSMQ.

3. Leverage industry-standard technologies.

eConnect includes components for MSMQ and BizTalk Server, which are industry-standard tools that support integration between applications.

4. Use XML to transfer data.

eConnect uses XML documents to move data into and out of Microsoft Dynamics GP. The XML documents are a text-based representation of back office data. An XML schema specifies the data that is included in each type of XML document. This allows eConnect to provide back office integration to any application capable of creating or consuming these XML documents.

Getting started

How you start depends on your role:

System administrator

If you are the system administrator, complete the following:

• Review Chapter 2, “eConnect Architecture,” to understand the components that comprise an eConnect installation. This information can help you to understand how eConnect will fit with your existing systems.

• Review Chapter 3, “Prerequisites,” to determine whether your system has all the prerequisites for eConnect. You may need to install some additional software or configure Dynamics GP before installing eConnect.

• Review Chapter 4, “eConnect Installation,” to acquaint yourself with the eConnect installation procedure.

• If you are planning to use eConnect’s BizTalk adapter, review Chapter 5, “BizTalk Adapter Installation,” to acquaint yourself the procedure for installing the adapter.

• Review Chapter 6, “Configuring eConnect Services,” to understand the configuration files used to control eConnect’s Windows services and BizTalk adapter. You control the behavior of the services and adapter by changing the

(13)

C H A P T E R 1 E C O N N E C T O V E R V I E W

Software Developer

If you are a developer, complete the following:

• Review Chapter 2, “eConnect Architecture,” to familiarize yourself with eConnect’s components. You need to understand how eConnect’s components work together to meet your integration requirements.

• Discuss the installation procedure with the system administrator to learn what configuration settings were used during the eConnect installation.

• Review the eConnect Programmer’s Guide and Reference document. The document describes eConnect’s tools, application programming interfaces (APIs), and XML schemas. Use the eConnect Programmer’s Guide and Reference to learn how eConnect meets your application integration requirements.

(14)

(15)

Chapter 2:

eConnect Architecture

When using Microsoft Dynamics GP eConnect, it is helpful to understand its architecture. Architectural information is divided into the following sections: • Architecture diagram

• Configurations

• Business objects

• eConnect API

• BizTalk

• Transaction Requester

• Replication Service

Architecture diagram

eConnect installs a collection of components that work together to provide programmatic access to Microsoft Dynamics GP data. The following diagram illustrates the basic components:

COM .NET

Microsoft

MSMQ

Incoming Outgoing

Replication Transaction Requester XML XML XML Service Service Service BizTalk BizTalk Server Adapter Dynamics GP XML XML Integrating Applications API Layer Data Access Layer Business Objects

Pre SQL stored procedures Post .NET

(16)

The diagram illustrates eConnect’s two key layers and the components that make up those layers. The data access layer contains the eConnect business objects. The business objects are installed on the Microsoft Dynamics GP server. The application programming interfaces (API) layer contains the components that simplify using the eConnect business objects. The API layer installs on the same computer as the integrating application. The diagram also shows that your integrating application can bypass the API and use the eConnect business objects directly.

The Transaction Requester allows you to publish Microsoft Dynamics GP documents to a queue. You typically use the Transaction Requester with the API layer’s Outgoing Service to publish specified Microsoft Dynamics GP documents as eConnect XML documents. The Transaction Requester identifies the specific transactions the Outgoing Service needs to publish.

The Replication Service allows you to replicate transactions that occur in Microsoft Dynamics GP to another database.

Configurations

There are two common configurations for an eConnect installation. In the basic configuration eConnect and Microsoft Dynamics GP are installed on the same server. This is shown in the following illustration:

The following illustration shows the second common configuration for eConnect. In this configuration, eConnect is installed on a separate server, and accesses the SQL Server that manages Microsoft Dynamics GP data over the local network. To obtain optimal performance, you should use the two server configuration whenever possible.

SQL Server with Dynamics GP Data

+

eConnect Business Objects eConnect API

eConnect COM+ Object

eConnect Transaction Requester eConnect Replication Service Integrating Application

(17)

C H A P T E R 2 E C O N N E C T A R C H I T E C T U R E

Which configuration you choose will depend on what types of integration you need, and what server resources you have available. eConnect can also be part of a BizTalk integration. Refer to BizTalk documentation for information about the types of configurations possible with BizTalk Server.

Business objects

The most basic eConnect components are known as business objects. The eConnect business objects are a collection of SQL stored procedures. The eConnect install adds these stored procedures to the system database (DYNAMICS) and each specified company database.

The stored procedures contain the business logic used by eConnect. In addition, the stored procedures validate the data and supply default values. Any eConnect action that queries, creates, updates, or deletes data from Dynamics GP is completed using one or more of these stored procedures.

The eConnect business objects include Dynamics GP documents and transactions that are commonly used in application integration. While eConnect supplies a large number of documents, not every Dynamics GP feature is available through eConnect.

You cannot modify eConnect stored procedures. However, eConnect provides an alternative that allows you to customize its business logic. Each stored procedure includes specially named pre and post stored procedures. You customize eConnect’s business logic by adding SQL queries and commands to these pre and post procedures. The pre stored procedure runs your custom code immediately before the eConnect stored procedure, while the post stored procedure runs immediately after the eConnect stored procedure.

The following diagram illustrates the relationship between an eConnect stored procedure and its pre and post stored procedures:

For example, assume you want to modify the business logic for the eConnect stored procedure named taSopHdrIvcInsert. You complete this modification by adding custom SQL code to the stored procedure named taSopHdrIvcInsertPost. Your custom code will run immediately after every execution of the taSopHdrIvcInsert procedure. To run custom code prior to the execution of the taSopHdrIvcInsert procedure, place the custom SQL code in the stored procedure named taSopHdrIvcInsertPre. stored procedure called executes pre stored procedure executes post stored procedure

The eConnect stored procedure cannot be modified. Start “Pre” stored procedure eConnect stored procedure “Post” stored procedure

(18)

Once eConnect installs its business objects, the stored procedures are available on the server and can be utilized by your application. However, a direct call to an eConnect stored procedure requires you to:

• Create a connection to the database server.

• Implement security restrictions to prevent unauthorized use of your database connection.

• Implement transaction management to commit or rollback changes. • Identify and handle error conditions.

• Update your application whenever changes are made to the parameters for the stored procedure.

To avoid the extra work of direct calls to the stored procedures, use one of the APIs that eConnect supplies. These API provide a simpler approach to using the eConnect business objects.

eConnect API

eConnect provides a collection of APIs that interact with the business objects. There are APIs for Microsoft .NET, COM, and Microsoft Message Queuing (MSMQ). The variety of eConnect APIs allows you to use the interface that best fits your integration project and the available development tools.

To support its API, eConnect supplies a COM+ component that manages interaction with the eConnect business objects. The COM+ object installs in Component Services on your eConnect client computer. The COM+ object requires a user logon. The logon must have sufficient privileges (i.e. be assigned to DYNGRP) to access the Dynamics GP databases on your SQL server.

Schema information can be found in the eConnect

Programmer’s Guide and Reference

To use the eConnect API, your application must create or read eConnect XML documents. eConnect supplies XML schema to specify the contents of each document.

A schema is an XML file (with typical extension .xsd) that describes the syntax and semantics of XML documents using a standard XML syntax. An XML schema specifies the content constraints and the vocabulary that compliant documents must accommodate.

The eConnect business objects validate documents against the schema and reject documents that do not comply.

The COM+ component supports the following APIs:

Microsoft .NET

eConnect installs .NET assemblies on your computer and adds them to the global assembly cache. The assemblies use the COM+ object to access the eConnect business objects. To use eConnect in a .NET development project, add references to these assemblies.

(19)

The COM library is a deprecated feature. All new development should use the .NET assemblies.

MSMQ

The MSMQ API uses MSMQ queues and Windows services to asynchronously transport data between your application and Microsoft Dynamics GP. Your application must be able to access the queues used by the services. Both the Incoming and Outgoing services use the COM+ object to access the eConnect business objects.

To use the eConnect Incoming Service, create an XML document and place it in the specified queue. The Incoming Service monitors that queue and periodically processes the valid XML documents stored in the queue.

The eConnect Outgoing Service relies on SQL triggers and the business objects to retrieve specified eConnect documents. The service stores the documents in a specified queue. Your application must monitor the queue, retrieve the supplied documents, and perform its actions based on the data in the documents.

BizTalk

eConnect provides aBizTalk adapter is an application integration component (AIC) that you can install on your BizTalk 2004 server. The BizTalk adapter allows you to use BizTalk to manage interaction with eConnect business objects.

The BizTalk adapter supports the use of eConnect as a part of a BizTalk orchestration or in a simple pass-through situation.

Transaction Requester

The Transaction Requester is a collection of SQL database tables and database triggers that eConnect uses to make Dynamics GP data changes available to other applications. The following diagram illustrates the Transaction Requester:

Microsoft Dynamics GP database

MSMQ

Outgoing Service

An application creates a new record.

The Outgoing Service queries the eConnect_Out table. XML representing the new record is sent to the eConnect outgoing queue in MSMQ.

eConnect_Out table

The Transaction Requester’s SQL trigger reacts to the record’s creation, and inserts an entry to the eConnect_Out table.

(20)

The Transaction Requester supports other eConnect services that export data from Dynamics GP to other applications.

When eConnect installs the Transaction Requester, it creates three tables in each specified Dynamics GP database:

• eConnect_Out This table stores data from selected create, update, or delete operations that occur within Microsoft Dynamics GP. The data identifies the individual transactions that occurred. Other eConnect services use the data in the table to create messages that can be used to integrate Dynamics GP data with other applications.

• eConnect_Out_Setup This table contains configuration information for the Transaction Requester. To keep the Transaction Requester working, do not make changes to this table.

• eConnectOutTemp This table is a temporary data store.

To configure the eConnect Transaction Requester, use the eConnect Requester Setup utility. The eConnect Requester Setup utility allows you to specify Dynamics GP objects and operations you want to export to another application. The utility then adds SQL triggers to Dynamics GP that populate the eConnect_Out table for the specified objects and operations. For a detailed explanation of how to configure the Transaction Requester, see Transaction Requester on page 48.

For example, assume you want an external application to be updated when a new customer is added to Microsoft Dynamics GP. To begin, use the eConnect Requester Setup utility to specify the customer object and the SQL insert operation. The eConnect Requester Setup adds a SQL trigger to the database. When a new customer record is inserted, the SQL trigger creates a record of the event in the eConnect_Out table.

The eConnect Outgoing Service periodically queries the eConnect_Out table. The service uses the record in the table to create an XML document that describes the new customer transaction.

The Outgoing Service then places the XML document in a message queue where it can be retrieved and used to notify the external application.

Replication Service

eConnect includes the Replication Service that copies selected data changes from Microsoft Dynamics GP to a specified target database. The Replication Service asynchronously updates the target database to reflect changes made in Dynamics GP.

To use the Replication Service, the target database must have the same table structure as the Microsoft Dynamics GP database.

(21)

The following diagram illustrates the Replication Service:

The Replication Service uses many of eConnect’s other components and interfaces: • The Transaction Requester specifies the documents and transactions to

replicate.

• The eConnect Outgoing Service creates the XML documents from the information provided by the Transaction Requester Service. It places them in the Outgoing queue in MSMQ.

• The eConnect Replication Service takes the documents from the Outgoing Queue and uses the data to replicate the transaction directly into the external application’s database.

Since the Replication Service performs a specific task, it does not provide an API. You cannot programmatically customize the Replication Service. Before starting the

External application

XML

Microsoft Dynamics GP database MSMQ Outgoing Service Replication Service

The Replication Services retrieves the XML document from the eConnect outgoing queue and inserts the new data into the specified external application database.

eConnect_Out table

database

An application creates a new record in Microsoft Dynamics GP.

The Outgoing Service queries the eConnect_Out table, retrieves the data, creates an XML document, and places the document in the eConnect outgoing queue.

The data from the record created in Microsoft Dynamics GP is visible in the external application. The Transaction Requester’s SQL

trigger reacts to the record’s creation, and inserts an entry to the eConnect_Out table.

eConnect Outgoing queue

(22)

Replication Service, you must configure the service. For a detailed explanation of how to configure the Replication Service, see Replication Service on page 45.

(23)

(24)

Part 2: Installation

This portion of the documentation explains how to install Microsoft Dynamics GP eConnect. The following information is discussed:

• Chapter 3, “Prerequisites,” describes the software required and the actions you must perform before you install Microsoft Dynamics GP eConnect.

• Chapter 4, “eConnect Installation,” describes the process to install eConnect. • Chapter 5, “BizTalk Adapter Installation,” describes the process to install the

(25)

Chapter 3:

Prerequisites

Before installing Microsoft Dynamics GP eConnect, there are several prerequisites you must check. This portion of the documentation describes the software requirements and the additional steps to perform before installing eConnect. The following topics are discussed:

• Operating system

• Microsoft .NET 1.1 Framework

• COM+ user account

• Distributed Transaction Coordinator (DTC)

• Functional currency

• Microsoft Message Queueing (MSMQ)

Operating system

To install eConnect, the computer must be running one of the following operating systems:

• Windows Server 2003 • Windows XP

• Windows 2000 Server

Microsoft .NET 1.1 Framework

To use eConnect, the Microsoft .NET 1.1 Framework is required. The eConnect installer verifies this framework is installed on your computer. If the framework is not installed, the eConnect installer will load and configure the framework.

COM+ user account

The eConnect COM+ object uses SQL Server integrated security to connect to the eConnect business objects. During the installation of eConnect, you need to supply a user account for the COM+ object. To set up the user account, complete the following procedure:

1. Select a user account.

Select or create a user account for the eConnect COM+ object.

• If you plan to install eConnect on a different computer than the Dynamics GP server in a domain environment, select or create a domain user account. • If you plan to install eConnect on a different computer than the Dynamics GP server in a workgroup environment, select or create a user on the Dynamics GP server.

• If you plan to install eConnect on the same server as Microsoft Dynamics GP, select or create a local user account.

2. Give the user account database access.

Add the user account you selected or created to the DYNGRP role for the system (DYNAMICS) database and for each company database that will be used with eConnect.

(26)

P A R T 2 I N S T A L L A T I O N

When you install eConnect, you will be prompted to supply the credentials for this user account.

Distributed Transaction Coordinator (DTC)

If eConnect will be running on a different computer than the SQL Server that is managing Microsoft Dynamics GP data, the Distributed Transaction Coordinator (DTC) must be active on both systems.

Enabling DTC

For Windows Server 2003, you can enable the network DTC through the Windows Components Wizard. To do this, complete the following procedure:

1. Open Add or Remove Programs.

Choose to add or remove Windows Components. The Windows Components Wizard will be displayed.

2. Select the Application Server components.

Click Details to display the Application Server Details.

(27)

C H A P T E R 3 P R E R E Q U I S I T E S

Configuring DTC

If the two computers are in the same domain, the default configuration for DTC can be used with eConnect. The default settings are as follows:

• Network DTC Access enabled • Allow Inbound communications • Allow Outbound communications • Mutual Authentication Required

If the two computer are in a Windows workgroup, or are in domains that do not have an established trust relationship, you must change the DTC security configuration. To configure the Distributed Transaction Coordinator on Windows Server 2003 and Windows XP SP2, complete the following procedure:

1. Open Component Services.

In the Administrative Tools accessed from the Start menu, choose Component Services.

2. Display the My Computer node.

Expand the Component Services node, and then expand the Computer node to display the My Computer node.

3. Display properties for the My Computer node.

Select the My Computer node, and then choose Properties from the Action menu.

(28)

5. Display the Transaction Configuration settings.

Click Security Configuration to display the security setting for DTC.

Mark No Authentication Required. Click OK.

Functional currency

eConnect requires a functional currency to be set up for Microsoft Dynamics GP, even if multicurrency is not being used. To set up a functional currency, complete the following procedure:

1. Open the Multicurrency Setup window in Microsoft Dynamics GP.

Choose Tools >> Setup >> Financial >> Multicurrency. Set the Functional Currency. This example designates US dollars as the functional currency.

Refer to the Microsoft Dynamics GP documentation for additional information about currency setup and multicurrency access.

(29)

C H A P T E R 3 P R E R E Q U I S I T E S

Microsoft Message Queueing (MSMQ)

Application integrations that use the eConnect Incoming, Outgoing and Replication services use MSMQ to transport and store XML documents. These XML documents represent data retrieved from or sent to Microsoft Dynamics GP. You can install eConnect prior to installing MSMQ, but the eConnect services will not start until MSMQ is available. To install MSMQ, complete the following procedure:

1. Start the Windows Components wizard.

Open the Add or Remove Programs window. Click Add/Remove Windows Components.

2. Select Application Server.

In the Windows Components Wizard, select Application Server. Click Details.

3. Select Message Queuing.

Select the Message Queuing check box.

4. Accept the selection.

Click OK to accept the selection. Click Next to begin the installation.

5. Close the wizard.

When the MSMQ install completes, click Finish to close the Windows Components Wizard.

(30)

(31)

Chapter 4:

eConnect Installation

This portion of the documentation describes how to install Microsoft Dynamics GP eConnect. The following information is discussed:

• Installation types

• Installation procedure

Installation types

eConnect provides two install options:

Complete installation eConnect normally installs all the eConnect samples, components, and documentation. This type of installation provides the greatest flexibility and is best suited to eConnect development.

Runtime installation The eConnect runtime installs only the eConnect business objects, the eConnect COM+ object, the COM library file, the .NET assemblies, the Incoming Service, the Outgoing Service, and the BizTalk adapter installer. This type of installation is used to run existing integration projects created with eConnect.

Both installation methods support a custom install option. A custom install excludes specified components or documentation from the installation. This reduces the disk space requirements and gives you the ability to install only the eConnect features needed for an integration project.

Installation procedure

To install eConnect, complete the following procedure:

1. Verify the user you are logged in as.

The user you are currently logged in as must be in the Administrator group for the computer on which you are installing eConnect.

2. Save existing SQL stored procedure customizations.

An eConnect installation drops all pre and post stored procedures for any previously installed version of eConnect.

To prevent the loss of existing customizations, make a backup of all custom stored procedure code before continuing with the eConnect installation.

Store the backup copy in a safe location.

3. Start the eConnect installer.

To install all eConnect components and documentation, start the installer named Microsoft_Business_Solutions_eConnect.msi.

To install only the eConnect runtime components, start the installer named Microsoft_Business_Solutions_eConnect_Runtime.msi.

(32)

4. Review the license agreement.

After reviewing the license agreement, mark the option to accept the terms. Click Next to continue.

5. Review the release notes.

Review the release notes to see the changes included in the current release. Click Next to continue.

6. Specify customer information.

The user name and organization default to the name and organization of the current user. Accept the default, or enter another name and organization. Mark the option to install eConnect for all users.

The single user install is no longer a valid install option.

Click Next to continue.

7. Select the setup type.

To install all available eConnect components, documentation, and samples, mark the Complete option. To install specified eConnect components, documentation, or samples, mark the Custom option. Click Next to continue.

(33)

C H A P T E R 4 E C O N N E C T I N S T A L L A T I O N

All features are installed by default. You must unmark a feature to prevent it from being installed.

When you click a button for a feature, a pop-up menu of options appears. Refer to the following table for information about each option

.

To exclude a feature, click the button and select “This feature will not be available.” Repeat as needed to specify all the features to be excluded.

A custom install also allows you to view the installation’s disk space requirements. Click Space to open the Disk Space Requirements window, where you can view the amount of available disk space and the amount required for installation.

You may also specify the folder where eConnect files are installed. The default folder is C:\Program Files\Microsoft Great Plains\eConnect9\. To select a different folder, click Change.

A custom install allows you to select from the following features:

BizTalk Components Installs the file needed to install the BizTalk 2004 application integration component (AIC) adapter.

Business Objects Installs the business objects in the SQL Server database and creates a shortcut to the Requester Setup link in the eConnect program group.

COM+ Components Installs the COM Component and .NET Assembly in COM+ Administration. Also registers the .NET Assembly in the global assembly cache.

Option What happens

This feature will be installed on the local hard disk.

Installs the feature on the local hard disk. This option installs the feature but not sub features.

This feature, and all subfeatures, will be installed on the local hard disk.

Installs the feature and all of its sub features. This feature will be installed when required. Will not install the selected feature. Allows the

feature to be installed later using Add or Remove Programs.

This feature will not be available. Will not install the selected feature or sub feature.

(34)

eConnect Incoming Service Installs the eConnect Incoming Service into the Service Control Manager.

eConnect Outgoing Service Installs the eConnect Outgoing Service into the Service Control Manager.

eConnect Replication Service Installs the eConnect Replication Service into the Service Control Manager. If you use the Microsoft_Business_Solutions _eConnect_Runtime installer, the Replication Service is not added to the Service Control Manager. To use the Replication Service, use the complete eConnect install.

If you chose the eConnect runtime install, eConnect Help, eConnect Samples, Queue Control, and Schema features will not be listed. These features are not part of the eConnect runtime install.

eConnect Help Installs help for eConnect and creates a shortcut to the help file in the eConnect program group.

eConnect Samples Installs the source code for several sample applications that demonstrate how to work with the eConnect API.

Queue Control Installs a tool that enables users to view, update, and move documents in a queue inside of Message Queuing Control.

Schemas Installs eConnect XSD and XDR Schemas.

If the custom install excludes the eConnect business objects, skip the next step. Click Next to continue.

9. Create the connection string (required if installing the business objects).

eConnect requires a connection string to install business objects into the Microsoft Dynamics GP databases. To automate the completion of the connection string, click the ellipsis (…) button.

(35)

C H A P T E R 4 E C O N N E C T I N S T A L L A T I O N

Select the option to specify a user name and password (like the sa logon) when you need to use SQL Server authentication. If you select the option to specify a user name and password, you must also mark the Allow saving password check box. This saves the password as part of the connection string. If you do not mark the check box, the password will not be included in the connection string and the install will not be able to complete. You should only select the user name and password option in situations where disclosure of the password is not considered a security risk. When the connection string is saved, the password is unmasked and unencrypted.

Select the database. To install business objects to all existing company databases, specify the DYNAMICS database in the connection string. To install to an individual company database (for example, the TWO sample company), specify that company database in the connection string.

Click Test Connection to ensure the connection is working. If the test fails, verify the specified combination of SQL Server, log on, and database is valid and retest the connection. If the test is successful, click OK to continue.

The Connection String field is now populated.

If you are installing eConnect on a separate computer from the SQL Server that manages the Microsoft Dynamics GP data, you need to update the data source in the configuration files for the Incoming and Outgoing services. Information about configuring the Incoming and Outgoing services is located in Chapter 6, “Configuring eConnect Services.”

(36)

10. Start the installation.

Click Install to begin the installation process. The install will run for several minutes.

11. Specify an account to perform database access.

Several eConnect components require a user login and password to access the eConnect business objects that were installed in the Microsoft Dynamics GP databases. The eConnect Incoming Service, Outgoing Service, and COM+ object will use this account. Enter the domain\login and password credentials for the user account you set up as an eConnect prerequisite. For more information about creating a user account see COM+ user account on page 21. Click Next to continue.

12. Complete the installation.

Once the installation completes, click Finish.

The specified company databases on the Microsoft Dynamics GP SQL Server will contain the eConnect business objects. You will also find the newly installed eConnect folders and files in the default directory C:\Program Files\Microsoft Great Plains\eConnect9\ or in the directory you specified during the custom install.

The installation also creates the eConnect event log. The log stores all the error, warning and information messages that eConnect generates. To view the eConnect event log, open the Start menu and select Control Panel >> Administrative Tools >> Event Viewer. Click eConnect to view the current list of messages.

(37)

Chapter 5:

BizTalk Adapter Installation

This portion of the documentation describes how to install the eConnect Adapters for BizTalk Server 2004 and BizTalk Server 2006. The following information is discussed:

• Overview

• Installing the eConnect Adapter for BizTalk 2004

• Installing the eConnect Adapter for BizTalk 2006

Overview

eConnect includes two adapters that enable eConnect to work with BizTalk Server. The installation includes the following BizTalk adapters:

• The eConnect Adapter for BizTalk 2004 is an optional install that allows eConnect to work with BizTalk Server 2004. To use eConnect with BizTalk Server 2004, you must install the eConnect Adapter for BizTalk 2004. Install the adapter on the computer where you installed BizTalk Server 2004.

• The eConnect Adapter for BizTalk 2006 is an optional install that allows eConnect to work with BizTalk Server 2006. To use eConnect with BizTalk Server 2006, you must install the eConnect Adapter for BizTalk 2006. Install the adapter on the computer where you installed BizTalk Server 2006.

You will only be able to install a BizTalk adapter if the BizTalk Components were included in the original eConnect install. See Installation procedure on page 27 for more information about installing eConnect.

Installing the eConnect Adapter for BizTalk 2004

To install the BizTalk 2004 Adapter, complete the following procedure:

1. Install the eConnect business objects.

The eConnect Adapter for BizTalk 2004 requires the installation of the eConnect business objects in the Dynamics GP database. Complete the install of the eConnect business objects before installing the adapter.

2. Start the BizTalk Adapter installer.

Open the installer file named BTS_eConnectAdapter.msi. The default location for the eConnect Adapter for BizTalk 2004 installer is C:\Program Files\Microsoft Great Plains\eConnect9\BizTalk\BizTalk 2004.

The eConnect Adapter for BizTalk 2004 installer must be installed on the server where BizTalk 2004 is loaded.

When the installer displays the Welcome page, click Next to continue.

3. Specify the installation folder.

Specify the location where the files for the eConnect BizTalk Adapter will be installed. Use the default location, or click Browse to specify a different location. You may also view the installation’s disk space requirements.

(38)

P A R T 2 I N S T A L L A T I O N

Click Next to begin the installation process. The install will run for several minutes.

Once the installation completes, click Close.

The installation places the adapter’s files in the folder C:\Program Files\Microsoft Great Plains\eConnect9\Microsoft eConnect Adapter for BizTalk 2004 or the folder you specified. To configure your BizTalk server to work with the eConnect BizTalk adapter, see BizTalk adapter on page 51.

Installing the eConnect Adapter for BizTalk 2006

To install the BizTalk 2006 Adapter, complete the following procedure:

1. Install the eConnect business objects.

The eConnect Adapter for BizTalk 2006 requires the installation of the eConnect business objects in the Dynamics GP database. Complete the install of the eConnect business objects before installing the adapter.

2. Start the BizTalk Adapter installer.

Open the installer file named BTS_eConnectAdapter.msi. The default location for the eConnect Adapter for BizTalk 2006 installer is C:\Program Files\Microsoft Great Plains\eConnect9\BizTalk\BizTalk 2006.

The eConnect Adapter for BizTalk 2006 installer must be installed on the server where BizTalk Server 2006 is loaded.

When the installer displays the Welcome page, click Next to continue.

(39)

C H A P T E R 5 B I Z T A L K A D A P T E R I N S T A L L A T I O N

Click Next to begin the installation process. The install will run for several minutes.

(40)

(41)

(42)

Part 3: Administration

This portion of the documentation explains the configuration and maintenance options for Microsoft Dynamics GP eConnect. The following information is discussed:

• Chapter 6, “Configuring eConnect Services,” describes configuration options for eConnect services and the BizTalk adapter.

• Chapter 7, “Maintenance,” describes how to make changes to an existing eConnect installation.

• Chapter 8, “Utilities,” identifies the utilities eConnect supplies to setup and monitor eConnect.

• Chapter 9, “Troubleshooting,” discusses how to troubleshoot issues that occur when using eConnect.

(43)

Chapter 6:

Configuring eConnect Services

After installing eConnect, you may need to configure the eConnect services or the BizTalk adapter. The following sections describes how to configure these components:

• Overview

• Incoming Service

• Outgoing Service

• Replication Service

• Transaction Requester

• BizTalk adapter

Overview

The complete eConnect installation adds three Windows services to your computer’s Service Control Manager. The installer initially configures each service and stores the configuration information in an XML file. These XML configuration files contain keys and values that control the operation of each service. To customize the behavior of a service or to adjust the service to reflect changes in your server environment, change the values for one or more keys in the configuration file.

Make a backup copy of the configuration file before making any changes. This ensures you will always be able to restore the service if necessary.

After changing the settings in a configuration file, you must stop and restart the service. The changes in the configuration file will not be implemented until the service restarts.

The eConnect install also includes the Transaction Requester that publishes eConnect XML documents to a specified queue. Use the eConnect Requester Setup utility to specify which Microsoft Dynamics GP documents to publish.

If you install the eConnect Adapter for BizTalk 2004, you must configure BizTalk Server 2004 to work with the adapter. You use the BizTalk Server Administration utility and Visual Studio .NET 2003 to configure the BizTalk server.

Incoming Service

The Incoming Service integrates eConnect XML documents into Microsoft Dynamics GP. The Incoming Service uses a configuration file named eConnect_Incoming.exe.config to control its operations. This file is found in the eConnect installation location, typically C:\Program files\Microsoft Great Plains\eConnect9\Services\Incoming Service.

The following example displays the contents of an eConnect_Incoming.exe.config file:

<? xml version="1.0"encoding="Windows-1252"?> <configuration > <appSettings > <addkey="eConnect.Incoming_Queue"value=""/> <addkey="eConnect.Transactional_deadletter_Queue"value="0"/> <addkey="eConnect.Schema.Type"value=""/> <addkey="eConnect.Schema"value=""/>

(44)

P A R T 3 A D M I N I S T R A T I O N

<addkey="eConnect.BackOffice.ConnectionString"value="data source=MYServer;initial catalog=MyDatabase;integrated

security=SSPI;persist security info=False;packet size=4096"/> <addkey="eConnect.LogAll"value=""/>

</configuration>

The keys are defined as follows:

eConnect.Incoming_Queue This key specifies the message queue that the service will monitor. The default value is blank.

<addkey="eConnect.Incoming_Queue"value=""/>

The default creates and monitors a queue named machine_name\private$\

econnect_incoming. To use another message queue, set the value to the queue’s name.

eConnect.Transactional_deadletter_Queue This key specifies where undeliverable messages are stored. The default value for the key is zero.

<addkey="eConnect.Transactional_deadletter_Queue"value="0"/>

The value “0” stores the undeliverable message in the system’s transactional deadletter queue.

A value of ”1” stores undeliverable messages in the deadletter queue associated with the message queue specified by the eConnect.Incoming_Queue key. If the eConnect.Incoming_Queue key has value="", the service sends undeliverable messages to machine_name\private$\econnect_incoming_deadletter.

If the eConnect.Incoming_Queue key specifies a queue name, the service sends undeliverable messages to a queue with a name that appends _deadletter to the specified queue name. For example, the eConnect.Incoming_Queue key sets value="machine_name\private$\TestQueue", the service sends undeliverable messages to the queue named machine_name\private$\TestQueue_deadletter.

eConnect.Schema.Type This key specifies whether to perform schema validation and the type of schema to use. The default value is blank.

<addkey="eConnect.Schema.Type"value=""/>

A blank key value means there is no schema validation. The other possible values are XSD, or XDR. You set the value based on the type of the file that contains the schema information.

Schema validation ensures the XML document in the message contains all the information required for a successful create, update, or delete operation in

(45)

C H A P T E R 6 C O N F I G U R I N G E C O N N E C T S E R V I C E S

node with an unrecognized name, the data value for that node is omitted but the specified operation is allowed to proceed. No log entry is made about the omitted node. Invalid data values are detected and logged as an error in the eConnect event log even when schema validation is not performed. XML documents with invalid data are discarded after logging the error message.

eConnect.Schema This key specifies the location of the XSD or XDR schema file. The default value is blank.

<addkey="eConnect.Schema"value=""/>

A blank key value indicates incoming XML documents will not be validated. If you have set the eConnect.Schema.Type key to XSD or XDR, use this key to supply the path to the XSD or XDR schema file. For example, use value="C:\Documents and Settings\Myuser\My Documents\Visual Studio Projects\eConnect_API\bin\ eConnect.xsd" to validate against the schema definitions contained in that XSD file.

eConnect.BackOffice.ConnectionString This key stores the connection string the service uses to connect to the Microsoft Dynamics GP SQL Server. The default value is derived from connection string specified during installation.

<addkey="eConnect.BackOffice.ConnectionString"value="data source=MYServer; initial catalog=MyDatabase;integrated security=SSPI;persist security info= False;packet size=4096"/>

You change how the connection string works by changing the value parameters. For example, you may change the data source or initial catalog parameters to reflect changes in your server configuration.

If you install eConnect on a separate computer from the SQL Server that manages Microsoft Dynamics GP data, you must change this key’s data source parameter. The default configuration assumes a single server install. Change the data source value to specify the SQL Server where the eConnect business objects are installed.

Invalid changes to connection string parameters can prevent the service from working. You should carefully test changes to ensure the connection string is valid.

eConnect.LogAll The key specifies the types of messages to log in the eConnect event log. The default value is blank.

<addkey="eConnect.LogAll"value=""/>

The value ““ logs only errors. Change the value to “1” to log all messages in the eConnect event log.

eConnect.Threads This key specifies the number of threads that are available when the service starts. The default value is “0”.

A value of “0” indicates a single thread will be used. You can set the value to any number between 0 and 19. A value of 19 makes 20 threads available when the service starts. A higher number of threads should allow the service to process documents more quickly.

(46)

There are scenarios where increasing the number of threads degrades system performance. If the server cannot support more threads, or custom code added to an eConnect pre or post stored procedures is not thread safe, adding threads may cause unexpected results. Changes to this key’s value require careful evaluation and testing.

Outgoing Service

The Outgoing Service allows you to integrate transaction information originating in Microsoft Dynamics GP into your application. The Outgoing Service creates XML documents and stores them in a message queue. Your application must retrieve these messages to use the XML documents they contain. The Outgoing Service creates a default queue named machine_name\private$\econnect_outgoing to store outgoing messages.

The Outgoing Service works in conjunction with the eConnect Transaction Requester. Use the Transaction Requester to specify the Dynamics GP documents you want sent to the message queue. Refer to Transaction Requester on page 48 section for more information.

The Outgoing Service uses a configuration file named eConnect_Outgoing.exe.config to control its operations. This file is found in the eConnect installation location, typically C:\Program files\Microsoft Great Plains\eConnect9\Services\Outgoing Service\eConnect_Outgoing.exe.config. The following example displays the contents of an eConnect_Outgoing.exe.config file:

<?xmlversion="1.0"encoding="Windows-1252"?> <configuration>

<addkey="BackOffice.ConnectionString"value="data

source=MyServer;initial catalog=MyDatabase;Integrated

Security=SSPI;persist security info=False;packet size=4096"/> <add key ="Requester.ACTION" value ="0" />

The keys are defined as follows:

Requester.ACTION This key specifies the type of database operations you want the service to monitor. The default value is “0”.

(47)

The following is a list of possible action types:

Use this key to specify the types of XML documents produced by the Outgoing Service.

Requester.OutputType This key specifies the type of the XML document that is created. The default value is “2”, which retrieves the complete document.

<addkey="Requester.OutputType"value="2"/>

The following is a list of possible output types:

Use this key to adjust the amount of data the Outgoing Service places in each XML document.

Requester.Remove This key specifies whether or not the record is deleted from the eConnect_Out table after the service places the document in the message queue. The default value is “1”.

<addkey="Requester.Remove"value="1"/>

A value of ”1” deletes the record from the eConnect_Out table. A value of ”0” keeps the record in the eConnect_Out table.

Value Description

0 Creates an XML document and stores it in a message queue for each Transaction Requester enabled insert, update, or delete operation. 1 Creates an XML document and stores it in a message queue for each

Transaction Requester enabled insert operation. The Outgoing Service ignores any Transaction Requester enabled update or delete operations.

2 Creates an XML document and stores it in a message queue for each

Transaction Requester enabled update operation. The Outgoing Service ignores any Transaction Requester enabled insert and delete operations.

Transaction Requester enabled delete operation. The Outgoing Service ignores any Transaction Requester enabled insert and update operations.

Transaction Requester enabled insert or update operation. If a record is updated multiple times, the queue contains an XML document for each update

operation. The Outgoing Service ignores any Transaction Requester enabled delete operations.

5 Creates an XML document and stores it in a message queue for Transaction Requester enabled insert and update operations. Inserts and updates to the same record produce only a single XML document in the queue. The Outgoing Service ignores any Transaction Requester enabled delete operations.

Value Description

0 Retrieves key information. The XML document contains the record’s unique key value and the database and table in Microsoft Dynamics GP where it is stored. 1 Retrieves the master document only. The XML master document contains all

the eConnect schema fields for that record. For example, the XML document produced for a new customer will include every field defined by the eConnect customer schema.

2 Retrieves the complete document. The XML document contains the master document data and any child documents related to the master document. For example, the XML document for a customer will also include the address documents for that customer.

(48)

The service queries the list of records in the eConnect_Out table. It then cycles through the list of records to identify the documents to place in the message queue. If the record in the eConnect_Out table is not deleted, the service creates a duplicate document in the message queue each time it runs.

Timer1.Interval This key specifies the number of milliseconds the service pauses between queries of the eConnect_Out table. Default value is ”1000”

<addkey="Timer1.Interval"value="1000"/>

Change the value when you need to optimize the workload the service places on your computer.

Delay.Interval This key specifies the number of seconds a record must exist in the eConnect_Out table to be eligible for processing by the service. The default value is ”5”.

<addkey=”Delay.Interval"value="5"/>

The default value indicates a record will not be processed until it has been in the eConnect_Out table for a minimum of five seconds.

eConnect.BackOffice.ConnectionString This key stores the connection string the service uses to connect to the Microsoft Dynamics GP SQL Server. The default value is the connection string specified during installation.

<addkey="BackOffice.ConnectionString"value="data source=MyServer;initial catalog=MyDatabase;Integrated Security=SSPI;persist security

info=False;packet size=4096"/>

You change how the connection string works by changing the value parameters. For example, you may change the data source or initial catalog parameters to reflect changes in your server configuration.

If you install eConnect on a separate computer from the SQL Server that manages Microsoft Dynamics GP data, you must change this key’s data source parameter. The default configuration assumes a single server install. Change the data source value to specify the SQL Server where the eConnect business objects are installed.

Invalid changes to connection string parameters can prevent the service from working. You should carefully test changes to ensure the connection string is valid.

DatabaseNames This XML node contains attributes that specify the databases the Outgoing Service monitors. The default includes all of the Dynamics GP databases that existed when the service was installed.

(49)

• Install the eConnect business objects to the CONTOSO database. See Installing additional companies on page 57 for information about adding the business objects.

• Add database3="CONTOSO” as an attribute to the DatabaseNames node of the Outgoing Services’s configuration file. The update to the DatabaseNames node appears as follows:

Replication Service

The Replication Service allows you to integrate information originating in Microsoft Dynamics GP with a front office database. The Replication Service requires the Outgoing Service to retrieve documents from Microsoft Dynamics GP. The Replication Service uses the XML documents in the outgoing queue to replicate the data changes to the front office database.

The Replication Service uses a configuration file named eConnectFrontOfficeService.exe.config to control its operations. This file is found in the eConnect installation location, typically C:\Program files\Microsoft Great Plains\eConnect9\Services\ Replication Service\.

The following example displays the contents of an eConnectFrontOfficeService.exe.config file:

<? xml version="1.0"encoding="Windows-1252"?> <configuration >

<addkey="eConnect.FrontOffice.ConnectionString.0" value="data source=127.0.0.1;initial catalog=TWO_FRONT;integrated

security=SSPI;persist security info=False;packet size=4096"/> <addkey="eConnect.FrontOffice.ConnectionString.1" value="data

source=127.0.0.1;initial catalog=DYNAMICS_FRONT;integrated security=SSPI;persist security info=False;packet size=4096"/> <addkey="eConnect.Requester.Incoming_Queue.0 "value=".\private$\econnect_company_front"/> <addkey="eConnect.Requester.Incoming_Queue.1 "value=".\private$\econnect_system_front"/> <addkey="eConnect.Requester.DeadLetter_Queue.0‘ "value=".\private$\econnect_company_front_deadLetter"/> <addkey="eConnect.Requester.DeadLetter_Queue.1 "value=".\private$\econnect_system_front_deadLetter"/> <addkey="eConnect.Timer.Interval"value="1000"/> </appSettings > </configuration>

The configuration settings allow the Replication Service to target one or more front office databases. The front office database is specified by the key named eConnect.FrontOffice.ConnectionString.0.

Additional databases can be added by creating new connection string keys. Increment the integer value appended to the key name to uniquely identify each key. The following example shows a connection string key that specifies a second target database:

Microsoft Dynamics GP. econnect Installation and Administration Guide Release 9.0