Extension methods and additional functionality for the Endjin.FreeAgent.Client library, providing timesheets management, project filtering, user settings, and activity summaries.
Extension methods and additional functionality for the Endjin.FreeAgent.Client library, providing enhanced features for working with the FreeAgent API.
Features
Extension Members - .NET 10 extension member support for FreeAgent client
Timesheets Module - Comprehensive timesheet management and aggregation
Project Extensions - Advanced project filtering with flexible rule-based system
User Settings - Employee payroll configuration and management
Activity Summaries - Time tracking and activity reporting
Flexible Architecture - Extensible registry pattern for adding custom modules
The Timesheets extension provides comprehensive time tracking functionality:
using Endjin.FreeAgent.Client;
using Endjin.FreeAgent.Client.Extensions;
using Microsoft.Extensions.Caching.Memory;
// Initialize client with Timesheets extension
FreeAgentClient client = FreeAgentClient.CreateWithTimesheets(
options,
cache,
httpClientFactory,
loggerFactory,
"Artefacts/example-employee-payroll.yml");
// Or add to existing client
client.WithTimesheets(cache, "Artefacts/example-employee-payroll.yml");
// Get timesheets for current week
List<WeeklyTimesheet> weeklyTimesheets = await client.Timesheets
.GetTimesheetsForCurrentWeekAsync();
// Get timesheets for specific week
List<WeeklyTimesheet> specificWeek = await client.Timesheets
.GetTimeslipsForYearAndWeekNumberAsync(2024, 42);
// Get monthly timesheets
List<MonthlyTimesheet> monthlyTimesheets = await client.Timesheets
.GetTimesheetsForMonthAsync(DateTime.Now.Year, DateTime.Now.Month);
Project Extensions
Advanced project filtering with flexible rule-based system:
using Endjin.FreeAgent.Client.Extensions;
using Endjin.FreeAgent.Client.Extensions.Extensions;
// Register projects extension
client.WithProjectsExtended(cache);
// Configure project filtering with rules
var filterOptions = new ProjectFilterOptions
{
Rules = new[]
{
// Exclude projects with specific name prefixes
new FilterRule(FilterField.ProjectName, FilterRuleType.Prefix, "test", FilterAction.Exclude),
new FilterRule(FilterField.ProjectName, FilterRuleType.Prefix, "demo", FilterAction.Exclude),
// Exclude projects containing certain keywords
new FilterRule(FilterField.ProjectName, FilterRuleType.Contains, "internal", FilterAction.Exclude),
// Use regex for complex patterns
new FilterRule(FilterField.ProjectName, FilterRuleType.Regex, @"^(DEV|TEST)-\d{3}-",
FilterAction.Exclude, caseSensitive: true)
},
ExcludedProjectIds = new[] { "999", "888" },
RequireContactEntry = true,
RequireProjectName = true,
RequireOrganizationName = false
};
// Get filtered active projects
IEnumerable<Project> filteredProjects = await client.Projects.GetIncludedActiveAsync(filterOptions);
// Get detailed project information
DateInterval range = new(DateTime.Now.AddMonths(-1), DateTime.Now);
List<ProjectDetails> projectDetails = await client.ProjectsExtended
.GetAllProjectDetailsAsync(range);
foreach (ProjectDetails details in projectDetails)
{
Console.WriteLine($"Project: {details.Project.Name}");
Console.WriteLine($" Total Hours: {details.TotalHours}");
Console.WriteLine($" Total Cost: {details.TotalCost:C}");
}
User Settings
Manage employee payroll configuration from YAML:
using Endjin.FreeAgent.Client.Extensions;
using Endjin.FreeAgent.Domain.Extensions;
// Initialize user settings service
client.WithUserSettings(cache, "Artefacts/example-employee-payroll.yml");
// Access via extension property
UserSettingsService settingsService = client.UserSettings;
// Get all user settings
IEnumerable<UserSettings> allUsers = settingsService.GetAllUserSettings();
// Get only directors
IEnumerable<UserSettings> directors = settingsService.GetAllDirectorsUserSettings();
// Get active employees (excluding directors)
IEnumerable<UserSettings> employees = settingsService.GetAllActiveEmployeeUserSettings();
// Work with user settings
foreach (UserSettings user in allUsers)
{
// Use extension members
string fullName = user.FullName; // Extension member property
bool isActive = user.IsActive; // Extension member property
Console.WriteLine($"{fullName} - Active: {isActive}");
// Access roles
EmploymentRole? currentRole = user.Roles
.OrderBy(r => r.StartDate)
.LastOrDefault(r => r.EndDate == null);
if (currentRole != null)
{
Console.WriteLine($" Role: {currentRole.Title}");
Console.WriteLine($" Cost: {currentRole.Cost:C}");
}
}
Extension Registry
The extension registry pattern allows for modular functionality:
// Check if extensions are available
if (client.HasTimesheets)
{
Timesheets timesheets = client.Timesheets;
// Use timesheet functionality
}
// Check extension count
int count = client.ExtensionCount;
Console.WriteLine($"Loaded {count} extensions");
// Get all extension types
IReadOnlyCollection<Type> extensions = client.Extensions;
// Register all extensions at once
client.WithAllExtensions(cache, "Artefacts/example-employee-payroll.yml");
Advanced Features
Activity Summaries
Aggregate time tracking data:
// Get timesheet activity for a user
TimesheetActivitySummary summary = await client.Timesheets.GetTimesheetActivityAsync(
userId: "123",
fromDate: "2024-01-01",
toDate: "2024-01-31");
Console.WriteLine($"Total Hours: {summary.TotalHours}");
Console.WriteLine($"Total Projects: {summary.ProjectCount}");
// Get weekly timesheet activity
TimesheetActivitySummary weeklySummary = await client.Timesheets
.GetWeeklyTimesheetActivityAsync("123", 2024, 42);
Weekly and Monthly Aggregations
// Get last week's timesheets
List<WeeklyTimesheet> lastWeek = await client.Timesheets.GetTimesheetsForLastWeekAsync();
foreach (WeeklyTimesheet timesheet in lastWeek)
{
// Use extension members for calculations
decimal hours = timesheet.CalculateHours();
bool isValid = timesheet.IsValid(); // Validates against 40-hour week
string userName = $"{timesheet.User?.FirstName} {timesheet.User?.LastName}";
Console.WriteLine($"{userName}: {hours}h (Valid: {isValid})");
// Access individual timeslips
if (timesheet.Timeslips != null)
{
foreach (Timeslip slip in timesheet.Timeslips)
{
Console.WriteLine($" {slip.Project}: {slip.Hours}h");
}
}
}
// Get current month's timesheets
List<MonthlyTimesheet> currentMonth = await client.Timesheets
.GetTimesheetsForCurrentMonthAsync();
foreach (MonthlyTimesheet monthly in currentMonth)
{
decimal hours = monthly.CalculateHours();
decimal target = monthly.TargetHours(); // MonthlyTimesheet has TargetHours() method
bool isValid = monthly.IsValid();
Console.WriteLine($"Month {monthly.MonthOfYear}: {hours}h / {target}h (Valid: {isValid})");
}
// Get full year timesheet
Timesheet yearlyTimesheet = await client.Timesheets.GetTimeslipsForYearAsync(2024);
Project Filtering Rules
The filtering system supports multiple rule types and actions:
// Available FilterRuleTypes:
// - Prefix: Matches if field starts with pattern
// - Suffix: Matches if field ends with pattern
// - Contains: Matches if field contains pattern
// - Exact: Matches if field exactly equals pattern
// - Regex: Matches using regular expression
// Available FilterActions:
// - Exclude: Exclude matching projects
// - Include: Include matching projects (stops processing further rules)
// - RequireExplicitInclusion: Only include if project ID is in explicit inclusion list
var advancedFilters = new ProjectFilterOptions
{
Rules = new[]
{
// Exclude test projects
new FilterRule(FilterField.ProjectName, FilterRuleType.Prefix, "TEST-", FilterAction.Exclude),
// Require explicit inclusion for partner projects
new FilterRule(FilterField.OrganizationName, FilterRuleType.Contains, "Partner",
FilterAction.RequireExplicitInclusion)
{
ExplicitInclusions = new[] { "proj-123", "proj-456" }
},
// Include specific projects by exact name
new FilterRule(FilterField.ProjectName, FilterRuleType.Exact, "Important Project",
FilterAction.Include)
},
ExcludedProjectIds = new[] { "excluded-1", "excluded-2" },
RequireContactEntry = true,
RequireProjectName = true
};
IEnumerable<Project> projects = await client.Projects.GetIncludedActiveAsync(advancedFilters);
Loading Filter Configuration from JSON
You can also load filter rules from a JSON configuration file: