Lists of objects

A "GetList" method returns a collection of summary objects, or in certain special cases, the collection of objects themselves. The content of the list is controlled by a criteria object. The list will contain only summary objects that meet the restrictions set by the criteria object.

Warning: By default, only the first 1000 items that meet the specified criteria will be returned in the list. This limit prevents the service from being overloaded by a query that returns an extremely large collection.

Creating a criteria object

To specify which objects you want to retrieve in a list, you will first create a criteria object for that type. For instance, you will create a CustomerCriteria object to specify which customer objects to return from the GetCustomerList method.

The criteria object has restriction properties that correspond to specific properties of the object. For example, the Name property of the CustomerCriteria object is a string restriction that corresponds to the Name property of the Customer object. When you set the Name property of the CustomerCriteria object, customer summary objects for customers with names that meet the restriction will be returned. Refer to Restriction reference for more information about the types of restrictions used for criteria.

List examples

The following example demonstrates how to retrieve a list of vendor summaries. The vendor summary list produced by the example contains only vendors with the specified vendor class property.

Notice how the object named classIdRestriction of the LikeRestrictionOfString class is used to specify the vendor class name. The classIdRestriction object is then used to populate the ClassId property of the vendor criteria object named vendorCriteria.

The vendorCriteria object is passed as the first parameter in the GetVendorList method. The GetVendorList method also requires a context object to be created and passed as the method's second parameter.

** Legacy endpoint**

using System;
using System.Collections.Generic;
using System.Text;
using System.Windows.Forms;
using DynamicsGPWebServiceSample.DynamicsGPService;

namespace DynamicsGPWebServiceSample
{
    class Program
    {
        static void Main(string[] args)
        {
            CompanyKey companyKey;
            Context context;
            VendorCriteria vendorCriteria;
            VendorSummary[] vendorSummaryList;
            LikeRestrictionOfString classIdRestriction;

            // Create an instance of the web service
            DynamicsGP wsDynamicsGP = new DynamicsGP();

            // Be sure that default credentials are being used
            wsDynamicsGP.UseDefaultCredentials = true;

            // Create a context object with which to call the service
            context = new Context();

            // Specify which company to use (sample company)
            companyKey = new CompanyKey();
            companyKey.Id = (-1);

            // Set up the context object
            context.OrganizationKey = (OrganizationKey)companyKey;

            // Specify the criteria for the vendor summaries to retrieve
            classIdRestriction = new LikeRestrictionOfString();
            classIdRestriction.EqualValue = "USA-US-I";

            // Create a vendor criteria object and set the restriction
            vendorCriteria = new VendorCriteria();
            vendorCriteria.ClassId = classIdRestriction;

            // Retrieve the list of vendor summaries
            vendorSummaryList = wsDynamicsGP.GetVendorList(vendorCriteria,
            context);

            MessageBox.Show("Total vendors in class: " +
            vendorSummaryList.Length);
        }
    }
}

** Native endpoint **

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Windows.Forms;
using DynamicsGPWebServiceSample.DynamicsGPService;

namespace DynamicsGPWebServiceSample
{
    class Program
    {
        static void Main(string[] args)
        {
            CompanyKey companyKey;
            Context context;
            VendorCriteria vendorCriteria;
            VendorSummary[] vendorSummaryList;
            LikeRestrictionOfstring classIdRestriction;

            // Create an instance of the web service
            DynamicsGPClient wsDynamicsGP = new DynamicsGPClient();

            // Create a context object with which to call the service
            context = new Context();

            // Specify which company to use (sample company)
            companyKey = new CompanyKey();
            companyKey.Id = (-1);

            // Set up the context object
            context.OrganizationKey = (OrganizationKey)companyKey;
            context.CultureName = "en-US";

            // Specify the criteria for the vendor summaries to retrieve
            classIdRestriction = new LikeRestrictionOfstring();
            classIdRestriction.EqualValue = "USA-US-I";

            // Create a vendor criteria object and set the restriction
            vendorCriteria = new VendorCriteria();
            vendorCriteria.ClassId = classIdRestriction;

            // Retrieve the list of vendor summaries
            vendorSummaryList = wsDynamicsGP.GetVendorList(vendorCriteria,
            context);

            MessageBox.Show("Total vendors in class: " +
            vendorSummaryList.Length);

            // Close the service
            if (wsDynamicsGP.State != CommunicationState.Faulted)
            {
                wsDynamicsGP.Close();
            }
        }
    }
}

