Service design patterns

The Dynamics GP Service framework supports the following types of service design patterns:

• A service that retrieves a single document or a collection of summary documents. This type of service requires you to use the GetByKey and GetList operations of the Dynamics GP Service framework.
• A service that creates, updates, and deletes or voids documents. This type of service requires you to use the Create, Update, Delete, or Void operations of the Dynamics GP Service framework.

The first step to design a new service requires you to determine what type of access you want to provide to an external application. The choice of design type determines the steps you need to complete to implement your service.

For example, a service that provides an external application the ability to retrieve an existing document requires you to implement the retrieve document design. However, a service that combines the ability to retrieve a document with the ability to create and update documents requires you to implement both the retrieve document and create and update document design patterns.

The following sections of the documentation describe the important elements of each service design pattern.

Retrieving documents

To enable an external application to retrieve a single document, the Dynamics GP Service completes the following process.

To retrieve more than one document, the Dynamics GP Service uses the Dynamics GP Service framework GetList operation. The process is similar except that GetList requires a criteria object instead of a key and returns a collection of summary documents.

To better understand how the service works, look at the role played by each element in the process.

• The Windows Communication Foundation (WCF) service provides a GetByKey method that the external application uses to retrieve a specified document. To use the service method, the external application supplies parameters that specify the document key, the type of the document, and a context object that provides important details of how the service call should be performed.
• The service method calls the GetByKey operation of the Dynamics GP Service framework.
• The Dynamics GP Service framework uses the Dynamics Security Service to verify that the user calling the service method is authorized to access the method. If the external application attempts to run a service method for which the current user does not have access, a security exception is raised and the operation ends.
• To retrieve the document data, the framework uses the document key with the eConnect Transaction Requester.
• The eConnect Transaction Requester performs the database query that retrieves the data for the specified document. The Transaction Requester uses metadata to determine the data fields for the specified type of document. The Transaction Requester returns the data in a Transaction Requester XML document.
• The framework uses XSLT (Extensible Stylesheet Language Transformation) to convert the XML document that the Transaction Requester produces into an XML document that the framework can deserialize into a document object.
• The service method returns the document object to the caller.

When you design a service that retrieves a new type of document, you need to supply the following elements.

• A .NET assembly that defines the document. The assembly contains classes that define the document data fields, the document key, the fields of the summary document, and the criteria and restrictions used to retrieve a collection of summary documents.
• A WCF service that contains the GetByKey and GetList methods for your document type.
• Transaction Requester metadata that describes the data fields to use in the query that retrieves the document or summary documents.
• An XSLT template that transforms the Transaction Requester XML document into a service XML document that the Dynamics GP Service framework serializes into a document object from your .NET document type assembly.
• Dynamics Security Service metadata that add GetByKey and GetList security operations for your document type. The Dynamics Security Service uses the security operation and the user role to determine whether the user is authorized to perform the GetByKey or GetList operation.

Creating, updating, and deleting or voiding documents

To enable an external application to create a document, the Dynamics GP Service uses the following process.

To update, delete, or void a document, the Dynamics GP Service uses the Dynamics GP Service framework Update, Delete, or Void operations. The process is similar for each of these operations.

To better understand how the service works, look at role played by each element in the process.

• The WCF service provides a Create method that the external application uses to create a new document in Microsoft Dynamics GP. To use the method, the external application supplies parameters that include the document, the policy associated with the document, and a context object that provides important details of how the service call should be performed.
• The service method calls the Create operation of the Dynamics GP Service framework.
• The Dynamics GP Service framework uses the Dynamics Security Service to verify that the user calling the service method is authorized to create the document. If the external application attempts to run a method for which the current user does not have access, a security exception is raised and the operation ends.
• The Dynamics GP Service framework retrieves policy information for the document. The policy contains information that controls important characteristics of the new document.
• The framework serializes the document object and the policy information into a service XML document.
• The framework uses XSLT to convert the service XML document into an eConnect XML document that eConnect uses to run an eConnect SQL stored procedure. In addition, the conversion process is used to update the XML to include the characteristics specified by the policy XML.
• eConnect uses the XML document to create the document in Microsoft Dynamics GP. The eConnect stored procedure validates the data and performs business logic associated with operation. eConnect returns information that indicates whether the operation was successfully completed.
• The Dynamics GP Service framework checks the return values from eConnect to see whether an error occurred. If eConnect detected an error, the eConnect exception information is sent to the Dynamics GP Service exception system and is returned to the caller as a BusinessException.

When you design a service that creates, updates, deletes, or voids a document, you need to supply the following elements.

• A .NET assembly that defines the document. The assembly contains classes that define the document, and the document key.
• A WCF service that contains the Create, Update, and Delete or Void methods for your document type.
• An eConnect SQL stored procedure that validates the data, implements business logic for the operation, and adds, updates or removes data in Microsoft Dynamics GP.
• An eConnect XML document schema that works with your eConnect SQL stored procedure. The XML document schema needs to specify the name of the document type, the SQL stored procedure, and the data fields that represent the input parameters for the SQL stored procedure.
• An XSLT template that transforms the XML document from the service XML document schema to your eConnect XML document schema.
• Dynamics Security Service metadata that add Create, Update, and Delete or Void security operations for your document type. The Dynamics Security Service uses the security operation and the user role to determine whether the user is authorized to perform the specified operation.
• Policy metadata that add a policy and behaviors for each type of operation your service supports. The policy metadata defines the characteristics of the operation that can be configured for all documents of the specified type. In addition, the policy metadata allows the administrator to view and configure your policy in the Dynamics Security console.