Share via

Retrieving XML documents with GetEntity

  • Article

The eConnectMethods class includes a method named GetEntity that enables you to retrieve data from Microsoft Dynamics GP. The GetEntity method gives you programmatic access to the eConnect Transaction Requester. You use the GetEntity method to get a string that represents a Transaction Requester XML document.

The Transaction Requester limits the types of documents you can retrieve with the GetEntity method. To retrieve a document, that document type must be specified in the eConnect_Out_Setup table of your company database. To see the default set of document types, see Requester document types.

To specify the data to retrieve, create an XML string that represents a Transaction Requester query document. The following are the most common techniques for creating a string that represents a Transaction Requester query document.

  • Construct a string that contains the XML tags and values required by the Transaction Requester for the specified document type.

  • Load text from a file or other data store that contains an existing Transaction Requester query into a .NET XmlDocument. Use the OuterXML property of the XmlDocument class to convert the XML document to a string.

    Warning: To work with eConnect, the text that is loaded into the XmlDocument object must be a valid Transaction Requester query. For more information about the structure of a Transaction Requester query document, see Retrieve a customer.

  • Use the eConnectOut, RQeConnectOutType, and eConnectType classes from the eConnect Serialization namespace to construct an object that represents a Transaction Requester query. Use a .NET XmlSerializer and a XmlDocument object to convert the query document to a string.

The following steps show how to use the GetEntity method to retrieve a transaction requester document for a customer.

Instantiate an eConnectMethods object

To begin, instantiate an eConnectMethods object. The following Visual Basic example shows how to instantiate an eConnectMethods object:

'Instantiate an eConnectMethods object
Dim eConnectObject As New eConnectMethods

Create a Transaction Requester document

The following Visual Basic example shows how to use classes from the eConnect serialization namespace to construct an object that requests a single customer record. Notice how the INDEX1FROM and INDEX1TO fields specify the ID of the customer, the OUTPUTTYPE field specifies the customer master document, and the FORLIST field specifies to return the document to the caller. Also notice how the .NET XmlSerializer is used to load the document object into a .NET XmlDocument.

'**Create an eConnect requestor document that specifies a single customer**
'Create the requestor node
Dim myRequest As New eConnectOut()
With myRequest
    .DOCTYPE = "Customer"
    .OUTPUTTYPE = 1
    .INDEX1FROM = "AARONFIT0001"
    .INDEX1TO = "AARONFIT0001"
    .FORLIST = 1
End With
'Create the requestor schema document type
'Since the eConnect document requires an array, create an
'array of RQeConnectOutType
Dim econnectOutType() As RQeConnectOutType = _
    New RQeConnectOutType(0) {New RQeConnectOutType}
econnectOutType(0).eConnectOut = myRequest
'Create the eConnect document type
Dim eConnectDoc As New eConnectType()
eConnectDoc.RQeConnectOutType = econnectOutType
'**Serialize the eConnect document**
'Create a memory stream for the serialized eConnect document
Dim memStream As New MemoryStream()
'Create an Xml Serializer and serialize the eConnect document
'to the memory stream
Dim serializer As New XmlSerializer(GetType(eConnectType))
serializer.Serialize(memStream, eConnectDoc)
'Reset the position property to the start of the buffer
memStream.Position = 0
'**Load the serialized Xml into an Xml document**
Dim xmldoc As New XmlDocument()
xmldoc.Load(memStream)

Create an eConnect connection string

The GetEntity method requires that you supply an eConnect connection string. Use the connection string to specify the Dynamics GP data server and the company database.

For information about eConnect connection strings, see the eConnect Installation chapter of the eConnect Installation and Administration Guide.

The following Visual Basic code example shows how to creates a connection string:

'Create an eConnect connection string
Dim connectionString As String
connectionString = "data source=localhost; initial catalog=TWO; " _
    & "integrated security=SSPI; persist security info=False; " _
    & "packet size=4096"

Retrieve the XML document

Use the GetEntity method to populate a string that represents the XML document that the Transaction Requester retrieved. To call the method, supply parameters that specify the connection string, and an XML string that specifies the data you want to retrieve.

For more information about the eConnect_Requester method, see eConnect_Requester Method.

The following Visual Basic example uses the GetEntity method to retrieve a customer XML document. Notice the following:

  • The ConnectionString parameter specifies the Dynamics GP data server and the company database.
  • The XML string parameter is created using the OuterXml property of the XmlDocument object.
'Retrieve the specified document
Dim customerDoc = eConnectMethods.GetEntity(connectionString, _
    EnumTypes.ConnectionStringType.SqlClient, xmldoc.OuterXml)