Microsoft Dynamics GP

Web Service Programmers 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 the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation. Notwithstanding the foregoing, the licensee of the software with which this document was provided may make a reasonable number of copies of this document solely for internal use.

Trademarks

Microsoft, Microsoft Dynamics, Visual Basic, Visual Studio, Windows, and Windows Server are either registered trademarks or trademarks of Microsoft Corporation or its affiliates in the United States and/or other countries. The names of actual companies and products mentioned herein may be trademarks or registered marks - in the United States and/or other countries - of their respective owners. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred.

Intellectual property

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property. Microsoft Corporation disclaims any warranty regarding the sample code contained in this documentation, including the warranties of merchantability and fitness for a particular purpose. The content of this document is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Microsoft Corporation. Microsoft Corporation assumes no responsibility or liability for any errors or inaccuracies that may appear in this manual. Neither Microsoft Corporation nor anyone else who has been involved in the creation, production or delivery of this documentation shall be liable for any indirect, incidental, special, exemplary or consequential damages, including but not limited to any loss of anticipated profit or benefits, resulting from the use of this documentation or sample code. Use of this product is covered by a license agreement provided with the software product. If you have any questions, please call the Microsoft Dynamics GP Customer Assistance Department at 800-456-0025 (in the U.S. or Canada) or +1-701-281-6500.

Warranty disclaimer

Limitation of liability

License agreement

Publication date

September 2008 - Last updated September 9. 2008

Contents
Introduction ................................................................................................................................................. 2
Whats in this manual...................................................................................................................................2 Whats new in this release? .........................................................................................................................2 Prerequisites...................................................................................................................................................3 Symbols and conventions ............................................................................................................................3 Product support ............................................................................................................................................4

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

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

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

Web service foundation................................................................................................................................9 Configurations...............................................................................................................................................9 Security for web services ...........................................................................................................................10 Policy for web services............................................................................................................................... 11 Exception logging ....................................................................................................................................... 11

Part 2: Getting Started ............................................................................................................. 14

Chapter 3: Connecting to the Web Service ............................................................... 15
Web service URL .........................................................................................................................................15 Creating a web reference............................................................................................................................16 Web service namespace..............................................................................................................................18 Creating a web service instance................................................................................................................18

Chapter 4: Web Service Object Model ........................................................................... 19

Object categories .........................................................................................................................................19 Inheritance ...................................................................................................................................................20 Learning the object model .........................................................................................................................21 Dynamics GP Web Service Reference ......................................................................................................21

Chapter 5: Web Methods ............................................................................................................ 23

Web method categories ..............................................................................................................................23 Framework methods ..................................................................................................................................24

Chapter 6: Data types.................................................................................................................... 25

Standard data types ....................................................................................................................................25 Enumerations ..............................................................................................................................................26 Account numbers........................................................................................................................................26 Choice types.................................................................................................................................................27

WEB

SERVICE

PROGRAMMERS

GUIDE

C O N T E N T S

Chapter 7: Context ........................................................................................................................... 29

Organization key.........................................................................................................................................29 Culture..........................................................................................................................................................29 Currency.......................................................................................................................................................29 Role key ........................................................................................................................................................30 WorkOnBehalfOf.........................................................................................................................................30

Part 3: Using the Web Service ........................................................................................ 32

Chapter 8: Creating Objects .................................................................................................... 33
Create methods............................................................................................................................................33 Create policy ................................................................................................................................................34

Chapter 9: Retrieving Objects ................................................................................................ 39

Retrieve methods ........................................................................................................................................39 Individual objects........................................................................................................................................39 Lists of objects..............................................................................................................................................40 Restriction reference ...................................................................................................................................44

Chapter 10: Updating Objects ............................................................................................... 47

Update methods..........................................................................................................................................47 Update policy ..............................................................................................................................................50 Concurrency.................................................................................................................................................52

Chapter 11: Deleting or Voiding Objects ..................................................................... 57

Delete or void methods..............................................................................................................................57 Delete or void policy ..................................................................................................................................58

Chapter 12: Exceptions ................................................................................................................ 61

Exceptions console......................................................................................................................................61 System exceptions.......................................................................................................................................64 Validation exceptions .................................................................................................................................64

Chapter 13: Policy ............................................................................................................................. 67

Policy overview...........................................................................................................................................67 Configuring from the Dynamics Security Console ................................................................................68 Configuring from code...............................................................................................................................68 Using policy in a web service application...............................................................................................69

Chapter 14: Entity ID Filtering .............................................................................................. 73

Setting up entity ID filtering .....................................................................................................................73 Security for entity ID filtering ...................................................................................................................74 Implementing entity ID filtering ..............................................................................................................75 Filtering limitations ....................................................................................................................................76 Entity ID filtering example ........................................................................................................................76

Chapter 15: Other Programming Techniques ........................................................... 79

Calling web methods asynchronously.....................................................................................................79 Working on behalf of another user...........................................................................................................81 Creating an optimized access point .........................................................................................................82

ii

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C O N T E N T S

Part 4: Extending the Web Service........................................................................... 88

Chapter 16: Overview .................................................................................................................... 89
How objects can be extended ....................................................................................................................89 Parts of a web service extension ...............................................................................................................90 Creating a web service extension .............................................................................................................90

Chapter 17: Web Service Events .......................................................................................... 91

How events are processed .........................................................................................................................91 Event list.......................................................................................................................................................91

Chapter 18: Extension Assembly ........................................................................................ 95

Creating an extension assembly ...............................................................................................................95 Event handler methods ..............................................................................................................................96 Sample: Retrieved event handler method...............................................................................................98 Sample: ValidatingForCreate event handler method ............................................................................99 Sample: Creating event handler method...............................................................................................102 Sample: ValidatingForUpdate event handler method.........................................................................104 Sample: Updating event handler method .............................................................................................106 Sample: Deleting event handler method ...............................................................................................108

Chapter 19: Registering Events ......................................................................................... 109

Business object configuration file ...........................................................................................................109 Modifying the configuration file ............................................................................................................ 110 Event registration example...................................................................................................................... 111

Chapter 20: Using Web Service Extensions ........................................................... 113

Retrieving extension data ........................................................................................................................ 113 Creating or updating extension data ..................................................................................................... 115

Part 5: Web Service Samples ....................................................................................... 120

Chapter 21: Sales Documents ............................................................................................ 121
Overview of Sales Documents sample ..................................................................................................121 Running the Sales Documents sample...................................................................................................121 How the Sales Documents sample works .............................................................................................122 Web Service use for Sales Documents sample ......................................................................................122

Chapter 22: Import GL Transactions ............................................................................. 125

Overview of Import GL Transactions sample.......................................................................................125 Running the Import GL Transactions sample.......................................................................................125 How the Import GL Transactions sample works .................................................................................126 Web Service use for Import GL Transactions sample ..........................................................................126

Chapter 23: Update Customers ......................................................................................... 127

Overview of Update Customers sample ...............................................................................................127 Running the Update Customers sample ...............................................................................................127 How the Update Customers sample works ..........................................................................................128 Web Service use for Update Customers sample...................................................................................128

WEB

SERVICE

PROGRAMMERS

GUIDE

iii

C O N T E N T S

Appendix .................................................................................................................................................. 132

Appendix A: Culture Codes ................................................................................................... 133 Appendix B: ISO Currency Codes .................................................................................... 135 Appendix C: Troubleshooting ............................................................................................. 137
Exceptions ..................................................................................................................................................137 The stored data differs from what was submitted ...............................................................................141 Performance...............................................................................................................................................142 Web service does not respond.................................................................................................................142 Security .......................................................................................................................................................143 Policy ..........................................................................................................................................................144

Glossary ..................................................................................................................................................... 145 Index ............................................................................................................................................................... 147

iv

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

INTRODUCTION

Introduction
Welcome to Web Services for Microsoft Dynamics GP. This documentation explains how you can use these web services from within your own applications. Before you begin using the web services for Microsoft Dynamics GP, take a few moments to review the information presented here. Understanding the information provided here will help you learn about what the web services provide.

Whats in this manual

The Microsoft Dynamics GP Web Services Programmers Guide is designed to give you an in-depth understanding of how to use these web services in your application development. Even if you are familiar with using web services, you will find it helpful to browse the material presented here. Information is divided into the following parts: Part 1, Web Service Basics, explains what is provided by the web services for Microsoft Dynamics GP and describes the architecture. Part 2, Getting Started, describes how to connect to the web service, introduces the object model, web methods, and datatypes. Part 3, Using the Web Service, explains how to perform various actions through the web service, handle exceptions that occur, and use policies to configure the web service behavior. Part 4, Extending the Web Service, describes how to extend objects in the web service to provide access to additional data. Part 5, Web Service Samples, provides extended example applications that demonstrate how to use the Dynamics GP web service.

In addition, the Microsoft Dynamics GP Web Service Reference is an online help file that contains detailed information about the web methods, classes, enumerations, and policies provided by the web service. You will use this reference frequently as you develop your application that uses the Dynamics GP web service.

Whats new in this release?

Refer to the following list for more information about the new features added in this release of Web Services for Microsoft Dynamics GP and where you can learn more about each:

1. Entity ID Filtering
Several objects in the Dynamics GP web service have identity information associated with them. For example, each sales order has a salesperson ID. Entity ID filtering allows restricting access to these objects, based on the Windows User ID of the person accessing the web service. Refer to Chapter 14, Entity ID Filtering, for details about this feature.

2. Additional classes
Several classes have been added to the Dynamics GP web service for this release. Most of the new classes provide access to objects for the Field Service module in Microsoft Dynamics GP. Refer to the Dynamics GP Web Service Reference online help file for a complete list of the new classes.

WE B

S E R V I C E

P R O G R A M M E R S

G U I D E

IN T RO D U C T IO N

3. New web methods

Several new web methods have been added to the Dynamics GP web service. Many of these support the new Field Service classes. Other web methods provide access to entity ID assignment information, security roles in Microsoft Dynamics GP, and information about which companies are enabled for web services. Refer to the Dynamics GP Web Service Reference online help file for a complete list of the new classes.

Prerequisites
Since you will be working with information from Microsoft Dynamics GP, knowledge of the accounting system will be helpful. Consult the Microsoft Dynamics GP documentation resources to learn more about the product. It is assumed that you have already installed and configured the Web Services for Microsoft Dynamics GP. If you havent done so, consult the Web Services for Microsoft Dynamics GP Installation and Administration Guide for information about performing the installation. The information provided in this documentation will help you understand how to use the web services for Microsoft Dynamics GP. It is assumed that you are familiar with the development system that you will be using to create your application that accesses the web services. This guide uses Visual Studio 2005 to demonstrate the various techniques for web service development. If youre using another development tool, the general techniques will be similar. Refer to the documentation for your development tool for details about accessing web services.

Symbols and conventions

To help you use this documentation more effectively, weve used the following symbols and conventions to make specific types of information stand out.
Symbol Description

The light bulb symbol indicates helpful tips, shortcuts, and suggestions. Warnings indicate situations you should be aware of when completing tasks.
Margin notes summarize important information.

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

Convention

Part 1, Web Service Basics Bold type indicates a part name. Chapter 5, Web Methods Quotation marks indicate a chapter name. Creating a web reference
using System.IO;

Italicized type indicates a section name. This font is used to indicate script examples. Acronyms are spelled out the first time theyre used. Small capital letters indicate a key or a key sequence.

Web Services Description Language (WSDL)

TAB

or ALT+M

WEB

SERVICE

PROGRAMMERS

GUIDE

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

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

WE B

S E R V I C E

P R O G R A M M E R S

G U I D E

PART 1: WEB SERVICE BASICS

Part 1: Web Service Basics

This portion of the documentation contains basic information you should know before developing applications that use Web Services for Microsoft Dynamics GP. The following information is discussed: Chapter 1, Dynamics GP Web Service Overview, provides an overview of web services and what the Dynamics GP web service provides. Chapter 2, Web Service Architecture, describes the parts that make up the Web Services for Microsoft Dynamics GP, and how these parts work together.

WE B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 1:

Dynamics GP Web Service Overview

The Web Services for Microsoft Dynamics GP provide an ideal way for external applications to integrate with the data contained in the Microsoft Dynamics GP accounting system. The following topics introduce 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 is designed to support machine-to-machine interaction over a network. More specifically, web services are software systems that provide data and services to other applications. Web services use standard Internet transport protocols such as Hypertext Transfer Protocol (HTTP) and standard XML-based document formats such as Simple Object Access Protocol (SOAP) to exchange information.

Web server hosting the web services.

Communication occurs over the Internet or local intranet.

ASP .NET is used as the foundation to implement the Web Services for Microsoft Dynamics GP. It provides the support for the standard protocols that make the web services accessible.

Web service benefits

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

1. Based on industry standards

Once a software developer learns how to use a web service, the learning curve is greatly reduced for other web services that follows the standards.

2. Development tool independence

Any development tool that supports the web service standard should be able to access the data and services provided by the web service.

3. Insulation from future changes

Web services attempt to keep the web service interface unchanged, even though the data and code behind the web service may change in future versions of a product. This helps applications that use the web service to continue working properly, even though the application behind the web service has changed.

WEB

SERVICE

PROGRAMMERS

GUIDE

PA RT

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 make available to other applications.

What the Dynamics GP Web Service provides

The Microsoft Dynamics GP web service provides access to the primary documents 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, create new documents, update existing documents, and delete or void documents. The web service for Microsoft Dynamics GP is fully integrated with the Dynamics Security Service. The administrator of the web service can configure security so only specified users are allowed to perform actions like creating or updating sales documents.

WE B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 2:

Web Service Architecture

When developing applications that use the Web Services for Microsoft Dynamics GP, it will be helpful to understand the architecture used to implement them. Information about the architecture is divided into the following sections: Web service foundation Configurations Security for web services Policy for web services Exception logging

Web service foundation

The foundation for web services on the Microsoft Windows Server platform is Internet Information Services (IIS). ASP .NET adds the web service capabilities. With this foundation, Web Services for Microsoft Dynamics GP provides a standard web service interface that allows external applications to access data in Microsoft Dynamics 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 and supporting code used by integrating applications to access data in Microsoft Dynamics GP. Data validation logic is built into eConnect, helping ensure the integrity of any data written to the database through the web services. Though eConnect provides the data access for the Dynamics GP web service, no knowledge of eConnect is required to use the web service. The Dynamics GP web service interface completely isolates the web service developer from eConnect. The eConnect interfaces can still be used when the Dynamics GP web service is installed.

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

SQL Server with Dynamics GP Data and eConnect + IIS Server with ASP .NET and Web Services for Microsoft Dynamics GP

WEB

SERVICE

PROGRAMMERS

GUIDE

PA RT

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 Web Services for Microsoft Dynamics GP. In this configuration, the web services are installed on a separate server, and access the SQL Server that manages Microsoft Dynamics GP data over the local network.

Local Network

IIS Server with ASP .NET and Web Services for Microsoft Dynamics GP

SQL Server with Dynamics GP Data and eConnect

Which configuration you choose will depend on how extensively you will be using the Web Services for Microsoft Dynamics GP, and what server resources you have available. The two-server configuration will provide better performance if the web service will be heavily used.

Security for web services

Security for the Dynamics GP web service is controlled by the Dynamics Security web service. The Dynamics Security web service is installed onto the same web server as the Dynamics GP web service. Through this web service, the web service administrator will configure which users and groups are able to execute the web methods (operations) provided by the Dynamics GP web service. If an application attempts to run a web method for which the current user doesnt have access, a security exception will be raised and the action will be prevented. Security is controlled through the Dynamics Security Administration console, which is a snap-in for Microsoft Management Console (MMC). The console is shown in the following illustration.

10

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

W E B

S E R V I C E

A R C HI TE C T U R E

Policy for web services

Policy is another security-related feature for the Dynamics GP web service. The policy system allows the web service administrator to control how business objects are created, updated, or deleted through the Dynamics GP web service. Each create, update, and delete or void web service operation has a policy object that is passed with the operation. This policy object specifies the set of behaviors for the operation. Each behavior controls one characteristic for the operation being performed. For instance, the policy for the CreateCustomer web method has the behavior named Create Active Behavior. This behavior controls whether the customer being created is set to the active or inactive state. Behaviors are classified as internal or external. An internal behavior is one that can be specified 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 the policy object. Policy is configured using the Dynamics Security console. You will learn more about specifying behaviors from within your web service application in Chapter 13, Policy.

Exception logging
The Dynamics GP web service maintains a record of all exceptions (errors) that occur for web service operations. The web service administrator will use this information to help diagnose and resolve any issues for applications that use the web service. You can use the Dynamics GP Web Services Exceptions console to view the exception 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 the Dynamics GP web service. Retrieving exception information allows the client applications to display helpful error messages for the user, or to respond appropriately to exceptions that occur. You will learn more about working with exceptions in Chapter 12, Exceptions.

WEB

SERVICE

PROGRAMMERS

GUIDE

11

12

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

PART 2: GETTING STARTED

Part 2: Getting Started

This portion of the documentation explains how to start developing an application that accesses the Web Services for Microsoft Dynamics GP. The following information is discussed: Chapter 3, Connecting to the Web Service, explains how to view the web service, create a web reference, and create an instance of the service. Chapter 4, Web Service Object Model, describes the object model for the web service. Chapter 5, Web Methods, describes the web methods that are provided in the web service for Microsoft Dynamics GP. Chapter 6, Data types, explains how to work with the various types of data used in the objects for the web services. Chapter 7, Context, describes the context object, and how it is used when calling web methods.

14

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 3:

Connecting to the Web Service

To use a web service, you must first create a connection to it. Information about connecting to the web service for Microsoft Dynamics GP is divided into the following sections: Web service URL Creating a web reference Web service namespace Creating a web service instance

Web service URL

The Dynamics GP web service is accessible through a standard web browser. Simply supply the URL to the DynamicsGPService.asmx file that defines the web service interface. By default, the URL to this file will be: http://machine_name/DynamicsGPWebServices/DynamicsGPService.asmx When you view this file, you will see a list of the operation (web methods) available in the service. This is shown in the following illustration.

Click the individual operations to see the SOAP messages that are sent when the operations are performed and results are returned. Click Service Description to see the entire Web Service Description Language (WSDL) file that completely describes the web service. The WSDL file is in XML format. Typically, the WSDL file isnt used directly by the developer. It is designed to be read by development tools so they can learn about the definitions of the operations, objects, and enumerations provided by the web service.

WEB

SERVICE

PROGRAMMERS

GUIDE

15

PA RT

G E TT I N G

S T A R TE D

Creating a web reference

While it is possible to directly interact with a web service by exchanging messages in SOAP format, most web service interaction happens through a proxy. A proxy is a special set of classes that will act as a wrapper for the operations, objects, and enumerations defined by the web service. Your code will interact with the proxy classes, rather than the web service directly. This greatly simplifies the code to access the web service. In most development tools, you create the proxy for a web service by adding a web reference to your project. The web reference is simply a URL that points to the .asmx file that defines the web service. Once the development tool has been given the location of the .asmx file, it will retrieve the WSDL file that describes the web service. It will use this information to build the proxy classes for the web service. For example, to add a web reference to the Dynamics GP web service for a C# project being developed in Visual Studio 2005 or later, do the following. 1. Choose to add a web reference. In the Project menu, choose Add Web Reference. The Add Web Reference window will be displayed. 2. Supply the URL that points to the web service. To point to the Dynamics GP web service, you would supply the URL that specifies the location of the DynamicsGPService.asmx file. Click Go to search for the web service at the specified URL. When the web service is found, its information will be displayed. 3. Name the web service reference. The web service will be referenced in your code, so it must be given a name. The Web reference name control provides a place to enter the name.

Throughout this documentation, the web reference to the Dynamics GP web service is named DynamicsGPService. 4. Add the web reference. Click Add Reference to create the proxy for the web service.

16

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

C O N N E C T I N G

T O

T H E

W E B

S ER V I C E

The following illustration shows the web reference to the Dynamics GP web service that was added to a Visual C# project.

This web reference points to the Dynamics GP web service.

Most development tools will have a browsing tool that allows you to view the details of the proxy created for the web service. In Visual Studio 2005 or later you can view the web service proxy with the Object Browser. The Object Browser shows the details of the classes in the proxy. Its a good way to see the details of the Dynamics GP web service.

The Dynamics GP web service is large, and uses some web service standards that are not fully supported by some development tools and applications that can access web services. You may not be able to create web references to the Dynamics GP web service from some of these tools.

WEB

SERVICE

PROGRAMMERS

GUIDE

17

PA RT

G E TT I N G

S T A R TE D

Web service namespace

In Visual Studio, the generated proxy classes will be added to a separate namespace in the project. The name of this namespace is the same as the name you assigned to the web reference. For example, if the web reference is named DynamicsGPService, the namespace will also have this name. To make it easier to reference the classes, methods, and enumerations from the web service, you will want to add this namespace to your application code. For instance, the following C# statement will add this namespace to the current application (named WebServiceApplication).
using WebServiceApplication.DynamicsGPService;

Adding the using statement will keep you from having to fully-qualify the classes, methods, and enumerations you refer to in the web service proxy.

Creating a web service instance

After you have made a web reference to the Dynamics GP web service, you will create an instance of the service so you can access the web service methods. The DynamicsGP class in the generated proxy represents the base web service. You will create an instance of this class that provides access to the web service methods. The following example shows the C# code required to create an instance of the Dynamics GP web service.
// Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP();

Throughout the code examples in this documentation, the web service instance is named wsDynamicsGP. The web service instance also provides access to properties that control how the web service is called. For instance, when accessing the Dynamics GP web service you can specify that the current users login credentials will be used for the web service call. The following C# code shows how this is done for a project created in Visual Studio 2005.
// Be sure that default credentials are being used wsDynamicsGP.UseDefaultCredentials = true;

The following C# code shows how this is done for Visual Studio 2003.
// Be sure that default credentials are being used wsDynamicsGP.Credentials = System.Net.CredentialCache.DefaultCredentials;

The Timeout property is another important property of the web service instance. It specifies how long the client application will wait for a web service request to be completed. If your web service application is working with a large number of documents, it may encounter timeout errors. You can use the Timeout property to increase the timeout value. The following C# example sets the timeout to infinite.
wsDynamicsGP.Timeout = System.Threading.Timeout.Infinite;

Refer to the troubleshooting information in the Web Services Installation and Administration Guide for more information about timeout issues.

18

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 4:

Web Service Object Model

The Dynamics GP web service contains numerous objects that you can work with through the web service. To effectively use the web service, its helpful to understand how these objects work together to represent data in the system. Information about the object model is divided into the following sections: Object categories Inheritance Learning the object model Dynamics GP Web Service Reference

Object categories
The number of objects available through the Dynamics GP web service is quite large. To understand how all of these objects are used, it helps to divide them into three categories.

Business document objects

These are the objects that represent business documents in Microsoft Dynamics GP. You will recognize them because their names closely match the documents they correspond to in the accounting system. Examples include: Customer Vendor CreditLimit Account SalesInvoice

Other objects are parts of business documents or define a set of properties for a business document. Example of this type of object include: Address SalesLine Tax

The vast majority of objects in the Dynamics GP web service are business documents or some part of a business document.

Base objects
Many objects in the Dynamics GP web service share common characteristics. Rather than repeat these characteristics for every individual object, a single base object is used. This object serves as the basis for each specific type of object. The following are some common base objects: BusinessObject Key Criteria Restriction

For instance, all business documents such as Customer and SalesInvoice are based on BusinessObject. Every key object used to uniquely identify an object is based on the Key object. You will never work with the base objects directly. They are used only by the web service to implement the other objects.

WEB

SERVICE

PROGRAMMERS

GUIDE

19

PA RT

G E TT I N G

S T A R TE D

Helper objects
Some objects are included simply to help you work with the Dynamics GP web service. They perform actions such as controlling how the web service is called, or dealing with errors that occur during processing. The following are some of the helper objects: Context Policy ExceptionInformation ValidationItem

Inheritance
As described in Object categories on page 19, many of the business document objects you will use as you work with the web service inherit characteristics from other objects. For instance, the CustomerAddress object, which completely describes the address information for a customer, inherits from a series of other objects. The inheritence hierarchy for the CustomerAddress object is shown in the following illustration:

CustomerAddress

ConstituentAddress

BusinessAddress

InternationalAddress

Address

Address Base

BusinessObject

Base Object

The CustomerAddress object has all of the characteristics (properties) of each of the objects it inherits from. Notice that BusinessObject serves as the base object for the inheritence hierarchy.

