Overview of service transforms

  • Article

The Dynamics GP Service framework uses eConnect to perform operations on the Dynamics GP database. To perform an operation, the service framework and eConnect exchange XML documents. Since the schema of the service framework XML document differs from the schema of the eConnect XML document, the framework uses XSLT to transform XML to and from the eConnect schema. The service framework uses transforms for the following operations:

  • To retrieve data, the service framework uses the eConnect Transaction Requester to get a document or a list of summary documents. The framework uses XSLT to transform the Transaction Requester XML into an XML document that the service framework uses to populate the properties of a document object.
  • To perform a create, update, or delete operation, the service framework uses an XSLT transform to convert a framework XML document into an eConnect XML document. The transform produces an eConnect XML document that works with a specified eConnect SQL stored procedure to perform the database operation.

When adding a new type of document to the service, you need to supply XSLT transforms that enable the service framework to complete operations using your document. Typically, your XSLT maps property names and values from a service framework XML document to the corresponding property and value in an eConnect XML document.

You must create an XSLT transform for each service operation your document supports. Store each transform in a separate XSLT file.

Warning: The Dynamics GP Service framework requires XSLT files to follow an established naming convention. The framework uses the name to match the document type and operation to a transform. If your XSLT file does not include the expected name, you will receive an error when you try to perform the service operation.

To create an XSLT file for the Dynamics GP Service framework, specify a filename that contains the document type name and the operation. In addition, your XSLT filename cannot duplicate the name of an existing XSLT file. While you can precede your XSLT filename with namespace descriptors, your filename must include the following information:

<document type><operation>.xslt

The operation specifies the method. All XSLT filenames use one of the following operation descriptors:

  • GetByKey
  • GetList
  • Create
  • Update
  • Delete
  • Void

For example, the LeadGetByKey.xslt part of the filename for the file with the name Microsoft.Dynamics.GP.Samples.Leads.LeadGetByKey.xslt specifies that the file contains the XSLT transform to use with a GetByKey method that retrieves a Lead document.

The XSLT is also where you implement the create, update, and delete policy for your document. When the service framework serializes a document into XML, it adds XML for the policy object associated with the document. Use XSLT with the policy XML to identify the document data members that are affected by the policy and its behaviors. Also, use the transform process to implement any data changes that the policy and behaviors require.

One challenging part of creating the XSLT is testing the output of your transform. Visual Studio includes a useful XSLT debugger, but requires you to supply a file that contains the XML to transform. To generate the XML file, use the Serialize method of the SerializationManager to create an XML version of your document. SerializationManager is in the Microsoft.Dynamics.Common namespace and the Microsoft.Dynamics.Common.dll assembly. The sample Lead Service in the SDK includes a project named XsltTest that shows how to use the SerializationManager. For more information about installing the sample Lead Service files, see Lead Service.