DataExtDefAdd

This request adds a data extension definition to the specified object type (e.g. Customer) so that extension data can be written to a particular object of that type (e.g., this customer, John Smith. A data extension definition must be created before data can be written to the data extension. Notice that a custom field data extension definition can be created either by using DataExtDefAdd or via the QuickBooks UI by the user specifying a custom field for an object. Only custom fields can be defined through the UI, however, not private data extensions. Via the SDK, you create a custom field definition by setting the OwnerID to 0. You create a private data definition by setting OwnerID to a GUID that only your application owns or shares with other applications. Custom fields are available and visible within the QuickBooks UI, whereas private data extensions are seen and used only by your own application or other applications that know the OwnerID GUID. Data is written to custom fields either via the SDK DataExtAdd/Mod requests or via the QuickBooks UI directly by the end user. Data is written to private data extensions only via the SDK DataExtAdd/Mod requests. You should be careful not to use private data extensions in transaction line items because queries will not return that private data (use only custom fields on transaction line items). Notice that creating a custom field data extension definition for Customer and Item causes an automatic propagation of that definition to certain transaction objects. See “AssignToObject” for more details. A full description of this behavior and its usefulness is provided in the QB SDK Programmer’s Guide. DataExtDefAdd does not cause any events to be generated.


Request

Response

XMLOPS

VB.NET

C#

Tag Type Max length Implementation Required

IDataExtDefAdd

This request adds a data extension definition to the specified object type (e.g. Customer) so that extension data can be written to a particular object of that type (e.g., this customer, John Smith. A data extension definition must be created before data can be written to the data extension. Notice that a custom field data extension definition can be created either by using DataExtDefAdd or via the QuickBooks UI by the user specifying a custom field for an object. Only custom fields can be defined through the UI, however, not private data extensions. Via the SDK, you create a custom field definition by setting the OwnerID to 0. You create a private data definition by setting OwnerID to a GUID that only your application owns or shares with other applications. Custom fields are available and visible within the QuickBooks UI, whereas private data extensions are seen and used only by your own application or other applications that know the OwnerID GUID. Data is written to custom fields either via the SDK DataExtAdd/Mod requests or via the QuickBooks UI directly by the end user. Data is written to private data extensions only via the SDK DataExtAdd/Mod requests. You should be careful not to use private data extensions in transaction line items because queries will not return that private data (use only custom fields on transaction line items). Notice that creating a custom field data extension definition for Customer and Item causes an automatic propagation of that definition to certain transaction objects. See “AssignToObject” for more details. A full description of this behavior and its usefulness is provided in the QB SDK Programmer’s Guide. DataExtDefAdd does not cause any events to be generated.
        

OwnerID

OwnerID refers to the owner of a data extension. A value of 0 means the data extension is a custom field visible and usable within the QuickBooks UI. Any other non zero value that is a valid GUID means that the data extension is a private data extension. Usually you would keep your application’s GUID confidential to prevent other applications from accessing your data extensions. But if you want to share data extensions with another application, the applications need to use the same GUID. In this case, each application could use two GUIDs, one for shared data extensions and one for confidential data extensions. (An application can have any number of GUIDs.) When you share a data extension with another application, the other application must know both the OwnerID and the DataExtName, as these together form a data extension’s unique name.
 IQBGUIDType     Y

DataExtName

The name of the data extension. If this is a custom field, DataExtName will be visible as a label in the QuickBooks user interface. Also because OwnerID and DataExtName together make the data extension unique, and because custom fields all have the same OwnerID of zero, the DataExtName must be a unique value among existing custom fields. In contrast, the DataExtName for private data extensions must be unique only for the specified OwnerID GUID.
 IQBStringType     Y

DataExtType

b>DataExtType The type of the data extension.
 IQBENDataExtTypeType     Y

AssignToObjectList

This list contains one or more type enums that specify the object types that can use the data extension definition. To add a type to this list, you invoke AssignToObjectList.Add on the data extension def add object, specifying the object type, as in the following snippet that adds two types to the AssignToObjectList: MyDataExtDefAdd.AssignToObjectList.Add atoDepartment MyDataExtDefAdd.AssignToObjectList.Add atoVendor
 ENAssignToObject      
Tag Type Max length Implementation Required

IResponse

This request adds a data extension definition to the specified object type (e.g. Customer) so that extension data can be written to a particular object of that type (e.g., this customer, John Smith. A data extension definition must be created before data can be written to the data extension. Notice that a custom field data extension definition can be created either by using DataExtDefAdd or via the QuickBooks UI by the user specifying a custom field for an object. Only custom fields can be defined through the UI, however, not private data extensions. Via the SDK, you create a custom field definition by setting the OwnerID to 0. You create a private data definition by setting OwnerID to a GUID that only your application owns or shares with other applications. Custom fields are available and visible within the QuickBooks UI, whereas private data extensions are seen and used only by your own application or other applications that know the OwnerID GUID. Data is written to custom fields either via the SDK DataExtAdd/Mod requests or via the QuickBooks UI directly by the end user. Data is written to private data extensions only via the SDK DataExtAdd/Mod requests. You should be careful not to use private data extensions in transaction line items because queries will not return that private data (use only custom fields on transaction line items). Notice that creating a custom field data extension definition for Customer and Item causes an automatic propagation of that definition to certain transaction objects. See “AssignToObject” for more details. A full description of this behavior and its usefulness is provided in the QB SDK Programmer’s Guide. DataExtDefAdd does not cause any events to be generated.
        

StatusCode

A number that corresponds to a statusSeverity and statusMessage. Five status codes relate directly to signon messages: 2000, 2010, 2020, 2030, and 2040. For details about these and other statusCode values that can be returned, see the statusCode table on the Error Codes page.
 IQBIntType     Y

StatusSeverity

One of the following values: INFO The request was completed, and the results are consistent with what your application expected. WARNING The request was completed, but the results might not be consistent with what you expected. ERROR The request was not completed. No data will appear in the server’s response after the statusMessage.
 IQBStringType     Y

StatusMessage

A user-readable explanation of the success or error condition that is indicated by the statusCode. For details about the statusMessage values that can be returned, see the “Explanation” column of the statusCode table on the Error Codes page.
 IQBStringType     Y

Detail

 IDataExtDefRet      

OwnerID

OwnerID refers to the owner of a data extension. A value of 0 means the data extension is a custom field visible and usable within the QuickBooks UI. Any other non zero value that is a valid GUID means that the data extension is a private data extension. Usually you would keep your application’s GUID confidential to prevent other applications from accessing your data extensions. But if you want to share data extensions with another application, the applications need to use the same GUID. In this case, each application could use two GUIDs, one for shared data extensions and one for confidential data extensions. (An application can have any number of GUIDs.) When you share a data extension with another application, the other application must know both the OwnerID and the DataExtName, as these together form a data extension’s unique name.
 IQBGUIDType     Y

DataExtName

The name of the data extension. If this is a custom field, DataExtName will be visible as a label in the QuickBooks user interface. Also because OwnerID and DataExtName together make the data extension unique, and because custom fields all have the same OwnerID of zero, the DataExtName must be a unique value among existing custom fields. In contrast, the DataExtName for private data extensions must be unique only for the specified OwnerID GUID.
 IQBStringType     Y

DataExtType

b>DataExtType The type of the data extension.
 IQBENDataExtTypeType     Y

AssignToObjectList

This list contains one or more type enums that specify the object types that can use the data extension definition. To add a type to this list, you invoke AssignToObjectList.Add on the data extension def add object, specifying the object type, as in the following snippet that adds two types to the AssignToObjectList: MyDataExtDefAdd.AssignToObjectList.Add atoDepartment MyDataExtDefAdd.AssignToObjectList.Add atoVendor
 ENAssignToObject       

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<?xml version="1.0" encoding="utf-8"?>
<?qbposxml version="4.0"?>
<QBPOSXML>
        <QBPOSXMLMsgsRq onError="stopOnError">
                <DataExtDefAddRq>
                        <DataExtDefAdd> <!-- required -->
                                <OwnerID >GUIDTYPE</OwnerID> <!-- required -->
                                <DataExtName >STRTYPE</DataExtName> <!-- required -->
                                <!-- DataExtType may have one of the following values: INTTYPE, AMTTYPE, PRICETYPE, QUANTYPE, PERCENTTYPE, DATETIMETYPE, STR255TYPE, STR1024TYPE -->
                                <DataExtType >ENUMTYPE</DataExtType> <!-- required -->
                                <!-- AssignToObject may have one of the following values: Department, Customer, Vendor, Employee, ItemInventory, SalesReceipt, Voucher, InventoryQtyAdjustment, InventoryCostAdjustment, TransferSlip, SalesOrder, PurchaseOrder, TimeEntry, Company -->
                                <AssignToObject >ENUMTYPE</AssignToObject> <!-- optional, may repeat -->
                        </DataExtDefAdd>
                </DataExtDefAddRq>

                <DataExtDefAddRs statusCode="INTTYPE" statusSeverity="STRTYPE" statusMessage="STRTYPE">
                        <DataExtDefRet> <!-- optional -->
                                <OwnerID >GUIDTYPE</OwnerID> <!-- required -->
                                <DataExtName >STRTYPE</DataExtName> <!-- required -->
                                <!-- DataExtType may have one of the following values: INTTYPE, AMTTYPE, PRICETYPE, QUANTYPE, PERCENTTYPE, DATETIMETYPE, STR255TYPE, STR1024TYPE -->
                                <DataExtType >ENUMTYPE</DataExtType> <!-- required -->
                                <!-- AssignToObject may have one of the following values: Department, Customer, Vendor, Employee, ItemInventory, SalesReceipt, Voucher, InventoryQtyAdjustment, InventoryCostAdjustment, TransferSlip, SalesOrder, PurchaseOrder, TimeEntry, Company -->
                                <AssignToObject >ENUMTYPE</AssignToObject> <!-- optional, may repeat -->
                        </DataExtDefRet>
                </DataExtDefAddRs>
        </QBPOSXMLMsgsRq>
</QBPOSXML>


  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
'The following sample code is generated as an illustration of
'Creating requests and parsing responses ONLY
'This code is NOT intended to show best practices or ideal code
'Use at your most careful discretion

imports System
imports System.Net
imports System.Drawing
imports System.Collections
imports System.ComponentModel
imports System.Windows.Forms
imports System.Data
imports System.IO
imports Interop.qbposfc4

        Public Class SampleDataExtDefAdd
                Public Sub  DoDataExtDefAdd()
                        Dim sessionBegun as Boolean
                        sessionBegun = False
                        Dim connectionOpen as Boolean
                        connectionOpen = False
                        Dim sessionManager as QBPOSSessionManager
                        sessionManager = nothing

                        Try
                                'Create the session Manager object
                                sessionManager = new QBPOSSessionManager

                                'Create the message set request object to hold our request
                                Dim requestMsgSet as IMsgSetRequest
                                requestMsgSet = sessionManager.CreateMsgSetRequest(4,0)
                                requestMsgSet.Attributes.OnError = ENRqOnError.roeContinue

                                BuildDataExtDefAddRq(requestMsgSet)

                                'Connect to QuickBooks and begin a session
                                sessionManager.OpenConnection("","Sample Code from OSR")
                                connectionOpen = True
                                sessionManager.BeginSession("")
                                sessionBegun = True

                                'Send the request and get the response from QuickBooks
                                Dim responseMsgSet as IMsgSetResponse
                                responseMsgSet = sessionManager.DoRequests(requestMsgSet)

                                'End the session and close the connection to QuickBooks
                                sessionManager.EndSession()
                                sessionBegun = False
                                sessionManager.CloseConnection()
                                connectionOpen = False

                                WalkDataExtDefAddRs(responseMsgSet)
                        Catch e as Exception
                                MessageBox.Show(e.Message, "Error")
                                if (sessionBegun) then
                                        sessionManager.EndSession()
                                End If
                                if (connectionOpen) then
                                        sessionManager.CloseConnection()
                                End If
                        End Try
                End Sub
                Public Sub BuildDataExtDefAddRq(requestMsgSet as IMsgSetRequest)
                        Dim DataExtDefAddRq as IDataExtDefAdd
                        DataExtDefAddRq= requestMsgSet.AppendDataExtDefAddRq()
                        'Set field value for OwnerID
                        DataExtDefAddRq.OwnerID.SetValue(System.Guid.NewGuid().ToString())
                        'Set field value for DataExtName
                        DataExtDefAddRq.DataExtName.SetValue("ab")
                        'Set field value for DataExtType
                        DataExtDefAddRq.DataExtType.SetValue(ENDataExtType.detINTTYPE)
                        'Set field value for AssignToObjectList
                        'May create more than one of these if needed
                        DataExtDefAddRq.AssignToObjectList.Add(ENAssignToObject.atoDepartment)
                End Sub




                Public Sub WalkDataExtDefAddRs( responseMsgSet as IMsgSetResponse)
                        if (responseMsgSet is nothing) then
                                Exit Sub
                        End If

                        Dim responseList as IResponseList
                        responseList = responseMsgSet.ResponseList
                        if (responseList is nothing) then
                                Exit Sub
                        End If

                        'if we sent only one request, there is only one response, we'll walk the list for this sample
                        for j=0 to responseList.Count-1
                                Dim response as IResponse
                                response = responseList.GetAt(j)
                                'check the status code of the response, 0=ok, >0 is warning
                                if (response.StatusCode >= 0) then
                                        'the request-specific response is in the details, make sure we have some
                                        if (not response.Detail is nothing) then
                                                'make sure the response is the type we're expecting
                                                Dim responseType as ENResponseType
                                                responseType = CType(response.Type.GetValue(),ENResponseType)
                                                if (responseType = ENResponseType.rtDataExtDefAddRs) then
                                                        'upcast to more specific type here, this is safe because we checked with response.Type check above
                                                        Dim DataExtDefRet as IDataExtDefRet
                                                        DataExtDefRet = CType(response.Detail,IDataExtDefRet)
                                                                WalkDataExtDefRet(DataExtDefRet)
                                                End If
                                        End If
                                End If
                        Next j
                End Sub




                Public Sub WalkDataExtDefRet(DataExtDefRet as IDataExtDefRet)
                        if (DataExtDefRet is nothing) then
                                Exit Sub
                        End If

                        'Go through all the elements of IDataExtDefRet
                        'Get value of OwnerID
                        Dim OwnerID547 as String
                        OwnerID547 = DataExtDefRet.OwnerID.GetValue()
                        'Get value of DataExtName
                        Dim DataExtName548 as String
                        DataExtName548 = DataExtDefRet.DataExtName.GetValue()
                        'Get value of DataExtType
                        Dim DataExtType549 as ENDataExtType
                        DataExtType549 = DataExtDefRet.DataExtType.GetValue()
                        'Get value of AssignToObjectList
                        if ( not DataExtDefRet.AssignToObjectList is nothing) then
                                Dim AssignToObject550 as ENAssignToObject
                                AssignToObject550 = DataExtDefRet.AssignToObjectList.GetAt(0)
                        End If
                End Sub




        End Class


  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
//The following sample code is generated as an illustration of
//Creating requests and parsing responses ONLY
//This code is NOT intended to show best practices or ideal code
//Use at your most careful discretion

using System;
using System.Net;
using System.Drawing;
using System.Collections;
using System.ComponentModel;
using System.Windows.Forms;
using System.Data;
using System.IO;
using Interop.qbposfc4;

namespace com.intuit.idn.samples
{
        public class SampleDataExtDefAdd
        {
                public void  DoDataExtDefAdd()
                {
                        bool sessionBegun = false;
                        bool connectionOpen = false;
                        QBPOSSessionManager sessionManager = null;

                        try
                        {
                                //Create the session Manager object
                                sessionManager = new QBPOSSessionManager();

                                //Create the message set request object to hold our request
                                IMsgSetRequest requestMsgSet = sessionManager.CreateMsgSetRequest(4,0);
                                requestMsgSet.Attributes.OnError = ENRqOnError.roeContinue;

                                BuildDataExtDefAddRq(requestMsgSet);

                                //Connect to QuickBooks and begin a session
                                sessionManager.OpenConnection("","Sample Code from OSR");
                                connectionOpen = true;
                                sessionManager.BeginSession("");
                                sessionBegun = true;

                                //Send the request and get the response from QuickBooks
                                IMsgSetResponse responseMsgSet = sessionManager.DoRequests(requestMsgSet);

                                //End the session and close the connection to QuickBooks
                                sessionManager.EndSession();
                                sessionBegun = false;
                                sessionManager.CloseConnection();
                                connectionOpen = false;

                                WalkDataExtDefAddRs(responseMsgSet);
                        }
                        catch (Exception e)
                        {
                                MessageBox.Show(e.Message, "Error");
                                if (sessionBegun)
                                {
                                        sessionManager.EndSession();
                                }
                                if (connectionOpen)
                                {
                                        sessionManager.CloseConnection();
                                }
                        }
                }
                void BuildDataExtDefAddRq(IMsgSetRequest requestMsgSet)
                {
                        IDataExtDefAdd DataExtDefAddRq= requestMsgSet.AppendDataExtDefAddRq();
                        //Set field value for OwnerID
                        DataExtDefAddRq.OwnerID.SetValue(Guid.NewGuid().ToString());
                        //Set field value for DataExtName
                        DataExtDefAddRq.DataExtName.SetValue("ab");
                        //Set field value for DataExtType
                        DataExtDefAddRq.DataExtType.SetValue(ENDataExtType.detINTTYPE);
                        //Set field value for AssignToObjectList
                        //May create more than one of these if needed
                        DataExtDefAddRq.AssignToObjectList.Add(ENAssignToObject.atoDepartment);
                }




                void WalkDataExtDefAddRs(IMsgSetResponse responseMsgSet)
                {
                        if (responseMsgSet == null) return;
                        IResponseList responseList = responseMsgSet.ResponseList;
                        if (responseList == null) return;
                        //if we sent only one request, there is only one response, we'll walk the list for this sample
                        for(int i=0; i < responseList.Count; i++)
                        {
                                IResponse response = responseList.GetAt(i);
                                //check the status code of the response, 0=ok, >0 is warning
                                if (response.StatusCode >= 0)
                                {
                                        //the request-specific response is in the details, make sure we have some
                                        if (response.Detail != null)
                                        {
                                                //make sure the response is the type we're expecting
                                                ENResponseType responseType = (ENResponseType)response.Type.GetValue();
                                                if (responseType == ENResponseType.rtDataExtDefAddRs)
                                                {
                                                        //upcast to more specific type here, this is safe because we checked with response.Type check above
                                                        IDataExtDefRet DataExtDefRet = (IDataExtDefRet)response.Detail;
                                                                WalkDataExtDefRet(DataExtDefRet);
                                                }
                                        }
                                }
                        }
                }




                void WalkDataExtDefRet(IDataExtDefRet DataExtDefRet)
                {
                        if (DataExtDefRet == null) return;
                        //Go through all the elements of IDataExtDefRet
                        //Get value of OwnerID
                        string OwnerID551 = (string)DataExtDefRet.OwnerID.GetValue();
                        //Get value of DataExtName
                        string DataExtName552 = (string)DataExtDefRet.DataExtName.GetValue();
                        //Get value of DataExtType
                        ENDataExtType DataExtType553 = (ENDataExtType)DataExtDefRet.DataExtType.GetValue();
                        //Get value of AssignToObjectList
                        if (DataExtDefRet.AssignToObjectList != null)
                        {
                                ENAssignToObject AssignToObject554 = (ENAssignToObject)DataExtDefRet.AssignToObjectList.GetAt(0);
                        }
                }




        }
}