Microsoft GP 10(WSInstallAdminGuide)

8/6/2019 Microsoft GP 10(WSInstallAdminGuide)

http://slidepdf.com/reader/full/microsoft-gp-10wsinstalladminguide 1/91

Microsoft Dynamics ® GPWeb Services Installation and Administration Guide

Release 10



Copyright Copyright © 2008 Microsoft Corporation. All rights reserved.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting therights under copyright, no part of this document may be reproduced, stored in or introduced intoa 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 softwarewith which this document was provided may make a reasonable number of copies of thisdocument solely for internal use.

Trademarks Microsoft, Microsoft Dynamics, Visual Basic, Visual Studio, Windows, and Windows Server areeither registered trademarks or trademarks of Microsoft Corporation or its affiliates in the UnitedStates and/or other countries.

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

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

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

Warranty disclaimer Microsoft Corporation disclaims any warranty regarding the sample code contained in thisdocumentation, 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 withoutnotice, and should not be construed as a commitment by Microsoft Corporation. MicrosoftCorporation assumes no responsibility or liability for any errors or inaccuracies that may appearin this manual. Neither Microsoft Corporation nor anyone else who has been involved in thecreation, 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 anticipatedprofit 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 youhave any questions, please call the Microsoft Dynamics GP Customer Assistance Department at800-456-0025 (in the U.S. or Canada) or +1-701-281-6500.

Publication date September 3, 2008



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

Contents

Introduction .................................................................................................................................................2What’s in this manual ...................................................................................................................................2

Symbols and conventions ............................................................................................................................2

Product support ............................................................................................................................................3

Part 1: Web Service Basics ......................................................................................................6

Chapter 1: Dynamics GP Web Service Overview .................................................... 7What is a web service? .................................................................................................................................7

Web service benefits .....................................................................................................................................7

What the Dynamics GP Web Service provides .........................................................................................8

Chapter 2: Web Service Architecture ................................................................................ 9Web service foundation. ...............................................................................................................................9

Configurations ...............................................................................................................................................9

Security .........................................................................................................................................................10

Policy ............................................................................................................................................................11

Exception logging .......................................................................................................................................11

Part 2: Installation .......................................................................................................................... 14

Chapter 3: Prerequisites .............................................................................................................. 15Server operating system .............................................................................................................................15

Microsoft .NET 2.0 Framework .................................................................................................................15

Internet Information Services and ASP .NET .........................................................................................15

Secure Sockets Layer (SSL) ........................................................................................................................17Windows Management Instrumentation service ...................................................................................17

Active Directory Lightweight Directory Services role ..........................................................................17

Distributed Transaction Coordinator (DTC) ...........................................................................................18

Microsoft Management Console (MMC) 3.0 ...........................................................................................22

Web service user account ...........................................................................................................................22

Microsoft Dynamics GP 10.0 .....................................................................................................................23

ISO currency codes .....................................................................................................................................23

Windows Server 2008 role summary .......................................................................................................24

Chapter 4: Web Services Installation ..............................................................................25

Installing web services ...............................................................................................................................25Upgrading an earlier installation .............................................................................................................27

Verifying the web service installation ......................................................................................................30

User account summary ..............................................................................................................................31

What to do next ...........................................................................................................................................32

Chapter 5: Management Tools Installation ................................................................33Prerequisites .................................................................................................................................................33

Installing the management tools. ..............................................................................................................33



ii 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

C O N T E N T S

Required roles and permission .................................................................................................................34

Accessing the management tools ..............................................................................................................34

Part 3: Security ....................................................................................................................................36

Chapter 6: Web Services Security ...................................................................................... 37

Overview ......................................................................................................................................................37Administering security ..............................................................................................................................38

Tasks ..............................................................................................................................................................39

Roles ..............................................................................................................................................................41

Enterprise level groups ..............................................................................................................................43

Application level groups. ...........................................................................................................................44

Role assignments .........................................................................................................................................46

Entity ID assignments ................................................................................................................................47

Chapter 7: Policy ................................................................................................................................ 49Overview ......................................................................................................................................................49

Editing a policy instance ............................................................................................................................50Creating a new policy instance .................................................................................................................51

Deleting a policy instance ..........................................................................................................................52

Chapter 8: Authentication Methods ................................................................................53Supported authentication methods. .........................................................................................................53

Enabling Kerberos for the web services. ..................................................................................................53

Registering the SPN ....................................................................................................................................55

Part 4: Running the Web Service ................................................................................58

Chapter 9: Troubleshooting ...................................................................................................... 59Exceptions ....................................................................................................................................................59

Web service does not respond ...................................................................................................................60

Security .........................................................................................................................................................60

Policy ............................................................................................................................................................61

Timeout issues .............................................................................................................................................61

Chapter 10: Logging and Auditing .................................................................................... 63Dynamics GP web service logging ...........................................................................................................63

Dynamics Security Admin web service logging ....................................................................................64

Chapter 11: Making Backups .................................................................................................. 67

SQL tables ....................................................................................................................................................67ADAM database ..........................................................................................................................................67

Web service installation ..............................................................................................................................68

Chapter 12: Adding Additional Companies ............................................................... 69

Chapter 13: Repairing Web Services ...............................................................................71Repair options .............................................................................................................................................71

Repair procedure .........................................................................................................................................71



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 iii

C O N T E N T S

Appendix ...................................................................................................................................................... 76

Appendix A: ADAM or ADLDS Administrators .....................................................77

Glossary .........................................................................................................................................................81

Index ................................................................................................................................................................... 83



iv 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



2 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

IntroductionWelcome to Web Services for Microsoft Dynamics™ GP. This documentationexplains how to install and administer these web services so they can be used byapplications that integrate with Microsoft Dynamics GP. Before you begin installingand using the web services, take a few moments to review the informationpresented here.

What’s in this manual

The Microsoft Dynamics GP Web Services Installation and Administration Guide isdesigned to give you an in-depth understanding of how to install and administerthese web services. Information is divided into the following parts:

• Part 1, Web Service Basics , explains what is provided by the web services forMicrosoft Dynamics GP and describes the architecture.

• Part 2, Installation , describes how to install and configure the web services.

• Part 3, Security , explains how to configure security for the web services.

• Part 4, Running the Web Service , describes the day-to-day operation of theweb services.

To learn about creating applications that use the Web Services for MicrosoftDynamics GP, refer to the documentation included with the Web Services forMicrosoft Dynamics GP Software Development Kit (SDK).

Symbols and conventions

To help you use this documentation more effectively, we’ve used the followingsymbols and conventions within the text to make specific types of informationstand out.

Symbol Description

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

Warnings indicate situations you should be aware ofwhen completing tasks.

Margin notes summarize important information.

Margin notes call attention to critical information anddirect you to other areas of the documentation wherea topic is explained.

Convention Description

Part 1, Web Service Basics Bold type indicates a part name.Chapter 7, “Policy” Quotation marks indicate a chapter name.Installing web services Italicized type indicates a section name.using System.IO; This font is used to indicate script examples.Web Services DescriptionLanguage (WSDL)

Acronyms are spelled out the first time they’re used.

TAB or ALT+M Small capital letters indicate a key or a key sequence.



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/BusinessSolutions and click the CustomerSource orPartnerSource link, or call 888-477-7877 (in the US and Canada) or 701-281-0555.

http://www.microsoft.com/businesssolutions

http://www.microsoft.com/businesssolutions




Part 1: Web Service BasicsThis portion of the documentation contains basic information you should know

before deploying Web Services for Microsoft Dynamics GP. The followinginformation is discussed:

• Chapter 1, “Dynamics GP Web Service Overview ,” provides an overview ofweb services and what the Dynamics GP web service provides.

• Chapter 2, “Web Service Architecture ,” describes the parts that make up theWeb Services for Microsoft Dynamics GP, and how these parts work together.




Chapter 1: Dynamics GP Web Service OverviewWeb Services for Microsoft Dynamics GP provide an ideal way for externalapplications to integrate with the data contained in the accounting system. Thefollowing topics introduce the Web Services for Microsoft Dynamics GP:

• What is a web service?• Web service benefits• What the Dynamics GP Web Service provides

What is a web service?

In the most general terms, a web service is defined as a software system that isdesigned to support machine-to-machine interaction over a network. Morespecifically, web services are software systems that provide data and services toother applications. Web services use standard Internet transport protocols such asHypertext Transfer Protocol (HTTP) and standard XML-based document formatssuch as Simple Object Access Protocol (SOAP) to exchange information.

ASP .NET is used as the foundation to implement the Web Services for MicrosoftDynamics GP. It provides the support for the standard protocols that make the webservice accessible.

Web service benefits

In general terms, web services provide several key benefits for software systems:

1. Based on industry standardsApplications that can interact with with services should be able to access thedata and services provided by the web service.

2. Development tool independenceAny development tool that supports the web service standard should be able tointeract with the web service.

3. Insulation from future changesWeb services attempt to keep the web service interface unchanged, even thoughthe data and code behind the web service may change in future versions of aproduct. This helps applications that use the web service to keep working, eventhough the application behind the web service has changed.

Web server hosting the web services.

Communication occurs over the Internet or local

intranet.



P A R T 1 W E B S E R V I C E B A S I C S


4. Secure access to data.Web services can tightly control access to the data and services they are makingavailable.

What the Dynamics GP Web Service provides

The web service for Microsoft Dynamics GP provides access to the primarydocuments in the accounting system. Some of the document types include:

• Customers• Vendors• Sales documents• Purchase documents• Receivables transactions• Payables transactions• General ledger transactions• Accounts

Through the web service, integrating applications can retrieve documents, createnew documents, update existing documents, and delete or void documents.

The web service for Microsoft Dynamics GP is fully integrated with the DynamicsSecurity Service. The administrator of the web service can configure security so onlyspecified users are allowed to perform actions like creating or updating salesdocuments.




Chapter 2: Web Service ArchitectureWhen deploying the Web Services for Microsoft Dynamics GP, it will be helpful tounderstand the architecture used to implement them. Information about thearchitecture is divided into the following sections:

• Web service foundation• Configurations• Security• Policy• Exception logging

Web service foundation

The foundation for web services on the Microsoft Windows Server platform isInternet Information Services (IIS). ASP .NET adds the web service capabilities.With this foundation, Web Services for Microsoft Dynamics GP provides a standardweb service interface that allows external applications to access data in MicrosoftDynamics GP.

The Dynamics GP web service uses eConnect to provide access to the data managed by the accounting system. eConnect is a set of SQL stored procedures andsupporting code used by integrating applications to access data in MicrosoftDynamics GP. Data validation logic is built into eConnect, helping ensure theintegrity of any data written to the database through the web services.

The eConnect interfaces can still be used when the Dynamics GP web service isinstalled. This allows you to run integrations based directly on eConnect in thesame installation as the Dynamics GP web service.

Configurations

Two common configurations are used with Web Services for Microsoft DynamicsGP. In the basic configuration, IIS with ASP .NET and the Web Services forMicrosoft Dynamics GP are installed on the same server that is hosting SQL Serverand managing Microsoft Dynamics GP data. This is shown in the followingillustration:

SQL Server with

with ASP .NET andWeb Services

for Microsoft Dynamics GP

IIS Server

