Resource load#

This guide shows how to measure how busy each resource is over a date range, which is the data behind a resource histogram. It covers the profile query, how capacity follows resource calendars, which tasks fill each bucket, and how to get the load for dates you haven't committed yet.

How a load profile works#

Project#loadProfile reads the solved baseline and cuts the date range into buckets of an hour or a day. For every resource it reports each bucket's load and capacity. The call is synchronous and read-only: it never schedules and never changes the project.

Three types are involved:

A ProfileQuery says what to measure: the range from..to, which resources, the bucket size (basis) and whether to list tasks. new ProfileQuery(from, to) gives you every resource, the default basis and no task lists. Override the rest with the fluent withResources, withBasis and withTasks setters.
LoadProfileOptions wraps the query and adds an optional baselineId. The usual call is project.loadProfile(new LoadProfileOptions(query)).
The result is a LoadProfile: the basis it used and a Vec<ResourceLoad>, one ResourceLoad per resource. Each ResourceLoad has the resource id, its capacityMode and a list of LoadBucket values with start, load, capacity and tasks.

These rules decide what ends up in the buckets:

Range. A bucket is included when its start lies in [from, to). A day bucket starts at midnight, so a from of Monday 12:00 skips Monday and starts on Tuesday. to is exclusive.
Dense output. Every bucket in the range appears, including empty ones with load 0. That's why the range is capped at 100 000 buckets per resource, about 11 years at hour basis.
Basis. With basis left null, the basis follows config.durationUnit: Basis.DAY for days, Basis.HOUR for hours and minutes. Set basis to override it.
Load units. Load is in assignment value units, where 1 is 100 %. Nothing is converted to hours. An assignment that works in a bucket books its value there, so two full-time tasks on the same day give a load of 2.0.
Same load as leveling. The profile uses the same sweep as the leveler and as the overallocations in ScheduleResult: only real work segments, each assignment on its own calendar, cut to its slice. A bucket overallocates when load > capacity.
Order. Resources come back in input order, and so do the task ids in a bucket.

The profile always describes the accepted baseline, so the project has to be solved and clean. Failures throw unchecked exceptions:

Failure	Exception
Project not solved yet, or edited with `apply` since the last solve	`ProjectException` with code `NO_BASELINE`
`baselineId` doesn't name the current baseline	`ProjectException` with code `STALE_BASELINE`
`to <= from`, or more than 100 000 buckets	`InputException`, path `to`
Unknown id in `resources`	`InputException`, path `resources`

See Handling errors for the exception types and the LoadProfile reference for every field.

Querying a profile#

Solve the project, build a ProfileQuery and pass it to loadProfile.

import org.dhtmlx.plen.*;
import java.util.List;

public class QueryProfile {
    static Moment at(int day, int hour) {
        return Moment.fromYmdHm(2026, 8, day, hour, 0);
    }

    static TaskData task(String id, Moment start, double duration) {
        return new TaskData(Id.str(id)).withStartDate(start).withDuration(duration);
    }

    static AssignmentData assign(String task, String resource, double value) {
        return new AssignmentData()
            .withId(Id.str(task + ":" + resource))
            .withTask(Id.str(task))
            .withResource(Id.str(resource))
            .withValue(value);
    }

    public static void main(String[] args) throws Exception {
        // 2026-08-10 is a Monday.
        ProjectData data = new ProjectData()
            .withTasks(List.of(
                task("a", at(10, 8), 2.0),
                task("b", at(10, 8), 1.0),
                task("c", at(11, 8), 1.0),
                task("d", at(12, 8), 1.0)))
            .withResources(List.of(new ResourceData().withId(Id.str("dev"))))
            .withAssignments(List.of(
                assign("a", "dev", 1.0),
                assign("b", "dev", 1.0),
                assign("c", "dev", 0.5),
                assign("d", "dev", 1.0)));

        Project project = new Project();
        project.solve(data, new SolveOptions());

        // Sunday 9 up to Friday 14; `to` is exclusive.
        ProfileQuery query = new ProfileQuery(at(9, 0), at(14, 0));
        LoadProfile profile = project.loadProfile(new LoadProfileOptions(query));

        System.out.println("basis: " + profile.basis);
        for (ResourceLoad row : profile.resources) {
            for (LoadBucket bucket : row.buckets) {
                System.out.println(row.resource + " " + bucket.start
                    + ": load " + bucket.load + " of " + bucket.capacity);
            }
        }
    }
}

