eConnect XML document structure

  • Article

An eConnect XML document is collection of related XML components that represent a Microsoft Dynamics GP transaction or document. The XML components are in a parent/child hierarchy that define the data structure for the document type. The components and hierarchy for a document type is specified by an XML schema. For information about the schema, see eConnect schema overview.

The following table lists the basic components of an eConnect XML document:

Component type

Description

eConnect document

The root of the document. The eConnect document is the parent to one or more eConnect transaction type nodes.

eConnect transaction type

Specifies the type of the document or transaction. The transaction type is the parent to one or more eConnect XML nodes.

eConnect XML nodes

The parent to one or elements. The elements contain the data values for the document.

The following diagram illustrates a simple eConnect XML document. Notice how the eConnect document implements the parent/child relationships specified by the eConnect schema. Also notice how the eConnect transaction type is the parent to the <eConnectProcessInfo> and <taSopHdrIvcInsert> eConnect XML nodes.

JJ902628.XmlDocument(en-us,MSDN.10).gif

eConnect document

An eConnect XML document always contains a single <eConnect> node. The <eConnect> node is the root node of the document. The <eConnect> node contains one or more transaction type nodes.

In addition, the <eConnect> node defines the scope of the SQL transaction for the specified operation. If any child component of the <eConnect> node fails, a rollback is performed that removes all the changes and updates specified by the XML document.

As a result, an eConnect XML document should include information related to a single Microsoft Dynamics GP operation. This ensures all the component pieces of the operation are consistently applied or rolled back.

If you encounter a situation that requires using unrelated transaction types within a document, evaluate whether a SQL rollback will cause problems for your application or your Microsoft Dynamics GP data.

eConnect Transaction Type

An eConnect transaction type is an XML component that represents a Microsoft Dynamics GP document or operation. An eConnect XML document always includes one or more transaction type nodes. If you want your eConnect XML document to perform more than one operation, you have to add a transaction type node for each operation.

To create an eConnect XML document, you first add a transaction type node to the <eConnect> root node. For example, you add a <RMCustomerMasterType> transaction type node to a document that represents a new customer.

A transaction type node is the parent of one or more eConnect XML nodes. The eConnect schema files show the XML nodes you use to populate each transaction type. For information about the schema files, see Using eConnect schema.

eConnect XML node

An eConnect node is an XML component that contains a collection of elements. An element has a name and can contain a data value. You use the data values of the elements when you use eConnect to perform a Microsoft Dynamics GP operation. The eConnect schema files specify the elements contained in an XML node.

Some eConnect transaction types can include a collection of more than one XML node of a specified type. The schema identifies these nodes by appending "_Items" to the node name. For example, the <RMCustomerMasterType> can include more than one address for a customer. The <taCreateCustomerAddress_Items> node indicates that you can add more than one <taCreateCustomerAddress> XML node for a customer.

The following table describes the properties for an eConnect XML element:

Property

Description

Name

Specifies the name that identifies the element. You use the name to identify a specific element in a document.

Required

Specifies whether the element requires a value. If you do specify a value for the element, the transaction produces an error,

In the schema files, a required element has both the minOccurs and maxOccurs property set to 1.

Type

Specifies the expected data type for the element value. For example, an element that contains text will have a data type of string.

Default

Specifies the default value for an element.

Length

Specifies the maximum data length of the value you can use to populate an element. The length is determined by the business object input parameter that handles the specified element.

Constraint

Specifies the data value or values that the element can accept. To populate the element, you must specify a value that satisfies the data constraint. If you specify a value that does not meet the data constraint, an error occurs and the transaction fails.

The <eConnectProcessInfo> node

The eConnect schema specifies that the first XML node of each eConnect transaction type schema must be an <eConnectProcessInfo> node. You can use the elements of the <eConnectProcessInfo> node to change how specific transaction types are processed. The following example shows how to use the <eConnectProcessInfo> node to override the default eConnect connection string:

<eConnectProcessInfo>
    <ConnectionString>
        Integrated Security=SSPI;
        Persist Security Info=False;
        Initial Catalog=TWO;
        Data Source=machinename
    </ConnectionString>
</eConnectProcessInfo>

Refer to XML Schema Reference to view the transaction type schemas.