Dynamics GP Data and eConnect+



P A R T 1 W E B S E R V I C E B A S I C S


The following illustration shows the second common configuration for the WebServices for Microsoft Dynamics GP. In this configuration, the web services areinstalled on a separate server, and access the SQL Server that manages MicrosoftDynamics GP data over the local network.

Which configuration you choose will depend on how extensively you will be usingthe Web Services for Microsoft Dynamics GP, and what server resources you have

available. The two-server configuration will provide better performance if the webservice will be heavily used.

Security

Refer to Chapter 6,“Web Services Security,” for details about managing web service security.

Security for the Dynamics GP web service is controlled by the Dynamics Securityweb service. The Dynamics Security web service is installed onto the same webserver as the Dynamics GP web service.

Through this web service, the web service administrator will configure which usersand groups are able to execute the web methods (operations) provided by theDynamics GP web service. If an application attempts to run a web method forwhich the current user doesn’t have access, a security exception will be raised andthe action will be prevented. Security is controlled through the Dynamics SecurityAdministration console, which is a snap-in for Microsoft Management Console(MMC). The console is shown in the following illustration.

SQL Serverwith Dynamics GP Data

and eConnect

IIS Serverwith ASP .NET and

Web Servicesfor Microsoft Dynamics GP

Local Network




C H A P T E R 2 W E B S E R V I C E A R C H I T E C T U R E

Policy

Refer to Chapter 7,“Policy,” for details about configuring policy for the Dynamics GP web

service.

Policy is another security-related feature for the Dynamics GP web service. Thepolicy system allows the web service administrator to control how business objectsare created, updated, or deleted through the Dynamics GP web service.

Each create, update, and delete or void web service operation has a policyobject that

is passed with the operation. This policy object specifies the set of behaviors for theoperation. Each behavior controls one characteristic for the operation beingperformed. For instance, the policy for the CreateCustomer web method has the

behavior named “Create Active Behavior”. This behavior controls whether thecustomer being created is set to the active or inactive state.

Behaviors are classified as internal or external. An internal behavior is one that can bespecified by only the web service administrator. An external behavior is one that can

be specified by the application that is calling the web method and passing in thepolicy object. Policy is configured using the Dynamics Security console.

Exception logging

Refer to Chapter 9,“Troubleshooting,” for more informationabout using the exception log totroubleshoot the web service.

The Dynamics GP web service maintains a record of all exceptions (errors) thatoccur for web service operations. The web service administrator will use thisinformation to help diagnose and resolve any issues for applications that use theweb service.

You can use the Dynamics GP Web Services Exceptions console to view theexception information. This is a snap-in for Microsoft Management Console (MMC)that retrieves and displays the exceptions logged by the Dynamics GP web service.

The console is shown in the following illustration.

The exception information can also be queried by applications that access theDynamics GP web service. Retrieving exception information allows the clientapplications to display helpful error messages for the user, or to respondappropriately to exceptions that occur.




Part 2: InstallationThis portion of the documentation explains how to install the Web Services forMicrosoft Dynamics GP. The following information is discussed:

• Chapter 3, “Prerequisites ,” describes the software required and the actions you

must perform before you install the Web Services for Microsoft Dynamics GP.

• Chapter 4, “Web Services Installation ,” describes the steps needed to install theweb services.

• Chapter 5, “Management Tools Installation ,” explains how to install themanagement tools available for the web services.




Chapter 3: PrerequisitesBefore installing Web Services for Microsoft Dynamics GP, there are severalprerequisites needed. This portion of the documentation describes the softwarerequired and the additional steps that must be performed before installing the webservices. The following topics are discussed:

• Server operating system• Microsoft .NET 2.0 Framework• Internet Information Services and ASP .NET • Secure Sockets Layer (SSL)• Windows Management Instrumentation service• Active Directory Lightweight Directory Services role• Distributed Transaction Coordinator (DTC)• Microsoft Management Console (MMC) 3.0• Web service user account• Microsoft Dynamics GP 10.0• ISO currency codes• Windows Server 2008 role summary

Server operating system

To install Web Services for Microsoft Dynamics GP, the server must be running theone of the following operating systems:

• Windows Server 2003 Standard or Enterprise edition

• Small Business Server 2003

• Windows Server 2008 Standard or Enterprise edition

Microsoft .NET 2.0 Framework

To use Web Services for Microsoft Dynamics GP, the Microsoft .NET 2.0 Frameworkis required. You can download and install this framework by going to the MicrosoftUpdate site:

http://update.microsoft.com

Internet Information Services and ASP .NET

To use Web Services for Microsoft Dynamics GP, the server must be runningInternet Information Services (IIS) with ASP .NET installed.

Windows Server 2003 and Small Business ServerYou can install IIS and ASP .NET by opening the Add or Remove Programs window

and clicking the Add/Remove Windows Components button. In the WindowsComponents Wizard, select Application Server and click Details. Be sure thefollowing two items are marked:

• ASP .NET• Internet Information Services (IIS)

Other items might already be marked in the list. Click OK to accept the selections.Click Next to complete the installation, then click Finish to close the WindowsComponents Wizard.



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


Windows Server 2008You can install IIS by adding the Web Server (IIS) server role in the Server Manager.To install this role, complete the following steps:

1. Open the Server Manager.Roles are added in the Server Manager. Choose Start >> Administrative Tools>> Server Manager.

2. Select the Roles node in the Server Manager.The roles currently installed will be displayed.

3. Add a new role.In the Action menu, choose Add Roles. The Add Roles Wizard will bedisplayed. Click Next to continue.

4. Mark the Web Server (IIS) role.In the list of available roles, mark the Web Server (IIS) role. Click Next tocontinue.

5. Review the information about the Web services.Click Next to continue.

6. Confirm the installation.Review the installation messages, and then click Install.

7. Review the installation results.After you have viewed the installation results, click Close.

Once the Web Server (IIS) server role in installed, you can select it in the Roles groupin the Server Manager. Be sure that ASP.NET appears with the status Installed in theRole Services list. If it does not, click Add Role Services to add it.

The ASP.NET role service must be installed.




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

Secure Sockets Layer (SSL)

If you require additional security for the data accessed through the web services,you may want to implement SSL for the IIS web site. If you implement SSL, theURLs that access the web services will be https instead of http .

Windows Management Instrumentation service

The Windows Management Instrumentation (WMI) service must be running for theWeb Services for Microsoft Dynamics GP installation to complete properly. If thisservice isn’t running, errors will occur when performance counters are installed forthe web services.

Active Directory Lightweight Directory Services role

When running Web Services for Microsoft Dynamics GP on Windows Server 2008,the Active Directory Lightweight Directory Services (ADLDS) role is required. Toinstall this role, complete the following steps:




4. Mark the Active Directory Lightweight Directory Services role.In the list of available roles, mark the Active Directory Lightweight Directory

Services role. Click Next to continue.

5. Review the information about the directory services.Click Next to continue.

Mark the Active Directory Lightweight Directory

Services role.







Distributed Transaction Coordinator (DTC)

If the Web Services for Microsoft Dynamics GP will be running on a different serverthan the SQL Server that is managing Microsoft Dynamics GP data, the DistributedTransaction Coordinator (DTC) must be active on both systems. The followingsections explain how to enable and configure DTC for Windows Server 2003 andWindows Server 2008.

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

1. Open Add or Remove Programs.Choose to add or remove Windows Components. The Windows ComponentsWizard will be displayed.

2. Select the Application Server components.Click Details to display the Application Server Details.

Mark Enable network DTC access and click OK.

3. Complete the changesClick Next to complete the changes, and then click Finish to close the wizard.





Configuring DTC for Windows Server 2003The default configuration for DTC can be used with Web Services for MicrosoftDynamics GP. If you have made modifications to the security configuration forDTC, you must be sure the following settings are being used:

• Network DTC Access enabled• Allow Inbound communication

• Allow Outbound communication• Mutual Authentication Required (when running in a domain environment)• No Authentication Required (when running in a workgroup environment or

with domains that don’t have an established trust relationship)

To configure the Distributed Transaction Coordinator on Windows Server 2003,complete the following procedure:

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

2. Display the My Computer node.Expand the Component Services node, and then expand the Computers node todisplay the My Computer node.

3. Display properties for the My Computer node.Select the My Computer node, and then choose Properties in the Action menu.

4. Select the MSDTC tab.

5. Display the Transaction Configuration settings.Click Security Configuration to display the security settings for DTC.

Make the appropriate settings, and click OK.





Enabling DTC for Windows Server 2008For Windows Server 2008, you can enable the network DTC by installing theApplication Server role. To install this role, complete the following procedure.




4. Mark the Application Server role.In the list of available roles, mark the Application Server role. Click Next tocontinue.

5. Review the information about the application services.Click Next to continue.



Mark the ApplicationServer role.





Configuring DTC for Windows Server 2008The default configuration for DTC can be used with Web Services for MicrosoftDynamics GP. If you have made modifications to the security configuration forDTC, you must be sure the following settings are being used:

• Network DTC Access enabled• Allow Inbound communication

• Allow Outbound communication• Mutual Authentication Required (when running in a domain environment)• No Authentication Required (when running in a workgroup environment or

with domains that don’t have an established trust relationship)

To configure the Distributed Transaction Coordinator on Windows Server 2008,complete the following procedure:

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

2. Display the My Computer node.Expand the Component Services node, and then expand the Computers node todisplay the My Computer node.

3. Display the Local DTC node.Expand the My Computer node, and then expand the Distributed TransactionCoordinator node. Select the Local DTC node.

4. Display properties for the Local DTC node.Select the Local DTC node, and then choose Properties from the Action menu.

5. Select the Security tab.Select the Security tab to display the security settings for DTC.

Select the Local DTC node.





Make the appropriate settings, and click OK.

Microsoft Management Console (MMC) 3.0

Version 3.0 of the Microsoft Management Console (MMC) is required to use theSecurity Console and Exception Management console that will be installed withWeb Services for Microsoft Dynamics GP. If you have Windows Server 2003 R2 orWindows Server 2008, you already have MMC 3.0 installed. If you do not, there aretwo ways to get this version of the MMC:

• Install the upgrade for Windows Server 2003 R2.

• Go to www.microsoft.com and search for Knowledge Base article KB907265.This article explains how to download and install the MMC 3.0 update.

Web service user account

The Dynamics GP web service and the Dynamics Security web service each have anapplication pool that must run with a designated user account. To make the webservices more secure, this “web service user” should be created and used only forthis purpose.

Which type of user (local or domain) you need to create depends on theconfiguration you plan to use for Web Services for Microsoft Dynamics GP.

• If you will be installing the web services on the same computer that is runningthe SQL Server and managing data for Microsoft Dynamics GP, you can create alocal user account.

• If you will be installed the web services on a different computer than the onerunning SQL Server and managing data for Microsoft Dynamics GP, you mustcreate a domain account.

For improved security, this new user should be given minimal privileges.

When you install Web Services for Microsoft Dynamics GP, you will need to supplythe credentials for this new account.





Microsoft Dynamics GP 10.0

To use this release of Web Services for Microsoft Dynamics GP, you must be usingMicrosoft Dynamics GP 10.0. Be sure the Microsoft Dynamics GP installation isworking properly, and that you have made a complete backup before installing theWeb Services for Microsoft Dynamics GP.