The project uses day units, so the basis is DAY and you get five buckets, Sunday to Thursday. The loads are 0.0, 2.0 (a and b), 1.5 (a plus c at half time), 1.0 (d) and 0.0. Capacity is 1.0 in every bucket: dev has no capacity of its own, so it takes config.defaultResourceCapacity.

Narrowing the query#

Set resources to measure only some resources, and basis to change the bucket size. Both are fluent setters on ProfileQuery; withResources also takes a List.of(...).

import org.dhtmlx.plen.*;
import java.util.List;

public class NarrowQuery {
    static Moment at(int day, int hour) {
        return Moment.fromYmdHm(2026, 8, day, hour, 0);
    }

    static TaskData task(String id, Moment start, double duration) {
        return new TaskData(Id.str(id)).withStartDate(start).withDuration(duration);
    }

    static AssignmentData assign(String task, String resource) {
        return new AssignmentData()
            .withTask(Id.str(task))
            .withResource(Id.str(resource))
            .withValue(1.0);
    }

    public static void main(String[] args) throws Exception {
        ProjectData data = new ProjectData()
            .withTasks(List.of(task("a", at(10, 8), 2.0), task("b", at(10, 8), 1.0)))
            .withResources(List.of(
                new ResourceData().withId(Id.str("dev")),
                new ResourceData().withId(Id.str("qa"))))
            .withAssignments(List.of(assign("a", "dev"), assign("b", "dev")));

        Project project = new Project();
        project.solve(data, new SolveOptions());

        // Monday 07:00 to 10:00, hour buckets, `dev` only.
        ProfileQuery query = new ProfileQuery(at(10, 7), at(10, 10))
            .withResources(List.of(Id.str("dev")))
            .withBasis(Basis.HOUR);
        LoadProfile profile = project.loadProfile(new LoadProfileOptions(query));

        for (ResourceLoad row : profile.resources) {
            List<Double> loads = row.buckets.stream().map(b -> b.load).toList();
            System.out.println(row.resource + ": " + loads);
        }
    }
}

Only dev comes back, with three hour buckets. The 07:00 bucket is before work starts (0.0), and 08:00 and 09:00 carry both tasks (2.0 each). An id in resources that isn't in the project throws an InputException at path resources.

Pinning the profile to a baseline#

A UI often fetches the profile some time after the solve. To make sure the profile matches the dates on screen, pass the token from the solve result as LoadProfileOptions.baselineId. If the project was solved again in the meantime, the call throws a ProjectException with code STALE_BASELINE instead of returning load for other dates.

import org.dhtmlx.plen.*;
import java.util.List;

public class PinnedProfile {
    static Moment at(int day, int hour) {
        return Moment.fromYmdHm(2026, 8, day, hour, 0);
    }

    public static void main(String[] args) throws Exception {
        ProjectData data = new ProjectData()
            .withTasks(List.of(
                new TaskData(Id.str("a")).withStartDate(at(10, 8)).withDuration(2.0)))
            .withResources(List.of(new ResourceData().withId(Id.str("dev"))))
            .withAssignments(List.of(new AssignmentData()
                .withTask(Id.str("a"))
                .withResource(Id.str("dev"))
                .withValue(1.0)));

        Project project = new Project();
        ScheduleResult solved = project.solve(data, new SolveOptions());

        LoadProfileOptions options =
            new LoadProfileOptions(new ProfileQuery(at(10, 0), at(15, 0)))
                .withBaselineId(solved.baselineId);
        LoadProfile profile = project.loadProfile(options);
        System.out.println(profile.resources.size() + " resource(s) measured");
    }
}

Take the token from the latest solve result. Tokens are opaque, and the same data solved twice can get a different one, so don't store them or compare them across runs.

Capacity modes#

Capacity is the resource's capacity, or config.defaultResourceCapacity (1.0) when it's null. The capacityMode of each ResourceLoad tells you how it's spread over the buckets:

CapacityMode.CALENDAR: the resource has its own calendar, config.calendarMode is RESOURCE (the default) and config.useCalendars is on. Buckets with working time on that calendar get the full capacity, all others get 0.
CapacityMode.FLAT: every bucket gets the full capacity, weekends and nights included. This applies when the resource has no calendar, when calendarMode is a task mode (TASK or TASK_INHERITED), or when useCalendars is false.

In calendar mode an assignment always works on the resource's calendar, or on the overlap of the task's and the resource's calendars. So a bucket with capacity 0 never gets load, and a bucket overallocates in the profile exactly when leveling sees it as overallocated.