20

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

W E B

S E R V I C E

O B J E C T

M O D E L

Learning the object model

At first, the large number of objects in the Dynamics GP web service object model can seem overwhelming. As you work with the Dynamics GP web service, you will learn about each category of object. Soon you will be able to quickly decide what category an object is in, and how it should be used. One approach to learning the object model is to start with a specific web method. Each web method requires a set of objects to perform its action. Begin with those objects, and branch out to the related objects. For example, assume you wanted to execute the CreateCustomer method, which creates a customer in Microsoft Dynamics GP. This method uses the following objects: Customer Context Policy

As you work with the Customer object, you will see that it references some additional objects including: CustomerKey CustomerClassKey CustomerAddressKey CustomerCreditLimit

As you learn about these related objects, you will expand your understanding of the object model for the Customer object you are creating.

Dynamics GP Web Service Reference

The Dynamics GP Web Service Reference is an online help file that provides detailed information about the classes (objects) available in the Dynamics GP web service. Use this comprehensive reference as you learn about the object model for the web service. The links in the help file make it easy to browse through the properties of an object and see the other objects related to it.

WEB

SERVICE

PROGRAMMERS

GUIDE

21

22

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 5:

Web Methods
To perform tasks with the Dynamics GP web service, you must call the web methods provided. The following sections introduce the web methods available in the web service: Web method categories Framework methods

Web method categories

The web method for the Dynamics GP web service can be divided into the following categories: Get, GetList, Create, Update, and Delete or Void.

Get
Get operations retrieve individual documents from Microsoft Dynamics GP. To retrieve a document, you specify the documents key (unique identifier). If the document can be found, it will be returned from the web service. You will learn more about Get operations in Chapter 9, Retrieving Objects.

GetList
GetList operations retrieve collections of summary objects that meet the specified set of search criteria. A summary object is a special version of a business document, containing only the most important properties of the document. For example, the CustomerSummary object contains only the most important properties of the Customer object. You will learn more about criteria and GetList operations in Chapter 9, Retrieving Objects.

Create
Create operations create new documents in Microsoft Dynamics GP. To create a new document, you will first create a new instance of the document object. After you specify the details for the object, you will call the Create method to create the new object. You will learn more about creating new documents in Chapter 8, Creating Objects.

Update
Update operations modify existing documents in Microsoft Dynamics GP. For most documents, you can create an instance of the document type, specify the properties to update, and supply the key value to indicate which document will be updated. Other types of documents, specifically sales documents, require you to first retrieve an instance of the document before you can update it. You will learn more about updating documents in Chapter 10, Updating Objects.

Delete or void
Delete operations permanently delete existing documents from Microsoft Dynamics GP. Some documents cannot be deleted, but can be voided instead. Void operations perform this action. Chapter 11, Deleting or Voiding Objects, describes how to do this in detail.

WEB

SERVICE

PROGRAMMERS

GUIDE

23

PA RT

G E TT I N G

S T A R TE D

Framework methods
The web service also provides several methods that help you work with the Dynamics GP web service framework.

Exceptions
Code that accesses the Dynamics GP web service must be able to handle any exceptions that occur while web methods are processed. Several web methods are included in the Dynamics GP web service that your application can use to retrieve information about an exception that occurred. The exception information can be used to present a helpful error message to the user, explaining an issue such as a data validation exception. The information might also be used directly by the code to handle an error, such as retrying the web service call after a timeout exception. You will learn more about exceptions in Chapter 12, Exceptions.

Policy
Policy allows the administrator of the Dynamics GP web service to control how create, update, and delete or void operations are performed. The individual characteristics that can be controlled are called behaviors. For instance, the policy for the UpdateSalesOrder web method has a behavior that can specify how quantity shortages are to be handled for the sales order document. Your application that uses the Dynamics GP web service must retrieve and use the appropriate policies when it calls web methods that require them. The Dynamics GP web service contains special web methods that retrieve policy information for the specified web methods. You will learn more about policy in Chapter 13, Policy.

24

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 6:

Data types
Several types of data are represented in the properties defined in the objects for the Dynamics GP web service. This portion of the documentation provides details you will need to know as you work with these different data types in your own applications. The following topics are discussed: Standard data types Enumerations Account numbers Choice types

Standard data types

The following is a list of the standard data types are used in the Dynamics GP web service, along with some details about each type.

String values
String values in the Dynamics GP web service must be handled carefully to avoid truncation issues. String properties for the business documents in the Dynamics GP web service have a defined length that is detailed in the Dynamics GP Web Service Reference online documentation. Its essential that you dont exceed the stated string length for these properties. Any strings that exceed the specified length will be truncated, resulting is data corruption. No exception will be logged when a string value is truncated by the Dynamics GP web service. The empty string ("") is considered the empty value for a string property.

Integer values
The value 0 (zero) is considered the empty value for an integer property.

Decimal values
The value 0.0 is considered the empty value for a decimal property.

DateTime values
The value 1/1/1900 12:00:00am is considered the empty value for a DateTime property.

MoneyAmount values
The MoneyAmount data type maintains three pieces of data: The currency used for the amount The value of the amount (as a decimal) The number of decimal digits in the amount

The currency corresponds to the ISO code for the currency represented. Refer to Appendix B, ISO Currency Codes, for a list of the standard ISO codes used for currencies in Microsoft Dynamics GP. The value is considered empty when when the currency hasnt been specified, the decimal value is 0.0, and the number of digits is 0.

WEB

SERVICE

PROGRAMMERS

GUIDE

25

PA RT

G E TT I N G

S T A R TE D

Percent values
The Percent data type maintains two pieces of data: The value of the amount (as a decimal) The number of decimal digits in the amount

The value is considered empty when the value amount is 0.0 and the number of digits is 0.

Enumerations
To make using the Dynamics GP web service easier, several properties have enumerations (a predefined set of values) defined for them. For example, the Customer class has the StatementCycle property that defines when the customer will be billed. This property has the type StatementCycle, which is an enumeration defined by the web service. It has the following values:
Constant
No Statement Weekly Bi-Weekly Semi-Monthly Monthly Bi-Monthly Quarterly

Description
No statements sent Statements sent weekly Statements sent once every two weeks Statements sent twice each month Statements sent once each month Statements sent once every two months Statements sent once each quarter

The proxy created when the web reference for the Dynamics GP web service will contain all of the enumerations. These simplify working with these properties. For example, the following C# statement shows how the StatementCycle property can be set for a customer object.
customer.StatementCycle = DynamicsGPService.StatementCycle.Monthly;

For some properties that use an enumeration, the value of the property isnt a single value from the enumeration. Instead, it is the summation of zero or more of the values from the enumeration. For instance, the Company class has the CompanyOptions property. The CompanyOptions enumeration is used to set the value of this property. The value of the property is the sum of the enumeration items that apply to the company.

Account numbers
The format for account numbers is defined at the time Microsoft Dynamics GP is installed. The Dynamics GP web service uses the account number format that was defined. The web service will return account numbers in this format. When your web service application uses account numbers, it must supply them in the format that matches the current Microsoft Dynamics GP installation.
Refer to Chapter 9, Retrieving Objects, for information about how to retreive data from the Dynamics GP web service.

Since the account format may not be known at the time you write your application, the Dynamics GP web service includes the GetGLAccountFormatList web method to retrieve information about the account number format. This web method retrieves a collection of GLAccountFormat objects, each of which describes one segment of the account number. Examine each of these objects to determine the length of the account segment.

26

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

DA TA

T Y P E S

The separator character that appears between the segments of the account number is available from the AccountSegmentSeparator property of the Company object. Use the GetCompanyByKey method to retrieve this object. With this information, you can construct the format needed for account numbers to be processed by the web service.

Choice types
Of the data types used for the Dynamics GP web service, choice types require the most additional work to reference from your web service application. The choice type allows a single parameter to contain one of several different types of data. For instance, the FinanceCharge property for a customer is of type MoneyPercentChoice. It can contain either a money value or a percent value. When you look at the MoneyPercentChoice in the generated proxy, you will see that that it apprears with a single Item property, which has the type Object.

The MoneyPercentChoice type has only one property, which is named Item.

When your code reads the value of a parameter that uses the choice type, it must determine what type of value to read. When your code writes a choice parameter, it must specify which type of data it is writing. You can get this type information from the generated proxy code, or from the WSDL file for the Dynamics GP web service. In Visual Studio 2005 or later, you can double-click the Item property in the Object Browser to view its implementation details in the generated proxy. The following is the generated code for the MoneyPercentChoice type in the proxy for the Dynamics GP web service:
public partial class MoneyPercentChoice { private object itemField; [System.Xml.Serialization.XmlElementAttribute("Amount", typeof(MoneyAmount))] [System.Xml.Serialization.XmlElementAttribute("Percent", typeof(Percent))] public object Item { get { return this.itemField; } set { this.itemField = value; } } }

Notice in the XML serialization that the type for the Item property can be MoneyAmount or Percent, which are standard types for the Dynamics GP web service.

WEB

SERVICE

PROGRAMMERS

GUIDE

27

PA RT

G E TT I N G

S T A R TE D

Reading a choice type

The following C# example shows how you would retrieve the value of the FinanceCharge property for a customer object. The example will find out the type of the Item property for the MoneyAmount type, and then retrieve the underlying type.
DynamicsGPService.MoneyPercentChoice financeCharge; DynamicsGPService.MoneyAmount financeChargeAmount; DynamicsGPService.Percent financeChargePercent; // Examine the finance charge for the customer financeCharge = customer.FinanceCharge; if (financeCharge.Item.GetType() == typeof(DynamicsGPService.MoneyAmount)) { financeChargeAmount = (DynamicsGPService.MoneyAmount)financeCharge.Item; MessageBox.Show("Finance charge is a money amount of: " + financeChargeAmount.Value.ToString()); } if (financeCharge.Item.GetType() == typeof(DynamicsGPService.Percent)) { financeChargePercent = (DynamicsGPService.Percent)financeCharge.Item; MessageBox.Show("Finance charge is a percentage: " + financeChargePercent.Value.ToString()); }

Writing a choice type

The following C# example shows how you would write the value of the FinanceCharge property for a customer object. The value being written has the type MoneyAmount.
MoneyAmount financeCharge = new MoneyAmount(); financeCharge.Currency = "USD"; financeCharge.DecimalDigits = 2; financeCharge.Value = 5000.00; customer.FinanceCharge.Item = financeCharge;

28

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 7:

Context
The Context object is used for every web service method in the Dynamics GP web service. It provides important details that specify how the web service call should be performed. Information about the Context object is divided into the following sections: Organization key Culture Currency Role key WorkOnBehalfOf

Organization key
The organization key property of the Conext object specifies the company in Microsoft Dynamics GP that the web service method should be performed in. Specifying the company allows the web service to perform requests in the correct company database in SQL Server. The value corresponds to the numeric Company ID value in Microsoft Dynamics GP. The following C# example demonstrates setting the OrganizationKey property.
// Create a context with which to call the web service context = new Context(); // Specify which company companyKey = new CompanyKey(); companyKey.Id = 1; // Set up the context context.OrganizationKey = companyKey;

If the web method is to be performed in the context of the system (DYNAMICS database) then the OrganizationKey should be set to null.

Culture
The Culture property of the Context object is optional. It is a string property that specifies the culture (locale) of the user who is making the web service call. Based on the locale specified, the web service could return values in a format specific to that locale. Refer to Appendix A, Culture Codes, for a list of the culture codes.

Currency
The Currency property of the Context object specifies how currency information is be be handled for the web service call. The following options are available:
Constant
Transactional Local

Description
The transaction currency (originating) amount will be used. The local currency (functional) amount will be used.

This property is used only for documents that support multicurrency. If multicurrency isnt supported for a document, the Local (functional) currency amount will be used.

WEB

SERVICE

PROGRAMMERS

GUIDE

29

PA RT

G E TT I N G

S T A R TE D

Role key
The role key property of the Context object is optional. If supplied, the role specified will be used to choose the policy instance and appropriate behavior options for the web service call. If you dont supply a role key, the Dynamics GP web service will attempt to find a role for the user and company specified in the context object. If only one role can be found, that role will be used. If more than one role is found, or no roles are found, the default role will be used.

WorkOnBehalfOf
The WorkOnBehalfOf property of the Context object is used in the special cases where one user is running the web service methods, but the security privileges for a second user should be used. The WorkOnBehalfOf property will be set to the login name for this second user. For typical web service calls, you shouldnt set this property. It should be set only in the special cases where one web service user is performing actions on behalf of a different user. The value for the property will have the following form: DOMAIN\USERNAME or COMPUTERNAME\USERNAME Refer to Working on behalf of another user on page 81 for more details about the special situations where the property is used.

30

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

PART 3: USING THE WEB SERVICE

Part 3: Using the Web Service

This portion of the documentation provided detailed information about performing actions with the Dynamics GP web service. The following items are discussed: Chapter 8, Creating Objects, explains techniques for creating objects through the web service. Chapter 9, Retrieving Objects, describes techniques for retrieving objects from the web service. Chapter 10, Updating Objects, describes how to update objects using the web service. Chapter 11, Deleting or Voiding Objects, explains how to delete or void objects using the web service. Chapter 12, Exceptions, describes how to handle exceptions that occur during web service calls. Chapter 13, Policy, explains how to use policy to control the web service operations. Chapter 14, Entity ID Filtering, explains how the identity information contained in objects can be used to filter them as they are retrieved from the Dynamics GP web service. Chapter 15, Other Programming Techniques, describes some additional programming techniques that will be useful when working with the Dynamics GP web service.

32

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 8:

Creating Objects
The Dynamics GP web service allows new objects to be created in Dynamics GP. Information about creating objects is divided into the following sections: Create methods Create policy

Create methods
The Create web methods add new data to Dynamics GP. Create methods use objects to specify the type of data being created and the values to be saved. To create an object, use the following basic steps: Instantiate an object of the type to be created. Populate the objects properties with values. All required properties must be assigned a value. All non-required properties that are not populated will receive a default value when the Create method is run. The required properties for each object are indicated in bold in the Microsoft Dynamics GP Web Service Reference online help file. Create a policy object for the create operation. A policy object provides additional control for the create operation. You will learn more about the policies in Create policy on page 34. Use the object as a parameter for the Create method.