ISO currency codesThe Dynamics GP web service uses ISO codes to identify currencies in MicrosoftDynamics GP. These ISO codes were not previously required for the currenciesdefined in the system, so the currencies may not have them. If they do not, you mustadd the appropriate ISO code for each currency.

Web Services for Microsoft Dynamics GP does not support using the same ISO code fomore than one currency.

To add ISO codes, complete the following procedure:

1. Open the Currency Setup window in Microsoft Dynamics GP.Choose Microsoft Dynamics GP menu >> Tools >> Setup >> System >>Currency and enter the system password to display this window.

2. Display each currency.Use the Currencies lookup to display each currency.

3. Enter the ISO value and save the currency.The following table lists the ISO values for the currencies commonly defined inMicrosoft Dynamics GP:

ISO Code Country/Region Currency

AUD Australia Dollars

CAD Canada Dollars

EUR European Union Euros

JPY Japan Yen

MXN Mexico Pesos

NZD New Zealand Dollars

PLN Poland Zlotych

SGD Singapore Dollars

ZAR South Africa Rand

GBP United Kingdom Pounds

USD United States Dollars





Windows Server 2008 role summary

The following table summarizes the roles and role services for Windows Server 2008that are used by Web Services for Microsoft Dynamics GP.

Role Role Services

Active Directory Lightweight Directory Services N/A

Application Server Distributed TransactionsIncoming Remote TransactionsOutgoing Remote Transactions

Web Server (IIS) Common HTTP FeaturesStatic ContentDefault ContentDirectory BrowsingHTTP Errors

Application DevelopmentASP .NET.NET ExtensibilityISAPI ExtensionsISAPI Filters

Server Side IncludesHealth and Diagnostics

HTTP LoggingRequest Monitor

SecurityBasic AuthenticationWindows AuthenticationDigest AuthenticationRequest Filtering

PerformanceStatic Content Compression

Management ToolsIIS Management ConsoleIIS Management Compatibility

IIS 6 Metabase CompatibilityIIS 6 WMI CompatibilityIIS 6 Scripting ToolsIIS 6 Management Console




Chapter 4: Web Services InstallationThis portion of the documentation describes how to perform the installation of WebServices for Microsoft Dynamics GP. The following items are discussed:

• Installing web services• Upgrading an earlier installation

• Verifying the web service installation• What to do next

Installing web servicesIf you’re upgrading anexisting installation of web services, refer toUpgrading an earlier installation on page 27 .

To install Web Services for Microsoft Dynamics GP, complete this procedure.

Be aware that the Web Services for Microsoft Dynamics GP installer may reset IIS as part othe installation. Keep this in mind if you have other applications running on IIS.

1. Verify the user you are logged in as.This user will become the initial Security Administrator for the DynamicsSecurity Service. This user will also be added to the Superuser role for theDynamics GP web service, allowing access to all web service operations. OnWindows Server 2003, the user you are currently logged in as must be in theAdministrator role for the computer on which you are installing.

2. Start the Web Services for Microsoft Dynamics GP installer.On Windows Server 2003, you can launch the installer by double-clickingDynamicsGPWebServices.msi . On Windows Server 2008, you must run theinstaller with elevated privileges. You can do this by running Setup.exe , whichwill prompt for administrator credentials. The Welcome page of the installerwill be displayed. Click Next to continue.

3. Review the license agreement.After reviewing the license agreement, mark the option to accept the terms andclick Next to continue.

4. Specify the location of the Microsoft Dynamics GP data.In the Server Name field, supply the name of the machine that is running SQLServer and managing the data for Microsoft Dynamics GP. The installationprogram must connect to this database to complete the installation. You can useWindows Trusted Authentication or SQL Authentication (supplying theAdministrator login ID and password).

Click Next to continue. If the database connection cannot be made, an error will be displayed. Correct the issue and continue.





5. Select the web site and installation location.Specify the web site on the IIS server that should be used for the web services.Also, select the location where the files for the Web Services for MicrosoftDynamics GP will be installed. You can use the default location, or click Browseto specify a different location.

Do not install Web Services for Microsoft Dynamics GP on a web site that is running aSharePoint web application, such as Business Portal. Web Services for MicrosoftDynamics GP must be installed on its own web site.

When you have made your selections, click Next to continue.

6. Specify the application account.This account will be used for the following:

• Application Pool user for Dynamics GP web service• Application Pool user for Dynamics Security service• Reader of ADAM• Reader of AzMan

• User for SQL Server and the databases used for Microsoft Dynamics GPTypically, you will enter the account that you created while performing theprerequisites for the installation. If you are installing Web Services for MicrosoftDynamics GP on a different machine than the SQL Server used to manageMicrosoft Dynamics GP data, this must be a domain user account. If you areinstalling on the same machine as the SQL Server, it can be a local machineaccount. This case is shown in the following illustration:

If the account you specified has already been added as a user for Microsoft SQL Server,be sure the case for the Domain and User Name match those of the user ID in SQL.




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

Click Next to continue.

7. Start the installation.Click Install to begin the installation process. The following additionalinstallations may occur if they have not already been performed:

• eConnect Runtime Installation

• ADAM or ADLDS instance - This component is required by the DynamicsSecurity Service. The current user is added as an ADAM or ADLDSadministrator.

You may want to add other users as ADAM or ADLDS administrators so they can perform repair or upgrade procedures for the Web Services for Microsoft Dynamics GPRefer to Appendix A, “ADAM or ADLDS Administrators,” for details about addingother users as administrators.

8. Complete the installation.After a few minutes, the installation will complete. Click Finish.

Upgrading an earlier installationIf you have a web services installation from an earlier release of Microsoft DynamicsGP, you can upgrade it to the current version. The same upgrade method is usedwhether you are upgrading to a new major version or just applying a service pack.Use the Microsoft Dynamics GP installer to update the Dynamics system andcompany databases to the new release before you update web services.

Before you start the upgrade, be sure that your current Web Services for MicrosofDynamics GP installation is working properly. Do not perform other maintenance activities,such as switching web services to a different IIS server, as part of the upgrade processPerform these other maintenance activities before starting the upgrade or after the upgradehas been successfully finished.

Among the various upgrade tasks, the web service upgrade does the following:

• Adds additional objects for the web service

• Adds additional policy objects

• Updates the Dynamics Security Console

• Adds new security objects, such as roles and tasks. The roles and tasks that havechanged, but were part of the earlier version of web services will not be updatedThe update will try to preservce the changes you have made to the securitydata.

• Re-creates the Superuser role so that it will include access to all of the webservice objects.

• Updates the BusinessObjectFile.config, to add registrations for any new eventsfor the Dynamics GP Web Service. This file is located in the Dynamics GP webservice “bin” folder, typically found in this this location:

C:\Program Files\Microsoft Dynamics\GPWebServices\WebServices\Bin

If you have manually added any event registrations to the BusinessObjectFile.config, bsure to make a copy of this file before you perform the upgrade. You may need manually re-add the additional registrations after the web service upgrade is complete.





Complete the following procedure to upgrade the web service installation.

Be aware that the Web Services for Microsoft Dynamics GP installer may reset IIS as part of the upgrade. Keep this in mind if you have other applications running on IIS.

1. Verify that the Dynamics databases have been updated.You must have used the Microsoft Dynamics GP installer to update the

databases to the new release.

2. Verify the user you are logged in as.The user you are currently logged in as must be the following:

• For Windows Server 2003, you must be in the Administrator role for thecomputer on which you are upgrading the installation.

• An ADAM or ADLDS administrator. The user who installed the earlier ver-sion of web services will be an ADAM administrator. Refer to Appendix A,“ADAM or ADLDS Administrators,” for information about adding otherusers as administrators.

This user will become a Security Administrator for the Dynamics SecurityService. This user will also be added to the Superuser role for the Dynamics GPweb service, allowing access to all web service operations.

3. Start the Web Services for Microsoft Dynamics GP installer.On Windows Server 2003, you can launch the installer by double-clickingDynamicsGPWebServices.msi . On Windows Server 2008, you must run theinstaller with elevated privileges. You can do this by running Setup.exe , whichwill prompt for administrator credentials. The Welcome page of the installerwill be displayed. Click Next to continue.

4. Review the license agreement.After reviewing the license agreement, mark the option to accept the terms andclick Next to continue.

5. Specify the location of the Microsoft Dynamics GP data.In the Server Name field, supply the name of the machine that is running SQLServer and managing the data for Microsoft Dynamics GP.

The installation program must connect to this database to complete theinstallation. You can use Windows Trusted Authentication or SQLAuthentication (supplying the Administrator login ID and password).






6. Verify the installation location.The web site on the IIS server that is being used for the web services will belisted. Also, the location where the files for the previous version of Web Servicesfor Microsoft Dynamics GP will be displayed. Click Next to continue.

7. Specify the application account.This account will be used for the following:

• Application Pool user for Dynamics GP web service• Application Pool user for Dynamics Security service• Reader of ADAM• Reader of AzMan• User for SQL Server and the databases used for Microsoft Dynamics GP

Typically, you will use the same account that you created when you installedthe previous version of web services. If you are installing Web Services forMicrosoft Dynamics GP on a different machine than the SQL Server used tomanage Microsoft Dynamics GP data, this must be a domain user account. Ifyou are installing on the same machine as the SQL Server, it can be a localmachine account. This case is shown in the following illustration:

If the account you specified has already been added as a user for Microsoft SQL Servbe sure the case for the Domain and User Name match those of the user ID in SQL.


8. Start the installation.Click Install to begin the installation process, upgrading the installed instance ofthe web services

9. Complete the installation.After a few minutes, the installation will complete. Click Finish.





Verifying the web service installation

After the web service installation is complete, you should verify that the WebServices for Microsoft Dynamics GP are operational.

Dynamics GP web serviceTo verify this web service is operational, complete the following steps while loggedin to the server:

1. Open a web browser.The web browser will be used to view the list of web service methods.

2. Verify the Dynamics GP web service.In the web browser, enter the URL for the Dynamics GP web service. This URLwill have the form:

http:// machine_name/DynamicsGPWebServices/DynamicsGPService.asmx

Replace machine_name with the name of the server onto which you installedWeb Services for Microsoft Dynamics GP.

A login window may be displayed, asking you to supply your login credentials. Use thecredentials you normally use when you log in to Windows.

If the list of web service methods is displayed, the Dynamics GP web serviceshould be operational.

Close the browser when you have finished.

Dynamics Security serviceTo verify the Dynamics Security service, complete the following steps:

1. Open the Dynamics Security Console.Choose the Dynamics Security Console from the Administrative Tools group,accessed through the Start menu. After a few moments, the Dynamics SecurityConsole will be displayed.

2. Select the application to manage.Select the Microsoft Dynamics Security node in the left pane of the console. Inthe Action menu, choose Select Applications. The Select Applications windowwill appear.





3. Choose the Dynamics GP Web Services application.In the Select Applications window, choose SecurityService in the SecurityAdmin Service drop-down list, and then mark the Dynamics GP Web Servicesapplication.

Click OK to close the window. Additional nodes will be added in the left paneof the Dynamics Security Console.

