Overview of a service interface

To give developers access to a new type of business document, create a service interface with methods that access the document. A service interface for Microsoft Dynamics GP requires the following references:

• A reference to an assembly that defines the business document type. The document type includes the document, the document key, the summary document, and the document criteria.
• A reference to the Microsoft.Dynamics.GP.BusinessLogic assembly. The assembly includes the GreatPlainsBusinessService class. This class performs the following operations for any properly-defined business document type.

  Operation	Description
  Create	Adds a new document to the Dynamics GP database.
  Delete	Removes an existing document from the Dynamics GP database.
  GetByKey	Retrieves a single document.
  GetList	Retrieves a list of summary documents.
  Update	Modifies an existing document in the Dynamics GP database.
  Void	Marks an existing document as void but does not remove it from the Dynamics GP database.

To enable the Dynamics Security Service to control access to your documents, add a Dynamics GP context object as a parameter for your methods. The Dynamics Security Service uses context information to determine whether the user calling the method is authorized to access that method.

The create, delete, update, and void methods of the GreatPlainsBusinessService require a policy object. To obtain policy information, add policy as a parameter for your create, delete, update, and void methods.

To simplify the retrieval of policy information, add the GetPolicyByKey method from the Dynamics GP Service to your service. The GetPolicyByKey method gives developers a way to retrieve policy information using a single service reference. If you do not include GetPolicyByKey, you force developers to use the Dynamics GP Service to retrieve policy information for your service methods.

You might find that adding methods from the Dynamics GP Service makes your service interface easier to use. To use an existing Dynamics GP method, add a method to your service that calls methods on the Microsoft Dynamics GP Service. For more information about how to add methods from the Dynamics GP Service to your service, see Adding Dynamics GP Service methods.

To return information about errors identified by the GreatPlainsBusinessService, convert the error to a message that can be viewed by the service user. Errors that originate in a Dynamics GP Service method that you add to your service do not require conversion. For more information about how to handle errors in a service method, see the example code in Implementing a service contract for the native endpoint.