**The following example demonstrates how to retrieve a list of vendor summaries that were modified during a specific time period. Notice how the object named modifiedDateRestriction of the BetweenRestrictionOfNullableOfDateTime class is used to specify the time period to be examined. The ModifiedDate property of the criteria object requires that both the date and time portion of the value be specified. The values for this criteria property must also be converted to Universal Coordinated Time (UTC). The modifiedDateRestriction object is then used to populate the ModifiedDate property of the vendor criteria object named vendorCriteria.

The vendorCriteria object is passed as the first parameter in the GetVendorList method. The GetVendorList method also requires a context object to be created and passed as the method's second parameter.

** Legacy endpoint**

using System;
using System.Collections.Generic;
using System.Text;
using System.Windows.Forms;
using DynamicsGPWebServiceSample.DynamicsGPService;

namespace DynamicsGPWebServiceSample
{
    class Program
    {
        static void Main(string[] args)
        {
            CompanyKey companyKey;
            Context context;
            VendorCriteria vendorCriteria;
            VendorSummary[] vendorSummaryList;
            BetweenRestrictionOfNullableOfDateTime modifiedDateRestriction;

            // Create an instance of the web service
            DynamicsGP wsDynamicsGP = new DynamicsGP();

            // Make sure that default credentials are being used
            wsDynamicsGP.UseDefaultCredentials = true;

            // Create a context object with which to call the service
            context = new Context();

            // Specify which company to use (sample company)
            companyKey = new CompanyKey();
            companyKey.Id = (-1);

            // Set up the context object
            context.OrganizationKey = (OrganizationKey)companyKey;

            // Specify the criteria for the vendor summaries to retrieve
            modifiedDateRestriction = new
            BetweenRestrictionOfNullableOfDateTime();
            DateTime startDate = new
            DateTime(2017, 4, 9, 8, 0, 0).ToUniversalTime();
            DateTime endDate = new
            DateTime(2017, 4, 9, 17, 0, 0).ToUniversalTime();
            modifiedDateRestriction.From = startDate;
            modifiedDateRestriction.To = endDate;

            vendorCriteria = new VendorCriteria();
            vendorCriteria.ModifiedDate = modifiedDateRestriction;

            // Retrieve the list of vendor summaries
            vendorSummaryList = wsDynamicsGP.GetVendorList(vendorCriteria,
            context);

            MessageBox.Show("Total vendors modified today: " +
            vendorSummaryList.Length);
        }
    }
}

** Native endpoint **

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Windows.Forms;
using DynamicsGPWebServiceSample.DynamicsGPService;

namespace DynamicsGPWebServiceSample
{
    class Program
    {
        static void Main(string[] args)
        {
            CompanyKey companyKey;
            Context context;
            VendorCriteria vendorCriteria;
            VendorSummary[] vendorSummaryList;
            BetweenRestrictionOfNullableOfdateTime modifiedDateRestriction;

            // Create an instance of the web service
            DynamicsGPClient wsDynamicsGP = new DynamicsGPClient();

            // Create a context object with which to call the service
            context = new Context();

            // Specify which company to use (sample company)
            companyKey = new CompanyKey();
            companyKey.Id = (-1);

            // Set up the context object
            context.OrganizationKey = (OrganizationKey)companyKey;
            context.CultureName = "en-US";

            // Specify the criteria for the vendor summaries to retrieve
            modifiedDateRestriction = new
            BetweenRestrictionOfNullableOfdateTime();
            DateTime startDate = new
            DateTime(2017, 4, 9, 8, 0, 0).ToUniversalTime();
            DateTime endDate = new
            DateTime(2017, 4, 9, 17, 0, 0).ToUniversalTime();
            modifiedDateRestriction.From = startDate;
            modifiedDateRestriction.To = endDate;

            vendorCriteria = new VendorCriteria();
            vendorCriteria.ModifiedDate = modifiedDateRestriction;

            // Retrieve the list of vendor summaries
            vendorSummaryList = wsDynamicsGP.GetVendorList(vendorCriteria,
            context);

            MessageBox.Show("Total vendors modified today: " +
            vendorSummaryList.Length);

            // Close the service
            if (wsDynamicsGP.State != CommunicationState.Faulted)
            {
                wsDynamicsGP.Close();
            }
        }
    }
}

Using the list

The objects returned in the collection won't be editable. If the objects need to be edited, or the necessary information isn't contained in the summary object, you will need to use the GetByKey method to retrieve the corresponding complete object.

Optimizing list operations

For optimal performance when retrieving lists of object from the Dynamics GP service, it's important that you structure the criteria carefully. Use the following guidelines when setting up criteria:

• Use the simplest criteria that can perform the search. The more properties you specify for the criteria object, the longer the search will take.
• Use properties in the criteria object that correspond to indexed columns in the database. In the Dynamics GP Web Service Reference, the properties of the criteria objects that correspond to indexed columns are marked with a dagger (†).