4. Select the Policy node.Expand the Microsoft Dynamics Security node, and then expand theDynamicsGPWebServices node. Select the Policy node. A list of policycategories should be displayed. If it is, the Dynamics Security Service and itsinteraction with the Dynamics GP web service are operating properly.

When you have finished, close the Dynamics Security Console.

User account summary

Several user accounts are used for a Web Services for Microsoft Dynamics GPinstallation. These user accounts are:

• The account the installer for Web Services for Microsoft Dynamics GP is run as.(Referred to as the installation account )

• The account supplied during the installation that the web services will run as.(Referred to as the application account )

• The account created during the installation that is used to access ADAM.(Referred to as the Dynamics GP ADAM account )

Select the Policy node. Alist of policy categories

should be displayed.





Installation accountThis is the account under which the installer for Web Services for MicrosoftDynamics GP is run. In addition to being an administrator on the system on whichweb services is being installed, this account is used for the following:

• Added to the Superuser role for the Dynamics GP web service• Added as a Security Administrator for the Dynamics Security service

• An ADAM administrator (Windows Server 2003) or ADLDS administrator(Windows Server 2008)

Application accountThis is the account supplied during the Web Services for Microsoft Dynamics GPinstallation. It is used for the following:

• Application Pool user for Dynamics GP web service• Application Pool user for Dynamics Security service• Reader of ADAM• Reader of AzMan• User for SQL Server and the databases used for Microsoft Dynamics GP

Dynamics GP ADAM account.This is a local machine account (named DynamicsGPAdm) created by the WebServices for Microsoft Dynamics GP installer during the installation process. It isused for the following:

• Application Pool user for Dynamics Security Admin web service• Reader of ADAM• Administrator of AzMan

What to do next

After the Web Services for Microsoft Dynamics GP have been installed and verified,consider taking the following steps:

• Set up the security for the Dynamics GP web service. Refer to Part 3, Security ,for details about security configuration.

• Learn about actions you will need to take in the day-to-day operation of theweb services. Details are found in Part 4, Running the Web Service .

• To learn about developing applications that use the Web Services for MicrosoftDynamics GP, install the Web Services for Microsoft Dynamics GP SoftwareDevelopment Kit (SDK).




Chapter 5: Management Tools InstallationThe Management Tools for Microsoft Dynamics GP Web Services consist of theMicrosoft Dynamics Security console and the Microsoft Dynamics GP Web ServiceException Management console. These tools are automatically installed on thecomputer that is running the Web Services for Microsoft Dynamics GP. TheManagement Tools Installer allows these tools to be installed on other computers.The following topics are discussed:

• Prerequisites• Installing the management tools• Required roles and permission• Accessing the management tools

Prerequisites

To use the Management Tools for Microsoft Dynamics GP Web Services, yoursystem must have the following:

• Microsoft .NET Framework 2.0• Microsoft Management Console (MMC) 3.0

The Microsoft .NET Framework 2.0 can be downloaded from the web siteupdate.microsoft.com. The MMC 3.0 is available for download fromwww.microsoft.com. Search for Knowledge Base article KB907265.

In the situation where the Web Services for Microsoft Dynamics GP have beeninstalled for a network that does not have a domain controller, you cannot use theManagement Tools for Microsoft Dynamics GP. The web services must beadministered from the server where they were installed.

Installing the management tools

Complete the following steps to install the Microsoft Dynamics GP Web ServicesManagement Tools.

1. Start the installer.The installer is named DynamicsGPWebServicesManagementTools.msi.

2. Acknowledge the welcome screen.Click Next to continue.

3. Read and acknowledge the license agreement.After reading and accepting the terms of the license agreement, click Next tocontinue.

4. Enter the URLs for the web services.These URLs allow the management tools to locate the Microsoft Dynamics GPweb service and the Microsoft Dynamics Security Administration service.

The typical URL for the Microsoft Dynamics GP web service is:

http:// machine/DynamicsGPWebServices/DynamicsGPService.asmx





The typical URL for the Microsoft Dynamics Security Administration service is:

http:// machine: port_number/DynamicsAdminService.asmx

Notice this URL contains a port number. The port value 49152 is the defaultvalue that will be used when the Microsoft Dynamics Security Administrationservice is installed. Use this value when entering the URL.

For example if the machine running the Microsoft Dynamics SecurityAdministration service was named GPWebService, the URL would be:

http://GPWebService:49152/DynamicsAdminService.asmx

If this port value doesn’t work to access the service, you will need to contactyour administrator to find what port the Microsoft Dynamics SecurityAdministration service is running on.

Press the TAB key to accept the URL values entered, and then click Next tocontinue.

5. Begin the installation.Click Install to begin installing the management tools.

6. Finish the installation.After the management tools are installed, click Finish to complete theinstallation.

Required roles and permission

Refer to Chapter 6,“Web Services Security,” for detailed information about assigning roles.

To use the Microsoft Dynamics Security console and the Microsoft Dynamics GPWeb Service Exception Management console, a user must be assigned to therequired roles and permission.

Dynamics Security consoleTo access the Microsoft Dynamics Security console, a user must be assigned to be aSecurity Administrator for the service. To access the Policy node displayed in theMicrosoft Dynamics Security console, a user must also be assigned to the PolicyAdministrator role, or to the Superuser role.

Exception Management consoleTo access the Microsoft Dynamics GP Web Service Exception Management console,the user must be assigned to the Error Viewer role for all companies.

Accessing the management tools

The Management Tools Installer creates shortcuts in the Administrative Toolsprogram group for the two consoles that it installs. Choose the item from the groupto display the corresponding console.

The Dynamics Security console and the Exception Management console have a significantamount of data to retrieve. They can take a few moments to open and display.




Part 3: SecurityThis portion of the documentation provides detailed information about managingsecurity for the Web Services for Microsoft Dynamics GP. The following items arediscussed:

• Chapter 6, “Web Services Security ,” explains how to configure and controlsecurity access for the Dynamics GP web service.

• Chapter 7, “Policy ,” describes how policy is used to control web serviceoperations.

• Chapter 8, “Authentication Methods ,” describes how to control whatauthentication method is used for the web services.




Chapter 6: Web Services SecurityBecause the Web Services for Microsoft Dynamics GP can access sensitive data, it’simportant that proper security is applied for the web service. Information aboutweb service security is divided into the following sections:

• Overview• Administering security• Tasks• Roles• Enterprise level groups• Application level groups• Role assignments• Entity ID assignments

Overview

The Microsoft Dynamics Security Service provides security features for variousMicrosoft Dynamics applications and features, such as Web Services for MicrosoftDynamics GP. The Microsoft Dynamics Security Service controls access to theoperations that can be performed by users of the Dynamics GP web service.

Security AdministratorThe Security Administrator uses the Microsoft Dynamics Security Console toconfigure which users have access to web service operations. A user must bedesignated as a Security Administrator in order to access the Microsoft DynamicsSecurity Console and configure security settings.

The user who initially installed Web Services for Microsoft Dynamics GP is automatically Security Administrator.

To designate which users will be Security Administrators for the Microsoft

Dynamics Security Service, complete the following steps:1. Select the Microsoft Dynamics Security node.

In the left pane of the Dynamics Security Console, select the MicrosoftDynamics Security node.

2. Choose to define Security Administrators.In the Action menu, choose Define Security Administrators. The SecurityAdministrators window will appear.

3. Add or remove users.Click Add to select additional users to become Security Administrators. Toremove current users, select them in the list and click Remove.

4. Close the Security Administrators window.Click OK to close the window and save your changes.

Selecting applicationsBefore you can control security settings, you must select the applications that youwant to administer security for. To select applications, complete the following steps:

1. Select the Microsoft Dynamics Security node in the left pane ofthe Dynamics Security Console.



P A R T 3 S E C U R I T Y


2. Choose to select applications to administer.In the Action menu, choose Select Applications. The Select Applicationswindow will appear.

3. Select the Security Administration Service.This is the web service that controls administration for the Microsoft DynamicsSecurity Service.

4. Mark the applications to administer security for.The available applications for the selected security administration service will be listed. For example, mark the Dynamics GP Web Services application toconfigure security settings for it.

5. Close the Select Applications window.Click OK to close the window and save your changes.

Administering security

As you configure security settings with the Dynamics Security Console, it’simportant to understand when those changes will become effective.

To improve the performance of the Microsoft Dynamics Security Service, thevarious security settings for each application are cached. This cache is refreshed bydefault every 20 minutes. When you make changes to the security settings, thechanges will not become effective until the cache is refreshed. This could be up to 20minutes from the time the changes are made.

The web services administrator can change the cache refresh interval to a lowervalue (with a minimum of 5 minutes) by editing the configuration for theapplication. For example, to change the cache timeout for the Dynamics GP webservice, you would edit the web.config file for this application, typically found atthe location:

C:\Program Files\Microsoft Dynamics\GPWebServices\WebServices\web.config

The following key would be added to the <appSettings> section of thisconfiguration file:

<add key= “AzManCacheRefreshInterval” value=”300000”/>

The interval is specified in milliseconds, so divide by 60,000 to see the time inminutes. The previous setting will set the interval to the minimum 5 minutes.




C H A P T E R 6 W E B S E R V I C E S S E C U R I T Y

Tasks

Operations are the individual actions that can be performed by the application forwhich security is being configured. For instance, the web service operations that can

be performed by the Dynamics GP web service are displayed as operations in theDynamics Security console.

Tasks provide a way to group related operations together. A task can contain thefollowing:

• Individual operations• Other tasks

Predefined tasksApplications typically have several tasks already defined for them. For instance, theDynamics GP Web Services application has the View Commissions task defined.This task contains the Query Salesperson Commissions and View SalespersonCommissions operations.

One predefined task has special importance. The View Company Information taskcontains all of the operations needed to interact with the Dynamics GP web service.This task is automatically assigned to every role that is created. It’s important thatyou don’t remove any operations from the View Company Information task. Doingso could prevent users from accessing the Dynamics GP web service.

Creating tasksYou can create additional tasks to manage security access within an application. Tocreate a new task, complete the following steps:

1. Select the Tasks node in the left pane of the Dynamics SecurityConsole.

2. Choose to create a new task.In the Action menu, choose New. The New Task window will appear.

3. Name the task.

4. Provide a task description.The description will be displayed in the Actions pane when you select the taskin the Dynamics Security Console.

5. Select the keyword for the new task (optional).The keyword indicates in what area of Microsoft Dynamics the task applies.

6. Add operations or other tasks to the new task.

Click the Add button to display the Add Task Definition window. Use thiswindow to select the individual operations and other tasks you want to includein the new task. Click OK to add the operations and tasks.





7. Save the task definition.Click OK to save the new task definition.

Modifying tasksYou can modify tasks that have already been created for an application. To modify a

task, complete the following steps:1. Select the Tasks node in the left pane of the Dynamics Security

Console.

2. Select the task you want to modify.

3. Choose to modify the task.In the Action menu, choose Properties. The properties for the task will bedisplayed. Make the necessary changes to the task and click OK to save them.

Copying tasksYou can create a new task by starting with a copy of an existing task. This is useful

when the new task has many characteristics that are the same as those of an existingtask. To copy a task, complete the following steps:


2. Select the task you want to copy.