import org.dhtmlx.plen.*;
import java.util.List;

public class CapacityModes {
    static Moment at(int day, int hour) {
        return Moment.fromYmdHm(2026, 8, day, hour, 0);
    }

    // Days run Sunday..Saturday.
    static CalendarData calendar(String id, boolean[] days, int startHour, int endHour) {
        return new CalendarData()
            .withId(Id.str(id))
            .withWorktime(new Worktime()
                .withHours(List.of(new TimeRange(startHour * 60, endHour * 60)))
                .withDays(days));
    }

    static ResourceData resource(String id, String calendar) {
        return new ResourceData()
            .withId(Id.str(id))
            .withCalendarId(calendar == null ? null : Id.str(calendar));
    }

    static final boolean[] MON_FRI = {false, true, true, true, true, true, false};
    static final boolean[] TUE_SAT = {false, false, true, true, true, true, true};

    public static void main(String[] args) throws Exception {
        ProjectData data = new ProjectData()
            .withTasks(List.of(
                new TaskData(Id.str("a")).withStartDate(at(11, 8)).withDuration(2.0))) // Tuesday
            .withCalendars(List.of(
                calendar("global", MON_FRI, 8, 16),
                calendar("tue_sat", TUE_SAT, 8, 16),
                calendar("mornings", MON_FRI, 8, 12)))
            .withResources(List.of(
                resource("office", null),
                resource("shop", "tue_sat"),
                resource("part_time", "mornings")))
            .withAssignments(List.of(new AssignmentData()
                .withTask(Id.str("a"))
                .withResource(Id.str("shop"))
                .withValue(1.0)));

        Project project = new Project();
        project.solve(data, new SolveOptions());

        // One week in day buckets, Sunday 9 to Saturday 15.
        LoadProfile week = project.loadProfile(
            new LoadProfileOptions(new ProfileQuery(at(9, 0), at(16, 0))));
        for (ResourceLoad row : week.resources) {
            List<Double> capacity = row.buckets.stream().map(b -> b.capacity).toList();
            List<Double> load = row.buckets.stream().map(b -> b.load).toList();
            System.out.println(row.resource + " (" + row.capacityMode + "): capacity "
                + capacity + ", load " + load);
        }

        // Tuesday 06:00 to 18:00 in hour buckets, for the part-time resource.
        ProfileQuery day = new ProfileQuery(at(11, 6), at(11, 18))
            .withResources(List.of(Id.str("part_time")))
            .withBasis(Basis.HOUR);
        LoadProfile hours = project.loadProfile(new LoadProfileOptions(day));
        List<Double> capacity =
            hours.resources.get(0).buckets.stream().map(b -> b.capacity).toList();
        System.out.println("part_time hourly capacity: " + capacity);
    }
}

What the week shows:

office has no calendar, so it's FLAT with capacity 1.0 on all seven days, Sunday and Saturday included.
shop is CALENDAR. Its capacity is 0 on Sunday and Monday and 1.0 from Tuesday to Saturday. Task a runs Tuesday and Wednesday, so those two buckets have load 1.0.
At hour basis, part_time has capacity only in the four hour buckets between 08:00 and 12:00. The other eight hours are 0.

Set data.config.calendarMode = CalendarMode.TASK (or data.config.useCalendars = false) and all three resources become FLAT, with capacity 1.0 in every bucket. See Working time and calendars for calendar setup and the CapacityMode reference.

Task lists per bucket#

A histogram usually needs to say who is overloading a resource. Set ProfileQuery.tasks to fill LoadBucket.tasks:

`ProfileTasks`	`LoadBucket.tasks`
`NONE` (default)	`null` in every bucket
`OVER`	the ids in buckets where `load > capacity`, an empty `Vec` elsewhere
`ALL`	the ids of every task booked in the bucket

import org.dhtmlx.plen.*;
import java.util.List;

public class TaskLists {
    static Moment at(int day, int hour) {
        return Moment.fromYmdHm(2026, 8, day, hour, 0);
    }

    static TaskData task(String id, Moment start, double duration) {
        return new TaskData(Id.str(id)).withStartDate(start).withDuration(duration);
    }

    static AssignmentData assign(String task, double value) {
        return new AssignmentData()
            .withTask(Id.str(task))
            .withResource(Id.str("dev"))
            .withValue(value);
    }

