Data

Data can be read from DealCloud using a variety of methods with the SDK. To quickly summarise:

• Read Data from an object using the Object API Name

Client.Data.ReadObject(string objectId, string resolve = "", string query= "")

• Read Typed (<T>) Data from an object using the Object API Name

Client.Data.ReadObject<T>(string objectId, string resolve = "", string query= "")

• Read Data from an object using the Object ID

Client.Data.ReadObject(int objectId, string resolve = "", string query= "")

• Read Typed (<T>) Data from an object using the Object ID

Client.Data.ReadObject<T>(int objectId, string resolve = "", string query= "")

• Read Data from a View using the View Name

Client.Data.ReadView(string viewId, List<ViewQuery>? query = null)

• Read Typed (<T>) Data from a View using the View Name

Client.Data.ReadView<T>(string viewId, List<ViewQuery>? query = null)

• Read Data from a View using the View ID

Client.Data.ReadView(int viewId, List<ViewQuery>? query = null)

• Read Typed (<T>) Data from a View using the View ID

Client.Data.ReadView<T>(int viewId, List<ViewQuery>? query = null)

Read Object Data

As shown above, object data can be read in a few ways, either typed or untyped and using a string or integer identifier for the object. In addition, there are two common arguments in these method signatures: resolve and query. Data returned by these methods comes in the below format, an object with two fields, TotalRecords (containing a count of all rows in the object/query result) and Rows which contains the data itself. 1

Using resolve to simplify response data

The resolve argument is used to simplify referential data returned by DealCloud. Depending, on the desired downstream uses, it might be the case that only an entity's name or ID is important. For this reason, the SDK provides some simple abstractions to make this process more straightforward, rather than needing to handle it manually.

• When resolve = "" or is not passed:
  • This means that no resolution is desired and the data should be returned from DealCloud with no additional transformation. E.g.: Client.Data.ReadObject("Company") will return:

[
    {
        "EntryId": 12345,
        "CompanyName": "Company1",
        "CompanyType": [
            {
                "seqNumber": 3,
                "isAutoPdf": false,
                "id": 3197780,
                "name": "Limited Partner",
                "entryListId": -6
            }
        ]
    },
    {
        "EntryId": 12346,
        "CompanyName": "Company2",
        "CompanyType": [
            {
                "seqNumber": 1,
                "isAutoPdf": false,
                "id": 3197782,
                "name": "Operating Company",
                "entryListId": -6
            }
        ]
    },
    {
        "EntryId": 12347,
        "CompanyName": "Company3",
        "CompanyType": [
            {
                "seqNumber": 4,
                "isAutoPdf": false,
                "id": 3197779,
                "name": "Service Provider",
                "entryListId": -6
            }
        ]
    }
]

• When resolve = "id":
  • This means that all referential data should be resolved to the entry ID. e.g.: Client.Data.ReadObject("Company", resolve="id") will return:

[
    {
        "EntryId": 12345,
        "CompanyName": "Company1",
        "CompanyType": [3197780]
    },
    {
        "EntryId": 12346,
        "CompanyName": "Company2",
        "CompanyType": [3197782]
    },
    {
        "EntryId": 12347,
        "CompanyName": "Company3",
        "CompanyType": [3197779]
    }
]

• When resolve = "name":
  • This means that all referential data should be resolved to the entry name. e.g.: Client.Data.ReadObject("Company", resolve="name") will return:

[
    {
        "EntryId": 12345,
        "CompanyName": "Company1",
        "CompanyType": ["Limited Partner"]
    },
    {
        "EntryId": 12346,
        "CompanyName": "Company2",
        "CompanyType": ["Operating Company"]
    },
    {
        "EntryId": 12347,
        "CompanyName": "Company3",
        "CompanyType": ["Service Provider"]
    }
]

Using query to query data

A query can be passed to the DealCloud request for data to return more specific information, and reduce the volume of incoming data. To use a query, pass the query string to the query argument. The available query operations are below:

Client.Data.ReadObject("Company", query="{CompanyName: {$contains: \"1\"}}")

will return:

[
    {
        "EntryId": 12345,
        "CompanyName": "Company1",
        "CompanyType": [
            {
                "seqNumber": 3,
                "isAutoPdf": false,
                "id": 3197780,
                "name": "Limited Partner",
                "entryListId": -6
            }
        ]
    }
]

Some other example query strings are below: Filter on excluding records with a specific reference value:

Client.Data.ReadObject("Company", query="{CoveragePerson: {$nin: [5785]}")

Filter using Or:

Client.Data.ReadObject("Company", query="{$or: [{CompanyName: \"Company1\"},{CompanyName: \"Company2\"}]}")

ReadObject example

using DealCloudSDK;
using Microsoft.Extensions.Configuration;
 