3. Choose to copy the task.In the Action menu, choose Copy. The Copy Task window will be displayed.Make the necessary changes to the new task and click OK to save them.

Deleting tasksTo delete a task, complete the following steps:


2. Select the task you want to delete.

3. Choose to delete the task.In the Action menu, choose Delete. A dialog will be displayed, asking youwhether you want to delete the task. Click Yes to delete the task, or No to cancelthe delete operation.





Every role created will automatically include the View Company Information task. Theoperations in this task are required for users assigned to the role to use the DynamicsGP web service. Don’t delete operations from this task.

6. Save the role definition.

Click OK to save the new role definition.

Modifying rolesYou can modify roles that have already been created for an application. To modify arole, complete the following steps:

1. Select the Roles node in the left pane of the Dynamics SecurityConsole.

2. Select the role you want to modify.

3. Choose to modify the role.In the Action menu, choose Properties. The properties for the role will bedisplayed. Make the necessary changes to the role and click OK to save them.

Copying rolesYou can create a new role by starting with a copy of an existing role. This is usefulwhen the new role has many characteristics that are the same as those of an existingrole. To copy a role, complete the following steps:


2. Select the role you want to copy.

3. Choose to copy the role.In the Action menu, choose Copy. The Copy Role window will be displayed.Make the necessary changes to the new role and click OK to save them.





Deleting rolesTo delete a role, complete the following steps:


2. Select the role you want to delete.

3. Choose to delete the role.In the Action menu, choose Delete. A dialog will be displayed, asking youwhether you want to delete the role. Click Yes to delete the role, or No to cancelthe delete operation.

Enterprise level groups

Groups are used to create collections of Windows users for whom security access is being controlled. Enterprise Level groups are available to use in all of theapplications for which the Microsoft Dynamics Security Service is controllingaccess.

Enterprise level groups are used when you’re managing security for severalapplications. Since the same group can be used within multiple applications,adding or removing a user from an enterprise level group will add or remove theiraccess to multiple applications in one step.

Creating an enterprise level groupTo create a new enterprise level group, complete the following steps:

1. Select the Enterprise Level Groups node in the left pane of theDynamics Security Console.

2. Choose to create a new enterprise level group.

In the Action menu, choose New. The New Enterprise Level Group windowwill appear.

3. Name the group.

4. Provide a group description.The description will be displayed in the Actions pane when you select theenterprise level group in the Dynamics Security Console.

5. Add members to the group.Display the User Members or Group Members tabs to add individual users orother groups to the group being created.

6. Save the enterprise level group definition.Click OK to save the new enterprise level group definition.

Modifying enterprise level groupsYou can modify enterprise level groups that have already been created. To modifyan enterprise level group, complete the following steps:






2. Select the group you want to modify.

3. Choose to modify the group.In the Action menu, choose Properties. The properties for the enterprise levelgroup will be displayed. Make the necessary changes to the group and click OKto save them.

Copying enterprise level groupsYou can create a new enterprise level group by starting with a copy of an existinggroup. This is useful when the new group has many characteristics that are thesame as those of an existing enterprise level group. To copy a group, complete thefollowing steps:


2. Select the enterprise level group you want to copy.

3. Choose to copy the enterprise level group.In the Action menu, choose Copy. The Copy Enterprise Level Group windowwill be displayed. Make the necessary changes to the new group and click OKto save them.

Deleting enterprise level groupsTo delete an enterprise level group, complete the following steps:


2. Select the group you want to delete.

3. Choose to delete the group.

In the Action menu, choose Delete. A dialog will be displayed, asking youwhether you want to delete the enterprise level group. Click Yes to delete thegroup, or No to cancel the delete operation.

Application level groups

Groups are used to create collections of Windows users for whom security access is being controlled. Application Level groups are available to use only within theapplication for which they are defined. For example, any application level groupsdefined for the Dynamics GP Web Services application will be available to use onlywithin that application.

Creating an application level groupTo create a new application level group, complete the following steps:

1. Select the Application Level Groups node in the left pane of theDynamics Security Console.

2. Choose to create a new application level group.In the Action menu, choose New. The New Application Level Group windowwill appear.





3. Name the group.

4. Provide a group description.The description will be displayed in the Actions pane when you select theapplication level group in the Dynamics Security Console.

5. Add members to the group.

Display the User Members or Group Members tabs to add individual users orother groups to the group being created.

6. Save the application level group definition.Click OK to save the new application level group definition.

Modifying application level groupsYou can modify application level groups that have already been created for anapplication. To modify an application level group, complete the following steps:


2. Select the group you want to modify.

3. Choose to modify the group.In the Action menu, choose Properties. The properties for the application levelgroup will be displayed. Make the necessary changes to the group and click OKto save them.

Copying application level groupsYou can create a new application level group by starting with a copy of an existinggroup. This is useful when the new group has many characteristics that are thesame as those of an existing application level group. To copy a group, complete thefollowing steps:


2. Select the application level group you want to copy.

3. Choose to copy the application level group.In the Action menu, choose Copy. The Copy Application Level Group windowwill be displayed. Make the necessary changes to the new group and click OKto save them.

Deleting application level groupsTo delete an application level group, complete the following steps:


2. Select the group you want to delete.

3. Choose to delete the group.In the Action menu, choose Delete. A dialog will be displayed, asking youwhether you want to delete the application level group. Click Yes to delete thegroup, or No to cancel the delete operation.





Role assignments

A role assignment consists of the following:

• A role (with its associated tasks and operations)• A company or companies• A user or group for which access is being granted

When the role assignment is created, the users or groups of users will have access tothe items in the role for the specified company or companies.

Adding a role assignmentTo add a new role assignment, complete the following steps:

1. Select the Role Assignments node in the left pane of theDynamics Security Console.

2. Choose to add a new role assignment.In the Action menu, choose Add. The Add Role Assignments window willappear.

3. Select the role.In the Role drop-down list, select the role that you want to assign users orgroups to.

4. Add the users and groups.Click the Add Windows Users button to add individual windows users to therole assignment. Click the Add Groups button to add application level groupsor enterprise level groups to the role assignment.

5. Specify the company access.Indicate which company or companies for which the access applies. You can

choose All Companies, or you can choose Select Individual Companies. If youchoose individual companies, mark the appropriate companies in the list.

6. Save the new role assignment.Click OK to save the new role assignment.

Deleting a role assignmentTo delete a role assignment, complete the following steps:

1. Select the Role Assignments node in the left pane of theDynamics Security Console.

2. Select the role assignment you want to delete.

When you remove the role assignment, the users or groups will no longer haveaccess to the items specified in the role.

3. Choose to delete the role assignment.In the Action menu, choose Delete. A dialog will be displayed, asking youwhether you want to delete the role assignment. Click Yes to delete the roleassignment, or No to cancel the delete operation.





Entity ID assignments

Windows User IDs can be associated with the following objects in MicrosoftDynamics GP:

• Back Office User• Customer

• Salesperson• Sales Territory

These objects are referred to as user-assignable business objects. An entity IDassignment allows assigning a Windows User ID to one of these objects in MicrosoftDynamics GP. An entity ID assignment consists of the following:

• A Windows user ID• The type of entity in Microsoft Dynamics GP• A company or companies• The back office ID to which the Windows user ID will be associated

This assignment is used by web service applications to display data that is specific

to the user currently accessing the Dynamics GP web service. For instance, aWindows user assigned to a specifc salesperson ID could be restricted to see onlytheir own salesperson commission information.

A Windows User ID can be assigned to more than one type of entity ID in MicrosoftDynamics GP. A Windows User ID should not be assigned to more than one entityID of the same type. For example, a single Windows User ID should not be assignedto several different salesperson IDs.

Security for entity ID filteringAdditional security roles, operations, and tasks are defined for the Dynamics GPweb service to support entity ID filtering. These roles, operations, and tasks indicatewhether entity ID filtering will be applied for the current web service user.

For example, granting access to a role that contains the operation Query SalesOrders allows the user to retrieve any sales orders. Granting access to a role thatcontains the operation Query Sales Orders Based On User allows the user toretrieve only those sales orders that have an ID (such as the Salesperson ID)mapped to the current Windows User.

Roles that contain the tasks and operations that implement entity ID filtering havethe word “Self” in their name. Users assigned to these roles will be able to see onlyobjects that are associated to them based on the entity ID assignments. For example,the Salesperson - Self role provides access to customer, salesperson, and salestransaction information for the salesperson assigned to the current user.

Adding an entity ID assignmentTo add a new entity ID assignment, complete the following steps:

1. Select the Entity ID Assignments node in the left pane of theDynamics Security Console.

2. Choose to add a new entity ID assignment.In the Action menu, choose Add. The Add Entity ID Assignments window willappear.





3. Select the Windows user.Click Select Windows User to display the dialog used to select a Windows user.Specify the user for whom you are creating the entity ID assignment.

4. Select the entity type.This specifies the type of ID in Microsoft Dynamics GP to which you areassigning the Window ID. Choose one of the following:

• Back Office User• Customer• Sales Territory• Salesperson

5. Specify the company access.Indicate the company in Microsoft Dynamics GP for which the entity ID isdefined. After a few moments, the IDs of the specified type will be listed.

6. Filter the list of entity IDs (optional).The list of available entitiy IDs can be quite large for some types, such ascustomers. The total number of IDs listed is limited to 250 at one time. If moreentities are available, you must specify filter criteria to limit the number of IDsdisplayed. Type the filter text and click the Apply Filter button. For example, tolist only those entities with IDs that begin with “G”, enter that value and clickApply Filter. After a few moments, the list of IDs matching the filter criteria will

be displayed.

The filter applied uses SQL criteria syntax. The value you enter will automatically beenclosed by % wildcard characters. If you entered Erin as the filter text, the IDsmatching the criteria %Erin% will be displayed.

To remove the filte criteria, clear the text from Filter by ID and click the ApplyFilter button.

7. Select the back office entity ID.In the list of available entity IDs, select the ID to assign to the selected WindowsUser ID.

8. Save the new entity ID assignment.Click OK to save the new entity ID assignment and close the window. ClickApply to save the entity ID assignment, leaving the window open to addanother.

Deleting an entity ID assignmentTo delete an entity ID assignment, complete the following steps:

1. Select the Entity ID Assignments node in the left pane of the

Dynamics Security Console.2. Select the Entity ID assignment you want to delete.

When you remove the entity ID assignment, the Windows user will no longer be associate with the specified ID in Microsoft Dynamics GP.

3. Choose to delete the entity ID assignment.In the Action menu, choose Delete. A dialog will be displayed, asking youwhether you want to delete the entity ID assignment. Click Yes to delete theentity assignment, or No to cancel the delete operation.




Chapter 7: PolicyThe policy system for the Dynamics GP web service allows the web serviceadministrator and the application using the web service to control how businessobjects are created, updated, or deleted. The following items are discussed:

• Overview

• Editing a policy instance• Creating a new policy instance• Deleting a policy instance

OverviewEach create, update, and delete web service operation has a policy object that ispassed with the operation. This policy object specifies the set of behaviors for theoperation. Each behavior controls one characteristic for the operation beingperformed. For instance, the policy for the CreateCustomer web method has the

behavior named “Create Active Behavior”. This behavior controls whether thecustomer being created is set to the active or inactive state.

