InstanceService.GetInstances

Reference

PagedData<Instance> GetInstances(InstanceQuery instanceQuery)

Use GetInstances to get a paginated list of instances of a Protrak instance type based on an InstanceQuery.

Parameters

• InstanceQuery instanceQuery:
  • string InstanceTypeName: The instance type name for which instances need to be fetched. Required parameter.
  • string[] Attributes: Attribute names for which values need to be fetched for each instance in response. Optional parameter.
  • int Skip: Number of records to skip. Optional? Default value?
  • int Take: Number of records to fetch. Optional? Default value?
  • string[] StateFilter: Array of lifecycle state names to filter the instances with. Optional parameter.
  • AttributeFilterExpression[] AttributeFilterExpressions: Array of attribute filter expressions to filter the instances. Optional parameter.
  • RelationFilter[] ParentFilters: Array of RelationFilter to filter the instances based on relationships.
  • string SortBy: Attribute name to sort the instances by. Optional parameter. Default value is "ModifiedDate"
  • bool IsSortByDescending: Flag to indicate whether to sort instances by descending order of the value of attribute specified in SortBy. Optional parameter. Default value is false.
  • bool GetAllowedOperations: Flag to indicate whether the return value should contain allowed operations for each instance. Optional parameter. Default value is false.
  • bool GetAllowedActions: Flag to indicate whether the return value should contain allowed promote actions for each instance. Optional parameter. Default value is false.
  • bool GetOnlyActionableInstances: Flag to indicate whether the returned value should have only such instances having at least one promote action available to the context user. Optional parameter. Default value is false.
  • bool GetOnlyConnectableInstances: Flag to indicate whether the returned value should have only such instances having link permission to the context user. Optional parameter. Default value is false.
  • ActivityQuery ActivityQuery: ActivityQuery indicates whether the returned instances should have activities list based on the specified activity filter. Optional parameter.

Returns

• PagedData<Instance>:
  • int TotalCount: Total number of records after applying all specified filters.
  • int Skip: Skip parameter value provided.
  • int Take: Take parameter value provided.
  • IEnumerable<Instance> Items: See GetInstance

Caveats

Usage

• Using AttributeFilterExpressions

Add these namespaces before using simplified patterns:

```csharp
using Prorigo.Protrak.API.Contracts.Builders;
using Prorigo.Protrak.API.Contracts.Extensions;
using Prorigo.Protrak.API.Contracts.Enum;

• Using InstanceQueryBuilder with attribute filters

var instanceQuery = InstanceQueryBuilder.ForType(TYPE_TASK_TEMPLATE)
    .Select("Name", ATTR_PROJECT_TYPE, ATTR_EFFORT, ATTR_STAGE)
    .Where(ATTR_PROJECT_TYPE, AttributeFilterOperator.Equals, "Cloud")
    .SortBy(ATTR_INDEX)
    .TakeAll()
    .Build();

var tasks = new List<ProjectTask>();
var instances = InstanceService.GetInstances(instanceQuery);

foreach (var templateInstance in instances.SafeItems())
{
    AddMilestoneFromTemplate(tasks, templateInstance.Name, templateInstance.Attributes);
}

• Using ParentFilters

⚠ Builder gap: ParentFilters is not supported by InstanceQueryBuilder. Use the verbose new InstanceQuery { ... } form.

// ⚠ Builder gap: ParentFilters not supported — use verbose form
using Prorigo.Protrak.API.Contracts.Filters;
using Prorigo.Protrak.API.Contracts.Enum;

var dueDateInstQuery = new InstanceQuery
{
	InstanceTypeName = TYPE_DUE_DATE,
	ParentFilters = new RelationFilter[]
		{
			new RelationFilter()
			{
				RelationTypeName = RELATION_PATENT_TO_DUE_DATE,
				RelationDirection = RelationDirection.From,
				TypeName = TYPE_PATENT,
			}
		},
	Attributes = new string[] { ATTRIBUTE_FORM_TYPE, ATTRIBUTE_DUE_DATES, ATTRIBUTE_DUE_DATE_STATUS },
	Take = int.MaxValue
};

var dueDateInstances = InstanceService.GetInstances(dueDateInstQuery);

• Using ActivityQuery

⚠ Builder gap: ActivityQuery is not supported by InstanceQueryBuilder. Use the verbose new InstanceQuery { ... } form.

// ⚠ Builder gap: ActivityQuery not supported — use verbose form
using Prorigo.Protrak.API.Contracts.Enum;

var instanceQuery = new InstanceQuery
{
	InstanceTypeName = typeName,
	Take = int.MaxValue,
	ActivityQuery = new ActivityQuery
	{
		Type = ActivityType.ActionPromoted,
		IsSortByDescending = false,
		Take = int.MaxValue
	},
};

var instances = InstanceService.GetInstances(instanceQuery);

foreach (var instance in instances.SafeItems())
{
	var activities = instance.Activities;
	if (activities != null && activities.Count() > 1)
	{
		var instancesActivities = activities.ToList();
		foreach (var activity in instancesActivities)
		{
			var author = activity.Author;

			var startMonth = activity.StartTime.Date.ToString("MMM");
			var startYear = activity.StartTime.Date.Year;

			var	endMonth = activity.EndTime.Date.ToString("MMM");
			var endYyear = activity.EndTime.Date.Year;
			//....
			//...
		}
	}
}

Troubleshooting