The following example demonstrates creating a new vendor. The vendor object requires a vendor key to uniquely identify this vendor. Notice how a vendor key object is created and used to populate the required property. The Name property is also populated. The vendor objects remaining properties will use default values. The vendor object is then passed as the first parameter to the CreateVendor method. The CreateVendor method also requires context and policy objects to be created and passed as the second and third parameters. Notice how the GetPolicyByOperation method instantiates the vendorPolicy object and retrieves the policy for the operation. The CreateVendor parameter specifies the default create policy for a vendor object. GetPolicyByOperation also requires a context object for its second parameter.
using System; using System.Collections.Generic; using System.Text; using DynamicsGPWebServiceSample.DynamicsGPService; namespace DynamicsGPWebServiceSample { class Program { static void Main(string[] args) { CompanyKey companyKey; Context context;

WEB

SERVICE

PROGRAMMERS

GUIDE

33

PA RT

U S I N G

T H E

W E B

S ER V I C E

Vendor vendor; VendorKey vendorKey; Policy vendorPolicy; // Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP(); // Be sure the default credential are used wsDynamicsGP.UseDefaultCredentials = true; // Create a context object with which to call the web service context = new Context(); // Specify which company to use (sample company) companyKey = new CompanyKey(); companyKey.Id = (-1); // Set up the context context.OrganizationKey = companyKey; context.CultureName = "en-US"; // Create a new vendor key vendorKey = new VendorKey(); vendorKey.Id = "TstVndr0001"; // Populate the vendor object vendor = new Vendor(); vendor.Key = vendorKey; vendor.Name = "TestVendor0001"; // Get the create policy for the vendor vendorPolicy = wsDynamicsGP.GetPolicyByOperation("CreateVendor", context); // Create the vendor wsDynamicsGP.CreateVendor(vendor, context, vendorPolicy); } } }

Create policy
Refer to Chapter 13, Policy, for more information about using policies.

A Create method requires an instance of the create policy for the object being created. The create policy contains a set of behaviors that control various aspects of the create operation, such as how certain properties will be set, or whether additional actions will be performed. The web service administrator controls all of the internal behavior options throught the Dynamics Security console. The external behaviors can be set by the application that is calling the create method. When you call a Create method for the Dynamics GP service, you must retrieve an instance of the policy used for that method. Do this using either the GetPolicyByOperation web method or the GetPolicyByKey web method. If the context object you pass to either method specifies a valid role for the user, the policy that is configured for that role will be returned. Otherwise, the default policy for the operation will be returned.

34

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

C R EA T I N G

O B J E C T S

Once the policy for the create operation has been retrieved, any external behaviors for the policy can be changed, if needed. The policy object will be passed to the web service Create method. In the following C# example, a new GL transaction is created. The policy for the CreateGLTransaction web method is retrieved. One behavior for this policy controls whether a reversing transaction is also created. The ID (GUID) for this behavior is looked up from the Dynamics GP Web Service Reference and used to locate the behavior. The behavior option specifying that a reversing transaction should be created is also looked up in the reference. The parameter for this behavior option is set to the reversing transaction date. Finally, the selected option for the behavior is set to the option to create the reversing transaction.
using System; using System.Collections.Generic; using System.Text; using System.Windows.Forms; using DynamicsGPWebServiceSample.DynamicsGPService; using System.Xml; namespace DynamicsGPWebServiceSample { class Program { static void Main(string[] args) { CompanyKey companyKey; Context context; BatchKey batchKey; GLTransactionKey transactionKey; GLTransaction transaction; GLTransactionLineKey glTransactionLineKey; GLTransactionLine transactionDebitLine; GLTransactionLine transactionCreditLine; GLAccountNumberKey debitAccountKey; GLAccountNumberKey creditAccountKey; MoneyAmount debitAmount; MoneyAmount creditAmount; MoneyAmount zeroAmount; Policy transactionCreatePolicy; Behavior reversingTrxBehavior; BehaviorOption reversingTrxBehaviorOption; Guid behaviorGUID; int behaviorOptionID; // Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP(); // Be sure the default credentials are used wsDynamicsGP.UseDefaultCredentials = true; // Create a context with which to call the web service context = new Context(); // Specify which company to use (sample company) companyKey = new CompanyKey(); companyKey.Id = (-1);

WEB

SERVICE

PROGRAMMERS

GUIDE

35

PA RT

U S I N G

T H E

W E B

S ER V I C E

// Set up the context object context.OrganizationKey = (OrganizationKey)companyKey; context.CultureName = "en-US"; // Create a batch key object to specify the batch batchKey = new BatchKey(); batchKey.Id = "RMCSH00000011"; // Create a GL transaction key object to identify the transaction transactionKey = new GLTransactionKey(); transactionKey.JournalId = 3372; transactionKey.Date = new DateTime(2007, 4, 12); // Create the transaction object transaction = new GLTransaction(); // Populate the GL transaction object's key property transaction.Key = transactionKey; // Populate the batch key and reference properties transaction.BatchKey = batchKey; transaction.Reference = "Receivables Cash Receipts"; // Create a GL transaction line key glTransactionLineKey = new GLTransactionLineKey(); // Create two GL transaction lines: // Create the debit transaction line transactionDebitLine = new GLTransactionLine(); // Populate the transaction line key transactionDebitLine.Key = glTransactionLineKey; // Create a GL account number key object to specify the account debitAccountKey = new GLAccountNumberKey(); debitAccountKey.Id = "000-1100-00"; // Populate the debit line GL account key property transactionDebitLine.GLAccountKey = debitAccountKey; // Create a money object zeroAmount = new MoneyAmount(); zeroAmount.Value = 0m; zeroAmount.Currency = "USD"; // Create a money object for the debit amount debitAmount = new MoneyAmount(); debitAmount.Value = 500m; debitAmount.Currency = "USD"; // Populate the transaction line debit and credit amounts transactionDebitLine.DebitAmount = debitAmount; transactionDebitLine.CreditAmount = zeroAmount; // Create the credit transaction line transactionCreditLine = new GLTransactionLine();

36

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

C R EA T I N G

O B J E C T S

// Populate the transaction line key transactionCreditLine.Key = glTransactionLineKey; // Create a GL account number key object to specify the account creditAccountKey = new GLAccountNumberKey(); creditAccountKey.Id = "000-1200-00"; // Populate the credit line GL account key property transactionCreditLine.GLAccountKey = creditAccountKey; // Create a money amount object for the credit creditAmount = new MoneyAmount(); creditAmount.Value = 500m; creditAmount.Currency = "USD"; // Populate the transaction line debit and credit amounts transactionCreditLine.DebitAmount = zeroAmount; transactionCreditLine.CreditAmount = creditAmount; // Create an array to hold the two GL transaction line objects GLTransactionLine[] lines = { transactionDebitLine, transactionCreditLine }; // Add the array of GL transaction line objects to the transaction transaction.Lines = lines; // Get the create policy for GL transactions transactionCreatePolicy = wsDynamicsGP.GetPolicyByOperation( "CreateGLTransaction", context); // Find the behavior in the list (from Web Service Reference) behaviorGUID = new Guid("b0c9fe57-c4f0-4d6a-b0aa-ab4d6d7596c8"); reversingTrxBehavior = new Behavior(); foreach (Behavior b in transactionCreatePolicy.Behaviors) { if (b.Key.Id == behaviorGUID) { // Behavior was found reversingTrxBehavior = b; break; } } // Set the parameter (reversing date) for the behavior option DateTime reversingTrxDate; reversingTrxDate = new DateTime(2007, 5, 31); // Find the behavior option (from Web Service Reference) behaviorOptionID = 2; reversingTrxBehaviorOption = new BehaviorOption(); foreach (BehaviorOption bo in reversingTrxBehavior.Options) { if (bo.Key.Id == behaviorOptionID) { // Behavior option was found reversingTrxBehaviorOption = bo; break; } }

WEB

SERVICE

PROGRAMMERS

GUIDE

37

PA RT

U S I N G

T H E

W E B

S ER V I C E

// Set the reversing date for the behavior option reversingTrxBehaviorOption.Parameters[0].Value = reversingTrxDate.ToShortDateString(); // Set selected behavior option to create a reversing transaction reversingTrxBehavior.SelectedOption = reversingTrxBehaviorOption; // Create the GL transaction wsDynamicsGP.CreateGLTransaction(transaction, context, transactionCreatePolicy); } } }

38

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 9:

Retrieving Objects
An individual object or list of objects can be retrieved through the Dynamics GP web service. The objects returned by the web service will be populated with data from Microsoft Dynamics GP. Information about retrieving objects is divided into the following sections: Retrieve methods Individual objects Lists of objects Restriction reference

Retrieve methods
There are two ways to retrieve objects from the Dynamics GP web service. Objects can be retrieved individually or as a list. When objects are retrieved individually, you must specify the unique key value for the object you want to retrieve. The GetByKey web methods in the Dynamics GP web service are used to retrieve individual objects. When objects are returned as a list, you will supply a set of criteria that indicate which objects you want to retrieve. The Dynamics GP web service has criteria objects that you will use to specify criteria. The GetList web methods in the Dynamics GP web service are used to retrieve lists of objects. Individual objects in the Dynamics GP web service can contain a significant amount of data. When a list of objects is retrieved from the web service, a large amount of data would need to be returned. A summary object contains the most important details of the main object. For example, the CustomerSummary object contains the important details of a Customer object. To speed the request for a list of objects, the summary version of the object is returned by most of the GetList web methods in the Dynamics GP web service. For some of the smaller objects, the corresponding GetList methods return the actual objects in the list.

Individual objects
A GetByKey web method returns a single object specified by a key. You will create an instance of the key object for the type of object you want to retrieve. The key objects identification property must be set to the value that uniquely identifies the object to be retrieved. The following example demonstrates retrieving a customer object. Notice how the customer key object is created and its Id property populated with a specific customer ID value. The customer key object is then passed as the first parameter to the GetCustomerByKey method. The GetCustomerByKey method also requires a context object to be created and passed as the methods second parameter.
using System; using System.Collections.Generic; using System.Text; using System.Windows.Forms; using DynamicsGPWebServiceSample.DynamicsGPService;

WEB

SERVICE

PROGRAMMERS

GUIDE

39

PA RT

U S I N G

T H E

W E B

S ER V I C E

namespace DynamicsGPWebServiceSample { class Program { static void Main(string[] args) { CompanyKey companyKey; Context context; Customer customer; CustomerKey customerKey; // Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP(); // Be sure that default credentials are being used wsDynamicsGP.UseDefaultCredentials = true; // Create a context with which to call the web service context = new Context(); // Specify which company to use (lesson company) companyKey = new CompanyKey(); companyKey.Id = (-1); // Set up the context context.OrganizationKey = (OrganizationKey)companyKey; context.CultureName = "en-US"; // Create a customer key customerKey = new CustomerKey(); customerKey.Id = "AARONFIT0001"; // Retrieve the customer object customer = wsDynamicsGP.GetCustomerByKey(customerKey, context); MessageBox.Show(customer.Name); } } }

If the object specified cannot be found, the Dynamics GP web service will raise a Business object not found. exception. You may want to trap for this exception in in your code and display an appropriate message for the user.

Lists of objects
A GetList web method returns a collection of summary objects, or in certain special cases, the collection of objects themselves. The content of the list is controlled by a criteria object. The list will contain only summary objects that meet the restrictions set by the criteria object. By default, only the first 1000 items that meet the specified criteria will be returned in the list. This limit prevents the web service from being overloaded by a query that returns an extremely large collection.

40

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

R ET R I EV IN G

O B J E C T S

Creating a criteria object

To specify which objects you want to retrieve in a list, you will first create a criteria object for that type. For instance, you will create a CustomerCriteria object to specify which customer objects to return from the GetCustomerList web method. The criteria object has restriction properties that correspond to specific properties of the object. For example, the Name property of the CustomerCriteria object is a string restriction that corresponds to the Name property of the Customer object. When you set the Name property of the CustomerCriteria object, customer summary objects for customers with names that meet the restriction will be returned. Refer to Restriction reference on page 44 for more information about the types of restrictions used for criteria.

List examples
GetList method Example 1

The following example demonstrates how to retrieve a list of vendor summaries. The vendor summary list produced by the example contains only vendors with the specified vendor class property. Notice how the object named classIdRestriction of the LikeRestrictionOfString class is used to specify the vendor class name. The classIdRestriction object is then used to populate the ClassId property of the vendor criteria object named vendorCriteria. The vendorCriteria object is passed as the first parameter in the GetVendorList method. The GetVendorList method also requires a context object to be created and passed as the methods second parameter.
using System; using System.Collections.Generic; using System.Text; using System.Windows.Forms; using DynamicsGPWebServiceSample.DynamicsGPService; namespace DynamicsGPWebServiceSample { class Program { static void Main(string[] args) { CompanyKey companyKey; Context context; VendorCriteria vendorCriteria; VendorSummary[] vendorSummaryList; LikeRestrictionOfString classIdRestriction; // Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP(); // Be sure that default credentials are being used wsDynamicsGP.UseDefaultCredentials = true; // Create a context object with which to call the web service context = new Context(); // Specify which company to use (sample company) companyKey = new CompanyKey(); companyKey.Id = (-1);

WEB

SERVICE

PROGRAMMERS

GUIDE

41

PA RT

U S I N G

T H E

W E B

S ER V I C E

// Set up the context object context.OrganizationKey = (OrganizationKey)companyKey; context.CultureName = "en-US"; // Specify the criteria for the vendor summaries to retrieve classIdRestriction = new LikeRestrictionOfString(); classIdRestriction.EqualValue = "USA-US-I"; // Create a vendor criteria object and set the restriction vendorCriteria = new VendorCriteria(); vendorCriteria.ClassId = classIdRestriction; // Retrieve the list of vendor summaries vendorSummaryList = wsDynamicsGP.GetVendorList(vendorCriteria, context); MessageBox.Show("Total vendors in class: " + vendorSummaryList.Length); } } }

GetList method Example 2

The following example demonstrates how to retrieve a list of vendor summaries that were modified during a specific time period. Notice how the object named modifiedDateRestriction of the BetweenRestrictionOfNullableOfDateTime class is used to specify the time period to be examined. The ModifiedDate property of the criteria object requires that both the date and time portion of the value be specified. The values for this criteria property must also be converted to Universal Coordinated Time (UTC). The modifiedDateRestriction object is then used to populate the ModifiedDate property of the vendor criteria object named vendorCriteria. The vendorCriteria object is passed as the first parameter in the GetVendorList method. The GetVendorList method also requires a context object to be created and passed as the methods second parameter.
using System; using System.Collections.Generic; using System.Text; using System.Windows.Forms; using DynamicsGPWebServiceSample.DynamicsGPService; namespace DynamicsGPWebServiceSample { class Program { static void Main(string[] args) { CompanyKey companyKey; Context context; VendorCriteria vendorCriteria; VendorSummary[] vendorSummaryList; BetweenRestrictionOfNullableOfDateTime modifiedDateRestriction; // Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP();

42

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

R ET R I EV IN G

O B J E C T S

// Make sure that default credentials are being used wsDynamicsGP.UseDefaultCredentials = true; // Create a context object with which to call the web service context = new Context(); // Specify which company to use (sample company) companyKey = new CompanyKey(); companyKey.Id = (-1); // Set up the context object context.OrganizationKey = (OrganizationKey)companyKey; context.CultureName = "en-US"; // Specify the criteria for the vendor summaries to retrieve modifiedDateRestriction = new BetweenRestrictionOfNullableOfDateTime(); DateTime startDate = new DateTime(2007, 4, 9, 8, 0, 0).ToUniversalTime(); DateTime endDate = new DateTime(2007, 4, 9, 17, 0, 0).ToUniversalTime(); modifiedDateRestriction.From = startDate; modifiedDateRestriction.To = endDate; vendorCriteria = new VendorCriteria(); vendorCriteria.ModifiedDate = modifiedDateRestriction; // Retrieve the list of vendor summaries vendorSummaryList = wsDynamicsGP.GetVendorList(vendorCriteria, context); MessageBox.Show("Total vendors modified today: " + vendorSummaryList.Length); } } }

Using the list

The objects returned in the collection wont be editable. If the objects need to be edited, or the necessary information isnt contained in the summary object, you will need to use the GetByKey method to retrieve the corresponding complete object.

Optimizing list operations

For optimal performance when retrieving lists of object from the Dynamics GP web service, its important that you structure the criteria carefully. Use the following guidelines when setting up criteria: Use the simplest criteria that can perform the search. The more properties you specify for the criteria object, the longer the search will take. Use properties in the criteria object that correspond to indexed columns in the database. In the Dynamics GP Web Service Reference, the properties of the criteria objects that correspond to indexed columns are marked with a dagger ().

WEB

SERVICE

PROGRAMMERS

GUIDE

43

PA RT

U S I N G

T H E

W E B

S ER V I C E

Restriction reference
Several types of restrictions used with criteria objects. Some restriction types correspond to the various types of data, such as string values, integers, and booleans. Other restriction types are based on how the restriction is structured. For instance a list restriction specifies a collection of possible values for a property. The restriction types are part of a hierarchy, with more complex restriction types being constructed from the simpler types. All restriction objects derive from the Restriction class in the Dynamics GP web service.

Basic restrictions
The most basic restriction contains a single value of a specific type. These restrictions have a name with the form: RestrictionOfNullableOfType Some restrictions of this type are for primitive types. For example the restriction RestrictionOfNullableOfInt32 represents a single integer value. Other restrictions of this type represent a single instance of a more complex piece of information. For instance, the restriction RestrictionOfNullableOfSalesDocumentType represents a single type of sales document. The following C# example shows how to create and use a basic restriction for a criteria object. This example creates a boolean restriction for the IsOnHold property of the customer criteria object.
CustomerCriteria customerCriteria; RestrictionOfNullableOfBoolean onHoldRestriction; onHoldRestriction = new RestrictionOfNullableOfBoolean(); onHoldRestriction.EqualValue = true; customerCriteria = new CustomerCriteria(); customerCriteria.IsOnHold = onHoldRestriction;

List restrictions
The list restrictions specify a distinct set of values. These restrictions have a name with the form: ListRestrictionOfNullableOfType Like the basic restrictions, some of these list restrictions are for primitive types and others for more complex types. List restrictions represent a distinct set of values of the specific types. The following C# example shows how to create and use a list restriction for a criteria object. This example creates a list restriction for the Type property of the item criteria object. The restriction contains a list of two item types, for Service and SalesItem. Notice how an array is created that contains the two possible values for the list restriction.

44

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

R ET R I EV IN G

O B J E C T S

ItemCriteria itemCriteria; ListRestrictionOfNullableOfItemType typeRestriction; ItemType?[] itemTypes; typeRestriction = new ListRestrictionOfNullableOfItemType(); itemTypes = new ItemType?[2]; itemTypes[0] = ItemType.Service; itemTypes[1] = ItemType.SalesItem; typeRestriction.Items = itemTypes; itemCriteria = new ItemCriteria(); itemCriteria.Type = typeRestriction;

Between restrictions
The between restrictions specify a range of values. You can specify a GreaterThan value, a LessThan value, or From and To values to specify a range. These restrictions have a name with the form: BetweenRestrictionOfNullableOfType The between restrictions are available only for primitive types, like date/time or string values. The following C# example shows how to create and use a between restriction for a criteria object. This example creates a between restriction for the Date property of a GL transaction criteria object. The property is set to a range between April 25, 2007 and April 26, 2007.
GLTransactionCriteria transactionCriteria; BetweenRestrictionOfNullableOfDateTime dateRestriction; dateRestriction = new BetweenRestrictionOfNullableOfDateTime(); DateTime startDate = new DateTime(2007, 4, 25); DateTime endDate = new DateTime(2007, 4, 26); dateRestriction.From = startDate; dateRestriction.To = endDate; transactionCriteria = new GLTransactionCriteria(); transactionCriteria.Date = dateRestriction;

Like restriction
String properties for criteria object have unique behavior. A Like expression, similar to those used in Transact-SQL can be used to define the restriction. The LikeRestrictionOfString restriction inherits from the between and list restriction types, so restrictions of this type can also be used as well. The following C# example shows how to create and use a Like restriction for a string property of a criteria object. This example creates a restriction for the State property of the customer criteria object. Notice how the Like clause is used to specify customers from the state ND.
CustomerCriteria customerCriteria; LikeRestrictionOfString stateRestriction; stateRestriction = new LikeRestrictionOfString(); stateRestriction.Like = "%ND%"; customerCriteria = new CustomerCriteria(); customerCriteria.State = stateRestriction;

WEB

SERVICE

PROGRAMMERS

GUIDE

45

46

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 10:

Updating Objects
The Dynamics GP web service can be used to change the values of individual properties for existing objects in Dynamics GP. Information about updating objects is divided into the following sections: Update methods Update policy Concurrency

Update methods
The Update web methods are used to change the values of an existing objects properties. Most updates can be performed using the following steps: Instantiate an object of the type to be updated. Create and set the key value for the object being updated. Populate only the properties that are to be updated. Create a policy object for the update operation. A policy object provides additional control for the update operation. You will learn more about the policies in Update policy on page 50. Use the object as a parameter for the Update method.

The following example demonstrates updating a vendor object. Notice how the vendor key objects Id property is populated with the ID of an existing vendor. A new vendor object will use this vendor key to specify which vendor to update. A value is supplied for the vendor objects Name property. The vendor object is then passed as the first parameter of the UpdateVendor method. The UpdateVendor method also requires context and policy objects to be created and passed as the second and third parameters. Notice how the GetPolicyByOperation method instantiates the vendorPolicy object. The UpdateVendor parameter specifies the default update policy for a vendor object. GetPolicyByOperation also requires a context object for its second parameter.
using System; using System.Collections.Generic; using System.Text; using DynamicsGPWebServiceSample.DynamicsGPService; namespace DynamicsGPWebServiceSample { class Program { static void Main(string[] args) { CompanyKey companyKey; Context context; VendorKey vendorKey;

WEB

SERVICE

PROGRAMMERS

GUIDE

47

PA RT

U S I N G

T H E

W E B

S ER V I C E

Vendor vendor; Policy vendorPolicy; // Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP(); // Make sure the default credentials are being used wsDynamicsGP.UseDefaultCredentials = true; // Create a context object with which to call the web service context = new Context(); // Specify which company to use (sample company) companyKey = new CompanyKey(); companyKey.Id = (-1); // Set up the context context.OrganizationKey = companyKey; context.CultureName = "en-US"; // Specify the vendor to be updated vendorKey = new VendorKey(); vendorKey.Id = "ACETRAVE0001"; // Create the vendor object and set the value of // the field to be updated vendor = new Vendor(); vendor.Name = "A Travel Company, Inc."; vendor.Key = vendorKey; // Get the update policy for vendor vendorPolicy = wsDynamicsGP.GetPolicyByOperation("UpdateVendor", context); // Update the vendor information wsDynamicsGP.UpdateVendor(vendor, context, vendorPolicy); } } }

When performing an update on a sales document (backorder, fulfillment order, invoice, order, quote, or return), the object must first be populated by a retrieve method. Retrieving the object ensures no data fields will be lost when the update is completed. The following example demonstrates how to update a sales return object. Notice how the sales document key object specifies the sales document to be updated. The GetSalesReturnByKey method uses the key object along with a context object to return the specified sales return object. The sales return objects Comment property is populated with a new value. The update occurs when the sales return object is passed as the first parameter to the UpdateSalesReturn method. The UpdateSalesReturn method also requires context and policy objects to be created and passed as the second and third parameters.

48

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A PT E R

1 0

U P D A T I N G

O B J E C T S

Notice how the GetPolicyByOperation method instantiates the salesReturnPolicy object with the default policy for updating sales returns.
using System; using System.Collections.Generic; using System.Text; using DynamicsGPWebServiceSample.DynamicsGPService; namespace DynamicsGPWebServiceSample { class Program { static void Main(string[] args) { CompanyKey companyKey; Context context; // Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP(); // Be sure that default credentials are used wsDynamicsGP.UseDefaultCredentials = true; // Create a context with which to call the web service context = new Context(); // Specify which company to use (sample company) companyKey = new CompanyKey(); companyKey.Id = (-1); // Set up the context object context.OrganizationKey = (OrganizationKey)companyKey; context.CultureName = "en-US"; // Set up a policy object Policy salesReturnPolicy = wsDynamicsGP.GetPolicyByOperation ("UpdateSalesReturn",context); // Create a Sales Return key SalesDocumentKey salesReturnKey = new SalesDocumentKey(); salesReturnKey.Id = "RTN10010"; // Retrieve the sales return object SalesReturn salesReturn = wsDynamicsGP.GetSalesReturnByKey (salesReturnKey, context); // Update the comment property salesReturn.Comment = "Update test comment"; // Update the sales return object wsDynamicsGP.UpdateSalesReturn(salesReturn, context, salesReturnPolicy); } } }

WEB

SERVICE

PROGRAMMERS

GUIDE

49

PA RT

U S I N G

T H E

W E B

S ER V I C E

Update policy
Refer to Chapter 13, Policy, for more information about using policies.

An Update method requires an instance of the update policy for the object being updated. The update policy contains a set of behaviors that control various aspects of the update operation, such as how certain properties will be set, or whether additional actions will be performed. The web service administrator controls all of the internal behavior options throught the Dynamics Security console. The external behaviors can be set by the application that is calling the update method. When you call an Update method for the Dynamics GP service, you must retrieve an instance of the policy used for that method. Do this using either the GetPolicyByOperation web method or the GetPolicyByKey web method. If the context object you pass to either method specifies a valid role for the user, the policy that is configured for that role will be returned. Otherwise, the default policy for the operation will be returned. Once the policy for the update operation has been retrieved, any external behaviors for the policy can be changed, if needed. The policy object will be passed to the web service Update method. In the following C# example, a quantity for a line item in a sales order document is updated. The policy for the UpdateSalesOrder web method is retrieved. One behavior for this policy controls whether promotions are to be used. The ID (GUID) for this behavior is looked up from the Dynamics GP Web Service Reference and used to locate the behavior. The behavior option that indicates that promotions should be used is located, based on the ID from the Dynamics GP Web Service Reference. The selected behavior option for the behavior is set to this specific behavior option.
using System; using System.Collections.Generic; using System.Text; using System.Windows.Forms; using DynamicsGPWebServiceSample.DynamicsGPService; using System.Xml; namespace DynamicsGPWebServiceSample { class Program { static void Main(string[] args) { CompanyKey companyKey; Context context; SalesDocumentKey salesOrderKey; SalesOrder salesOrder; Policy salesOrderUpdatePolicy; Behavior promotionBehavior; BehaviorOption includePromotionsBehaviorOption; Guid behaviorGUID; int behaviorOptionID; // Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP(); // Be sure the default credentials are used wsDynamicsGP.UseDefaultCredentials = true;

50

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A PT E R

1 0

U P D A T I N G

O B J E C T S

// Create a context with which to call the web service context = new Context(); // Specify which company to use (sample company) companyKey = new CompanyKey(); companyKey.Id = (-1); // Set up the context object context.OrganizationKey = (OrganizationKey)companyKey; context.CultureName = "en-US"; // Create a sales document key salesOrderKey = new SalesDocumentKey(); salesOrderKey.Id = "ORDST2227"; // Retrieve the sales order salesOrder = wsDynamicsGP.GetSalesOrderByKey(salesOrderKey, context); // Update the first line of the sales order salesOrder.Lines[0].Quantity.Value = 2; // Retrieve the update policy for sales orders salesOrderUpdatePolicy = wsDynamicsGP.GetPolicyByOperation ("UpdateSalesOrder", context); // Find the behavior in the list (from Web Service Reference) behaviorGUID = new Guid("2e58b57c-8fe1-4e98-bf04-371621f8e8b7"); promotionBehavior = new Behavior(); foreach (Behavior b in salesOrderUpdatePolicy.Behaviors) { if (b.Key.Id == behaviorGUID) { // Behavior was found promotionBehavior = b; break; } } // Find the behavior option (from Web Service Reference) behaviorOptionID = 1; includePromotionsBehaviorOption = new BehaviorOption(); foreach (BehaviorOption bo in promotionBehavior.Options) { if (bo.Key.Id == behaviorOptionID) { // Behavior option was found includePromotionsBehaviorOption = bo; break; } } // Set the selected behavior option promotionBehavior.SelectedOption = includePromotionsBehaviorOption;

WEB

SERVICE

PROGRAMMERS

GUIDE

51

PA RT

U S I N G

T H E

W E B

S ER V I C E

// Update the sales order object wsDynamicsGP.UpdateSalesOrder(salesOrder, context, salesOrderUpdatePolicy); } } }

Concurrency
When update operations are performed, the Dynamics GP web service must handle any concurrency issues that occur. These issues happen because other users have locked the same rows in the database that the update operation is trying to change. Documents for which the Microsoft Dynamics GP client application actively locks rows, such as sales document, can produce these situations. Typically, other users in Microsoft Dynamics GP wont see concurrency issues caused by web service operations. The update operations occur quickly, and hold row locks for only the time necessary to perform the update. If a concurrency issue is caused by a Dynamics GP web service update operation, the other user affected will see the standard message displayed that indicates another user has updated a record. The most likely scenario in which a web service update operations will encounter concurrency issues occurs when the web service application is updating a large number of rows that the Microsoft Dynamics GP client can actively lock. For example, if a web service application was updating all of the sales orders created on a specific date, and other users are accessing the Microsoft Dynamics GP system, it is possible the web service application will encounter one of the sales documents being locked (in use). If this occurs, a validation exception will occur, indicating the sales order being updated was in use. Your web service code must be able to handle concurrency exceptions that occur. The following C# example demonstrates one way this can be done. This example updates the comment for all sales orders created on 4/12/07. If a concurrency exception occurs because a sales order is being edited by another user, the following message is displayed. The user can choose to try updating the sales order again, or canceling the update and moving to the next document.

In this example, a list of the sales orders for the specific date is retrieved. The comment for each of these order is updated. Note the try...catch block that handles the validation error if a concurrency issue occurs. If the user chooses to retry the update operation, the goto statement causes the update operation to be run again.

52

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A PT E R

1 0

U P D A T I N G

O B J E C T S

using System; using System.Collections.Generic; using System.Text; using System.Windows.Forms; using DynamicsGPWebServiceSample.DynamicsGPService; using System.Xml; using System.Web.Services.Protocols; namespace DynamicsGPWebServiceSample { class Program { static void Main(string[] args) { CompanyKey companyKey; Context context; BetweenRestrictionOfNullableOfDateTime transactionDateRestriction; SalesOrderCriteria salesOrderCriteria; SalesOrderSummary[] salesOrderSummary; DateTime dateValue; SalesDocumentKey salesOrderKey; SalesOrder salesOrder; Policy salesOrderUpdatePolicy; ValidationResult validationResult; // Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP(); // Be sure the default credentials are used wsDynamicsGP.UseDefaultCredentials = true; // Create a context with which to call the web service context = new Context(); // Specify which company to use (sample company) companyKey = new CompanyKey(); companyKey.Id = (-1); // Set up the context object context.OrganizationKey = (OrganizationKey)companyKey; context.CultureName = "en-US"; // Create a date restriction object transactionDateRestriction = new BetweenRestrictionOfNullableOfDateTime(); dateValue = new DateTime(2007, 4, 12); transactionDateRestriction.EqualValue = dateValue; // Create a sales order criteria object salesOrderCriteria = new SalesOrderCriteria(); salesOrderCriteria.Date = transactionDateRestriction; // Retrieve the sales order summaries specified by the criteria salesOrderSummary = wsDynamicsGP.GetSalesOrderList( salesOrderCriteria, context);

WEB

SERVICE

PROGRAMMERS

GUIDE

53

PA RT

U S I N G

T H E

W E B

S ER V I C E

// Retrieve the update policy for sales orders salesOrderUpdatePolicy = wsDynamicsGP.GetPolicyByOperation( "UpdateSalesOrder", context); // Update the comment for each of the documents found foreach (SalesOrderSummary a in salesOrderSummary) { // Create a sales document key salesOrderKey = new SalesDocumentKey(); salesOrderKey = a.Key; // Retrieve the sales order salesOrder = wsDynamicsGP.GetSalesOrderByKey(salesOrderKey, context); // Set the comment property salesOrder.Comment = "Customer notified - April 12"; // Update the sales order object UpdateSalesDocument: try { wsDynamicsGP.UpdateSalesOrder(salesOrder, context, salesOrderUpdatePolicy); } catch (SoapException soapErr) { if (soapErr.Detail.HasChildNodes == true) { // Create a guid for the logid value Guid guid = new Guid(soapErr.Detail.InnerText); // Get the validation result object validationResult = wsDynamicsGP. GetLoggedValidationResultByKey(guid, context); if (validationResult.Errors[0].Id == "EConnectError-2079") { // It is a concurrency error, with record in use if (MessageBox.Show(null, "Document: " + a.Key.Id + ". "Sales Document Update", MessageBoxButtons.RetryCancel, MessageBoxIcon.Warning, MessageBoxDefaultButton.Button1) == DialogResult.Retry) { goto UpdateSalesDocument; } } else { // It is a different error " + validationResult.Errors[0].Message + ".",

54

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A PT E R

1 0

U P D A T I N G

O B J E C T S

MessageBox.Show(null, validationResult.Errors[0].Message, "Sales Document Update"); } } } } } } }

WEB

SERVICE

PROGRAMMERS

GUIDE

55

56

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 11:

Deleting or Voiding Objects

An individual object can be deleted or voided through the Dynamics GP web service. Deleted objects will be removed from the database. Voided object will remain in the database, but be in the voided state. Information about deleting or voiding objects is divided into the following sections: Delete or void methods Delete or void policy

Delete or void methods

The Delete or Void methods remove an object from or void an object in the database. To delete or void an object, use the following basic steps: Create a key object for the type of document you want to delete or void. Populate the key object with the unique ID of the document. Create a policy object for the delete or void operation. A policy object provides additional control for the delete or void operation. You will learn more about the policies in Delete or void policy on page 58. Pass the key object to the Delete or Void method.

The following example demonstrates deleting a customer. Notice how a customer key object is created and populated with the unique ID value CONTOSO for the customer. The DeleteCustomer policy is retrieved to populate the policy object. The customer key object is passed as the first parameter to the DeleteCustomer method. The DeleteCustomer method also requires the context and policy objects to be passed as the second and third parameters.
using System; using System.Collections.Generic; using System.Text; using System.Windows.Forms; using DynamicsGPWebServiceSample.DynamicsGPService; namespace DynamicsGPWebServiceSample { class Program { static void Main(string[] args) { CompanyKey companyKey; Context context; CustomerKey customerKey; Policy customerPolicy; // Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP(); // Be sure that default credentials are being used wsDynamicsGP.UseDefaultCredentials = true; // Create a context with which to call the web service context = new Context();

WEB

SERVICE

PROGRAMMERS

GUIDE

57

PA RT

U S I N G

T H E

W E B

S ER V I C E

// Specify which company to use (lesson company) companyKey = new CompanyKey(); companyKey.Id = (-1); // Set up the context context.OrganizationKey = (OrganizationKey)companyKey; context.CultureName = "en-US"; // Create a customer key customerKey = new CustomerKey(); customerKey.Id = "CONTOSO"; // Get the delete policy for the customer customerPolicy = wsDynamicsGP.GetPolicyByOperation ("DeleteCustomer", context); // Delete the customer wsDynamicsGP.DeleteCustomer(customerKey,context,customerPolicy); } } }

Delete or void policy

Refer to Chapter 13, Policy, for more information about using policies.

A Delete or Void method requires an instance of the delete policy for the object being deleted or the void policy for the object being voided. The delete or void policy contains a set of behaviors that control various aspects of how the operation will be performed. The web service administrator controls all of the internal behavior options throught the Dynamics Security console. The external behaviors can be set by the application that is calling the delete or void method. When you call a Delete or Void method for the Dynamics GP service, you must retrieve an instance of the policy used for that method. Do this using either the GetPolicyByOperation web method or the GetPolicyByKey web method. If the context object you pass to either method specifies a valid role for the user, the policy that is configured for that role will be returned. Otherwise, the default policy for the operation will be returned. Once the policy for the delete or void operation has been retrieved, any external behaviors for the policy can be changed, if needed. The policy object will be passed to the web service Delete or Void method. In the following C# example, a sales order is deleted. The policy for the DeleteSalesOrder web method is retrieved. One behavior for this policy controls whether posted deposits will be removed. The ID (GUID) for this behavior is looked up from the Dynamics GP Web Service Reference and used to locate the behavior. The behavior option specifying that posted deposits should not be removed is also looked up in the reference. Finally, the selected option for the behavior is set to the option to not remove posted deposits.
using System; using System.Collections.Generic; using System.Text; using System.Windows.Forms; using DynamicsGPWebServiceSample.DynamicsGPService; using System.Xml;

58

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 1

D E L ET I N G

O R

V O I D I N G

O B J E C T S

namespace DynamicsGPWebServiceSample { class Program { static void Main(string[] args) { CompanyKey companyKey; Context context; SalesDocumentKey salesOrderKey; Policy salesOrderDeletePolicy; Behavior removePostedDepositsBehavior; BehaviorOption doNotRemoveBehaviorOption; Guid behaviorGUID; int behaviorOptionID; // Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP(); // Be sure the default credentials are used wsDynamicsGP.UseDefaultCredentials = true; // Create a context with which to call the web service context = new Context(); // Specify which company to use (sample company) companyKey = new CompanyKey(); companyKey.Id = (-1); // Set up the context object context.OrganizationKey = (OrganizationKey)companyKey; context.CultureName = "en-US"; // Create a sales document key salesOrderKey = new SalesDocumentKey(); salesOrderKey.Id = "ORDST2226"; // Get the sales order delete policy salesOrderDeletePolicy = wsDynamicsGP.GetPolicyByOperation( "DeleteSalesOrder", context); // Find the behavior in the list (from Web Service Reference) behaviorGUID = new Guid("0f2c414b-fd12-4d83-940b-2bc0d65c3b77"); removePostedDepositsBehavior = new Behavior(); foreach (Behavior b in salesOrderDeletePolicy.Behaviors) { if (b.Key.Id == behaviorGUID) { // Behavior was found removePostedDepositsBehavior = b; break; } } // Find the behavior option (from Web Service Reference) behaviorOptionID = 0;

WEB

SERVICE

PROGRAMMERS

GUIDE

59

PA RT

U S I N G

T H E

W E B

S ER V I C E

doNotRemoveBehaviorOption = new BehaviorOption(); foreach (BehaviorOption bo in removePostedDepositsBehavior.Options) { if (bo.Key.Id == behaviorOptionID) { // Behavior option was found doNotRemoveBehaviorOption = bo; break; } } // Set selected behavior option to create a reversing transaction removePostedDepositsBehavior.SelectedOption = doNotRemoveBehaviorOption; // Delete the specified sales order wsDynamicsGP.DeleteSalesOrder(salesOrderKey, context, salesOrderDeletePolicy); } } }

60

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 12:

Exceptions
The Dynamics GP web service returns errors as SOAP exceptions. The web service classifies SOAP exception as either system exceptions or validation exceptions. System exceptions are events that prevent normal completion of web service methods. Validation exceptions occur when data passed into a web service method violates the data validation rules for an object. The web service maintains an exception log that contains detailed information for each exception that occurs. You can view the exception log entries to help you troubleshoot problems encountered by web service methods. Web methods also provide access to validation exception log entries so they can be handled or displayed by the application calling the web service. Information about exceptions is divided into the following sections: Exceptions console System exceptions Validation exceptions

Exceptions console
To view exceptions that have been logged, you can use the Dynamics GP Web Services Exceptions console. 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.

Opening the console

To open the Dynamics GP Web Services Exceptions, choose the item from the Administrative Tools menu accessed from the Start menu.

Selecting exceptions to display

The console can display system exceptions, validation exceptions, or both. Use the pane on the left to select which type of exceptions you want to view. The date controls on the top of the console specify the date range of the exceptions you want to display. By default, the current days exceptions are displayed.

WEB

SERVICE

PROGRAMMERS

GUIDE

61

PA RT

U S I N G

T H E

W E B

S ER V I C E

System exception details

To view detailed information for a system exception, select it in the list and choose Properties from the Action menu. Detailed properties for the system exception will be displayed.

Click this button to view more details about the exception.

Some exceptions will have additional details that you can view when you click the View Exception Detail button. Use the additional information provided, such as the messages and stack trace, to help you determine what caused the exception to occur.

The inner exceptions provide additional detail.

There may be several levels of inner-exception details that you can drill down into. Be sure to examine all of the levels for useful troubleshooting details. You can click View Request XML to see the complete XML message that was sent to the web service to be processed.

62

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 2

EX C E P T IO N S

Validation exception details

To view detailed information for a validation exception, select it in the list and choose Properties from the Action menu. Detailed properties for the validation exception will be displayed.

Click View Validation Results to see further details about the validation error and validation warnings that were logged. This additional detail can help you determine what validation rules have been broken.

WEB

SERVICE

PROGRAMMERS

GUIDE

63

PA RT

U S I N G

T H E

W E B

S ER V I C E

System exceptions
A system exception occurs when an unexpected event prevents the normal completion of a web method. The web service returns a SOAP exception to indicate the error occurred, and logs the details in the exception log. To improve security, a generic system exception message will be returned, telling the user to contact the system administrator for more details about the error. The details of the exception must be examined by the web service administrator.

A logged data exception object represents a system exception. The GetLoggedExceptionDataByKey method uses the exceptions log ID to retrieve a logged data exception object. The GetLoggedExceptionDataList method returns a list of logged exception summary objects. The method returns the list of exceptions logged during a specified time period.

Validation exceptions
A validation exception occurs when an object contains data that violates the web services data validation rules. A validation result object contains the detailed exception information from the exception log. Your application that uses the Dynamics GP web service can trap these validation exceptions, and display an appropriate message describing the validation issues. The following example demonstrates catching and retrieving a validation exception. Notice how the vendor object and the UpdateVendor method creates data that causes two validation exceptions. The try/catch block traps and handles the SOAP exception. The System.Web.Services.Protocols namespace is referenced so that the SoapException class is available to the code. The SOAP exception contains an ID which identifies the exception in the web service exception log. The GetLoggedValidationResultByKey method retrieves the validation result object for the specified log ID. The GetLoggedValidationResultByKey method also requires a context object to be passed as the second parameter.
using System; using System.Collections.Generic; using System.Text; using System.Windows.Forms; using System.Web.Services.Protocols; using DynamicsGPWebServiceSample.DynamicsGPService; namespace DynamicsGPWebServiceSample { class Program {

64

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 2

EX C E P T IO N S

static void Main(string[] args) { CompanyKey companyKey; Context context; VendorKey vendorKey; Vendor vendor; Policy policy; ValidationResult validationResult; // Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP(); // Make sure that default credentials are being used wsDynamicsGP.UseDefaultCredentials = true; // Create a context with which to call the web service context = new Context(); // Specify which company to use (sample company) companyKey = new CompanyKey(); companyKey.Id = (-1); // Set up the context context.OrganizationKey = (OrganizationKey)companyKey; context.CultureName = "en-US"; // Create a vendor key of the vendor to be updated vendorKey = new VendorKey(); vendorKey.Id = "ACETRAVE0001"; // Create a vendor object vendor = new Vendor(); vendor.Key = vendorKey; // Set a pair of properties to create two validation errors vendor.DiscountGracePeriod = 100; vendor.DueDateGracePeriod = 100; try { // Create a policy object policy = wsDynamicsGP.GetPolicyByOperation ("UpdateVendor", context); // Attempt to update the vendor wsDynamicsGP.UpdateVendor(vendor, context, policy); } catch(SoapException soapErr) { // If a validation exception occurred, the logid will // be in a child node if(soapErr.Detail.HasChildNodes == true) { // Create a guid for the logid value in the soap exception Guid guid = new Guid(soapErr.Detail.InnerText);

WEB

SERVICE

PROGRAMMERS

GUIDE

65

PA RT

U S I N G

T H E

W E B

S ER V I C E

// Get the validation result object validationResult = wsDynamicsGP. GetLoggedValidationResultByKey(guid, context); // Display the number of validation exceptions MessageBox.Show("Number of validation exceptions: " + validationResult.Errors.Length.ToString()); } } } } }

66

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 13:

Policy
Policy is a security-related feature for the Dynamics GP web service. The policy system allows the web service administrator and the application using the web service to control how business objects are created, updated, or deleted. Information about policy is divided into the following sections: Policy overview Configuring from the Dynamics Security Console Configuring from code Using policy in a web service application

Policy overview
Each create, update, and delete web service operation has a policy object that is passed with the operation. This policy object specifies the set of behaviors for the operation. Each behavior controls one characteristic for the operation being performed. For instance, the policy for the CreateCustomer web method has the behavior named Create Active Behavior. This behavior controls whether the customer being created is set to the active or inactive state. Behaviors are classified as internal or external. An internal behavior is one that can be specified 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 the policy object. Some policies do not have any behaviors, but the policy object must still be passed with the call to the web service operation.

Policy instances
Each company has a set of default policies that are always available. There is one default policy for each web service operation that requires a policy. Within a company, additional versions of the policy (with different behavior settings) can be created for each role defined in the Dynamics Security Service. Each of these is called a policy instance. When a web service application retrieves a policy to use, the Dynamics GP web service applies logic to ensure the appropriate policy instance is returned. You will learn more about this in Using policy in a web service application on page 69.

Policy reference
The Dynamics GP Web Service Reference help file contains a complete list of the default policies that are defined for the operations in the web service. All of the behaviors (including internal and external) are listed, including a description of what the behavior does.

WEB

SERVICE

PROGRAMMERS

GUIDE

67

PA RT

U S I N G

T H E

W E B

S ER V I C E

Configuring from the Dynamics Security Console

Most of the configuration for web service policy is performed using the Dynamics Security Console. The Policy node in the left-pane provides access to all of the policies that have been defined for the web service operations.

Information about configuring policy using this console can be found in the Web Services for Microsoft Dynamics GP Installation and Administration Guide.

Configuring from code

Several web methods are available in the Dynamics GP web service that can be used to configure policy settings from within a web service application. Details about these web methods can be found in the Dynamics GP Web Service Reference online help file. Each of the policy-related web mothods provides a detailed example that demonstrates its use. To use these methods, a user must be assigned to a role that can perform the operations in the Manage Policies task. The Policy Administrator role provides these capabilities.

Listing available policies

The following web methods are used to get a list of available policies: GetPolicyList GetPolicyListByRoleKey

Listing roles for policy instances

The following web method lists the roles for the various policy instances that have been created for a policy. GetPolicyRoles

68

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 3

P O LI C Y

Retrieving policy instances

The following web methods are used to retrieve policy instances for use in a web service application: GetPolicyByKey GetCompletePolicyByKey GetPolicyByOperation

Creating, updating, and deleting policy instances

The following web methods are used to create, update, and delete policy instances for specific policies. CreatePolicy UpdatePolicy DeletePolicy

Typically, policy instances for the various web service roles are managed using the Policy node in the Dynamics Security Console.

Using policy in a web service application

The create, update, and delete or void web methods in the Dynamics GP web service require the appropriate policy object to be passed to them. Your web service application must retrieve the appropriate policy instance to use. Your application can also control the external behaviors for the policy.

Retrieving a policy instance

To retrieve a policy instance to use for a web method, use one of the following: GetPolicyByKey GetPolicyByOperation

Which you choose depends on whether you prefer to have GUIDs in your code that identify policies, or string values for operation names. When a web service application retrieves the policy instance, the appropriate one will be returned, based on the context object that was used. The policy information will come from the company specified by the context object. If the context object has a role specified, the policy instance defined for that role will be returned. If no policy instance exists for that role within the specified company, the default policy for that operation will be returned. If you dont supply a role key, the Dynamics GP web service will attempt to find a role for the user and company specified in the context object. If only one role can be found, that role will be used. If more than one role is found, or no roles are found, the default role will be used. If you want to use a policy instance for a specific role, be sure that you specify the role key for the context object. Otherwise, its best to leave the role key property empty. This allows the web service administrator to control which policy instances are used based on the role a user is assigned to.

WEB

SERVICE

PROGRAMMERS

GUIDE

69

PA RT

U S I N G

T H E

W E B

S ER V I C E

Setting external behaviors

After your web service application has retrieved a policy instance, you can decide whether to change the values for any external behaviors. This process involves locating the external behavior in the policy instance, finding the behavior option you want to use, and setting the selected behavior option.
Find the behavior within the policy instance.

You will need to use the Dynamics GP Web Service Reference to find the GUID value that identifies the behavior you want to set. The reference will also provide the ID of the behavior option you want to use. For example, the following mutlipart C# example demonstrates how the Create Reversing Transaction behavior for the Create GL Transaction policy is used. First, the behavior is found within the policy instance:
Policy transactionCreatePolicy; Behavior reversingTrxBehavior; Guid behaviorGUID; BehaviorOption reversingTrxBehaviorOption; int behaviorOptionID; // Get the create policy for GL transactions transactionCreatePolicy = wsDynamicsGP.GetPolicyByOperation( "CreateGLTransaction", context); // Find the behavior in the list (from Web Service Reference) behaviorGUID = new Guid("b0c9fe57-c4f0-4d6a-b0aa-ab4d6d7596c8"); reversingTrxBehavior = new Behavior(); foreach (Behavior b in transactionCreatePolicy.Behaviors) { if (b.Key.Id == behaviorGUID) { // Behavior was found reversingTrxBehavior = b; break; } }

Find the behavior option to use.

The next portion of the C# code demontrates how the behavior option to create a reversing transaction is found:
// Find the behavior option (from Web Service Reference) behaviorOptionID = 2; reversingTrxBehaviorOption = new BehaviorOption(); foreach (BehaviorOption bo in reversingTrxBehavior.Options) { if (bo.Key.Id == behaviorOptionID) { // Behavior option was found reversingTrxBehaviorOption = bo; break; } }

70

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 3

P O LI C Y

Set the parameter for the behavior option (if required).

Some behavior options have a parameter that can be set. In this case, the date of the reversing transaction can be set. The next portion of the C# code shows how the parameter for the reversing date is set:
// Set the reversing date for the behavior option reversingTrxBehaviorOption.Parameters[0].Value = reversingTrxDate.ToShortDateString();

Set the selected behavior option.

Finally, the selected behavior option must be set for the behavior. The remainder of the C# code shows how the selected behavior is set for the Create Reversing Transaction behavior:
// Set selected behavior option to create a reversing transaction reversingTrxBehavior.SelectedOption = reversingTrxBehaviorOption;

The policy instance for the Create GL Transaction policy is ready to be passed to the CreateGLTransaction web method.

WEB

SERVICE

PROGRAMMERS

GUIDE

71

72

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 14:

Entity ID Filtering
Several objects in Dynamics GP have identity information associated with them. Examples include the Customer ID for customer objects, or the Salesperson ID for sales document objects. The Dynamics GP web service can use entity ID filtering to restrict access to these objects, based on the Windows User ID of the person accessing the web service. Information about entity ID filtering is divided into the following sections: Setting up entity ID filtering Security for entity ID filtering Implementing entity ID filtering Filtering limitations Entity ID filtering example

Setting up entity ID filtering

Windows User IDs can be associated with the following objects in Microsoft Dynamics GP: Back Office User Customer Salesperson Sales Territory

These objects are referred to as user-assignable business objects. Administrators of the Dynamics GP web service use the Microsoft Dynamics Security Administration Console to create entity ID assignments. These assign Windows User IDs to specific objects in Microsoft Dynamics GP. For example, the following illustration shows the entity ID assignment that assigns the Windows user CORPORATE\imarsh to the salesperson object in Microsoft Dynamics GP with the ID value IAN M..

Applications that access the Dynamics GP web service can use these entity ID assignments when retrieving data. When applied, the user will be able retrieve only those objects for which their Windows User ID is associated. For instance, the user can be restricted to retrieve sales documents where the primary Salesperson ID for the document is associated with the users Windows User ID.

WEB

SERVICE

PROGRAMMERS

GUIDE

73

PA RT

U S I N G

T H E

W E B

S ER V I C E

Security for entity ID filtering

Additional security roles, operations, and tasks are defined for the Dynamics GP web service to support entity ID filtering. These roles, operations, and tasks indicate whether entity ID filtering will be applied for the current web service user. For example, granting access to a role that contains the operation Query Sales Orders allows the user to retrieve any sales order. Granting access to a role that contains the operation Query Sales Orders Based On User allows the user to retrieve 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 have the word Self in their name. Users assigned to these roles will be able to see only objects that are associated to them based on the entity ID assignments. For example, the Salesperson - Self role provides access to customer, salesperson, and sales transaction information for the salesperson assigned to the current user. The following diagram shows how the security settings for entity ID filtering control access for a GetByKey operation in the Dynamics GP web service:
Application calls GetByKey

Yes

Does the user have access to the unrestricted operation?

No

Does the user have access to the Based On User operation?

No

Access is denied.

Yes

Is the user ID mapped to an entity ID?

No

Error: No mappings were found.

Yes

Does mapped ID match requested entity ID?

No

Error: User not authorized to see specific object.

Yes

Operation is performed.

74

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

When entity ID filtering is used for GetList operations, the Scope property of the criteria used for the operation also affects what values are returned. You will learn more about using the Scope property in Implementing entity ID filtering on page 75. The following diagram shows how the Scope property and security settings for entity ID filtering control access for a GetList operation in the Dynamics GP web service:
Application calls GetList

No

Was the Scope property supplied and set to a value other than All?

Yes

Access is denied.

No

Does the user have access to the unrestricted operation?

Does the user have access to the Based On User operation?

No

Access is denied.

Yes

Yes

Is the user ID mapped to an entity ID?

No

Error: No mappings were found.

Yes

Operation is performed.

Implementing entity ID filtering

When using the GetByKey operations for the Dynamics GP web service, be sure to check the Dynamics GP Web Service Reference help file to verify which operations can be affected by the entity ID filtering. The administrator for the Dynamics GP web service may have assigned roles that cause the entity ID assignments to be used. Your application must be able to handle any exceptions that occur when the web service administrator assigns one of the restricted operations. For instance, the application must handle cases where no entity ID assignment was found for the current user. The GetList operations that support entity ID filtering have a Scope property for the selection criteria that specifies which objects are returned. The Scope property can be set to return all objects, which is the default behavior. It can also be set to return only those objects that match the specific type of entity ID assigned to the current user.

WEB

SERVICE

PROGRAMMERS

GUIDE

75

PA RT

U S I N G

T H E

W E B

S ER V I C E

For example, the CustomerCriteria object supports entity ID filtering, so it contains the Scope property. This property can be set to Return All to return all customers. It can be set to Return Based on Customer Id to return the customer with an ID that matches the Customer ID assigned to the current user. It can also be set to Return Based on Salesperson Id to return the customers that have the Salesperson ID that matches the Salesperson ID assigned to the current user. If a Windows User ID is assigned to multiple entity IDs in Microsoft Dynamics GP, the GetList operation will return values for each of the entities that are mapped. If you use the entity ID filtering for GetList operations, be sure to handle the access denied exceptions that can occur if the web service administrator hasnt given access to the proper roles. Be sure to document the restricted operations that are required for your application. Its a good idea to test your web service applications with the roles that provide full access to web service operations and also the restricted roles that implement the entity ID filtering. If your application uses the WorkOnBehalfOf property for the Context object, be aware that this changes the user for entity ID filtering. The WorkOnBehalfOf user, not the user running the application, will be used for the entity ID filtering.

Filtering limitations
The entity ID filtering restricts which documents will be returned based on a primary ID associated with a document in Microsoft Dynamics GP. The entity ID filtering does not restrict documents based on the additional data they contain, such as line items. For example, when sales documents are returned based on the Windows User ID that is mapped to a salesperson ID, the documents are filtered based on the salesperson ID in the document header. The line items for the sales document are not filtered based on the salesperson ID. The document may contain line items that were added by other salespeople. These line items could contain information you dont want the restricted user to see. If your web service application relies on entity ID filtering, be aware of situations when your application could retrieve documents that contain sensitive data in the document. Consider using your applications user interface to filter out the data, such as the commission information for sales document line items.

Entity ID filtering example

The following C# code example shows how the Scope property of the criteria object is used. This example retrieves the historical sales orders for the current user. The Scope property of the Sales Order Criteria object is set to ReturnBasedOnSalespersonID, so that only documents associated with the current user will be returned. To work, this example requires that the user has access to the Query Sales Orders Based On User operation for the Dynamics GP web service. There must also be an entity ID assignment that maps the user to a Salesperson ID in Microsoft Dynamics GP.
using System; using System.Collections.Generic; using System.Text; using System.Windows.Forms;

76

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 4

E N T IT Y

I D

FI LT E R IN G

using System.Web.Services.Protocols; using DynamicsGPWebServiceSample.DynamicsGPService; namespace DynamicsGPWebServiceSample { class Program { static void Main(string[] args) { CompanyKey companyKey; Context context; ListRestrictionOfNullableOfSalesTransactionState transactionStateRestriction; SalesOrderCriteria salesOrderCriteria; SalesOrderSummary[] salesOrderSummary; // Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP(); // Be sure the default credentials are used wsDynamicsGP.UseDefaultCredentials = true; // Create a context with which to call the web service context = new Context(); // Specify which company to use (sample company) companyKey = new CompanyKey(); companyKey.Id = (-1); // Set up the context object context.OrganizationKey = (OrganizationKey)companyKey; context.CultureName = "en-US"; // Create a transaction state restriction object transactionStateRestriction = new ListRestrictionOfNullableOfSalesTransactionState(); transactionStateRestriction.EqualValue = SalesTransactionState.History; // Create a sales order criteria object // Retrieve summary objects for historical sales orders salesOrderCriteria = new SalesOrderCriteria(); salesOrderCriteria.TransactionState = transactionStateRestriction; // Specify the scope so that transactions for only the current // user are retrieved salesOrderCriteria.Scope = SalesDocumentScope.ReturnBasedonSalespersonId; try { // Retrieve the sales order summaries specified salesOrderSummary = wsDynamicsGP.GetSalesOrderList(salesOrderCriteria, context);

WEB

SERVICE

PROGRAMMERS

GUIDE

77

PA RT

U S I N G

T H E

W E B

S ER V I C E

// Display the ID and amount of each summary object StringBuilder summaryList = new StringBuilder(); foreach (SalesOrderSummary a in salesOrderSummary) { summaryList.AppendLine("Order number: " + a.Key.Id + " } MessageBox.Show(summaryList.ToString()); } catch (SoapException soapErr) { MessageBox.Show(soapErr.Message); } } } } Order amount: " + a.TotalAmount.Value.ToString("C"));

78

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 15:

Other Programming Techniques

The information presented here describes some additional programming techniques that you may find useful as you create applications that use the Dynamics GP web service. The following items are discussed: Calling web methods asynchronously Working on behalf of another user Creating an optimized access point

Calling web methods asynchronously

Some web methods can take considerable time to process, especially when working with large data sets in Microsoft Dynamics GP. Rather than making the user wait for a lengthy web service call to finish before returning control back to them, your application can call the web service method asynchronously. Control will be returned back to the application while the web service processes the request. When results are available, the event handler in your application will be notified and can act on the results. The GetList methods in the Dynamics GP web service can have longer processing times, especially when the data set being searched is large, and the criteria is complex. The following C# example demonstrates how the GetCustomerList web method can be called asynchronously. After setting up the criteria for the web service call, the example creates an event handler to receive the response of the asynchronous call. Then the asynchronous call is made. The event handler at the end of the example receives the result when the call has finished. It examines the result for any errors, and if there are none, displays the number of customers that match the criteria.
using System; using System.Collections.Generic; using System.Text; using System.Windows.Forms; using DynamicsGPWebServiceSample.DynamicsGPService; namespace DynamicsGPWebServiceSample { class Program { static void Main(string[] args) { CompanyKey companyKey; Context context; CustomerCriteria customerCriteria; LikeRestrictionOfString stateRestriction; LikeRestrictionOfString nameRestriction; RestrictionOfNullableOfBoolean activeRestriction; // Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP(); // Make sure that default credentials are being used wsDynamicsGP.UseDefaultCredentials = true;

WEB

SERVICE

PROGRAMMERS

GUIDE

79

PA RT

U S I N G

T H E

W E B

S ER V I C E

// Create a context with which to call the web service context = new Context(); // Specify which company to use (sample company) companyKey = new CompanyKey(); companyKey.Id = (-1); // Set up the context context.OrganizationKey = (OrganizationKey)companyKey; context.CultureName = "en-US"; // Create the criteria customerCriteria = new CustomerCriteria(); // Specify the criteria for the customer summaries to retrieve stateRestriction = new LikeRestrictionOfString(); stateRestriction.Like = "%IL%"; customerCriteria.State = stateRestriction; nameRestriction = new LikeRestrictionOfString(); nameRestriction.Like = "A%"; customerCriteria.Name = nameRestriction; activeRestriction = new RestrictionOfNullableOfBoolean(); activeRestriction.EqualValue = true; customerCriteria.IsActive = activeRestriction; // Use an event handler for the asynchronous web method wsDynamicsGP.GetCustomerListCompleted += new GetCustomerListCompletedEventHandler (wsDynamicsGP_GetCustomerListCompleted); // Retrieve the list of customer summaries (asynchronously) wsDynamicsGP.GetCustomerListAsync(customerCriteria, context); Console.WriteLine("Do additional work while waiting for result."); Console.ReadLine(); } // The event handler that responds to the completed event static private void wsDynamicsGP_GetCustomerListCompleted(object sender, GetCustomerListCompletedEventArgs e) { if (e.Error == null) { // Display the number of customers matching the criteria MessageBox.Show("Active IL customers beginning with 'A': " + e.Result.Length.ToString()); } } } }

80

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 5

O T H E R

PR O G R A M M I N G

T E C H N I Q U E S

Working on behalf of another user

An application that uses the Dynamics GP web service may be running as a specific user, but being accessed by other different users. For example, a web-based application running on a server may have this situation. The application is running as a specific user (often a local user account defined on the server), but other users are accessing the application with their own logon credentials. The various users of the application may have different security access for the web service. Some users of the application may be able to access web methods in the Dynamics GP web service that other users cannot. To provide proper security for the application, you will want to use the security settings for the user that is currently accessing the application. Since that user isnt actually running the application, the application needs a way to perform work on behalf of that user. The the WorkOnBehalfOf property of the Context object allows this capability when accessing the Dynamics GP web service. To use the WorkOnBehalfOf property, you need to create a role and assign the Work on Behalf of Other Users task to it. The user actually running the application (such as the local user on the server) must be assigned to this role. This allows that user to perform work on behalf of the other users who will be accessing the application. The following illustration shows this new role being created.

The Work on Behalf of Other Users task must be added to the new role you are creating.

WEB

SERVICE

PROGRAMMERS

GUIDE

81

PA RT

U S I N G

T H E

W E B

S ER V I C E

When your application calls web methods in the Dynamics GP web service, you will set the default credentials on the web service instance to be the local user that is actually running the application. For the Context object, you will set the WorkOnBehalfOf property to the login name for the user that is accessing the application. The security settings for that user will be used by the Dynamics GP web service.

Creating an optimized access point

The Dynamics GP Web Service contains over 250 web methods. When you create a web reference for the Dynamics GP Web Service, the proxy generated contains code to access all of these methods. In many cases, your web service application will use just a small subset of the available methods. You can create an optimized access point that contains only the web methods that your application is using. When you create a web reference that uses this optimized access point, the proxy generated contains code to access only the web methods you chose to include. The proxy will be significantly smaller and will load much more quickly. Use the following procedure to create an optimized access point. 1. Choose the web methods to include. Look through the list of web methods available in the Dynamics GP Web Service and decide which web methods you want to include in the optimized access point. For example, if your web service application was accessing customer data, you could include the following web methods: CreateCustomer DeleteCustomer GetCustomerByKey GetCustomerList UpdateCustomer

2. Create a Visual Studio project. In Visual Studio, choose to create a new project. Specify C# as the project type and Class Library as the template to use. Supply a name for the project that describes which web methods are being made available. For example, the name CustomersWebService could be used for the optimized access point that provides access to web methods for customer documents. 3. Add a reference to the system web services assembly. Add a reference to the System.Web.Services assembly that is part of the .NET framework. 4. Add references to the Dynamics GP web service assemblies. Add references to the following assemblies from the Bin folder for the Dynamics GP web service. Microsoft.Dynamics.Common Microsoft.Dynamics.Common.Types Microsoft.Dynamics.GP.BusinessLogic Microsoft.Dynamics.GP.WebServices Microsoft.Dynamics.Security

These assemblies are typically found in this location: C:\Program Files\Microsoft Dynamics\GPWebServices\WebServices\Bin

82

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 5

O T H E R

PR O G R A M M I N G

T E C H N I Q U E S

5. Add namespace references. Add using statements to provide convenient access to the classes and methods needed for the optimized access point. Include the following:
using Microsoft.Dynamics.GP; using Microsoft.Dynamics.GP.WebServices; using Microsoft.Dynamics.Common; using System.Web.Services;

6. Change the namespace. The namespace for the project will default to the name you supplied for the project. Change the namespace for the project to the following: Microsoft.Dynamics.GP.WebServices 7. Add the web service class. The web service class defines the web methods that you are making available through the optimized access point. You can add a new class, or rename the class that was added when you created the Visual Studio project. Use the same name that you did for the project. In this example, the name CustomersWebService was used for the project, so this name should also be used for the web service class. This is shown in the following code:
namespace Microsoft.Dynamics.GP.WebServices { public class CustomersWebService { } }

8. Specify the inheritance for the web service class. The web service class must inherit from the System.Web.Services.WebService class. This is shown in the following example.
public class CustomersWebService : System.Web.Services.WebService { }

9. Add attributes for the web service class. Add the following attributes to the web service class to define its characteristics.
[WebService(Name = "Dynamics GP", Namespace = "http:// schemas.microsoft.com/dynamics/gp/2006/01", Description = @"Optimized web service.")] [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1, EmitConformanceClaims = true)] public class CustomersWebService : System.Web.Services.WebService { }

WEB

SERVICE

PROGRAMMERS

GUIDE

83

PA RT

U S I N G

T H E

W E B

S ER V I C E

10. Add code to create an instance of the web service class. Add the following code to the web service class to create an instance of the class. Be sure to use the name of the web service class you are creating.
private static WebServices.WebService ws = new WebService(); public CustomersWebService() { }

11. Add the web methods. In the web service class, add the web methods that you want to include in the optimized access point. The parameter lists for the web methods will closely match the documentation for those web methods in the Dynamics GP web service. The following example shows the web methods added for the customer operations: CreateCustomer DeleteCustomer GetCustomerByKey GetCustomerList UpdateCustomer

Use the example as a template for the various operation types available in the Dynamics GP web service, such as Create, Delete, GetByKey, GetList, and Update. The complete code for the web service class is shown.
public class CustomersWebService : System.Web.Services.WebService { private static WebServices.WebService ws = new WebService(); public CustomersWebService() { } [WebMethod] public void CreateCustomer(Customer customer, Context context, Policy policy) { try { ws.CreateCustomer(customer, context, policy);} catch { throw; } } [WebMethod] public void DeleteCustomer(CustomerKey customerKey, Context context, Policy policy) { try { ws.DeleteCustomer(customerKey, context, policy); } catch { throw; } } [WebMethod] public Customer GetCustmerByKey(CustomerKey key, Context context) { try { return ws.GetCustomerByKey(key, context); } catch { throw; } } [WebMethod] public List<CustomerSummary> GetCustomerList(CustomerCriteria criteria, Context context) { try { return ws.GetCustomerList(criteria, context); } catch { throw; } }

84

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 5

O T H E R

PR O G R A M M I N G

T E C H N I Q U E S

[WebMethod] public void UpdateCustomer(Customer customer, Context context, Policy policy) { try { ws.UpdateCustomer(customer, context, policy); } catch { throw; } } }

12. Build and deploy the assembly. After the assembly for the optimized access point has been built, copy it to the Bin folder for the Dynamics GP web service installation. Typically this will be in the following location: C:\Program Files\Microsoft Dynamics\GPWebServices\WebServices\Bin 13. Create an active server methods (.asmx) file. The .asmx file specifies which class contains the web methods that are being made available through the access point. You can use a text editor such as Notepad to create the .asmx file. Use a filename that indicates what is being made available through the access point. For example, Customers.asmx would indicate customer information is being accessed. 14. Specify the content of the .asmx file. The .asmx file contains a single line that specifies the language and the complete name of the class that contains the web methods. The complete name consists of the namespace and the class name. For this example, the namespace is Microsoft.Dynamics.GP.WebServices and the class that contains the web methods is CustomersWebService. These names are used in the content for the Customers.asmx file.
<%@ WebService Language="C#" Class="Microsoft.Dynamics.GP.WebServices.CustomersWebService" %>

15. Deploy the .asmx file. The .asmx file for the optimized access point is added to the same location as the .asmx file for the Dynamics GP web service. Typically this will be in the following location: C:\Program Files\Microsoft Dynamics\GPWebServices\WebServices 16. Set the security properties for the .asmx file. After you have deployed the .asmx file, select it in Windows Explorer. Display the security properties for the file. Add the Authenticated Users group and allow that group to have Read and Read & Execute permissions for the .asmx file. The security permissions for your .asmx file should match those of the DynamicsGPService.asmx file.

WEB

SERVICE

PROGRAMMERS

GUIDE

85

PA RT

U S I N G

T H E

W E B

S ER V I C E

When you access your .asmx file through a web browser, you should see only the web methods that you made available. The following illustration shows the web methods that are made available through the Customers.asmx that was created in this example.

To use the optimized access point, create a web reference the same way you typically would. Instead of specifying the DynamicsGPService.asmx file, specify the .asmx file you created. The proxy created will contain only the web methods you made available through the optimized access point. Use the web methods in exactly the same way you would use those from the Dynamics GP web service. The security settings you specified for the Dynamics GP web methods also apply to the web methods you make available through the optimized access point.

86

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

PART 4: EXTENDING THE WEB SERVICE

Part 4: Extending the Web Service

This portion of the documentation provided detailed information about extending the Dynamics GP web service to handle additional data. The following items are discussed: Chapter 16, Overview, discusses how the Dynamics GP web service can be extended, and describes the steps involved. Chapter 17, Web Service Events, describes the events that are used when extending the Dynamics GP web service. Chapter 18, Extension Assembly, explains how to create an extension assembly containing the code for your web service extension. Chapter 19, Registering Events, describes how to register for the various events available in the Dynamics GP web service. Chapter 20, Using Web Service Extensions, provides examples that demonstrate how to use a Dynamics GP web service object that has been extended.

88

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 16:

Overview
Before extending objects for the Dynamics GP web service, its helpful to understand how the objects can be extended and the steps involved. The following topics are discussed: How objects can be extended Parts of a web service extension Creating a web service extension

How objects can be extended

All classes in the Dynamics GP web service that inherit from the BusinessObject class can be extended through a data extension mechanism and a collection of events. The standard business documents in Microsoft Dynamics GP, such as customers, vendors, sales documents, and so on that inherit from BusinessObject can all be extended. Typically, Dynamics GP web service objects are extended to support storing and retrieving additional data that is related to the object. For instance, the InventoryItem object could be extended to store additional data for the item. Web service objects can also be extended for other purposes, such as adding additional data validation. The ExtensionList collection for each business object contains the extensions (additional data) that is being passed along with the object. Each extension in the collection has the following: ExtensionId A string that identifies the extension. This typically describes what type of data the extension contains. DocExtension An XML element that contains the additional data being passed with the object. When an application uses a web service object that has been extended, the application is responsible for processing the XML element for each extension added to the object. It must process the XML element to extract the additional data when the object is retrieved. It must also create the properly-formed XML element for each extension when an object is being created or updated. Refer to Chapter 20, Using Web Service Extensions, for detailed examples of how web service consumers will access extensions.

WEB

SERVICE

PROGRAMMERS

GUIDE

89

PA RT

E XT E N DI N G

T HE

WE B

S ER V IC E

Parts of a web service extension

To extend objects in the Dynamics GP web service, you will create the following: An extension assembly that contains the processing code for the web service extension. This assembly wil be added to the Bin folder for the Dynamics GP web service installation. Entries in the BusinessObjectsFile.config that tell the Dynamics GP web service what additional events are to be processed.

Creating a web service extension

To create a web service extension, complete the following steps: 1. Decide what objects to extend and which events to use. Objects that inherit from the BusinessObject class can be extended. Refer to Chapter 17, Web Service Events, for information about the events available for the web service. 2. Determine the format for the XML element. If your web service extension will include additional data that will be passed along with the web service object, you must determine the format for the XML element that will contain this data. Remember that consumers of the web service will need to process this XML element, so a simple structure is preferrable. For example, the following XML element is used in an extension for the Customer object. It contains contact history information for the customer.
<ContactHistory> <FirstContactDate>6/6/1999 12:00:00 AM</FirstContactDate> <FirstContactSalesperson>NANCY B.</FirstContactSalesperson> <LastContactDate>3/1/2006 12:00:00 AM</LastContactDate> <LastContactSalesperson>ERIN J.</LastContactSalesperson> </ContactHistory>

3. Create the extension assembly. This assembly contains the processing code for the events that you are extending in the Dynamics GP web service. Refer to Chapter 18, Extension Assembly, for details about creating this assembly. 4. Register the events to process. Add entries to the BusinessObjectFile.config file so that the Dynamics GP web service will process the additional events. Refer to Chapter 19, Registering Events, for more information.

90

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 17:

Web Service Events

The Dynamics GP web service makes several events available to web service extensions. An event occurs for each step as an object in the web service is retrieved, created, updated, or deleted. A web service extension will be notified of each event for which it has been registered. Information about web service events is divided into the following sections: How events are processed Event list

How events are processed

When the Dynamics GP web service is started, it reads the entries in the BusinessObjectsFile.config to determine which additional events it should process. As the Dynamics GP web service processes requests, it makes the appropriate calls to the extension assemblies for which events are registered. These extension assemblies must have static methods with the specified names and proper event signatures so they can be called by the web service. When called, the event handling code in the extension assembly processes the request. Information about the request, such as the business object being processed, is available in the arguments passed to the event handling code. Depending on the event type, the response from the event handling code can influence further processing. For example, if the event handler for the event ValidateForUpdate encounters a validation error, the code in the event handler will add that error to the ValidationResult object passed back to the Dynamics GP web service. After all of the ValidateForUpdate events have been run, the web service will examine whether any validation errors have been noted. If any have, the web service will log the validation exceptions and stop any further processing.

Event list
The following table lists the events available for each extensible object in the Dynamics GP web service. You will use this information when planing which events to use for your extension, and when you edit the BusinessObjectFile.config to register the actual events.
Event
Retrieved

Occurs
After the object has been retrieved from the database, but before it has been returned from the web service. Before the object has been saved to the database. After the defaulting event, but before the object is saved to the database.

Typical use
Retrieve additional data for a web service object.

EventHandlerType
BusinessObjectEventHandler

Comments
None

DefaultingForCreate

Apply defaulting logic for the extended data. Apply validation rules for the extended data.

BusinessObjectEventHandler

None

ValidatingForCreate

BusinessObjectValidateEvent Handler

All validation events run, allowing all validation exceptions to be logged. If validation errors have been logged, further processing stops.

WEB

SERVICE

PROGRAMMERS

GUIDE

91

PA RT

E XT E N DI N G

T HE

WE B

S ER V IC E

Event
Creating

Occurs
Immediately after the object is created in the database. After the object has been created successfully in the database. Before the object has been updated in the database. After the defaulting event, but before the object is updated in the database.

Typical use
Save extended data to the appropriate tables in the database. None

EventHandlerType
BusinessObjectEventHandler

Comments
This event is included in the database transaction that creates the base object. None

Created

BusinessObjectEventHandler

DefaultingForUpdate

Apply defaulting logic for the extended data. Apply validation rules for the extended data.

BusinessObjectUpdateEvent Handler BusinessObjectValidateFor UpdateEventHandler

Has access to the original version of the core business object. Has access to the previous version (before update) of the core business object. All validation events run, allowing all validation exceptions to be logged. If validation errors have been logged, further processing stops. Has access to the original version of the core business object. This event is included in the database transaction that updates the base object. Has access to the original version of the core business object. None

ValidatingForUpdate

Updating

Immediately after the object is updated in the database.

Update extended data in the appropriate tables in the database.

BusinessObjectUpdateEvent Handler

Updated

After the object has been updated successfully in the database. Before the object has been deleted from the database. After the defaulting event, but before the object has been deleted from the database.

None

BusinessObjectUpdateEvent Handler

DefaultingForDelete

None

BusinessObjectEventHandler

ValidatingForDelete

BusinessObjectValidateEvent Verifies any preconditions required for the object to be Handler deleted.

All validation events run, allowing all validation exceptions to be logged. If validation errors have been logged, further processing stops. This event is included in the database transaction that deletes the base object. None

Deleting

Immediately after the object has been deleted from the database. After the object has been deleted successfully from the database. Before the object has been voided. After the defaulting event, but before the object has been voided.

Delete extended data from the appropriate tables in the database. None

BusinessObjectEventHandler

Deleted

BusinessObjectEventHandler

DefaultingForVoid ValidatingForVoid

None

BusinessObjectEventHandler

None All validation events run, allowing all validation exceptions to be logged. If validation errors have been logged, further processing stops. None

BusinessObjectValidateEvent Verifies any preconditions required for the object to be Handler voided.

Voiding

Immediately after the object has been voided.

Performs any necessary void action on the extended data.

BusinessObjectEventHandler

92

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 7

W E B

S E R V IC E

E V E N T S

Event
Voided

Occurs
After the object has been voided successfully.

Typical use
None

EventHandlerType
BusinessObjectEventHandler

Comments
None

WEB

SERVICE

PROGRAMMERS

GUIDE

93

94

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 18:

Extension Assembly
The extension assembly contains the processing code for the events you register for your web service extension. Its important that this assembly be created properly so that the Dynamics GP web service can call the static methods in the assembly. Information about creating an extension assembly is divided into the following sections: Creating an extension assembly Event handler methods Sample: Retrieved event handler method Sample: ValidatingForCreate event handler method Sample: Creating event handler method Sample: ValidatingForUpdate event handler method Sample: Updating event handler method Sample: Deleting event handler method

Creating an extension assembly

To create an extension assembly, complete the following steps: 1. Create a new class library. If Visual Studio, create a new project that has the type Class Library. 2. Add references to Dynamics GP web service assemblies. Add references to the following assemblies from the Bin folder for the Dynamics GP web service. Microsoft.Dynamics.Common Microsoft.Dynamics.Common.Types Microsoft.Dynamics.GP.BusinessLogic

These assemblies are typically found in this location: C:\Program Files\Microsoft Dynamics\GPWebServices\WebServices\Bin 3. Add namespace references. Add using (C#) or Imports (Visual Basic) statements to provide convenient access to the classes and methods needed for the extension assembly. Include the following: Microsoft.Dynamics.Common Microsoft.Dynamics.GP System.Data System.Data.SqlClient System.Xml

The Data, SqlClient, and Xml namespaces are added to provide access to resources you will need when you write your event handling methods. 4. Specify the name for the namespace. In the code for the class library, specify the name for the namespace. Use a name that indicates what who created the web service extension or what type of extended data is being made available.

WEB

SERVICE

PROGRAMMERS

GUIDE

95

PA RT

E XT E N DI N G

T HE

WE B

S ER V IC E

5. Add a public static class. This new class in the extension assembly will contain the static methods that respond to web service events. Be sure the class is marked public and static. The following C# code is an example of a public class for an extension assembly:
using System; using System.Data; using System.Data.SqlClient; using System.Xml; using Microsoft.Dynamics.Common; using Microsoft.Dynamics.GP; namespace ExtensionExample { public static class ContactHistory { // Event handler methods are added here } }

6. Add the event handler methods. These public static method will respond to the events from the Dynamics GP web service. For more information about these methods, refer to Event handler methods on page 96. 7. Build and deploy the extension assembly. Once the extension assembly has been built, copy it to the Bin folder for the Dynamics GP web service installation. Typically this will be in the following location: C:\Program Files\Microsoft Dynamics\GPWebServices\WebServices\Bin

Event handler methods

The event handler methods are static public methods that you add to the public static class in your extension assembly. In most cases, you will have one method for each event from the web service that your extension assembly will handle events for.

Event handler argument types

The names you use for the static methods arent critical. The name should describe the action that is being performed by the event handler. The method signature for each static method is important. The parameters must match what the web service is expecting. Each event handler method has the following basic form:
public static void method_name(object sender, EventArgsType e)

In place of EventArgsType you must specify the appropriate type for the type of event the static method is responding to. The following table lists the event types and the event arguments type that should be used.
Event
Retrieved DefaultingForCreate ValidatingForCreate

Event Arguments Type

BusinessObjectEventArgs BusinessObjectEventArgs BusinessObjectValidateEventArgs

96

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 8

EX T EN S I O N

A S S E M B L Y

Event
Creating Created DefaultingForUpdate ValidatingForUpdate Updating Updated DefaultingForDelete ValidatingForDelete Deleting Deleted DefaultingForVoid ValidatingForVoid Voiding Voided

Event Arguments Type

BusinessObjectEventArgs BusinessObjectEventArgs BusinessObjectUpdateEventArgs BusinessObjectValidateForUpdateEventArgs BusinessObjectUpdateEventArgs BusinessObjectUpdateEventArgs BusinessObjectEventArgs BusinessObjectValidateEventArgs BusinessObjectEventArgs BusinessObjectEventArgs BusinessObjectEventArgs BusinessObjectValidateEventArgs BusinessObjectEventArgs BusinessObjectEventArgs

For example, the static event handler method that responds to an Updating event from the Dynamics GP web service would look like the following:
public static void UpdateItem(object sender, BusinessObjectUpdateEventArgs e)

Writing event handler methods

The event handler method must perform the action to respond to the web service event, such as retrieving extended data for an object from the database. Properties passed in with the event arguments help the event handler complete its work. The following table lists the properties available with the event arguments.
Property
BusinessObject Context

Description
The complete business object for which the web service event is occurring. The Context object passed with the web service call. This object contains information used in processing the event, such as the OrganizationKey. For update events, the complete business object as it existed before it was updated. The Policy object passed with the web service call. For validation events, the collection of validation warning and errors. If the event handler encounters a validation issues, it must add them to this collection.

OriginalBusinessObject Policy ValidationResult

Event handler methods frequently need to access the Dynamics GP database to complete their actions. Objects available from the Microsoft.Dynamics.Common assembly are provided to help with these tasks. The examples provided in the following sections demonstrate how to perform these database actions. The event handler methods also need to work with the Extension objects that contain extended data for business objects. The examples provided show the techniques needed to work with the ExtensionList collection, as well as the XML element included with each Extension object.

WEB

SERVICE

PROGRAMMERS

GUIDE

97

PA RT

E XT E N DI N G

T HE

WE B

S ER V IC E

Sample: Retrieved event handler method

The following C# example shows the Retrieved event handler method used to retrieve contact history information associated with a customer object. The event handler retrieves the customer object from the event arguments passed in. After retrieving a connection to the current companys database and storing it in the connection private variable, it executes a SQL statement to retrieve the contact history information for the customer from the IG003 table. Finally, it builds the XML element that will contain the contact history information. It adds the XML element to an Extension object in the Extensions collection the customer object.
// Declare private variable of type Microsoft.Dynamics.Common.Connection private static Connection connection; public static void GetContactHistory(object sender, BusinessObjectEventArgs e) { string firstContactDate; string firstContactSalesperson; string lastContactDate; string lastContactSalesperson; XmlDocument doc; XmlElement contactHistoryXML; XmlElement firstContactDateXML; XmlElement firstContactSalespersonXML; XmlElement lastContactDateXML; XmlElement lastContactSalespersonXML; XmlText text; Customer customer; if (e.BusinessObject.GetType() == typeof(Customer)) { customer = (Customer)e.BusinessObject; // Get the connection to the database for the current company connection = Connection.GetInstance(); // The SQL command to retrieve contact history information string selectCommand = "SELECT FirstContactDate, ContactSalespersonID1, LastContactDate, ContactSalespersonID2 FROM IG003 WHERE CUSTNMBR='" + customer.Key.Id + "'"; SqlDataAdapter adapter = new SqlDataAdapter(selectCommand, (SqlConnection)connection.GetConnection(e.Context.OrganizationKey)); DataTable table = new DataTable(); adapter.Fill(table); if (table.Rows.Count > 0) { // Get the data from the SQL result firstContactDate = table.Rows[0].ItemArray[0].ToString(); firstContactSalesperson = table.Rows[0].ItemArray[1].ToString(); lastContactDate = table.Rows[0].ItemArray[2].ToString(); lastContactSalesperson = table.Rows[0].ItemArray[3].ToString();

98

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 8

EX T EN S I O N

A S S E M B L Y

// Build the Extension object to return from the web service Extension ContactHistory = new Extension(); ContactHistory.ExtensionId = "ContactHistory"; // Make the XML extension document doc = new XmlDocument(); contactHistoryXML = doc.CreateElement("ContactHistory"); // First Contact Date firstContactDateXML = doc.CreateElement("FirstContactDate"); text = doc.CreateTextNode(firstContactDate); firstContactDateXML.AppendChild(text); contactHistoryXML.AppendChild(firstContactDateXML); // First Contact Salesperson firstContactSalespersonXML = doc.CreateElement("FirstContactSalesperson"); text = doc.CreateTextNode(firstContactSalesperson); firstContactSalespersonXML.AppendChild(text); contactHistoryXML.AppendChild(firstContactSalespersonXML); // Last Contact Date lastContactDateXML = doc.CreateElement("LastContactDate"); text = doc.CreateTextNode(lastContactDate); lastContactDateXML.AppendChild(text); contactHistoryXML.AppendChild(lastContactDateXML); // Last Contact Salesperson lastContactSalespersonXML = doc.CreateElement("LastContactSalesperson"); text = doc.CreateTextNode(lastContactSalesperson); lastContactSalespersonXML.AppendChild(text); contactHistoryXML.AppendChild(lastContactSalespersonXML); // Add the extension to the Customer object ContactHistory.DocExtension = contactHistoryXML; e.BusinessObject.Extensions.Add(ContactHistory); } } }

Sample: ValidatingForCreate event handler method

The following C# example shows the ValidatingForCreate event handler method used to validate contact history information that is being added as extended data for a customer object. The event handler examines the Extension objects passed along with the customer. If one of the Extension objects has the ExtensionId value ContactHistory, the event handler will process it. After extracting the XML element from the Extension object, the two Salesperson ID values included in the extended data are validated. If the Salesperson ID values cannot be validated, validation errors are added to the ValidationResults object that was passed into the event handler.

WEB

SERVICE

PROGRAMMERS

GUIDE

99

PA RT

E XT E N DI N G

T HE

WE B

S ER V IC E

// Declare private variable of type Microsoft.Dynamics.Common.Connection private static Connection connection; public static void ValidateCreateContactHistory(object sender, BusinessObjectValidateEventArgs e) { bool found; string firstContactDate; string firstContactSalesperson; string lastContactDate; string lastContactSalesperson; string selectStatement; Customer customer; Extension ContactHistoryExtension = new Extension(); if (e.BusinessObject.GetType() == typeof(Customer)) { customer = (Customer)e.BusinessObject; // Look at the Extension list passed along found = false; foreach (Extension ext in customer.Extensions) { if (ext.ExtensionId == "ContactHistory") { ContactHistoryExtension = ext; found = true; break; } } if (found == true) { // Found an extension, so it should be processed XmlElement contactHistory; contactHistory = ContactHistoryExtension.DocExtension; XmlNodeList nodeList; nodeList = contactHistory.ChildNodes; // First contact date firstContactDate = nodeList[0].InnerText.ToString(); // First contact salesperson firstContactSalesperson = nodeList[1].InnerText.ToString(); // Last contact date lastContactDate = nodeList[2].InnerText.ToString(); // Last contact salesperson lastContactSalesperson = nodeList[3].InnerText.ToString(); // Get the connection to the database for the current company connection = Connection.GetInstance(); SqlCommand command = new SqlCommand(); command.Connection = (SqlConnection)connection.GetConnection (e.Context.OrganizationKey);

100

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 8

EX T EN S I O N

A S S E M B L Y

SqlDataAdapter adapter = new SqlDataAdapter(command); DataTable table = new DataTable(); // Verify that the First Contact Salesperson and Last Contact // Salesperson are valid // The SQL statement to verify the First Contact Salesperson selectStatement = "SELECT SLPRSNID FROM RM00301 WHERE SLPRSNID = '" + firstContactSalesperson + "'"; command.CommandText = selectStatement; adapter.Fill(table); if (table.Rows.Count < 1) { // Add an exception, because the First Contact salesperson was // not found ValidationError validationError = new ValidationError(); validationError.Id = "1001"; validationError.Message = "Invalid First Contact Salesperson specified in Contact History."; validationError.ObjectType = typeof(Customer).ToString(); validationError.PropertyNames.Add("FirstContactSalesperson"); e.ValidationResult.Errors.Add(validationError); } // The SQL statement to verify the Last Contact Salesperson selectStatement = "SELECT SLPRSNID FROM RM00301 WHERE SLPRSNID = '" + lastContactSalesperson + "'"; command.CommandText = selectStatement; adapter.SelectCommand = command; table.Clear(); adapter.Fill(table); if (table.Rows.Count < 1) { // Add an exception, because the Last Contact salesperson was // not found ValidationResult validationResult = new ValidationResult(); ValidationError validationError = new ValidationError(); validationError.Id = "1002"; validationError.Message = "Invalid Last Contact Salesperson specified in Contact History."; validationError.ObjectType = typeof(Customer).ToString(); validationError.PropertyNames.Add("LastContactSalesperson"); e.ValidationResult.Errors.Add(validationError); } } } }

WEB

SERVICE

PROGRAMMERS

GUIDE

101

PA RT

E XT E N DI N G

T HE

WE B

S ER V IC E

Sample: Creating event handler method

The following C# example shows the Creating event handler method used to save the contact history information for a customer object. The event handler examines the Extension objects passed along with the customer. If one of the Extension objects has the ExtensionId value ContactHistory, the event handler will process it. The code extracts the contact history information from XML element of the Extension object. After retrieving a connection to the current companys database and storing in the connection private variable, the event handler executes a SQL statement to save the contact history information for the customer into the IG003 table.
// Declare private variable of type Microsoft.Dynamics.Common.Connection private static Connection connection; public static void CreateContactHistory(object sender, BusinessObjectEventArgs e) { bool found; int rowsAffected; string contact; string firstContactDate; string firstContactSalesperson; string lastContactDate; string lastContactSalesperson; string updateStatement; string insertStatement; Customer customer; Extension ContactHistoryExtension = new Extension(); if (e.BusinessObject.GetType() == typeof(Customer)) { customer = (Customer)e.BusinessObject; // Look at the Extension list passed along found = false; foreach (Extension ext in customer.Extensions) { if (ext.ExtensionId == "ContactHistory") { ContactHistoryExtension = ext; found = true; break; } } if (found == true) { // Found an extension, so it should be processed XmlElement contactHistory; contactHistory = ContactHistoryExtension.DocExtension; XmlNodeList nodeList; nodeList = contactHistory.ChildNodes; //First contact date firstContactDate = nodeList[0].InnerText.ToString();

102

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 8

EX T EN S I O N

A S S E M B L Y

//First contact salesperson firstContactSalesperson = nodeList[1].InnerText.ToString(); //Last contact date lastContactDate = nodeList[2].InnerText.ToString(); //Last contact salesperson lastContactSalesperson = nodeList[3].InnerText.ToString(); // Get the connection to the database for the current company connection = Connection.GetInstance(); // The SQL statement to update contact history information updateStatement = "UPDATE IG003 SET ContactSalespersonID1='" + firstContactSalesperson + "', FirstContactDate='" + firstContactDate + "', ContactSalespersonID2='" + lastContactSalesperson + "', LastContactDate='" + lastContactDate + "' WHERE CUSTNMBR = '" + customer.Key.Id + "'"; // Create the SQL connection SqlCommand command = new SqlCommand(updateStatement); SqlConnection sqlConnection = new SqlConnection (connection.GetConnectionString(e.Context.OrganizationKey)); command.Connection = sqlConnection; // Open the SQL connection sqlConnection.Open(); // Execute the SQL statement rowsAffected = command.ExecuteNonQuery(); if (rowsAffected == 0) { // The row did not exist, so try creating it. // Is the ContactPerson specified? If not, set it to empty. if (customer.Addresses.Count == 0) contact = ""; else contact = customer.Addresses[0].ContactPerson; insertStatement = "INSERT IG003 VALUES ('" + firstContactSalesperson + "', '" + lastContactSalesperson + "', '" + contact + "', '" + lastContactDate + "', '" + firstContactDate + "', '" + customer.Name + "', '" + customer.Key.Id + "')"; command.CommandText = insertStatement; rowsAffected = command.ExecuteNonQuery(); } // Close the SQL connection sqlConnection.Close(); } } }

WEB

SERVICE

PROGRAMMERS

GUIDE

103

PA RT

E XT E N DI N G

T HE

WE B

S ER V IC E

Sample: ValidatingForUpdate event handler method

The following C# example shows the ValidatingForUpdate event handler method used to validate contact history information that is being updated as extended data for a customer object. The event handler examines the Extension objects passed along with the customer. If one of the Extension objects has the ExtensionId value ContactHistory, the event handler will process it. After extracting the XML element from the Extension object, the two Salesperson ID values included in the extended data are validated. If the Salesperson ID values cannot be validated, validation errors are added to the ValidationResults object that was passed into the event handler.
// Declare private variable of type Microsoft.Dynamics.Common.Connection private static Connection connection; public static void ValidateUpdateContactHistory(object sender, BusinessObjectValidateForUpdateEventArgs e) { bool found; string firstContactDate; string firstContactSalesperson; string lastContactDate; string lastContactSalesperson; string selectStatement; Customer customer; Extension ContactHistoryExtension = new Extension(); if (e.BusinessObject.GetType() == typeof(Customer)) { customer = (Customer)e.BusinessObject; // Look at the Extension list passed along found = false; foreach (Extension ext in customer.Extensions) { if (ext.ExtensionId == "ContactHistory") { ContactHistoryExtension = ext; found = true; break; } } if (found == true) { // Found an extension, so it should be processed XmlElement contactHistory; contactHistory = ContactHistoryExtension.DocExtension; XmlNodeList nodeList; nodeList = contactHistory.ChildNodes; // First contact date firstContactDate = nodeList[0].InnerText.ToString(); // First contact salesperson firstContactSalesperson = nodeList[1].InnerText.ToString(); // Last contact date lastContactDate = nodeList[2].InnerText.ToString();

104

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 8

EX T EN S I O N

A S S E M B L Y

// Last contact salesperson lastContactSalesperson = nodeList[3].InnerText.ToString(); // Get the connection to the database for the current company connection = Connection.GetInstance(); SqlCommand command = new SqlCommand(); command.Connection = (SqlConnection) connection.GetConnection(e.Context.OrganizationKey); SqlDataAdapter adapter = new SqlDataAdapter(command); DataTable table = new DataTable(); // Verify that the First Contact Salesperson and Last Contact // Salesperson are valid // The SQL statement to verify the First Contact Salesperson selectStatement = "SELECT SLPRSNID FROM RM00301 WHERE SLPRSNID = '" + firstContactSalesperson + "'"; command.CommandText = selectStatement; adapter.Fill(table); if (table.Rows.Count < 1) { // Add an exception, because the First Contact salesperson was // not found ValidationError validationError = new ValidationError(); validationError.Id = "1001"; validationError.Message = "Invalid First Contact Salesperson specified in Contact History."; validationError.ObjectType = typeof(Customer).ToString(); validationError.PropertyNames.Add("FirstContactSalesperson"); e.ValidationResult.Errors.Add(validationError); } // The SQL statement to verify the Last Contact Salesperson selectStatement = "SELECT SLPRSNID FROM RM00301 WHERE SLPRSNID = '" + lastContactSalesperson + "'"; command.CommandText = selectStatement; adapter.SelectCommand = command; table.Clear(); adapter.Fill(table); if(table.Rows.Count < 1) { // Add an exception, because the Last Contact salesperson was // not found ValidationResult validationResult = new ValidationResult(); ValidationError validationError = new ValidationError(); validationError.Id = "1002"; validationError.Message = "Invalid Last Contact Salesperson specified in Contact History."; validationError.ObjectType = typeof(Customer).ToString(); validationError.PropertyNames.Add("LastContactSalesperson"); e.ValidationResult.Errors.Add(validationError); } } } }

WEB

SERVICE

PROGRAMMERS

GUIDE

105

PA RT

E XT E N DI N G

T HE

WE B

S ER V IC E

Sample: Updating event handler method

The following C# example shows the Updating event handler method used to save the contact history information for a customer object. The event handler examines the Extension objects passed along with the customer. If one of the Extension objects has the ExtensionId value ContactHistory, the event handler will process it. The code extracts the contact history information from XML element of the Extension object. After retrieving a connection to the current companys database and storing it in the connection private variable, the event handler executes a SQL statement to save the updated contact history information for the customer into the IG003 table.
// Declare private variable of type Microsoft.Dynamics.Common.Connection private static Connection connection; public static void UpdateContactHistory(object sender, BusinessObjectUpdateEventArgs e) { bool found; int rowsAffected; string contact; string firstContactDate; string firstContactSalesperson; string lastContactDate; string lastContactSalesperson; string updateStatement; string insertStatement; Customer customer; Extension ContactHistoryExtension = new Extension(); if (e.BusinessObject.GetType() == typeof(Customer)) { customer = (Customer)e.BusinessObject; // Look at the Extension list passed along found = false; foreach (Extension ext in customer.Extensions) { if (ext.ExtensionId == "ContactHistory") { ContactHistoryExtension = ext; found = true; break; } } if (found == true) { // Found an extension, so it should be processed XmlElement contactHistory; contactHistory = ContactHistoryExtension.DocExtension; XmlNodeList nodeList; nodeList = contactHistory.ChildNodes; //First contact date firstContactDate = nodeList[0].InnerText.ToString(); //First contact salesperson firstContactSalesperson = nodeList[1].InnerText.ToString();

106

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 8

EX T EN S I O N

A S S E M B L Y

//Last contact date lastContactDate = nodeList[2].InnerText.ToString(); //Last contact salesperson lastContactSalesperson = nodeList[3].InnerText.ToString(); // Get the connection to the database for the current company connection = Connection.GetInstance(); // The SQL statement to update contact history information updateStatement = "UPDATE IG003 SET ContactSalespersonID1='" + firstContactSalesperson + "', FirstContactDate='" + firstContactDate + "', ContactSalespersonID2='" + lastContactSalesperson + "', LastContactDate='" + lastContactDate + "' WHERE CUSTNMBR = '" + customer.Key.Id + "'"; // Create the SQL connection SqlCommand command = new SqlCommand(updateStatement); SqlConnection sqlConnection = new SqlConnection (connection.GetConnectionString(e.Context.OrganizationKey)); command.Connection = sqlConnection; // Open the SQL connection sqlConnection.Open(); // Execute the SQL statement rowsAffected = command.ExecuteNonQuery(); if (rowsAffected == 0) { // The row did not exist, so try creating it. // Has a ContactPerson been specified? If not, set it to empty. if (customer.Addresses.Count == 0) contact = ""; else contact = customer.Addresses[0].ContactPerson; insertStatement = "INSERT IG003 VALUES ('" + firstContactSalesperson + "', '" + lastContactSalesperson + "', '" + contact + "', '" + lastContactDate + "', '" + firstContactDate + "', '" + customer.Name + "', '" + customer.Key.Id + "')"; command.CommandText = insertStatement; rowsAffected = command.ExecuteNonQuery(); } // Close the SQL connection sqlConnection.Close(); } } }

WEB

SERVICE

PROGRAMMERS

GUIDE

107

PA RT

E XT E N DI N G

T HE

WE B

S ER V IC E

Sample: Deleting event handler method

The following C# example shows the Deleting event handler method used to delete contact history information for a customer object. The event handler examines the customer object to retrieve the customer ID value. After retrieving a connection to the current companys database and storing it in the connection private variable, the event handler executes a SQL statement to delete the contact history information for the customer from the IG003 table.
// Declare private variable of type Microsoft.Dynamics.Common.Connection private static Connection connection; public static void DeleteContactHistory(object sender, BusinessObjectEventArgs e) { string deleteStatement; Customer customer; if (e.BusinessObject.GetType() == typeof(Customer)) { customer = (Customer)e.BusinessObject; // Get the connection to the database for the current company connection = Connection.GetInstance(); // The SQL statement to delete contact history information deleteStatement = "DELETE FROM IG003 WHERE CUSTNMBR = '" + customer.Key.Id + "'"; // Create the SQL connection SqlCommand command = new SqlCommand(deleteStatement); SqlConnection sqlConnection = new SqlConnection (connection.GetConnectionString(e.Context.OrganizationKey)); command.Connection = sqlConnection; // Open the SQL connection sqlConnection.Open(); // Execute the SQL statement command.ExecuteNonQuery(); // Close the SQL connection sqlConnection.Close(); } }

108

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 19:

Registering Events
To have events for the Dynamics GP web service be run, they must be registered. Information about registering events is divided into the following sections: Business object configuration file Modifying the configuration file Event registration example

Business object configuration file

The file named BusinessObjectFile.config contains the registrations for all of the additional events that are run by the Dynamics GP web service. This file is in XML format. It is located in the Dynamics GP web service bin folder, typically found in this this location: C:\Program Files\Microsoft Dynamics\GPWebServices\WebServices\Bin

DictionaryEntry elements
The BusinessObjectFile.config contains one <DictionaryEntry> element for each web service object that can have events registered for it. The web service objects that can raise events are those that inherit from BusinessObject. For convenience, the entries are in alphabetical order so they can be found easily. Not all objects have <DictionaryEntry> entries in this configuration file. For instance, the Customer object isnt included in the default version of this file. If you want to register events for an object that is not in the file, you will need to add a <DictionaryEntry> element for it. The easiest way to do this is by copying an existing element. The <Key> for the <DictionaryEntry> element is the complete name of the business object. The complete name has the prefix Microsoft.Dynamics.GP, followed by the name of the object. The name of the object corresponds to the class name you see in the Dynamics GP Web Service Reference. As an example, the complete name for the customer object is: Microsoft.Dynamics.GP.Customer.

Event elements
A <DictionaryEntry> element will have one or more <Event> elements, each describing an event for the business object. Each <Event> element has the following: EventName The name of the event being registered. This corresponds to one of the events listed in Event list on page 91. EventHandlerType Specifies the type of event handler needed for the event. The handler type for each event type is also listed in Event list on page 91. SoftwareVendor Identifies who added the event. Type The qualified name that indicates the namespace and static class containing the event handler method for the event. StaticMethod The name of the static method that will be run for the event. The signature for this static method must be appropriate for the type of event. Refer to Event handler methods on page 96 for more information.

WEB

SERVICE

PROGRAMMERS

GUIDE

109

PA RT

E XT E N DI N G

T HE

WE B

S ER V IC E

Assembly The name of the extension assembly that contains the static method for the event. Execute A boolean value that allows an event to be turned on or off. The value must be set to true for an event to be processed.

Modifying the configuration file

When modifying the configuration file, be aware of the following situations that can occur.

Restart after making changes

The BusinessObjectsFile.config is read when the Dynamics GP web service is started. If you make changes to this file while the web service is running, those changes will not be honored until the web service is restarted. An easy way to do this is by restarting Internet Information Services (IIS).

Configuration errors
Any configuration errors in the file, such as invalid class or method names, can cause system exceptions that prevent the Dynamics GP web service from running. When a web method is processed, system exceptions will be logged that describe the problem. Use the Exception Management Console to view the exceptions logged.

Issues with the extension assembly and web service events will be logged as exceptions.

Other modifications
Be aware that other modifications may have been made by other applications that are extending the Dynamics GP web service. The file may not be in the default state. Any automation you use to modify this file will need to account for this possibility.

Web service repair operations

When the Dynamics GP web service is repaired, the BusinessObjectsFile.config will be restored to its original state. Any changes made to it will be lost. If you make extensive changes to the file, you will want to make a backup after the changes are complete.

110

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

1 9

R E G I S T ER IN G

E V E N T S

Event registration example

The following example shows the entries made in the BusinessObjectFile.config to register events for the extension assembly that manages contact history information for the customer object. The events registered here correspond to the six sample event handler methods described in Chapter 18, Extension Assembly. The extension assembly in this example has the name ExtensionExample. The event handler static methods are located in the class named ContactHistory, in the namespace ExtensionExample. Each event specifies the appropriate event handler type for that event.
<DictionaryEntry> <Key xsi:type="xsd:string">Microsoft.Dynamics.GP.Customer</Key> <Value xsi:type="BusinessObjectConfiguration"> <Event> <EventName>Retrieved</EventName> <EventHandlerType> <Type>Microsoft.Dynamics.Common.BusinessObjectEventHandler </Type> <Assembly>Microsoft.Dynamics.Common</Assembly> </EventHandlerType> <EventHandler> <SoftwareVendor>MicrosoftDocumentation</SoftwareVendor> <Type>ExtensionExample.ContactHistory</Type> <StaticMethod>GetContactHistory</StaticMethod> <Assembly>ExtensionExample</Assembly> <Execute>true</Execute> </EventHandler> </Event> <Event> <EventName>ValidatingForUpdate</EventName> <EventHandlerType> <Type>Microsoft.Dynamics.Common.BusinessObjectValidateForUpdate EventHandler</Type> <Assembly>Microsoft.Dynamics.Common</Assembly> </EventHandlerType> <EventHandler> <SoftwareVendor>MicrosoftDocumentation</SoftwareVendor> <Type>ExtensionExample.ContactHistory</Type> <StaticMethod>ValidateUpdateContactHistory</StaticMethod> <Assembly>ExtensionExample</Assembly> <Execute>true</Execute> </EventHandler> </Event> <Event> <EventName>Updating</EventName> <EventHandlerType> <Type>Microsoft.Dynamics.Common.BusinessObjectUpdate EventHandler</Type> <Assembly>Microsoft.Dynamics.Common</Assembly> </EventHandlerType> <EventHandler> <SoftwareVendor>MicrosoftDocumentation</SoftwareVendor> <Type>ExtensionExample.ContactHistory</Type> <StaticMethod>UpdateContactHistory</StaticMethod>

WEB

SERVICE

PROGRAMMERS

GUIDE

111

PA RT

E XT E N DI N G

T HE

WE B

S ER V IC E

<Assembly>ExtensionExample</Assembly> <Execute>true</Execute> </EventHandler> </Event> <Event> <EventName>ValidatingForCreate</EventName> <EventHandlerType> <Type>Microsoft.Dynamics.Common.BusinessObjectValidate EventHandler</Type> <Assembly>Microsoft.Dynamics.Common</Assembly> </EventHandlerType> <EventHandler> <SoftwareVendor>MicrosoftDocumentation</SoftwareVendor> <Type>ExtensionExample.ContactHistory</Type> <StaticMethod>ValidateCreateContactHistory</StaticMethod> <Assembly>ExtensionExample</Assembly> <Execute>true</Execute> </EventHandler> </Event> <Event> <EventName>Creating</EventName> <EventHandlerType> <Type>Microsoft.Dynamics.Common.BusinessObjectEventHandler </Type> <Assembly>Microsoft.Dynamics.Common</Assembly> </EventHandlerType> <EventHandler> <SoftwareVendor>MicrosoftDocumentation</SoftwareVendor> <Type>ExtensionExample.ContactHistory</Type> <StaticMethod>CreateContactHistory</StaticMethod> <Assembly>ExtensionExample</Assembly> <Execute>true</Execute> </EventHandler> </Event> <Event> <EventName>Deleting</EventName> <EventHandlerType> <Type>Microsoft.Dynamics.Common.BusinessObjectEventHandler </Type> <Assembly>Microsoft.Dynamics.Common</Assembly> </EventHandlerType> <EventHandler> <SoftwareVendor>MicrosoftDocumentation</SoftwareVendor> <Type>ExtensionExample.ContactHistory</Type> <StaticMethod>DeleteContactHistory</StaticMethod> <Assembly>ExtensionExample</Assembly> <Execute>true</Execute> </EventHandler> </Event> </Value> </DictionaryEntry>

112

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 20:

Using Web Service Extensions

Application that access objects through the Dynamics GP web service will have to work with the additional data that is included in the ExtensionList collection for each object. The information presented here provides examples that demonstrate how this is done. The following items are discussed: Retrieving extension data Creating or updating extension data

Retrieving extension data

The ExtensionList collection is available for every web service object that inherits from the BusinessObject class. When an application retrieves an object from the web service, it should examine the ExtensionList collection to find whether any additional data is available in the Extension objects contained in the collection. The application should examine the ExtensionId parameter of each Extension object to find out what data is included in the extension. For example, assume the Customer object was extended to include contact history information. An Extension object with the ExtensionId value ContactHistory could be included with the customer object when the object was retrieved. The application retrieving the customer object would look in the ExtensionList collection for this additional data. Once the Extension object is found, the application will use the DocExtension property to retrieve the XML element that contains the additional data. In this example, the contact history XML element has the following format:
<ContactHistory> <FirstContactDate>6/6/1999 12:00:00 AM</FirstContactDate> <FirstContactSalesperson>NANCY B.</FirstContactSalesperson> <LastContactDate>3/1/2006 12:00:00 AM</LastContactDate> <LastContactSalesperson>ERIN J.</LastContactSalesperson> </ContactHistory>

It is the responsibility of developer who extended the web service to provide information about the format of the XML element containing the extended data. The following C# example demonstrates retrieving the contact history information that is being included with the Customer object in the ExtensionList collection. Note how the ExtensionList collection is examined to determine whether the contact history information has been included. The XML element containing the contact history data is processed to retrieve the individual items.
using System; using System.Collections.Generic; using System.Text; using System.Xml; using DynamicsGPWebServiceSample.DynamicsGPService; namespace DynamicsGPWebServiceSample { class Program { static void Main(string[] args)

WEB

SERVICE

PROGRAMMERS

GUIDE

113

PA RT

E XT E N DI N G

T HE

WE B

S ER V IC E

{ CompanyKey companyKey; Context context; Customer customer; CustomerKey customerKey; string firstContactDate; string firstContactSalesperson; string lastContactDate; string lastContactSalesperson; // Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP(); // Make sure that default credentials are being used wsDynamicsGP.UseDefaultCredentials = true; // Create a context with which to call the web service context = new Context(); // Specify which company to use (lesson company) companyKey = new CompanyKey(); companyKey.Id = (-1); // Set up the context context.OrganizationKey = (OrganizationKey)companyKey; context.CultureName = "en-US"; // Create a customer key customerKey = new CustomerKey(); customerKey.Id = "WORLDENT0001"; // Retrieve the customer object customer = wsDynamicsGP.GetCustomerByKey(customerKey, context); // Look for the contact history extension foreach (Extension ext in customer.Extensions) { if (ext.ExtensionId == "ContactHistory") { XmlElement contactHistory; contactHistory = customer.Extensions[0].DocExtension; XmlNodeList nodeList; nodeList = contactHistory.ChildNodes; //First contact date firstContactDate = nodeList[0].InnerText.ToString(); //First contact salesperson firstContactSalesperson= nodeList[1].InnerText.ToString(); //Last contact date lastContactDate = nodeList[2].InnerText.ToString(); //Last contact salesperson lastContactSalesperson = nodeList[3].InnerText.ToString();

114

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

2 0

U S I N G

W E B

S E R V I C E

E X T EN S I O N S

} } } } }

Creating or updating extension data

When an application uses the Dynamics GP web service to create a new object or update an existing object that has additional data included in the ExtensionList collection, it is the responsibility of the application to maintain this additional data. When creating new objects, the application must add the necessary Extension objects to the ExtensionList collection. When updating objects, the application must be sure the Extension objects in the collection contain the necessary information. For instance, in the example discussed in Retrieving extension data on page 113, the Customer object has been extended to include contact history information in an extension with the ExtensionId value ContactHistory. The XML element containing this information has the following format:
<ContactHistory> <FirstContactDate>6/6/1999 12:00:00 AM</FirstContactDate> <FirstContactSalesperson>NANCY B.</FirstContactSalesperson> <LastContactDate>3/1/2006 12:00:00 AM</LastContactDate> <LastContactSalesperson>ERIN J.</LastContactSalesperson> </ContactHistory>

The following C# example demonstrates creating the contact history information that is being included with the Customer object in the ExtensionList collection. An XML element is created that contains the contact history information. A new Extension object is created with the ExtensionId value ContactHistory. The XML element containing the contact history data is added as the DocExtension for the object. Finally, the new customer object is saved.
using System; using System.Collections.Generic; using System.Text; using System.Windows.Forms; using DynamicsGPWebServiceSample.DynamicsGPService; using System.Xml; using System.Globalization; namespace DynamicsGPWebServiceSample { class Program { static void Main(string[] args) { CompanyKey companyKey; Context context; Customer customer; CustomerKey customerKey; Policy customerPolicy; DateTime today;

WEB

SERVICE

PROGRAMMERS

GUIDE

115

PA RT

E XT E N DI N G

T HE

WE B

S ER V IC E

XmlDocument doc; XmlElement contactHistoryXML; XmlElement firstContactDateXML; XmlElement firstContactSalespersonXML; XmlElement lastContactDateXML; XmlElement lastContactSalespersonXML; XmlText text; // Create an instance of the web service DynamicsGP wsDynamicsGP = new DynamicsGP(); // Make sure that default credentials are being used wsDynamicsGP.UseDefaultCredentials = true; // Create a context with which to call the web service context = new Context(); // Specify which company to use (lesson company) companyKey = new CompanyKey(); companyKey.Id = (-1); // Set up the context context.OrganizationKey = (OrganizationKey)companyKey; context.CultureName = "en-US"; // Create a new customer object customer = new Customer(); // Create a customer key customerKey = new CustomerKey(); customerKey.Id = "CONTOSO"; customer.Key = customerKey; // Set properties for the new customer customer.Name = "Contoso, Ltd"; // Customer Address Key CustomerAddressKey customerAddressKey = new CustomerAddressKey(); customerAddressKey.CustomerKey = customerKey; customerAddressKey.Id = "PRIMARY"; // Customer Address List with Contact Person CustomerAddress[] customerAddresses = new CustomerAddress[1]; customerAddresses[0] = new CustomerAddress(); customerAddresses[0].Key = customerAddressKey; customerAddresses[0].ContactPerson = "Steve"; customer.DefaultAddressKey = customerAddressKey; customer.Addresses = customerAddresses; // Set today's date today = DateTime.Today; // Get the create policy for the customer customerPolicy = wsDynamicsGP.GetPolicyByOperation ("CreateCustomer", context);

116

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

2 0

U S I N G

W E B

S E R V I C E

E X T EN S I O N S

// Add the Contact History (extended data) for the new customer // Make a new Extension Extension ext = new Extension(); ext.ExtensionId = "ContactHistory"; // Make the XML extension document doc = new XmlDocument(); contactHistoryXML = doc.CreateElement("ContactHistory"); // First Contact Date firstContactDateXML = doc.CreateElement("FirstContactDate"); text = doc.CreateTextNode(today.ToString("G", DateTimeFormatInfo.InvariantInfo)); firstContactDateXML.AppendChild(text); contactHistoryXML.AppendChild(firstContactDateXML); // First Contact Salesperson firstContactSalespersonXML = doc.CreateElement("FirstContactSalesperson"); text = doc.CreateTextNode("PAUL W."); firstContactSalespersonXML.AppendChild(text); contactHistoryXML.AppendChild(firstContactSalespersonXML); // Last Contact Date lastContactDateXML = doc.CreateElement("LastContactDate"); text = doc.CreateTextNode(today.ToString("G", DateTimeFormatInfo.InvariantInfo)); lastContactDateXML.AppendChild(text); contactHistoryXML.AppendChild(lastContactDateXML); // Last Contact Salesperson lastContactSalespersonXML = doc.CreateElement("LastContactSalesperson"); text = doc.CreateTextNode("PAUL W."); lastContactSalespersonXML.AppendChild(text); contactHistoryXML.AppendChild(lastContactSalespersonXML); // Add the extension to the Customer object ext.DocExtension = contactHistoryXML; Extension[] extensionList = new Extension[1]; extensionList[0] = ext; customer.Extensions = extensionList; // Create the customer wsDynamicsGP.CreateCustomer(customer, context, customerPolicy); } } }

WEB

SERVICE

PROGRAMMERS

GUIDE

117

118

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

PART 5: WEB SERVICE SAMPLES

Part 5: Web Service Samples

This portion of the documentation describes several sample applications that demonstrate how to use the Dynamics GP web service. The following samples are are discussed: Chapter 21, Sales Documents, describes a sample that retrieves lists of sales documents for a specific customer. Chapter 22, Import GL Transactions, describes a sample that imports general ledger transactions into Microsoft Dynamics GP. Chapter 23, Update Customers, describes a sample that updates customer records in Microsoft Dynamics GP.

These samples have been created using Visual Studio 2005. To use them with Visual Studio 2008, allow the upgrade wizard to convert each project when you open the solution file.

120

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 21:

Sales Documents
The Sales Document sample is a C# .NET application that retrieves data using Web Services for Microsoft Dynamics GP. The application displays sales document summary information for a customer. The following topics are discussed: Overview of Sales Documents sample Running the Sales Documents sample How the Sales Documents sample works Web Service use for Sales Documents sample

Overview of Sales Documents sample

This sample application shows how web service methods can be used to populate the fields of a user interface. The application displays company, customer, and sales document data, and updates the displayed data to reflect choices made by the user.

This is the list of sales documents for the customer.

The sample application requires the computer to have Visual Studio 2005 or later and the 2.0 .NET framework installed.

Running the Sales Documents sample

To run this sample application, perform the following steps: 1. Verify the Dynamics GP web service. To ensure Dynamics GP web service is installed and ready, enter the web service URL into the address bar of the web browser. The default web service URL is: http://machine_name/DynamicsGPWebServices/DynamicsGPService.asmx If the browser displays a list of web methods, the web service is ready to use with the sample application. If an error occurs, correct the problem and retry the web service URL.

WEB

SERVICE

PROGRAMMERS

GUIDE

121

PA RT

W E B

S E R V I C E

S A M P L E S

2. Start Visual Studio and open the solution file for the sample application. The solution file for this sample is named SalesDocumentSample.sln. The solution file is in the SalesDocument folder inside the Samples folder. 3. Update the web reference. Open Visual Studio's Solution Explorer and select the Web References folder. Select the DynamicsGPService web reference to view its properties. Change the Web Reference URL property to use the URL for the Dynamics GP web service. 4. Choose Start Debugging from the Debug menu. To build the solution, choose Start Debugging in the Debug menu. The sales document sample application loads the web service proxy which may take several seconds to complete. The application will not be visible until loading the web service proxy has completed. 5. Select a company from the Company drop-down list. Once a company is selected, the Customer drop-down list contains all the customers for that company. 6. Select a customer from the Customer drop-down list. After a customer is selected, the data grid displays all the sales documents for that customer. 7. Mark one or more of the check boxes in the Sales Documents list. Use the check boxes to restrict the types of sales documents displayed in the data grid. 8. Click the Refresh button. The Refresh button forces the data grid to update and display only the specified document types for the customer.

How the Sales Documents sample works

The application consists of two classes: The CustomerSalesForm user interface class manages displaying data and selecting records by the user. The DataManagement class retrieves data using web service web methods and makes the data available for display by the user interface class. The DataManagement class also shows how to place the summary list data returned by a web method into a dataset. The user interface's list and grid controls use the datasets as the source of the data they display. The application uses basic error handling techniques to detect exceptions and displays all error information in message boxes.

Web Service use for Sales Documents sample

The sample application uses several Dynamics GP web service objects and methods. The DataManagement class loads a proxy class named wsDynamicsGP that allows web service objects and methods to be used. The application loads the wsDynamicsGP proxy class using information provided by the web service.

122

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

2 1

S A L E S

D O C U M E N T S

Web Service Methods

The DataManagement class constructor creates the web service proxy and creates a context object. The DataManagement constructor also sets the credentials for the web service proxy to use the default credentials. The GetCompanyList method retrieves the list of all available companies. The method uses a CompanyCriteria object along with a BetweenRestrictionOfNullableOfInt32 restriction object to retrieve a list of company summary objects. The GetCustomerList method retrieves a list of customers for a specified company. The company is designated by setting the OrganizationKey property of the Context object. The method uses a CustomerCriteria object and a LikeRestrictionOfString object to retrieve the list of customer summary objects. The GetSalesDocumentListAsync method retrieves a list of sales documents for the specified customer. The method uses a SalesDocumentCriteria object with a ListRestrictionOfNullableOfSalesDocumentType restriction object and a LikeRestrictionOfString object to retrieve the requested sales document summary objects. The asynchronous web method ensures the user interface remains responsive even when retrieving the sales document list becomes a lengthy operation. A GetSalesDocumentListCompletedEventHandler object specifies the method that receives the web service response to the asynchronous GetSalesDocumentListAsync method. The method wsDynamics GP_GetSalesDocumentListCompleted places the data supplied by the web service into a dataset and updates the user interface's data grid.

WEB

SERVICE

PROGRAMMERS

GUIDE

123

124

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 22:

Import GL Transactions
The Import GL Transaction sample is a C# .NET application that creates new GL transactions from an XML source file. The application uses a Windows Forms-based interface to identify the XML source file and to report progress. The following topics are discussed: Overview of Import GL Transactions sample Running the Import GL Transactions sample How the Import GL Transactions sample works Web Service use for Import GL Transactions sample

Overview of Import GL Transactions sample

This sample application shows how web service methods create data in Microsoft Dynamics GP. The sample application includes a source file that contains an XML representation of three GL transactions. The application reads the XML file, creates an XML document, and uses the XML document to create new GL transactions.

Click the file button to specify the location of the XML file.

Click the Begin button to import the GL transactions.

The sample XML file contains only data required by this solution. This allows the sample to focus on how to use web services in a batch handling solution, and to omit steps to validate the XML and identify missing data. The sample application requires the computer to have Visual Studio 2005 or later and the 2.0 .NET framework installed.

Running the Import GL Transactions sample

To run the application, perform the following steps. 1. Verify the Dynamics GP web service. To ensure the Dynamics GP web service is installed and ready, enter the web service URL into the address bar of the web browser. The default web service URL is: http://machine_name/DynamicsGPWebServices/DynamicsGPService.asmx If the browser displays a list of web methods the web service is ready to use with the sample application. If an error occurs, correct the problem and retry the web service URL. 2. Start Visual Studio and open the solution file for the sample application. The solution file for this sample is named BatchApplication.sln. The solution file is in the ImportGLTransactions folder inside the Samples folder.

WEB

SERVICE

PROGRAMMERS

GUIDE

125

PA RT

W E B

S E R V I C E

S A M P L E S

3. Update the web reference. Open Visual Studio's Solution Explorer and select the Web References folder. Select the DynamicsGPService web reference to view its properties. Change the Web Reference URL property to use the URL for the Dynamics GP web service. 4. Choose Start Debugging from the Debug menu. To build the solution, choose Start Debugging in the Debug menu. 5. Click the Open file button. An open file dialog box appears. Navigate to the file named TransactionBatchFile.xml located in the BatchApplication folder found inside the ImportGLTransactions folder. 6. Select the XML source file. Select the TransactionBatchFile.xml file. The textbox on the user interface displays the XML file's contents. 7. Click the Begin button. This button starts the batch processing of the GL transaction from the XML file.

How the Import GL Transactions sample works

The application consists of three classes: The TransactionProcessor user interface class manages the display of data, and reports the progress of the batch. The XmlManager class opens the XML file and creates an XML document object. The DataManager class uses XML and the web services CreateGLTransaction method to create a GL transaction in Microsoft Dynamics GP. The TransactionProcessor class handles all errors and logs error messages to a file. TransactionProcessor places the log file in the same directory as the XML source file, and names the log file TransactionProccessorErrorLog.txt.

Web Service use for Import GL Transactions sample

The sample application uses several Dynamics GP web service objects and methods. The DataManager class loads a proxy class named wsDynamicsGP that allows web service objects and methods to be used. The application loads the wsDynamicsGP proxy class using information provided by the web service.

Web Service Methods

The DataManager class constructor loads the web services proxy and creates a context object. DataManager constructor also sets the credentials for the web service proxy to use the default credentials. The XML for each transaction specifies the company ID for the transaction. DataManager re-sets the context object's OrganizationKey property during each transaction to ensure the transaction is applied to the specified company. The CreateGLTransaction method creates the transaction in Microsoft Dynamics GP. The method uses a GL transaction object to represent the details of the transaction. The GLTransaction object requires a GLTransactionKey object to identify the new transaction. The GL transaction object uses a collection of GLTransactionLine objects to specify the accounts for the transaction. GLTransactionLines require GLTransactionLineKey, GLAccountNumberKey, and MoneyAmount objects to specify the debit and credit accounts and the amounts for a transaction.

126

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Chapter 23:

Update Customers
The Update Customers sample is a C# .NET application that updates existing customer information. The application uses a Windows Forms-based interface to add or update comments about a customer. Overview of Update Customers sample Running the Update Customers sample How the Update Customers sample works Web Service use for Update Customers sample

Overview of Update Customers sample

This sample application shows how web service methods can update data in Microsoft Dynamics GP. The application provides the ability to edit the comment associated with a customer.

Click the Connect button to retrieve the list of companies.

The comment editing process begins with the selection of a company and one of its customers. The Comment textbox displays the existing comment and allows the comment text to be edited. The Update button saves the new comment in Microsoft Dynamics GP. The sample application requires the computer to have Visual Studio 2005 or later and the 2.0 .NET framework installed.

Running the Update Customers sample

To run the application, perform the following steps. 1. Verify the Dynamics GP web service. To ensure Dynamics GP web service is installed and ready, enter the web service URL into the address bar of the web browser. The default web service URL is: http://machine_name/DynamicsGPWebServices/DynamicsGPService.asmx If the browser displays a list of web methods the web services are ready to use with the sample application. If an error occurs, correct the problem and retry the web service URL. 2. Start Visual Studio and open the solution file for the sample application. The solution file for this sample is named CustomerUpdate.sln. The solution file is in the UpdateCustomers folder inside the Samples folder. 3. Update the web reference. Open Visual Studio's Solution Explorer and select the Web References folder. Select the DynamicsGPService web reference to view its properties. Change the Web Reference URL property to use the URL for the Dynamics GP web service.

WEB

SERVICE

PROGRAMMERS

GUIDE

127

PA RT

W E B

S E R V I C E

S A M P L E S

4. Choose Start Debugging from the Debug menu. To build the solution, choose Start Debugging in the Debug menu. 5. Click the Connect button. The Connect button loads the web service proxy which may take several seconds to complete. The Company drop-down list displays the list of available companies. 6. Select a company from the Company drop-down list. Once a company is selected, the Customer drop-down list contains all the customers for that company. 7. Select a customer from the Customer drop-down list. After a customer is selected, the Comment textbox displays any existing comment information. 8. Add or edit the comment information. Edit the existing comment or add a new comment. 9. Click the Update button. The Update button saves the new comment to Microsoft Dynamics GP.

How the Update Customers sample works

The application consists of two classes. The CustomerUpdate user interface class manages the display of data and the selection or editing of customer data. The WebServiceManager class uses web service methods to retrieve data and to save the comment information. The WebServiceManager class also shows how to place the summary list data returned by a web method into a dataset. The user interface's drop-down list controls use the datasets as the source of the data they display. The application uses basic error handling techniques to detect exceptions and displays all error information in message boxes.

Web Service use for Update Customers sample

The sample application uses several Dynamics GP web service objects and methods. The WebServiceManager class loads a proxy class named wsDynamicsGP that allows web service objects and methods to be used. The application loads the wsDynamicsGP proxy class using information provided by the web service.

Web Service Methods

The WebServiceManager class constructor loads the Web Services proxy and creates a context object. The WebServiceManager constructor also sets the credentials for the web service proxy to use the default credentials. The GetCompanyList method retrieves the list of all available companies. The method uses a CompanyCriteria object along with a BetweenRestrictionOfNullableOfInt32 restriction object to retrieve a list of company summary objects. The GetCustomerList method retrieves a list of customers for a specified company. The company is designated by setting the OrganizationKey property of the Context object. The method uses a CustomerCriteria object and a LikeRestrictionOfString object to retrieve the list of customer summary objects.

128

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

C H A P T E R

2 3

U P D A T E

C U S T O M E R S

The GetCustomerByKey method retrieves a single customer object. The Id property of the CustomerKey object is used to specify the customer to retrieve. A customer object and customer key object identify the customer to be updated. The contents of the user interface's Comment textbox populates the customer object's Comment1 property. The UpdateCustomer method saves the updated customer object to the database.

WEB

SERVICE

PROGRAMMERS

GUIDE

129

130

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

APPENDIX

Appendix
The following appendix is included for this manual: Appendix A, Culture Codes, lists the culture codes used for the Context object in the Dynamics GP web service. Appendix B, ISO Currency Codes, lists the standard 3-letter ISO currency codes used to identify currency types in the Dynamics GP web service. Appendix C, Troubleshooting, provides information about resolving issues you may encounter with Web Services for Microsoft Dynamics GP.

132

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Appendix A:

Culture Codes
The following chart lists the culture codes commonly used for the Context object in the Dynamics GP web service.
Culture
"" (empty string) de-DE da-DK nl-BE nl-NL en-AU en-CA en-NZ en-GB en-US fr-CA fr-FR pl-PL pt-BR es-CO es-MX es-ES

Language-Country/Region
invariant culture German - Germany Danish - Denmark Dutch - Belgium Dutch - The Netherlands English - Australia English - Canada English - New Zealand English - United Kingdom English - United States French - Canada French - France Polish - Poland Portuguese - Brazil Spanish - Colombia Spanish - Mexico Spanish - Spain

WEB

SERVICE

PROGRAMMERS

GUIDE

133

134

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Appendix B:

ISO Currency Codes

The following chart lists the standard 3-letter ISO currency codes used to identify currency types in the Dynamics GP web service.
ISO Code
AUD CAD EUR JPY MXN NZD PLN SGD ZAR GBP USD

Country/Region
Australia Canada European Union Japan Mexico New Zealand Poland Singapore South Africa United Kingdom United States

Currency
Dollars Dollars Euros Yen Pesos Dollars Zlotych Dollars Rand Pounds Dollars

WEB

SERVICE

PROGRAMMERS

GUIDE

135

136

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Appendix C:

Troubleshooting
You may encounter problems that prevent the Dynamics GP web service from working properly. The following is a list of common issues you may encounter, and possible solutions. Exceptions The stored data differs from what was submitted Performance Web service does not respond Security Policy

Exceptions
The following exceptions may occur when working with the Dynamics GP web service:

An unhandled system exception occurs

A system exception occurs when an unexpected event prevents the normal completion of a web method. A system exception returns the following SOAP message: "The application encountered an unhandled system exception. Contact your system administrator for details." The Dynamics GP Web Service Exceptions console logs the details surrounding each system exception. Refer to Chapter 12, Exceptions, for a description of the Exceptions console. The additional information the console provides may help identify the source of the system exception. Another source of exception information is the web servers system logs. Use the system event viewer to open and review the system logs. Relevant errors, warnings and informational updates for the Dynamics GP web service may be found in the Application log. Additional information surrounding system exceptions or other unexpected results can be obtained by enabling web service tracing. Tracing logs information to a file while the web service performs operations. All tracing occurs on the web server.

Web service tracing

A setting in the web service web.config configuration file enables web service tracing. The web.config file can be found in the folder where the web service is installed. The following example shows the default location of the web service web.config file: c:\Program Files\Microsoft Dynamics\GPWebServices\WebServices

WEB

SERVICE

PROGRAMMERS

GUIDE

137

A P PE N D I X

T R O U B L ES HO O T I N G

To enable web service tracing, edit the web.config file and add the following <system.diagnostic> element between the web.config files </ system.web> and </ configuration> nodes:
<system.diagnostics> <switches> <add name="ApplicationTraceSwitch" value="4" /> </switches> <trace autoflush="false" indentsize="4"> <listeners> <add name="myListener" type="System.Diagnostics.TextWriterTraceListener" initializeData="DGPWSTrace.log" /> </listeners> </trace> </system.diagnostics>

This will create a log file name DGPWSTrace.log in the same folder as the web.config file. The value assigned to the trace switch enables or disables tracing. It also controls the level of detail recorded in the log. The following table contains the possible values for the trace switch:
Value
0 1 2 3 4

Description
Disable logging. Log only error messages. Log warning messages and error messages. Log informational messages, warning messages, and error messages. Log all messages including informational messages, warning messages, and error messages.

To disable tracing, set the trace switch values to value="0" or remove the switches and listeners from the web.config file. Tracing should be disabled immediately after completing your research. If tracing is allowed to run, web service performance will diminish and the log file will quickly become quite large. Use a text editor to view the contents of the log. The log contains a series of text messages detailing the activities performed by the web service. Look for actions and operations surrounding the error. The logs help identify the actions of the service leading to the exception and may contain additional exception information that is not available in the exception console.

eConnect tracing
To trace eConnect activity related to the web services, you must add listeners for each of the operation types you want to log. You can choose to log create operations, get operations, or both. Any update operations are logged the same way as create operations. To log eConnect events, place the following <system.diagnostic> element between the web.config files </ system.web> and </ configuration> nodes:

138

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

A PP E N D I X

TR O U B L E S H O O T I N G

<system.diagnostics> <switches> <add name="eConnectXMLTraceSwitch" value="3" /> <add name="ApplicationTraceSwitch" value="1" /> </switches> <trace autoflush="false" indentsize="0"> <listeners> <add name="eConnectCreateListener" type="Microsoft.Dynamics.Common.EConnectCreateXmlTraceListener, Microsoft.Dynamics.Common.Types" initializeData="c:\eConnectCreateOperations.log" /> <add name="eConnectGetListener" type="Microsoft.Dynamics.Common.EConnectGetXmlTraceListener, Microsoft.Dynamics.Common.Types" initializeData="c:\eConnectGetOperations.log" /> </listeners> </trace> </system.diagnostics>

This addition to the web.config creates two log files in the C:\ location. The first is named eConnectCreateOperations.log, which logs all create operations performed by eConnect. Any update operations are also included in this log. The second file is named eConnectGetOperations.log. This file logs all of the get operations performed by eConnect. You may need to give the user identity that runs the web service write privileges to the specified folder. The value assigned to the eConnextXMLTraceSwitch specifies which types of operations will be logged. The following table lists the possible values for this trace switch:
Value
1 2 3

Description
Log only create operations. Log only get operations. Log both create and get operations.

You must include the ApplicationTraceSwitch in this configuration setting. It must be set to a valid value (1 to 4) for eConnect tracing to produce output. This is the same trace switch setting used when logging web service events.

The security object does not exist

When viewing a system exception in the exception console, you may find the following message: "Microsoft.Dynamics.Security.NonExistentSecurityObjectException: The security object does not exist. Key = 20" The message indicates the web method call attempted to access a company that does not exist. The company is specified by the OrganizationKey property of the Context object. The "Key = 20" in the example indicates the OrganizationKey was set to a Company ID of 20. This exception also occurs if the OrganizationKey is empty. To eliminate this exception, ensure the OrganizationKey is always populated with a valid Company ID. The OrganizationKey should be null only when retrieving system-level information like the list of companies in Microsoft Dynamics GP.

WEB

SERVICE

PROGRAMMERS

GUIDE

139

A P PE N D I X

T R O U B L ES HO O T I N G

HTTP status 404: Not Found

When an application attempts to use the web service and the service is not available, the application receives the following error message: "The request failed with HTTP status 404: Not Found" There are a number of potential resolutions: Ensure the web server is running and accessible from the client computer. Ensure the Dynamics GP web service has been successfully installed and is available on the web server. Ensure the application is using the correct URL for the Dynamics GP web service.

If the URL for the web service has changed, applications need to use the new URL. An application typically stores the web service URL in the application setting section of its configuration file. The following example shows the URL from a configuration file:
<applicationSettings> <DynamicsGPWebServiceSample.Properties.Settings> <setting name="DynamicsGPWebServiceSample" serializeAs="String"> <value> http://server/DynamicsGPWebServices/DynamicsGPService.asmx </value> </setting> </DynamicsGPWebServiceSample.Properties.Settings> </applicationSettings>

A web application stores the web service URL in the <appSettings> section of its Web.Config file. The following example shows the URL for a web application:
<appSettings> <add key="DynamicsGPWebService.GreatPlainsService" value="http://server/DynamicsGPWebService/DynamicsGPService.asmx"/> </appSettings>

Ensure the URL correctly specifies the location of the Dynamics GP web service. If the URL does not identify the web service, you will need to update the URL. Visual Studio can update the configuration file. Open the applications project file in Visual Studio. Update the URL property of the web reference and rebuild the application. Test the application to verify the error no longer occurs. A text editor can also update the URL in the configuration file. Always create a backup copy of the configuration file prior to editing the file. Update the value in the configuration file to the correct URL for the web service. Save the changes and test the application to verify the error no longer occurs.

Insufficient authorization to perform this action

When 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 security authorization to perform the requested operation. Logging on as a user with the necessary security authorization should resolve the exception. Another option is to assign the current user to a role that includes the required security authorization.

140

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

A PP E N D I X

TR O U B L E S H O O T I N G

This error may also occur when using the working on behalf of another user" option. This option allows the user and role performing the operation to be different from the logged-on user. The exception occurs when the user specified by the WorkingOnBehalfOf property of the Context object does not have authorization to perform the requested operation. Use the Security console to view the role or roles assigned to the user. The working on behalf of another user option may also produce this exception if the current user that is attempting to work on behalf of another user has not been granted access to the Work on Behalf of Other Users task. Use the Security console to determine whether the user has been assigned the Work on Behalf of Other Users task and to assign the role to the user. Entity ID filtering is another possible source of this error. If the application is requesting filtered results, users can receive this error if they dont have access to the restricted operation used for the entity ID filtering. They may also receive this error if the entity ID assignment that maps a Windows User ID to a back office object ID cannot be found.

Business object not found

When viewing a system exception in the exception console, you may find the following message: "Business object not found." This will occur when a Get or Update operation specifies an object that could not be retrieved. Check the key value used to identify the business object to ensure it specifies an object that exists in Microsoft Dynamics GP. If the object is known to exist, check the Context used for the request. Ensure the OrganizationKey property of the Context object is using the correct Company ID for the object being retrieved.

The stored data differs from what was submitted

The following issues can produce data different from the properties in the submitted business object:

Policy-related changes
You find the data values written or updated were not what you expected after a Create or Update operation saves the object to the database. A policy and its behaviors may be controlling some characteristics of the operation. Refer to Chapter 13, Policy, for additional information on policies and behaviors. In some instances, the unexpected data changes occur when a specific policy instance associated with the users role does not run. Use the Dynamics Security console to view the users role assignments. If the user is assigned to more than one role, the web services will use the systems default policy instead of a specific policy instance associated with an assigned role. Review the specific behaviors associated with a policy by opening the Dynamics Security console and navigating to the policy. The middle-pane of the console will list the behaviors for the policy. Highlight a policy and select Properties from the Action menu in the right-pane. The Policy Instance Property window will display the behavior and behavior options. View the behavior options to determine whether the policy is the source of specific data change.

WEB

SERVICE

PROGRAMMERS

GUIDE

141

A P PE N D I X

T R O U B L ES HO O T I N G

Check the policy for a behavior option with a behavior type of External. An external policy allows the application calling the web method to specify a behavior option. If the application uses an external behavior, the applications behavior choice produces data that was not submitted by the user. eConnect tracing may help by showing the actual data sent to Dynamics GP. The Exceptions topic describes the steps to enable eConnect tracing. Review the eConnect trace log to see the data eConnect used to create or update the record in the Dynamic GP database.

Extension-related changes
Another source of unexpected data changes includes extensions to the web service. Refer to Part 4, Extending the Web Service, for additional information on extensions. Other applications may react to the update or create event and add or change object properties. Review the BusinessObjectFile.config file to determine whether any assemblies are registered for the events associated with a create or update operation.

Performance
The following are suggestions for ensuring optimum performance from the Dynamics GP web service:

Ensure optimum performance

To ensure optimum performance from Get List operations, whenever possible use object or summary object properties that correspond to indexed columns in the Dynamics GP database. The Dynamics GP Web Service Reference online help file specifies the properties that are indexed.

Minimize the number of web service instances

Applications using Dynamics GP web services should create web service instances only when necessary. Creating a new instance of the web service and loading the proxy can be a lengthy operation. The best performing applications avoid repeatedly deleting and re-instantiating the web service. For most applications, you should be able to instantiate a single web service object that can be used throughout the lifetime of the application. To work with more than one company, change the OrganizationKey of the Context object or create a separate Context object to specify each company.

Web service does not respond

The following issues can cause web service to stop responding:

Extensions
Web service extensions require changes to the BusinessObjectsFile.config to register the extension for a web service event. If the edit creates an error in the contents of the configuration file, the web service may no longer respond. Always make a backup copy of the BusinessObjectsFile.config prior to editing the file. Store the copy to a safe location. Use the backup copy to restore the web service if problems occur.

142

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

A PP E N D I X

TR O U B L E S H O O T I N G

If changes to the BusinessObjectsFile.config prevent a web method from responding, open the Exception Management Console to identify the source of the error. Edit the BusinessObjectsFile.config to correct the specified error. Restart Internet Information Services (IIS) to ensure the changed BusinessObjectsFile.config is used. Refer to Chapter 19, Registering Events, for additional information about the business object configuration file.

Web.config file changes

Changes made to the web service web.config configuration file can cause the web service to stop responding. If an error occurs while editing the web.config file the web service will become unavailable. Always make a backup copy of the web.config prior to editing the file. Store the copy to a safe location. Use the backup to restore the web service if problems occur. To restore the web service, review changes to the web.config file for missing or incomplete information.

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

A security authorization change is not used

A change occurs to a users security authorization to add or restrict access to a web service operation. Testing by that user reveals the ability to perform the specified operation remains unchanged. To optimize the responsiveness of web services, a memory cache stores the web service security settings. The security service reloads the cache at 20 minute intervals. Changes to security authorization will not take effect until they are loaded into the security cache. If testing of a new security authorization change does not immediately show the expected result, re-test the operation after 20 minutes. The delay allows the security service to update its security cache with your change. A reset of Internet Information Services (IIS) can force an immediate reload of the security cache. An IIS reset should be performed only after careful consideration of the impact it will have on current web service users.

The security service is not working

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

WEB

SERVICE

PROGRAMMERS

GUIDE

143

A P PE N D I X

T R O U B L ES HO O T I N G

Policy
The following is an issue that occurs when using policies with the Dynamics GP web service:

The expected policy is not used

The Create, Update, and Delete operations can use a policy to control the characteristics of an operation. The user role determines the specific policy instance used by the operation. If an operation does not use the expected policy, view the users role assignments in the Dynamics Security console. A user that has more than one role will always use the default policy for the operation. To ensure a specific policy is used with an operation, assign the user to a single role.

144

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Glossary
Behavior
One characteristic for the web service operation being performed. A policy object has a collection of behaviors.

User-assignable business objects

Those objects in Microsoft Dynamics GP that have identity information and can be associated with a Windows User ID. Examples include customers or salespeople.

Web reference
A URL that points to the .asmx file that defines the web service.

Criteria object
An object that contains the restrictions that define what is to be returned from a GetList method in the Dynamics GP web service.

Web service
A software system that provides data and services to other applications. Web services use standard Internet transport protocols such as Hypertext Transfer Protocol (HTTP) and standard XML-based document formats such as Simple Object Access Protocol (SOAP) to exchange information.

eConnect
A set of SQL stored procedures and supporting code used by integrating applications to access data in Microsoft Dynamics GP.

Entity ID assignments
For the Dynamics GP web service, the things that assign Windows User IDs to specific objects in Microsoft Dynamics GP that have identity information. See also User-assignable business objects.

Web service events

Events that occur for each step as an object in the web service is retrieved, created, updated, or deleted. Events can be used by web service extensions.

WSDL
Web Service Description Language. The XML-based language used to describe web services.

Extension assembly
An assembly that contains the processing code for a web service extension that is extending one or more business objects for the Dynamics GP web service.

External behavior
A behavior that can be specified by the application that is calling the web method for the Dynamics GP web service and passing the policy object.

Internal behavior
A behavior that can be specified by only the web service administrator.

Policy
A feature of the Dynamics GP web service that allows the web service administrator to control how business objects are created, updated, or deleted.

Policy instance
The set of behaviors for a policy, set a specific way for a particular role.

Proxy
A special set of classes that will act as a wrapper for the operations, objects, and enumerations defined by the web service.

SOAP
Simple Object Access Protocol. The XMLbased protocol used to communicate with a web service.

Summary object
An object that contains only the most important details of the main object. For example, the customer summary object contains only the most important details of the customer object. Summary objects are retuned by the GetList methods in the Dynamics GP web service.

WEB

SERVICE

PROGRAMMERS

GUIDE

145

146

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

Index
A
account numbers determining format of 26 length of 26 using in Dynamics GP web service 26 asynchronously calling web methods 79

B
base objects, described 19 basic restrictions described 44 example 44 behavior option finding in policy instance 70 parameters for 71 behaviors defined 145 described 11 external behaviors 11, 67 finding behavior option 70 finding in policy instance 70 setting selected behavior option 71 setting with code 70 internal behaviors 11, 67 setting selected behavior option 71 benefits, of web services 7 between restrictions described 45 example 45 business document objects described 19 user-assignable 73 BusinessObjectsFile.config configuration errors in 110 described 91, 109 editing 109 impact of Repair operation 110 modifications by other applications 110 modifying 110 structure of 109

configurations, for Dynamics GP web service 9 Connecting to the Web Service, chapter 15-18 context chapter 29-30 culture used 29 currency used 29 for web service call 29 organization 29 role used 30 WorkOnBehalfOf 30 conventions, in documentation 3 Create methods described 23, 33 example 33 Create policy described 34 example 35 retrieving 34 setting behaviors 35 Created, web service event 92 Creating sample event handler method 102 web service event 92 Creating Objects, chapter 33-38 credentials, for web service instance 18 criteria objects creating 41 defined 145 described 39 indexed columns 43 restrictions for 44 culture codes in web service context 29 list of for Context object 133 currency see also MoneyAmount values in web service context 29 ISO codes list 135

C
choice types described 27 determining types in 27 example 27 reading values from 28 writing values to 28 company, specifying with web service context 29 concurrency issues displaying messages for 52 example 52 for Update methods 52 when likely encountered 52

data types chapter 25-28 choice types 27 datetime values 25 decimal values 25 enumerations 26 integer values 25 MoneyAmount values 25 Percent values 26 standard types 25 string values 25 database transactions, events included in 91 date values, empty date values 25 datetime values, described 25 E eConnect decimal values defined 145 described 25 described 9 empty decimal values 25 DefaultingForCreate, web service event 91

DefaultingForDelete, web service event 92 DefaultingForUpdate, web service event 92 DefaultingForVoid, web service event 92 Delete methods described 23, 57 example 57 Delete policy described 58 example 58 retrieving 58 setting behaviors 58 Deleted, web service event 92 Deleting sample event handler method 108 web service event 92 Deleting or Voiding Objects, chapter 57-60 documentation, symbols and conventions 3 Dynamics GP web service architecture 9 capabilities 8 configurations 9 creating objects 33 data types 25 deleting objects 57 documentation for 21 enumerations 26 learning object model 21 not responding 142 object model 19 overview 7 policy 11 reference documentation 21 retrieving individual objects 39 retrieving list of summary objects 40 updating objects 47 URL 15 voiding objects 57 web reference 16 web service instance 18 WSDL file 15 Dynamics GP Web Service Reference, described 21 Dynamics GP Web Services Exceptions console, described 11 Dynamics Security Administration console creating entity ID assignments 73 described 10 illustration 10 Dynamics Security web service described 10 troubleshooting 143 DynamicsGPService.asmx 15

WEB

SERVICE

PROGRAMMERS

GUIDE

147

IN DEX

empty values for dates 25 for decimals 25 for integers 25 for MoneyAmounts 25 for Percents 26 for strings 25 entity ID assignments defined 145 described 73 entity ID filtering chapter 73-78 example 76 GetByKey operations described 74 GetList operations described 75 implementing 75 limitations 76 operations for 74 overview 73 roles for 74 Scope property 75 security settings for 74 setting up 73 tasks for 74 enumerations described 26 example 26 event handler argument types, list of for web service events 96 event handler methods event handler argument types 96 in extension assembly 96 properties passed with event arguments 97 writing code for 97 EventHandlerType, for web service events 91 events EventHandlerType 91 for web service operations 91 how processed for web service operations 91 inclusion in database transactions 91 list of 91 registering for web service operations 91 registration example 111 types of for web service operations 91 Exception console, see Dynamics GP Web Services Exceptions console Exception methods, described 24 exceptions caused by BusinessObjectsFile.config 110 chapter 61-66 Dynamics GP Web Services Exceptions console 61 exception log 61 for Dynamics GP web service 11 list of 137 overview 61

exceptions (continued) system exceptions 64 types of 61 unhandled system exceptions 137 validation exceptions 64 viewing list of 61 Extending the Web Service, part 88-117 extending web service objects how to extend 89 overview 89 parts of the extension 90 procedure 90 web service events 91 extension assembly chapter 95-108 creating 95 defined 145 deploying 96 described 90 event handler methods 96 namespaces required 95 public static class for 96 referenced assemblies 95 Extension objects, working with 113 ExtensionList collection for objects 89 working with 113 external behaviors defined 145 described 11, 67 finding behavior option 70 finding in policy instance 70 setting selected behavior option 71 setting with code 70

inheritance example 20 in web service object model 20 insufficient authorization errors, troubleshooting 140 integer values described 25 empty integer values 25 internal behaviors defined 145 described 11, 67 ISO codes for MoneyAmount values 25 list of 135

L
learning the Dynamics GP web service object model 21 light bulb symbol 3 like restrictions described 45 example 45 list restrictions described 44 example 44 locking rows, concurrency issues for 52 login credentials, for web service instance 18

M
margin notes 3 methods, see web methods MoneyAmount values described 25 empty MoneyAmount values 25 ISO codes for 25

F
filtering, see entity ID filtering format, for account numbers 26

N
namespace for web service proxy 18 required for extension assembly 95

G
Get List methods criteria objects for 41 described 23, 40 examples 41, 42 optimizing performance 43 using results 43 with entity ID filtering 75 Get methods described 23, 39 examples 39 with entity ID filtering 74 Getting Started, part 14-30

O
Object Browser, in Visual Studio 17 object model for Dynamics GP web service 19 inheritance 20 learning 21 object categories 19 objects creating 33 deleting 57 ExtensionList collection 89 filtering 73 how to extend 89 retrieving individual 39 updating 47 voiding 57 which can be extended 89 operations, for entity ID filtering 74 optimized access point, creating 82

H
helper objects, described 20

I
Import GL Transactions, sample application 125 indexed columns, using for criteria objects 43

148

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E

I N D E X

optimizing Get List methods 43 web service access 82 web service applications 142 organization, in web service context 29 Other Programming Techniques, chapter 79-86 overflow, for strings 25

P
parameters, for behavior option 71 Percent values described 26 empty Percent values 26 performance, optimizing for web service applications 142 policy behaviors for 11, 67 chapter 67-71 configuring from code 68 configuring with Dynamics Security Console 68 defined 145 described 11, 67 for Create operations 34 for Delete operations 58 for Update operations 50 for Void operations 58 impacting data 141 listing available policies 68 overview 67 policy instances 67 reference information for 67 roles for 69 troubleshooting 144 using in an application 69 Policy Administrator role, described 68 policy instances creating with code 69 defined 145 deleting with code 69 described 67 retrieving 69 roles for 69 updating with code 69 Policy methods, described 24 prerequisites, for using web services 3 product support, for Microsoft Dynamics GP web services 4 proxy defined 145 described 16 for web service 16 optimized proxy 82

restriction objects basic restrictions 44 between restrictions 45 like restrictions 45 list restrictions 44 types of 44 used with criteria 44 retrieve methods, described 39 Retrieved sample event handler method 98 web service event 91 Retrieving Objects, chapter 39-45 role key automatically assigned for context 30 in web service context 30 roles for entity ID filtering 74 for policy instances 69

tracing modes 138 to log eConnect issues 138 to log web service issues 137 troubleshooting, Dynamics GP web service 137 truncation, for strings 25

U
unhandled system exceptions 137 Update Customers, sample application 127 Update methods concurrency issues 52 described 23, 47 example 47 Update policy described 50 example 50 retrieving 50 setting behaviors 50 Updated, web service event 92 Updating sample event handler method 106 web service event 92 Updating Objects, chapter 47-55 URL, for web service 15 user IDs, for Dynamics GP objects 73 user-assignable business objects defined 145 described 73 Using the Web Service, part 32-86 Using Web Service Extensions, chapter 113-117

S
Sales Documents, sample application 121 samples Import GL Transactions 125 Sales Documents 121 Update Customers 127 Scope property, for criteria objects 75 Security web service, see Dynamics Security web service segments, for account numbers 26 separator character, for account numbers 27 SOAP defined 145 described 7 exceptions from web service operations 61 string values described 25 overflow issues 25 truncation issues 25 summary objects defined 145 described 39 retrieving list of 40 support, for Microsoft Dynamics GP web services 4 symbols in documentation 3 system database, specifying in web service context 29 system exceptions described 61, 64 handling in code 64 viewing details 62

V
ValidatingForCreate sample event handler method 99 web service event 91 ValidatingForDelete, web service event 92 ValidatingForUpdate sample event handler method 104 web service event 92 ValidatingForVoid, web service event 92 validation exceptions described 61, 64 example 64 handling in code 64 viewing details 63 Void methods, described 23, 57 Void policy described 58 retrieving 58 Voided, web service event 93 Voiding, web service event 92

Q
queries, see Get List methods

T
tasks, for entity ID filtering 74 technical support, for Microsoft Dynamics GP web services 4 timeout, specifying for web service instance 18

W
warning symbol 3 web methods calling asynchronously 79 categories 23 chapter 23-24

R
Registering Events, chapter 109-112 registration example, for web service events 111

WEB

SERVICE

PROGRAMMERS

GUIDE

149

IN DEX

web methods (continued) Create methods 23 Delete methods 23 Exception methods 24 framework methods 24 Get methods 23 GetList methods 23 Policy methods 24 Update methods 23 Void methods 23 web reference adding to Visual Studio project 16 creating 16 defined 145 described 16 in C# project 17 web service architecture 9 benefits 7 configurations 9 context 29 defined 145 described 7 instance 18 namespace for 18 not responding 142 object model 19 overview 7 proxy 16 technical support 4 troubleshooting 137 URL 15 Web Service Architecture, chapter 9-11 Web Service Basics, part 6-11 web service events chapter 91-93 defined 145 how processed 91 list of 91 registering 91, 109 registration example 111 types of 91 web service extensions creating or updating data 115 retrieving data from 113 using 113 Web Service Object Model, chapter 19-21 Web Service Samples, part 120-129 Windows User IDs, associating with Dynamics GP objects 73 Work on Behalf of Other Users task 81 WorkOnBehalfOf property for Context object 81 impact of entity ID filtering 76 in web service context 30 WSDL accessing for web service 15 defined 145

X
XML element, used for web service object extension 89

150

W E B

S E R V I C E

P R O G R A M M E R S

G U I D E