Behaviors are classified as internal or external. An internal behavior is one that can bespecified only through the Dynamics Security Console. An external behavior is onethat can be specified by the application that is calling the web method and passingin the policy object.

Policy administratorThe policy administrator uses the Microsoft Dynamics Security Console toconfigure the various policies for the Dynamics GP web service. To manage policeswith the Microsoft Dynamics Security Console, a user must be designated as aSecurity Administrator. The user must also be assigned to the Policy Administratorrole. When you assign a user to the Policy Administrator role, the user will be ableto manage policies for all companies. Refer to Role assignments on page 46 for detailsabout assigning roles.

The user who initially installed Web Services for Microsoft Dynamics GP is automatically Security Administrator. That user is also assigned to the Superuser role, which has access tothe Manage Policies task.

Policy instancesEach company has a set of default policies that are available. There is one defaultpolicy for each web service operation that requires a policy. Within a company,additional versions of the policy (with different behavior settings) can be created foreach role defined in the Dynamics Security Service. Each of these is called a policyinstance. When a web service application retrieves a policy to use, the Dynamics GPweb service applies logic to ensure the appropriate policy instance is returned.

Applications that call the Dynamics GP web service can specify the role to use forthe web service call. If a policy instance exists for that role, it will be used.Developers creating applications that use the Dynamics GP web service areencouraged to not explicitly set the role. Instead, they should let the Dynamics GPweb service find what role the user of the application is assigned to, so the correctpolicy instance can be used.

Be aware that the Dynamics GP web service will set the role for a user only if theuser is assigned to a single role. If the user is assigned to more than one role, therole won’t be set, and the default policy instance will be used. For this reason, it’s agood idea to limit the number of roles you assign a user to.





Editing a policy instance

When you edit a policy instance, you are configuring the set of behaviors for thatpolicy. To do this, complete the following steps in the Dynamics Security Console:

1. Select and expand the Policy node in the left pane of theDynamics Security Console.

2. Locate the policy that you want to edit.Select the policy in the expanded tree view in the left pane of the DynamicsSecurity Console. It may take a few moments for the information about thepolicy to load.

3. Select the company for which the policy instance applies.

4. Select the role for the policy instance you want to edit.Choose Default to edit the policy instance that is used when no role isassociated with the user.

5. Edit the policy instance properties.Click the Properties link in the Actions pane to display the Policy InstanceProperties window. Within this window, you will edit the individual behaviorsthat are included in the policy. This window is shown in the followingillustration:

6. Edit the individual behaviors.Select a behavior in the list. The details of the behavior will be displayed. Usethe Behavior Option drop-down list to specify the behavior option that youwant to use.




C H A P T E R 7 P O L I C Y

Some behavior options allow you to supply a specific value that will be used,such as a transaction date. If you select one of these behavior options, the SetParameters button will become active. Click this button to open the SetParameters window. In the Parameter Value column, supply the value to use forthe parameter and click OK.

7. Save the changes.When you have finished making changes to the behaviors, click OK to save thepolicy instance.

Creating a new policy instance

To create a new policy instance, complete the following steps in the DynamicsSecurity Console:


2. Locate the policy for which you want to create a new instance.Select the policy in the expanded tree view in the left pane of the Dynamics

Security Console. It may take a few moments for the information about thepolicy to load.

3. Choose to create a new policy instance.In the Action menu, choose New. The New Policy Instance window will appear.

4. Select the company for which the new policy instance applies.

5. Select the role for which the new policy instance applies.

6. Edit the individual behaviors.Select a behavior in the list. The details of the behavior will be displayed. Usethe Behavior Option drop-down list to specify the behavior option that you

want to use. Refer to the previous procedure, Editing a policy instance on page 50,for details about editing the new policy instance.

7. Save the changes.When you have finished making changes to the behaviors, click OK to save thenew policy instance.





Deleting a policy instance

To delete a policy instance, complete the following steps in the Dynamics SecurityConsole:


2. Locate the policy for which you want to delete a policy instance.Select the policy in the expanded tree view in the left pane of the DynamicsSecurity Console. It may take a few moments for the information about thepolicy to load.

3. Select the company for which the policy instance applies.

4. Select the role for the policy instance you want to delete.

5. Delete the policy instance.Click the Delete link in the Actions pane. A dialog will be displayed, asking youwhether you want to delete the policy instance. Click Yes to delete the policyinstance, or No to cancel the delete operation.




Chapter 8: Authentication MethodsAs the administrator of the Web Services for Microsoft Dynamics GP, we encourageyou to take the steps to fully secure them. This includes specifying theauthentication mode used when accessing the web services. The following items arediscussed:

• Supported authentication methods• Enabling Kerberos for the web services• Registering the SPN

Supported authentication methods

Two methods of authentication are supported when connecting to the Web Servicesfor Microsoft Dynamics GP:

NTLM This the challenge/response authentication protocol used in Windows NT4.0 and earlier.

Kerberos This is a more secure authentication protocol used in Windows 2000and later.

When you installed Web Services for Microsoft Dynamics GP, you specified a useraccount under which the web services were to be run. The account type you chosespecified the default authentication used:

• If the account was a domain account, the virtual directories for the web servicesinstalled were configured to use NTLM authentication.

• If the account was a local machine account, the virtual directories for the webservices installed were configured to use Kerberos authentication.

Enabling Kerberos for the web servicesIf you have chosen to use the more secure Kerberos authentication method for yournetwork, you will likely want to run the Web Services for Microsoft Dynamics GPwith Kerberos. To do this, you must be sure the virtual directories for each of theweb services is set to use Kerberos authentication.

Enabling KerberosTo enable Kerberos for the web services, complete the following procedure:

1. Open a command prompt.In the Start menu, choose Run. Type cmd and click OK.

2. Set the working directory.The the working directory to the following location:

C:\inetpub\adminscripts

The configuration script you need to run is located here.





3. Find the virtual server ID numbers.Open Internet Information Services Manager. View the web site on which theweb services are installed. the virtual server ID number is listed in the“Identifier” column.

4. Enable Kerberos authentication for the Dynamics GP web service.To enable Kerberos authentication for the Dynamics GP web service, type thefollowing command at the command prompt, replacing ## with the virtualserver ID you found in the previous step:

cscript adsutil.vbs set w3svc/##/ROOT/DynamicsGPWebServices/

NTAuthenticationProviders "Negotiate,NTLM"

5. Enable Kerberos authentication for the Dynamics Security webservice.To enable Kerberos authentication for the Dynamics Security web service, typethe following command at the command prompt, replacing ## wih the virtualserver ID you found earlier:

cscript adsutil.vbs set w3svc/##/ROOT/DynamicsSecurityService/

NTAuthenticationProviders "Negotiate,NTLM"

6. Reset IIS.For the changes to take effect, you must reset IIS. Do this by typing thefollowing command at the command prompt:

iisreset

7. Close the command prompt window.

Disabling KerberosTo disable Kerberos for the web services and return to NTLM authentication,

complete the previous procedure, but specify the “NTLM” authentication method.For example, the following command sets the Dynamics GP web service to useNTLM authentication:

cscript adsutil.vbs set w3svc/##/ROOT/DynamicsGPWebServices/

NTAuthenticationProviders "NTLM"

Be sure to replace the ## with the virtual server ID.




Part 4: Running the Web ServiceThis portion of the documentation provides information about the day-to-dayoperation of the Web Services for Microsoft Dynamics GP. The following items arediscussed:

• Chapter 9, “Troubleshooting ,” discusses how to troubleshoot issues that occurwith the web services and the applications that use them.

• Chapter 10, “Logging and Auditing ,” describes how to log the events that occurfor the web services.

• Chapter 11, “Making Backups ,” explains how to include the web services in the backup strategy for the Microsoft Dynamics GP installation.

• Chapter 12, “Adding Additional Companies ,” describes how to add webservice support to additional companies added to Microsoft Dynamics GP.

• Chapter 13, “Repairing Web Services ,” explains how to perform repairoperations on a Web Services for Microsoft Dynamics GP installation.




Chapter 9: TroubleshootingIf you encounter problems with the Web Services for Microsoft Dynamics GP, thefollowing sections may be helpful. They describe some of the most commonsituations that can occur while running the web services. The following items arediscussed:

• Exceptions• Web service does not respond• Security• Policy• Timeout issues

Exceptions

The following are common exceptions that may occur when applications areworking with the Dynamics GP web service:

An unhandled system exception occursA system exception occurs when an unexpected event prevents the normalcompletion of a web method. A system exception returns the following SOAPmessage:

"The application encountered an unhandled system exception. Contact your systemadministrator for details."

The Dynamics GP Web Service Exceptions console displays the details for eachsystem exception. If you are logged into the server on which Web Services forMicrosoft Dynamics GP is installed, or you have installed the Management Tools forMicrosoft Dynamics GP Web Services, you can access the Exceptions console. It isfound in the Administrative Tools group accessed through the Start menu. Theadditional information the console provides may help identify the source of thesystem exception.

Another source of exception information is the web server’s system logs. Use thesystem event viewer to open and review the system logs. Relevant errors, warningsand informational updates for the Dynamics GP web service may be found in theApplication log.

Insufficient authorization to perform this actionWhen attempting to use the web service, an exception may return the message:

"Insufficient authorization to perform this action."

This exception indicates the current user does not have sufficient securityauthorization to perform the requested operation. Logging on as a user with thenecessary security authorization should resolve the exception. Another option is toassign the current user to a role that includes the required security authorization.

This error may also occur when an application is using the “working on behalf ofanother user” option. This option allows the user and role performing the operationto be different from the logged-on user. The user that is running the application maynot be assigned to the “Work On Behalf Of” task, or the user the application isworking on behalf of may not have security access to the operations the applicationis performing. Use the Security console to view the role or roles assigned to the user.



P A R T 4 R U N N I N G T H E W E B S E R V I C E


Entity ID filtering is another possible source of this error. If the application isrequesting filtered results, users can receive this error if they don’t have access tothe restricted operation used for the entity ID filtering. They may also receive thiserror if the entity ID assignment that maps a Windows User ID to a back officeobject ID cannot be found.

Web service does not respond

The following issues can cause the web service to stop responding:

ExtensionsApplications that access the Dynamics GP web service may have extensions thatyou needed to install. These web service extensions require changes to theBusinessObjectsFile.config (in the Dynamics GP web service installation) to registerthe extension for a web service event. If the edit creates an error in the contents ofthe configuration file, the web service may no longer respond.

Always make a backup copy of the BusinessObjectsFile.config prior to editing thefile. Store the copy to a safe location. Use the backup copy to restore the web serviceif problems occur.

If changes to the BusinessObjectsFile.config prevent a web method fromresponding, open the Exception Management Console to identify the source of theerror. Edit the BusinessObjectsFile.config to correct the specified error. RestartInternet Information Services (IIS) to ensure the changed BusinessObjectsFile.configis used.

Web.config file changesChanges made to the web service web.config configuration file can cause the webservice to stop responding. If an error occurs while editing the web.config file theweb service will become unavailable.

Always make a backup copy of the web.config prior to editing the file. Store thecopy to a safe location. Use the backup copy to restore the web service if problemsoccur.

To restore the web service, review changes to the web.config file for missing orincomplete information.