var config = new ConfigurationBuilder()
    .AddJsonFile("environment_config.json")
    .Build();
    
var dc = new Client(config);
 
var data = dc.Data.ReadObject("Company", resolve="name").Result;
 
Console.WriteLine($"Company has: {data.TotalRecords} rows.");
 
for (var company in data.Rows)
{
 Console.WriteLine($"{company["EntryId"]}: {company["CompanyName"]}");
}

will print something like (this will differ based on site data/fields):

Company has: 10123 rows
 
12345: Company 1
12346: Company 2
....
98543: Company 10123

Typed ReadObject example

using DealCloudSDK;
using Microsoft.Extensions.Configuration;
 
var config = new ConfigurationBuilder()
    .AddJsonFile("environment_config.json")
    .Build();
    
var dc = new Client(config);
 
var data = dc.Data.ReadObject("Company", resolve="name").Result;
 
Console.WriteLine($"Company has: {data.TotalRecords} rows.");
 
for (var company in data.Rows)
{
 Console.WriteLine($"{company["EntryId"]}: {company["CompanyName"]}");
}

will print something like (this will differ based on site data/fields):

Company has: 10123 rows
 
12345: Company 1
12346: Company 2
....
98543: Company 10123

Insert, Update and Upsert Data

Data can be edited in DealCloud using the SDK with a variety of methods. This includes methods to: Insert, Update and Upsert records. These methods are summarised below.

Insert Data

• Insert data to an object using the Object API Name

Client.Data.Insert(string objectId, List<IDictionary<string, object>> importData, bool useEntryIds = true)

• Insert typed data to an object using the Object API Name

Client.Data.Insert<T>(string objectId, List<T> importData, bool useEntryIds = true)

• Insert data to an object using the Object ID

Client.Data.Insert(int objectId, List<IDictionary<string, object>> importData, bool useEntryIds = true)

• Insert typed data to an object using the Object ID

Client.Data.Insert<T>(int objectId, List<T> importData, bool useEntryIds = true)

Insert Data Example

The below example demonstrates how to create two records in the Company object:

using DealCloudSDK;
using Microsoft.Extensions.Configuration;
 
var config = new ConfigurationBuilder()
    .AddJsonFile("environment_config.json")
    .Build();
    
var dc = new Client(config);
 
// generate data
var data = new List<IDictionary<string, object>> 
{
    new IDictionary<string, object> 
    {
        "CompanyName": "Test Company 1",
        "CompanyType": 12345,
        "BusinessDescription": "Here is a business description",
        "Sector": 14321,
    },
    new IDictionary<string, object> 
    {
        "CompanyName": "Test Company 2",
        "CompanyType": 12345,
        "BusinessDescription": "Here is another business description",
        "Sector": 14321,
    },
}
 
// insert data
var result = dc.Data.Insert("Company", data).Result;

If entry IDs are not known for fields such as CompanyType or Sector, the useEntryIds argument can be use to provide a lookup value.

using DealCloudSDK;
using Microsoft.Extensions.Configuration;
 
var config = new ConfigurationBuilder()
    .AddJsonFile("environment_config.json")
    .Build();
    
var dc = new Client(config);
 
// generate data
var data = new List<IDictionary<string, object>> 
{
    new IDictionary<string, object> 
    {
        "CompanyName": "Test Company 1",
        "CompanyType": "Operating Company",
        "BusinessDescription": "Here is a business description",
        "Sector": "Industrials",
    },
    new IDictionary<string, object> 
    {
        "CompanyName": "Test Company 2",
        "CompanyType": "Service Provider",
        "BusinessDescription": "Here is another business description",
        "Sector": "Legal",
    },
}
 
// insert data
var result = dc.Data.Insert("Company", data, false).Result;

To use the typed veresion of the above methods:

NOTE: The Newtonsoft.JSON package is a dependency for the C# SDK, and the JsonProperty attribute can be used to assist with serialisation and deserialisation of JSON and/or dynamic data into the desired types.

using DealCloudSDK;
using Microsoft.Extensions.Configuration;
 
var config = new ConfigurationBuilder()
    .AddJsonFile("environment_config.json")
    .Build();
    
var dc = new Client(config);
 
// generate data
public class Company
{
        [JsonProperty("EntryId")]
        public long EntryId { get; set; }
 
        [JsonProperty("CompanyName")]
        public string CompanyName { get; set; }
        
        [JsonProperty("CompanyType")]
        public long CompanyType { get; set; }
 
        [JsonProperty("BusinessDescription")]
        public string BusinessDescription { get; set; }
 
        [JsonProperty("Sector")]
        public long Sector { get; set; }
 
