Interface IDataApi
Namespace: Casewhere.Runtime.DSL.Api
Assembly: Casewhere.Runtime.dll
Provides methods for working with Data Objects and Data Sources.
public interface IDataApi : IDslApi
Implements
Extension Methods
ObjectExtension.ConvertToBsonValue(object), EnumExtensions.DeepClone<IDataApi>(IDataApi)
Examples
var dataApi = ctx.Use<IDataApi>();
dataApi.Add("Order", order);Methods
Add(string, object, Guid?, bool)
Add a new Data Object.
string Add(string dataClass, object data, Guid? caseId = null, bool notifyChange = true)
Parameters
dataClass string
Data Class name
data object
Data Object to be added.
caseId Guid?
Id of the case that the object will be added to. If null, the data object will be added to the case of the workflow.
notifyChange bool
Skip the data change notification when updating data.
Returns
Id of the added Data Object.
Examples
var dataApi = ctx.Use<IDataApi>();
var orderId = dataApi.Add("Order", new
{
OrderNo = 100,
Customer = "Jane",
Total = 15.5
});AddExternalDO(object, Guid?)
Add a new external data object.
string AddExternalDO(object data, Guid? caseId = null)
Parameters
data object
Data Object to be added.
caseId Guid?
Id of the case that the object will be added to. If null, the data object will be added to the case of the workflow.
Returns
Id of the added Data Object.
Examples
var dataApi = ctx.Use<IDataApi>();
var orderId = dataApi.AddExternalDO(new
{
OrderNo = 100,
Customer = "Jane",
Total = 15.5
});Any(string, DynamicFilter)
Determines whether any element of a Data Collection exists or satisfies a condition.
bool Any(string dataClassName, DynamicFilter filter)
Parameters
dataClassName string
The Data Class name.
filter DynamicFilter
Filter object that is built using Casewhere.Runtime.DataObjectExpressions.DSL.FilterBuilder.
Returns
True if there is a Data Object satisfies the filter condition; otherwise, False.
Examples
var dataApi = ctx.Use<IDataApi>();
var filter = FilterBuilder.Create()
.Eq("DepartmentId", ctx.Input.Id)
.Eq("Active", true)
.Build();
var any = dataApi.Any("Employee", filter);
if (any) Log.Info("There is Employee in the Department!!!");ChangeCreator(string, string)
Update the CreatedBy attribute value of an Data object
void ChangeCreator(string id, string value)
Parameters
id string
Id of the Data Object to be updated.
value string
The new CreatedBy value.
Examples
var dataApi = ctx.Use<IDataApi>();
var dataClass = dataApi.ChangeCreator("EmployeeUserName");Clone(string, Guid?, bool)
Clone new object and add to database.
string Clone(string id, Guid? caseId = null, bool notifyChange = true)
Parameters
id string
The data object id to be cloned.
caseId Guid?
Id of the case that the object will be added to. If null, the data object will be added to the case of the workflow.
notifyChange bool
Skip the data change notification when updating data.
Returns
The new data object id.
Examples
var dataApi = ctx.Use<IDataApi>();
var clonedId = dataApi.Clone(id);Copy(string, string, bool)
Copy data from one existing data object to another. Only properties that exist in both Data Classes are copied.
void Copy(string srcId, string destId, bool notifyChange = true)
Parameters
srcId string
The source data object id.
destId string
The destination data object id.
notifyChange bool
Skip the data change notification when updating data.
Examples
var dataApi = ctx.Use<IDataApi>();
dataApi.Copy(srcId, desId);Count(string, DynamicFilter)
Count the Data Objects that satisfies a condition.
long Count(string dataClassName, DynamicFilter filter)
Parameters
dataClassName string
The Data Class name.
filter DynamicFilter
Filter object that is built using Casewhere.Runtime.DataObjectExpressions.DSL.FilterBuilder.
Returns
The number of Data Objects that satisfies the condition.
Examples
var dataApi = ctx.Use<IDataApi>();
var filter = FilterBuilder.Create()
.Eq("DepartmentId", ctx.Input.Id)
.Eq("Active", true)
.Build();
var count = dataApi.Count("Employee", filter);
Log.Info("There are {Count} Employees in the Department", count);Delete(string, bool)
Delete a Data Object.
void Delete(string id, bool notifyChange = true)
Parameters
id string
Id of the Data Object to be deleted.
notifyChange bool
Skip the data change notification when updating data.
Examples
var dataApi = ctx.Use<IDataApi>();
dataApi.Delete(orderId);DeleteMany(DataObjectApiQuery, bool)
Delete multiple existing data objects based on a specified search query.
void DeleteMany(DataObjectApiQuery query, bool notifyChange = true)
Parameters
query DataObjectApiQuery
The search query.
notifyChange bool
Skip the data change notification when updating data.
Examples
var dataApi = ctx.Use<IDataApi>();
var filter = FilterBuilder.Create().Eq("DepartmentId", ctx.Input.Id).Eq("Active", true).Build();
var query = DataObjectApiQuery
.For("Employee")
.FilterBy(filter);
dataApi.DeleteMany(query);DeleteMany(string[], bool)
Delete multiple existing data objects based on a specified array of data object IDs.
void DeleteMany(string[] dataObjectIds, bool notifyChange = true)
Parameters
dataObjectIds string[]
The array of data object IDs.
notifyChange bool
Skip the data change notification when updating data.
Examples
var dataApi = ctx.Use<IDataApi>();
var dataObjectIds = new string[] { "doId1", "doId2" };
dataApi.DeleteMany(dataObjectIds);DeleteMany(DataEnumerationQuery, CancellationToken, bool)
Delete multiple existing data objects based on a specified enumeration data object query.
void DeleteMany(DataEnumerationQuery query, CancellationToken token = default, bool notifyChange = true)
Parameters
query DataEnumerationQuery
An instance of the DataEnumerationQuery type. The param contains Data Class Name, Batch Size, Filter, ProjectedFields, SortedFields. The Instances of DataEnumerationQuery can't create directly. It is just create from static method DataEnumerationQuery.For("dataClassName").
token CancellationToken
an instance of CancellationToken. If it isn't passed, the default value will be assigned.
notifyChange bool
Skip the data change notification when updating data.
Examples
var dataApi = ctx.Use<IDataApi>();
var filter = FilterBuilder.Create().Eq("Active", true).Build();
var query = DataEnumerationQuery
.For("Employee")
.FilterBy(filter);
dataApi.DeleteMany(query);Enumerate(DataEnumerationQuery, CancellationToken)
Query and loop through an extensive collection without writing a lot of code for data paging, Which is also inefficient when dealing with 100k+ records.
IEnumerable<DynamicDataObject> Enumerate(DataEnumerationQuery queryBuilder, CancellationToken token = default)
Parameters
queryBuilder DataEnumerationQuery
An instance of the DataEnumerationQuery type. The param contains Data Class Name, Batch Size, Filter, ProjectedFields, SortedFields. The Instances of DataEnumerationQuery can't create directly. It is just create from static method DataEnumerationQuery.For("dataClassName").
token CancellationToken
an instance of CancellationToken. If it isn't passed, the default value will be assigned.
Returns
IEnumerable<DynamicDataObject>
The method will returns DynamicDataObject list
Examples
var dataApi = ctx.Use<IDataApi>();
var filter = FilterBuilder.Create().Eq("Active", true).Build();
var query = DataEnumerationQuery.For("Employee").FilterBy(filter);
var counter = 0;
foreach (var employee in dataApi.Enumerate(query))
{
var fullName = employee["FirstName"] + " " + employee["LastName"];
dataApi.Update(employee["Id"], new { FullName = fullName });
counter++;
if (counter % 100 == 0)
{
ctx.CommitChanges();
}
}Enumerate(DataSourceEnumerationQuery, CancellationToken)
Query and loop through an extensive collection without writing a lot of code for data paging, Which is also inefficient when dealing with 100k+ records.
IEnumerable<DynamicDataObject> Enumerate(DataSourceEnumerationQuery queryBuilder, CancellationToken token = default)
Parameters
queryBuilder DataSourceEnumerationQuery
An instance of the DataSourceEnumerationQuery type. The param contains Data Source Name, Batch Size, Filter, ProjectedFields, SortedFields. The Instances of DataSourceEnumerationQuery can't create directly. It is just create from static method DataSourceEnumerationQuery.For("dataSourceName").
token CancellationToken
an instance of CancellationToken. If it isn't passed, the default value will be assigned.
Returns
IEnumerable<DynamicDataObject>
The method will returns DynamicDataObject list
Examples
var dataApi = ctx.Use<IDataApi>();
var filter = FilterBuilder.Create().Eq("Active", true).Eq("IsDeleted", false).Build();
var query = DataSourceEnumerationQuery.For("EmployeeWithCompany").FilterBy(filter);
foreach (var employee in dataApi.Enumerate(query))
{
var employee = item;
Log.Info("Employee - {name}", employee["Name"]);
var company = employee["Company"];
Log.Info("Company - {name}", company["Name"]);
}EscapeSearchPhrase(string, string)
Escape the search phrase1. Use this method when you build the search phrase without FilterBuilder.
string EscapeSearchPhrase(string dataClassName, string searchPhase)
Parameters
dataClassName string
Name of the Data Class.
searchPhase string
The search phrase.
Returns
The escaped search phrase.
Examples
var dataApi = ctx.Use<IDataApi>();
dataApi.EscapeSearchPhrase("Employee", "a search phrase");GetDataClass(string)
Get data class by name
DataClass GetDataClass(string dataClassName)
Parameters
dataClassName string
Name of data class.
Returns
DataClass
Data class by name.
Examples
var dataApi = ctx.Use<IDataApi>();
var dataClass = dataApi.GetDataClass("Employee");GetSchema(string)
Load schema of a Data Source by name. This is useful for get data schema of a data source.
IList<DataSourceField> GetSchema(string dataSourceName)
Parameters
dataSourceName string
The Data Source name
Returns
A list of DataSourceField of data source
Examples
var dataApi = ctx.Use<IDataApi>();
var emplyeeSchema = dataApi.GetSchema("Employee");
Log.Info("This is schema {emplyeeSchema} of the Employee", emplyeeSchema);HardDelete(params string[])
Remove any events and data of the data objects by their identifiers.
void HardDelete(params string[] dataObjectIds)
Parameters
dataObjectIds string[]
The identifiers of data objects.
Examples
var dataApi = ctx.Use<IDataApi>();
dataApi.HardDelete(customerIds);Inc(string, string, dynamic)
Increase value of an attribute by specified increment amount.
void Inc(string id, string attributeName, dynamic value)
Parameters
id string
The identifiers of the data object.
attributeName string
The attribute name of the data object
value dynamic
The increment amount of the data object.
Examples
var dataApi = ctx.Use<IDataApi>();
var customerId = ctx.Input["Id"];
var attributeName = "AvailableBalance";
var incrementAmount = 10000;
dataApi.Inc(customerId, attributeName, incrementAmount);Load(string)
Load a Data Object by id.
DynamicDataObject Load(string id)
Parameters
id string
Id of the Data Object to be loaded.
Returns
DynamicDataObject
The Data Object.
Examples
var dataApi = ctx.Use<IDataApi>();
var department = dataApi.Load(departmentId);
Log.Info(department.Name);Load(string, bool)
Force load a Data Object by id from the Database and update it to the cache.
DynamicDataObject Load(string id, bool forceReload = false)
Parameters
id string
Id of the Data Object to be loaded.
forceReload bool
forceReload flag indicates whether to load data object directly from the Database and update it to the cache. Default value: false
Returns
DynamicDataObject
The Data Object.
Examples
var dataApi = ctx.Use<IDataApi>();
var department = dataApi.Load(departmentId, true);
Log.Info(department.Name);Load(string, string)
Load a Data Object from a Data Source by id. This is useful for custom data loading e.g. query including related data objects.
DynamicDataObject Load(string dataSourceName, string id)
Parameters
dataSourceName string
The Data Source name.
id string
Id of the Data Object to be loaded.
Returns
DynamicDataObject
The Data Object.
Examples
var dataApi = ctx.Use<IDataApi>();
var employee = dataApi.Load("EmployeesWithDepartments", employeeId);
Log.Info(employee.Department["Name"]);Migrate(string, object, bool)
Migrate an Data Object with a specified ID. This method allows add or update a data object with a specified ID without using generated ID from system. Note: if canUpdateIfExist = false then the method will throw exception the specified ID already exits in DB
[Obsolete("Move to new Migrate(string id, object data, DslMigrationOption option) api")]
void Migrate(string id, object data, bool canUpdateIfExist = false)
Parameters
id string
Id of the Data Object to be updated or added
data object
Data to be updated or added
canUpdateIfExist bool
canUpdateIfExist flag indicates whether to update the data object if it have already exist. Default value: false
Examples
var dataApi = ctx.Use<IDataApi>();
dataApi.Migrate(orderId, new
{
Total = 20,
BillingAddress = "123 Sunset Blvd"
},
true);Migrate(string, object, DslMigrationOption)
Migrate an Data Object with a specified ID. This method allows add or update a data object with a specified ID without using generated ID from system.
void Migrate(string id, object data, DslMigrationOption option)
Parameters
id string
Id of the Data Object to be updated or added
data object
Data to be updated or added
option DslMigrationOption
option object that is built using Casewhere.Runtime.DSL.DslMigrationOption.
Examples
var dataApi = ctx.Use<IDataApi>();
dataApi.Migrate(orderId, new
{
Total = 20,
BillingAddress = "123 Sunset Blvd"
},
new DslMigrationOption(canUpdateIfExist: true, ignoreEnforceConstraints: true));MoveToCase(string, Guid)
Move data object to a specific case.
void MoveToCase(string id, Guid caseId)
Parameters
id string
Id of the Data Object.
caseId Guid
CaseId of the Data Object.
Examples
var dataApi = ctx.Use<IDataApi>();
dataApi.MoveToCase(id, caseId);Pull(string, string, params object[])
Pull data from an array attribute. This method is thread-safe. Schema elements that are equal to the input values will be removed.
void Pull(string id, string attributeName, params object[] data)
Parameters
id string
The data object id.
attributeName string
The attribute name.
data object[]
The pulled data.
Examples
var dataApi = ctx.Use<IDataApi>();
dataApi.Pull(id, "Categories", "item1", "item2");
dataApi.Pull(id, "Categories", new string[]{ "item1", "item2" });Push(string, string, params object[])
Push data to an array attribute. This method is thread-safe.
void Push(string id, string attributeName, params object[] data)
Parameters
id string
The data object id.
attributeName string
The attribute name.
data object[]
The pushed data.
Examples
var dataApi = ctx.Use<IDataApi>();
dataApi.Push(id, "Categories", "item1", "item2");
dataApi.Push(id, "Categories", new string[]{ "item1", "item2" });Search(DataObjectApiQuery)
Search Data Objects.
DynamicQueryResult Search(DataObjectApiQuery query)
Parameters
query DataObjectApiQuery
The search query.
Returns
Collection of Data Objects.
Examples
var dataApi = ctx.Use<IDataApi>();
var filter = FilterBuilder.Create().Eq("DepartmentId", ctx.Input.Id).Eq("Active", true).Build();
var result = dataApi.Search(DataObjectApiQuery
.For("Employee")
.FilterBy(filter));
Log.Info("Total: {TotalItems}", result.TotalItems);
foreach(var emp in result.Data)
Log.Info("{Employee}", emp);Search(DataSourceApiQuery)
Search Data Objects from a Data Source.
DynamicQueryResult Search(DataSourceApiQuery query)
Parameters
query DataSourceApiQuery
The search query.
Returns
Collection of Data Objects.
Examples
var dataApi = ctx.Use<IDataApi>();
var filter = FilterBuilder.Create().Eq("DepartmentId", ctx.Input.Id).Eq("Active", true).Build();
var result = dataApi.Search(DataSourceApiQuery
.For("EmployeesWithDepartments")
.FilterBy(filter));
Log.Info("Total: {TotalItems}", result.TotalItems);
foreach(var emp in result.Data)
Log.Info("{DepartmentName}", emp.Department.Name);Update(string, object, bool)
Update an existing Data Object.
void Update(string id, object data, bool notifyChange = true)
Parameters
id string
Id of the Data Object to be updated.
data object
Data to be updated.
notifyChange bool
Skip the data change notification when updating data.
Examples
var dataApi = ctx.Use<IDataApi>();
dataApi.Update(orderId, new
{
Total = 20,
BillingAddress = "123 Sunset Blvd"
});UpdateMany(string[], object, bool)
Updates multiple existing data objects based on an array of IDs with patch data.
void UpdateMany(string[] doIds, object patchData, bool notifyChange = true)
Parameters
doIds string[]
An array of IDs representing the data objects to be updated.
patchData object
Data to be updated.
notifyChange bool
Skip the data change notification when updating data.
Examples
var dataApi = ctx.Use<IDataApi>();
dataApi.UpdateMany(new string[] { "doId1", "doId2" }, new
{
Total = 20,
BillingAddress = "123 Sunset Blvd"
});UpdateMany(DataObjectApiQuery, object, bool)
Updates multiple existing data objects based on a specified search query with patch data.
void UpdateMany(DataObjectApiQuery query, object patchData, bool notifyChange = true)
Parameters
query DataObjectApiQuery
The search query.
patchData object
Data to be updated.
notifyChange bool
To skip the data change notification on updating data.
Examples
var dataApi = ctx.Use<IDataApi>();
var filter = FilterBuilder.Create().Eq("DepartmentId", ctx.Input.Id).Eq("Active", true).Build();
var query = DataObjectApiQuery
.For("Employee")
.FilterBy(filter);
dataApi.UpdateMany(query, new
{
Total = 20,
BillingAddress = "123 Sunset Blvd"
});UpdateMany(DataEnumerationQuery, object, CancellationToken, bool)
Update multiple existing data objects based on a specified enumeration data object query with patch data.
void UpdateMany(DataEnumerationQuery query, object patchData, CancellationToken token = default, bool notifyChange = true)
Parameters
query DataEnumerationQuery
An instance of the DataEnumerationQuery type. The param contains Data Class Name, Batch Size, Filter, ProjectedFields, SortedFields. The Instances of DataEnumerationQuery can't create directly. It is just create from static method DataEnumerationQuery.For("dataClassName").
patchData object
Data to be updated.
token CancellationToken
an instance of CancellationToken. If it isn't passed, the default value will be assigned.
notifyChange bool
To skip the data change notification on updating data.
Examples
var dataApi = ctx.Use<IDataApi>();
var filter = FilterBuilder.Create().Eq("DepartmentId", ctx.Input.Id).Eq("Active", true).Build();
var query = DataEnumerationQuery
.For("Employee")
.FilterBy(filter);
dataApi.UpdateMany(query,new
{
Total = 20,
BillingAddress = "123 Sunset Blvd"
});