Security

The following is a list of issues associated with the Dynamics SecurityAdministration service:

A security authorization change is not usedA change occurs to a user’s security authorization to add or restrict access to a webservice operation. Testing by that user reveals the ability to perform the specifiedoperation remains unchanged.

To optimize the responsiveness of web services, a memory cache stores the webservice security settings. The security service reloads the cache at 20 minuteintervals. Changes to security authorization will not take effect until they are loadedinto the security cache.




C H A P T E R 9 T R O U B L E S H O O T I N G

If testing of a new security authorization change does not immediately show theexpected result, re-test the operation after 20 minutes. The delay allows the securityservice to update its security cache with your change. A reset of InternetInformation Services (IIS) can force an immediate reload of the security cache. AnIIS reset should be performed only after careful consideration of the impact it willhave on current web service users.

The security service is not workingThe Dynamics Security Administration service uses two system logs to record errorand warning messages. The Dynamics and ADAM (DynamicsSecurityService) logscontain error and warning messages associated with the Dynamics SecurityAdministration service. If the security service is not running or is producing errormessages, use the system event viewer to find detailed errors or warnings messagesthat specify the source of the problem.

Policy

The following is an issue that occurs when using policies with the Dynamics GPweb service:

The expected policy is not usedVarious web service operations can use a policy to control the characteristics of anoperation. The user role determines the specific policy instance used by theoperation. If an operation does not use the expected policy, view the user’s roleassignments in the Dynamics Security console. A user that has more than one rolewill always use the default policy for the operation. To ensure a specific policy isused with an operation, assign the user to a single role.

Timeout issues

When a web service application processes large numbers of documents ordocuments that contain large amounts of data, it may encounter timeout errors. Thetimeout behavior of the web service is controlled in several areas.

You may need to restart IIS for these changes to take effect.

Web site propertiesThe properties of the web site used for the Dynamics GP Web Services are used toconfigure some of the timeout behaviors. To set these properties, use the InternetInformation Services (IIS) Manager.

Connection Time-out This property specifies how long idle connections areheld open before IIS allows them to drop. The default is 120 seconds. Whentroubleshooting, set this to a larger value, or to 0 to indicate that connections arenever dropped.

For Windows Server 2003, open the Internet Information Services Manager. Expandthe Web Sites list. Right-click the web site on which the Dynamics GP Web Service isinstalled, and then choose Properties. In the Web Site tab, locate the Connectionsgroup. Set the value of the Connection timeout. Click OK to save the change.

For Windows Server 2008, open the Internet Information Services Manager. Expandthe Sites list. Right-click the web site on which the Dynamics GP Web Service isinstalled, and then point to Manage Web Site and choose Advanced Settings.Expand the Connection Limits group. Set the value of the Connection Time-outproperty. Click OK to save the change.





TransactionTimeoutSeconds This property specifies how long an ASP.NETtransaction is allowed to run. The default is 60 seconds. When troubleshooting, setthis property to a larger value such as 600 seconds.

For Windows Server 2003, open the Internet Information Services Manager. Expandthe Web Sites list. Expand the node for the web site on which web services areinstalled. Right-click the DynamicsGPWebServices node, and then choose

Properties. Display the ASP.NET tab. Click Edit Configuration. In the Applicationsettings list, locate the TransactionTimeoutSeconds property. Set this property to thenew timeout value. Click OK to save the change.

For Windows Server 2008, open the Internet Information Services Manager. Expandthe Sites list. Expand the node for the web site on which web services are installed.Select the DynamicsGPWebServices node. Double-click the Application Settingsicon to display the application properties. Locate the TransactionTimeoutSecondsproperty. Set this property to the new timeout value.

Web configuration fileYou can add settings to the web.config file for the Dynamics GP Web Service tocontrol timeout behavior. This file is typically found in this location:


Edit the file with a text editor and add the following line immediately before the<webServices> node:

<httpRuntime maxRequestLength="16384" executionTimeout="300000" />

eConnectThe Web Services for Microsoft Dynamics GP use eConnect to access MicrosoftDynamics GP data. If Web Services for Microsoft Dynamics GP is not installed onthe same system as the SQL Server used to manage Microsoft Dynamics GP data,

you may experience timeout issues with the Distributed Transaction Coordinator(DTC). Refer to the troubleshooting information in the eConnect Installation andAdministration Guide for information about configuring timeout values for theDTC.

ApplicationApplications that access the Dynamics GP Web Service can control the timeoutlength for the web service requests they make. Refer to the information aboutcreating web service instances in the Web Service Programmer’s Guide for detailsabout setting timeout values for applications that access web services.




Chapter 10: Logging and AuditingWhen adminstering Web Services for Microsoft Dynamics GP, It can also be helpfulto log actions performed by the web services. Information about logging andauditing is divided into the following sections:

• Dynamics GP web service logging• Dynamics Security Admin web service logging

Dynamics GP web service logging

The Dynamics GP web service can log the security response for actions users areattempting to perform. For instance, the log could be used to show a user who wastrying to access information for which they were not authorized.

Types of eventsThe Dynamics GP web service can log the following events:

Success These are requests to perform operations in Dynamics GP web service

that were allowed by the current security settings. It’s most useful to log theseevents when you’re trying to assess the level of activity for the Dynamics GP webservice.

Fail These are requests to perform operations in the Dynamics GP web service thatwere denied by the current security settings. It’s most useful to log these eventswhen your trying to track unauthorized activity for the Dynamics GP web service.

Configuring loggingTo enable logging, you must adjust some settings in the web.config file for theDynamics GP web service. This file is typically found at this location:


Using a text editor, open the web.config file for the Dynamics GP web service. In the<appSettings> section of the file, you will see the keys that control logging.

Turning logging on or offTo turn on logging, set the following key to true:

<add key ="SecurityRuntimeAuditingIsActive" value="true"/>

Events to logTo specify which types of events to log, set the following key:

<add key ="SecurityRuntimeAuditLogType" value="SuccessFail"/>

The following table shows the possible values for this key:

Value Description

Success Log only successful access attempts.

Fail Log only failed access attempts.

SuccessFail Log both successful and failed access attempts.

Log locationTo specify the location of the log, set the following key:

<add key ="SecurityRuntimeAuditLogFolder" value="C:\Program Files\MicrosoftDynamics\GPWebServices\LogFiles"/>

The user that the Dynamics GP web service application pool is being run as must have writeaccess to the location that you specify.

Example logThe following shows a portion of a security audit log that was logging bothsuccessful and failed access attempts.





<log action='CheckAccess' operation='View Customers' member='HORIZON\kberg' result='Success'

datetime='2006-04-21 16:45:55Z'>

<context user='HORIZON\kberg' type='Scope'>

<application name='Dynamics GP Web Services' key='25cc1a21-2cc4-4b13-a1c8-eea186fb688a' />

<scope name='TWO' key='-1' />

</context>

</log>

<log action='CheckAccess' operation='View Vendors' member='HORIZON\mallen' result='Fail'

datetime='2006-04-21 16:48:28Z'>

<context user='HORIZON\mallen' type='Scope'>


<scope name='TWO' key='-1' />

</context>

</log>



Dynamics Security Admin web service logging

The Dynamics Security Admin web service can log the security configurationchanges that were made to the web service installation.

Configuring loggingBy default, the logging for te Dynamics Security Admin web service is enabled. Toconfigure the logging, you must adjust some settings in the web.config file for theDynamics Security Admin web service. This file is typically found at this location:

C:\Program Files\Common Files\Microsoft Shared\Microsoft Dynamics\SecurityAdmin Service\WebServices\web.config

Using a text editor, open the web.config file for the Dynamics Security Admin webservice. In the <appSettings> section of the file, you will see the keys that controllogging.

Turning logging on or offTo turn on logging, set the following key to true:

<add key="SecuritySetupAuditingIsActive" value="true" />




C H A P T E R 1 0 L O G G I N G A N D A U D I T I N G

Log locationTo specify the location of the log, set the following key:

<add key="SecuritySetupAuditLogFile" value="C:\Program Files\Common Files\Microsoft Shared\Microsoft Dynamics\Security Admin Service\Logfiles\SecuritySetupAudit.log" />

Example logThe following shows a portion of a security setup audit log that shows a securitychange that was made to assign a user to a role.

<log action='Create' type='RoleAssignment' name='Sales Representative' datetime='2006-05-01

18:22:33Z'>

<context user='HORIZON\kberg' type='Application'>


</context>

<values>

<fieldValues key='aaeb72e0-77f9-4925-ab9a-73012417fb37' />

<members>

<member value='HORIZON\mallen' />

</members>

</values>

</log>





Web service installation

The various web services installed with Web Services for Microsoft Dynamics GPcan be included in a system-wide backup for the server. You might also want tocreate backups for the configuration files used for the web services. The followingtable lists the files you might want to include:

File Typical location Descriptionweb.config C:\Program Files\Microsoft

Dynamics\GPWebServices\ WebServices

This configuration filecontains configurationinformation for theDynamics GP web service.

BusinessObjectsFile.config C:\Program Files\MicrosoftDynamics\GPWebServices\ WebServices\Bin

This file contains the eventsthat are registered for theDynamics GP web service,including those added forthird-party extensions to theweb service.

web.config C:\Program Files\CommonFiles\Microsoft Shared\MicrosoftDynamics\Security Admin Service\ Web Services

This configuration file for theDynamics SecurityAdministration web serviceincludes the list of users whoare Security Administrators.

web.config C:\Program Files\CommonFiles\Microsoft Shared\MicrosoftDynamics\SecurityService\WebServices

This configuration file for theDynamics Security webservice includes setupinformation for DynamicsSecurity.




Chapter 12: Adding Additional CompaniesIf you add a new company to Microsoft Dynamics GP after Web Services forMicrosoft Dynamics GP has been installed, you must perform the followingprocedure for the new company to be accessible through the Dynamics GP webservice.

1. Modify the Web Services for Microsoft Dynamics GP installation.For Windows Server 2003, go to Add or Remove Programs. For WindowsServer 2008, go to Programs and Features. Choose Web Services for MicrosoftDynamics GP, and then click Change. The program maintenance options will bedisplayed.

2. Install an additional company.Click Install Additional Company.

3. Specify the database and SQL login information.Specify the SQL Server that is managing data for the Dynamics GP installation.The installation program must connect to this database to complete theinstallation for the new company. You can use Windows Trusted Authenticationor SQL Authentication (supplying the Administrator login ID and password).Click Next to continue.

4. Start the installation.Click Install to begin installing web services for the new company.

5. Finish the installation.Click Finish to complete the installation.




Chapter 13: Repairing Web ServicesIf the Web Services for Microsoft Dynamics GP installation becomes damaged, therepair operations available may help resolve the issues. Information about repairingthe web services is divided into the following sections:

• Repair options• Repair procedure

Repair options

The basic repair routine for Web Services for Microsoft Dynamics GP will reinstallthe files needed, re-create basic configuration information, and repair any registrysettings. Essentially, the installation will be in the same state it was immediatelyafter it was initially installed.

When performing a repair operation, two additional options are available:

• You can re-create the items used for exception management. Doing so will

delete any previous exception information that was logged by the Dynamics GPweb service.

• You can choose to reload default security items, such as roles and tasks.