    public static void main(String[] args) throws Exception {
        ProjectData data = new ProjectData()
            .withTasks(List.of(
                task("a", at(10, 8), 2.0),
                task("b", at(10, 8), 1.0),
                task("c", at(11, 8), 1.0),
                task("d", at(12, 8), 1.0)))
            .withResources(List.of(new ResourceData().withId(Id.str("dev"))))
            .withAssignments(List.of(
                assign("a", 1.0),
                assign("b", 1.0),
                assign("c", 0.5),
                assign("d", 1.0)));

        Project project = new Project();
        project.solve(data, new SolveOptions());

        // Monday 10 to Thursday 13.
        ProfileQuery query = new ProfileQuery(at(10, 0), at(14, 0))
            .withTasks(ProfileTasks.OVER);
        LoadProfile profile = project.loadProfile(new LoadProfileOptions(query));

        for (LoadBucket bucket : profile.resources.get(0).buckets) {
            System.out.println(bucket.start + ": load " + bucket.load + ", tasks " + bucket.tasks);
        }
    }
}

With OVER, Monday lists a and b, and Tuesday lists a and c. Wednesday and Thursday aren't overloaded, so they get empty lists. Switch to ProfileTasks.ALL and Wednesday lists d too, because ALL reports every booked task regardless of capacity.

If you need only the overloaded periods, not the full histogram, skip the profile. Every ScheduleResult of a project with assignments carries overallocations: per-resource windows with peak, overload and the contending tasks. See Leveling resources for how to remove the overload.

Load of hypothetical dates#

loadProfile only reads the baseline. To see the load an edit would cause, set PreviewOptions.profile to a ProfileQuery and call preview. The result's profile is computed on the previewed dates, and the project is left untouched.

import org.dhtmlx.plen.*;
import java.util.List;

public class PreviewLoad {
    static Moment at(int day, int hour) {
        return Moment.fromYmdHm(2026, 8, day, hour, 0);
    }

    static TaskData task(String id, Moment start, double duration) {
        return new TaskData(Id.str(id)).withStartDate(start).withDuration(duration);
    }

    static AssignmentData assign(String task, String resource, double value) {
        return new AssignmentData()
            .withId(Id.str(task + ":" + resource))
            .withTask(Id.str(task))
            .withResource(Id.str(resource))
            .withValue(value);
    }

    public static void main(String[] args) throws Exception {
        ProjectData data = new ProjectData()
            .withTasks(List.of(
                task("a", at(10, 8), 2.0),
                task("b", at(10, 8), 1.0),
                task("c", at(11, 8), 1.0)))
            .withResources(List.of(
                new ResourceData().withId(Id.str("dev")),
                new ResourceData().withId(Id.str("qa"))))
            .withAssignments(List.of(
                assign("a", "dev", 1.0),
                assign("b", "dev", 1.0),
                assign("c", "dev", 0.5)));

        Project project = new Project();
        project.solve(data, new SolveOptions());

        // What if `b` moves from `dev` to `qa`?
        SchedulingChanges changes = new SchedulingChanges();
        changes.assignments.update.add(
            new AssignmentUpdate(Id.str("b:dev")).withResource(Patch.of(Id.str("qa"))));

        PreviewOptions options = new PreviewOptions()
            .withProfile(new ProfileQuery(at(10, 0), at(12, 0)));
        ScheduleResult preview = project.preview(changes, options);

        for (ResourceLoad row : preview.profile.resources) {
            List<Double> loads = row.buckets.stream().map(b -> b.load).toList();
            System.out.println("previewed " + row.resource + ": " + loads);
        }

        // The baseline still has both tasks on `dev`.
        LoadProfile base = project.loadProfile(
            new LoadProfileOptions(new ProfileQuery(at(10, 0), at(12, 0))));
        List<Double> loads = base.resources.get(0).buckets.stream().map(b -> b.load).toList();
        System.out.println("baseline dev: " + loads);
    }
}

In the preview, dev drops to 1.0 on Monday and keeps 1.5 on Tuesday, and qa gets 1.0 on Monday. The baseline profile still shows 2.0 and 1.5 for dev. Without PreviewOptions.profile, preview.profile is null.

PreviewOptions.profile takes a bare ProfileQuery, not LoadProfileOptions, so it has no baselineId of its own. To guard a preview against a stale baseline, set PreviewOptions.baselineId. An invalid query fails the whole preview with an InputException.

To profile a multi-step edit or a leveling run, take a Project#copy(), edit or level the copy, and call loadProfile on it. The copy is cheap and the original stays as it was. See Previewing changes for both approaches.