        public Company (long entryId, string companyName, long companyType, string businessDescription, long sector)
        {
            EntryId = entryId;
            CompanyName = companyName;
            CompanyType = companyType;
            BusinessDescription = businessDescription;
            Sector = sector;
        }
}
 
var data = new List<Company> 
{
    new Company
    (
        -1,
        "Test Company 1",
        12345,
        "Here is a business description",
        14321,
    ),
    new Company
    (
        -2,
        "Test Company 2",
        12345,
        "Here is another business description",
        14321,
    ),
}
 
// insert data
var result = dc.Data.Insert<Company>("Company", data, false).Result;

Update Data

To update records using the SDK, the pattern is the same as with Insert, except to update a record, you must pass Entry IDs for existing records in the DealCloud site.

• Update data to an object using the Object API Name

Client.Data.Update(string objectId, List<IDictionary<string, object>> importData, bool useEntryIds = true)

• Update typed data to an object using the Object API Name

Client.Data.Update<T>(string objectId, List<T> importData, bool useEntryIds = true)

• Update data to an object using the Object ID

Client.Data.Update(int objectId, List<IDictionary<string, object>> importData, bool useEntryIds = true)

• Update typed data to an object using the Object ID

Client.Data.Update<T>(int objectId, List<T> importData, bool useEntryIds = true)

Upsert Data

Upsert is a combination of Update and Insert, where Entry IDs can be included in importData and if the Entry ID is present, the record will be updated, if not it will be created.

Client.Data.Upsert(string objectId, List<IDictionary<string, object>> importData, bool useEntryIds = true)

• Upsert typed data to an object using the Object API Name

Client.Data.Upsert<T>(string objectId, List<T> importData, bool useEntryIds = true)

• Upsert data to an object using the Object ID

Client.Data.Upsert(int objectId, List<IDictionary<string, object>> importData, bool useEntryIds = true)

• Upsert typed data to an object using the Object ID

Client.Data.Upsert<T>(int objectId, List<T> importData, bool useEntryIds = true)

Mapping Data

The useEntryIds argument in the above methods allows the use of lookup values for referencing data in choice and reference fields. The default behaviour for this in reference fields is to lookup against the "Name" field for the object. However, using Client.Data.MapIDs(IDictionary<string, string> objectKeyColumns) it is possible to create a record of Entry IDs looked up against other fields, such as integration keys. The method accepts a dictionary describing the mapping to build. The keys should be the object API names to map. The values should be the API names of the fields that should be used as the lookup field for the desired object. e.g. {"Company":"LegacyID"} - instructs the construction of a mapping for the Company object, where LegacyID is to be used as the lookup value.

Once the mapping operation has been completed, the lookup store is maintained, and will be leveraged automatically when a data method is used with useEntryIds = false. For choice fields, the display value should be used, as it is not possible to store additional metadata on a choice value.

NOTE: To fully leverage this method, the Client should be constructed with the argument autoIdMapping = false. This indicates that the program will be managing the ID mapping explicitly, with custom fields in use as lookups.

Mapping Data Example:

using DealCloudSDK;
using Microsoft.Extensions.Configuration;
 
var config = new ConfigurationBuilder()
    .AddJsonFile("environment_config.json")
    .Build();
    
var dc = new Client(config, autoIdMapping = false);
 
// map sector with custom IDs
dc.Data.MapIDs(
    new Dictionary<string, string>
    {
        {"Sector": "Sector_ID"},
    }
).Result;
 
// generate data
var data = new List<IDictionary<string, object>> 
{
    new IDictionary<string, object> 
    {
        "CompanyName": "Test Company 1",
        "CompanyType": "Operating Company",
        "BusinessDescription": "Here is a business description",
        "Sector": "SECTOR_ID_TECH",
    },
    new IDictionary<string, object> 
    {
        "CompanyName": "Test Company 2",
        "CompanyType": "Service Provider",
        "BusinessDescription": "Here is another business description",
        "Sector": "SECTOR_ID_LEGAL",
    },
}
 
// insert data
var result = dc.Data.Insert("Company", data, false).Result;

Delete Data

It is possible to delete data using the following methods:

Client.Data.Delete(string objectId, List<long> records) Client.Data.Delete(int objectId, List<long> records)

The OBJECT API NAME or the OBJECT ID can be passed alongside a List of Entry IDs to be deleted, and the records will be deleted.

Delete Data Example:

The below example demonstrates how to delete records from the Company object with IDs: 12345, 12346.

using DealCloudSDK;
using Microsoft.Extensions.Configuration;
 
var config = new ConfigurationBuilder()
    .AddJsonFile("environment_config.json")
    .Build();
    
var dc = new Client(config);
 
_ = _dc.Data.Delete("Company", new List<long>{12345, 12346}).Result;