If you choose this repair option, all of your existing security settings will be lost. Usthis option only if you are certain you want to rebuild security data.

Repair procedure

To repair the Web Services for Microsoft Dynamics GP installation, complete thefollowing steps:

1. Modify the Web Services for Microsoft Dynamics GP installation.For Windows Server 2003, go to Add or Remove Programs. For WindowsServer 2008, go to Programs and Features. Choose Web Services for MicrosoftDynamics GP, and then click Change. The program maintenance options will bedisplayed.

2. Repair the installation.Click Repair.





3. Choose the repair options.If you want to re-create or re-load any of the exception management or securitydata, mark the corresponding options. Click Next to continue.

4. Specify the location of the Microsoft Dynamics GP data.In the Server Name field, supply the name of the machine that is running SQLServer and managing the data for Microsoft Dynamics GP.

The installation program must connect to this database to complete the repairoperation. You can use Windows Trusted Authentication or SQL Authentication(supplying the Administrator login ID and password).


5. Specify the application account.Typically, you will enter the account that you created while performing theinitial installation of Web Services for Microsoft Dynamics GP. If the installationof Web Services for Microsoft Dynamics GP is on a different machine than theSQL Server used to manage Microsoft Dynamics GP data, this must be adomain user account. If you are repairing an installation on the same machineas the SQL Server, it can be a local machine account. This case is shown in thefollowing illustration:

If the account you specified has already been added as a user for Microsoft SQL Server,be sure the case for the Domain and User Name match those of the user ID in SQL.





C H A P T E R 1 3 R E P A I R I N G W E B S E R V I C E S

6. Start the repair process.Click Repair to start the repair process.

The process can be quite lengthy, especially if you have several companies in you Microsoft Dynamics GP installation.

7. Complete the repair process.

Click Finish to complete the repair process.




AppendixThe following appendix is included for this documentation:

• Appendix A, “ADAM or ADLDS Administrators,” describes the procedure ofadding additional users to be administrators for ADAM.




Appendix A: ADAM or ADLDS AdministratorsBy default, the user who installed ADAM (Windows Server 2003) or ActiveDirectory Lightweight Directory Services (Windows Server 2008) will be an ADAMor ADLDS administrator. You may want to add additional users to beadministrators so that several different users could perform an install, repair, orupgrade of Web Services for Microsoft Dynamics GP. To add an administrator,complete the following procedure:

1. Verify the current login.You must be an ADAM or ADLDS administrator to add other users asadministrators.

2. Launch ADAM ADSI Edit or ADSI Edit.For Windows Server 2003, this is in the ADAM program group, and is typicallyfound in All Programs >> ADAM. For Windows Server 2008, this is inAdministrative Tools. The editing window will be displayed.

3. Create a connection.In the Action menu, choose Connect to. The Connection Settings window will

be displayed.

4. Specify the connection settings.You can supply a name for the connection or use the default name. Specify theserver name onto which ADAM or ADLDS was installed. If the Web Servicesfor Microsoft Dynamics GP installer has installed ADAM or the ADLDSinstance, it will use the default port 389. If you’ve used a different port, specifythat port value. Choose Configuration as the well-known naming context.



A P P E N D I X A A D A M O R A D L D S A D M I N I S T R A T O R S


The following illustration shows the connection settings for Windows Server2003:

The following illustration shows the connection settings for Windows Server2008:

Click OK to create the connection.

5. Locate the roles for the ADAM installation.The details of the ADAM installation will appear in the tree view on the left sideof the window. Expand the tree and select the CN=Roles node.




A P P E N D I X A A D A M O R A D L D S A D M I N I S T R A T O R S

6. Display the properties for the Administrators role.In the list of roles, select Administrators. Choose Properties from the Actionmenu to display the properties for the Administrators role.

7. Select and edit the “member” attribute.In the list of attributes for the Administrators role, locate and select “member”.Click Edit. The Multi-valued Distinguished Name With Security PrincipalEditor window will be displayed.

8. Add the user.Click Add Windows Account to specify the user to add as an administrator.Click OK to save your changes.

9. Close the properties window.Click OK to close the Administrator role properties window.

10. Close the ADSI Editor.




IndexAaccounts

application account 32Dynamics GP ADAM account 32installation account 32used for Web Services for Microsoft

Dynamics GP 31Active Directory Lightweight Directory

Servicessee also ADLDSrole for Windows Server 2008 17

ADAMadding administrators 77 backing up for web services 67defined 81installation 27restoring from backup 67

Adding Additional Companies, chapter69

additional companies, adding for webservices 69

ADLDSadding administrators 77defined 81

administratorsfor ADAM 77for ADLDS 77

application account, for web servicesinstallation 32

application level groupscopying 45creating 44deleting 45described 44modifying 45

Application Server, role for WindowsServer 2008 20

applicationsdeveloping for web services 2selecting for Dynamics Security

Service 37ASP .NET, required for web services 15authentication methods

chapter 53- 55for web services 53Kerberos 53NTLM 53verifying method used 55

Authorization Manager, defined 81AzMan , see Authorization Manager

B backups, making for web services 67 behavior options, parameters for 51 behaviors

described 11, 49editing 50types 49

benefits, of web services 7BusinessObjectFile.config

creating a copy of 27location 27upgrading 27

Ccache, for Dynamics Security Service 38

companies, adding web services support69

configurations, for web services 9conventions, in documentation 2

DDistributed Transaction Coordinator , see

DTCdocumentation, symbols and conventions

2DTC

configuring for Windows Server 200319

configuring for Windows Server 2008

21described 18enabling for Windows Server 2003 18enabling for Windows Server 2008 20

Dynamics GP ADAM account, for webservices installation 32

Dynamics GP web servicesee also web servicesadding additional companies 69architecture 9capabilities 8configurations 9installation 25not responding 60

overview 7policy 49prerequisites for installing 15security overview 37troubleshooting 59URL for accessing 30verifying installation 30

Dynamics GP Web Services Exceptionsconsole

described 11, 59illustration 11

Dynamics Security consoledescribed 37illustration 10

Dynamics Security Serviceadministering 38application level groups 44cache 38defined 81described 10enterprise level groups 43entity ID assignments 47overview 37port used for 34role assignments 46

Dynamics Security Service ( continued)roles 41Security Administrator 37selecting applications 37tasks 39troubleshooting 60

EeConnect

defined 81described 9installation 27

encrypting data, using SSL 17enterprise level groups

copying 44creating 43deleting 44described 43modifying 43

Entity Id Assignment Administrator role,described 41

entity ID assignmentsadding 47defined 81deleting 48described 47

entity ID filteringoperations for 47roles for 47security settings for 47tasks for 47

Error Viewer roleassigning for all companies 34described 41

errors, resolving for web service 59exceptions

described 11list of 59unhandled system exceptions 59

extensions to web service, troubleshooting60

external behaviors, described 11

Ffailed access events, logging 63

Ggroups

application level groups 44enterprise level groups 43

IIIS

installing for Small Business Server15

installing for Windows Server 2003 15installing for Windows Server 2008 16required for web services 15

installationaccount for web services installation

32part 14- 34



I N D E X


installation ( continued)procedure for web services 25upgrading web services 27

insufficient authorization errors,troubleshooting 59

internal behaviors, described 11ISO currency codes

adding to Microsoft Dynamics GP 23list of 23required for web services 23

KKerberos authentication

described 53disabling 54enabling 53registering the SPN 55

Llight bulb symbol 2logging

configuring

Dynamics GP web service 63Dynamics Security Admin webservice 64

Dynamics GP web service access 63Dynamics Security Admin web

service 64example log 64, 65

Logging and Auditing, chapter 63- 65

MMaking Backups, chapter 67- 68management tools

accessing 34installing 33

prerequisites 33requires roles and permission 34URLs for 33

Management Tools Installation, chapter33-34

margin notes 2Microsoft Dynamics GP, version required

for web services 23Microsoft Dynamics Security Service , see

Dynamics Security ServiceMicrosoft Management Console

described 10, 22installing 22

MMC, seeMicrosoft Management Console

N.NET Framework, required for web

services 15NTLM authentication, described 53

Ooperating system, required for web

services 15operations, for entity ID filtering 47

Pparameters, for behavior options 51policy

behaviors 49chapter 49- 52described 11, 49overview 49troubleshooting 61upgrading 27

policy administratorassigning 49described 49

Policy Administrator role 41policy instances

creating 51deleting 52described 49editing 50

port, for Microsoft Dynamics SecurityAdministration service 34

predefinedroles 41tasks 39

prerequisites.NET Framework 15ASP .NET 15chapter 15- 24DTC 18for web services 15IIS 15ISO currency code 23Microsoft Dynamics GP 23MMC 22server operating system 15user account for installation 22

WMI service 17product support, for Microsoft DynamicsGP web services 3

Rrefresh interval, for Dynamics Security

Service 38repair options, for web services 71repairing web services

chapter 71- 73described 71procedure 71

role assignmentsadding 46

deleting 46described 46role services, for Windows Server 2008 24roles

copying 42creating 41deleting 43described 41for entity ID filtering 47modifying 42predefined roles 41special predefined roles 41

roles ( continued)upgrading 27

roles for Windows Server 2008Active Directory Lightweight

Directory Services 17Application Server 20summary 24Web Server (IIS) 16

Running the Web Service, part 58- 73

SSDK, for Web Services for Microsoft

Dynamics GP 2secure sockets layer, using with web

services 17Security, part 36- 55Security Administrator

described 37designating users for 37for Microsoft Dynamics Security 34

security service , see Dynamics SecurityService

Service Principal Name , seeSPNsite, used for web services 26SOAP

defined 81described 7

SPN, registering 55SQL tables, backing up for web services 67SSL, using with web services 17successful access events, logging 63Superuser role

described 41upgrading 27

support, for Microsoft Dynamics GP webservices 3

symbols in documentation 2

Ttasks

copying 40creating 39deleting 40described 39for entity ID filtering 47modifying 40predefined tasks 39upgrading 27

technical support, for Microsoft DynamicsGP web services 3

timeout issues, troubleshooting 61troubleshooting, chapter 59- 62

Uunhandled system exceptions 59upgrade

actions performed by 27procedure for web services 27

URLfor Dynamics GP web service 30for management tools 33

user accounts , seeaccounts



I N D E X

user-assignable business objects, defined81

Vvalidation errors, resolving for web

service 59verifying web service installation 30View Company Information, task 39

Wwarning symbol 2web reference, defined 81Web Server (IIS), role for Windows Server

2008 16Web Service Architecture, chapter 9- 11Web Service Basics, part 6- 11web service user account, for Dynamics

GP web services 22web services

see also Dynamics GP web servicearchitecture 9authentication modes 53

backups for 67 benefits 7configurations 9defined 81described 7developing applications for 2events to be logged 63files to include in backup 68logging events 63logging security changes 64management tools 33overview 7repairing 71security for 10

support 3troubleshooting 59

Web Services Installation, chapter 25- 32Web Services Security, chapter 37- 48web site, used for web services 26Windows Management Instrumentation

service 17WMI service 17WSDL, defined 81

Microsoft GP 10(WSInstallAdminGuide)

Documents

Transcript of Microsoft GP 10(WSInstallAdminGuide)