EventModel
This class represent a single event in your schedule, usually added to a EventStore.
It is a subclass of the TimeSpan, which is in turn subclass of Model. Please refer to documentation of that class to become familiar with the base interface of the event.
Async date calculations
A record created from an EventModel is normally part of an EventStore, which in turn is part of a project. When
dates or the duration of an event is changed, the project performs async calculations to normalize the other fields.
For example if duration is change, it will calculate endDate.
As a result of this being an async operation, the values of other fields are not guaranteed to be up to date immediately after a change. To ensure data is up to date, await the calculations to finish.
For example, endDate is not up to date after this operation:
eventRecord.duration = 5;
// endDate not yet calculated
But if calculations are awaited it is up to date:
eventRecord.duration = 5;
await eventRecord.project.commitAsync();
// endDate is calculated
As an alternative, you can also use setAsync() to trigger calculations directly after the change:
await eventRecord.setAsync({ duration : 5});
// endDate is calculated
Subclassing the Event model class
The Event model has a few predefined fields as seen below. If you want to add new fields or change the options for the existing fields, you can do that by subclassing this class (see example below).
class MyEvent extends EventModel {
static get fields() {
return [
// Add new field
{ name: 'myField', type : 'number', defaultValue : 0 }
];
},
myCheckMethod() {
return this.myField > 0
},
...
});
If you in your data want to use other names for the startDate, endDate, resourceId and name fields you can configure them as seen below:
class MyEvent extends EventModel {
static get fields() {
return [
{ name: 'startDate', dataSource 'taskStart' },
{ name: 'endDate', dataSource 'taskEnd', format: 'YYYY-MM-DD' },
{ name: 'resourceId', dataSource 'userId' },
{ name: 'name', dataSource 'taskTitle' },
];
},
...
});
Please refer to Model for additional details.
Configs
1
Configs
1Properties
106
Properties
106Assignments & Resources
Returns all assignments for the event. Event must be part of the store for this method to work.
Returns the first assigned resource, or assigns a resource
Returns all resources assigned to an event.
Class hierarchy
Dependencies
Returns all predecessor dependencies of this event
Returns all successor dependencies of this event
Editing
Returns true if event can be drag and dropped
Returns false if the event is not persistable. By default it always is, override this getter if you need
custom logic.
Returns true if event can be resized, but can additionally return 'start' or 'end' indicating how this event can be resized.
Milestones and parent events (that are not manuallyScheduled) cannot be resized.
Other
This event´s effective calendar. Returns the project calendar if the event has no own calendar provided.
Returns the event store this event is part of.
The event first segment or null if the event is not segmented.
Property which encapsulates the effort's magnitude and units.
UI fields representing this property are disabled for summary events. See isEditable for details.
The event last segment or null if the event is not segmented.
Returns event end date adjusted by postamble (end date + duration).
Returns event start date adjusted by preamble (start date - duration).
Scheduling
Returns the event duration in milliseconds.
Flag which indicates that this event is an interday event. This means that it spans an entire day or multiple days.
This is essentially used by the Calendar package to determine if an event should go into the all day zone of a DayView.
JSON
Models & Stores
Parent & children
Progress
Recurrence
Functions
86
Functions
86Assignments & Resources
Returns either the resource associated with this event (when called w/o resourceId) or resource
with specified id.
| Parameter | Type | Description |
|---|---|---|
resourceId | String | To retrieve a specific resource |
Returns true if this event is assigned to a certain resource.
| Parameter | Type | Description |
|---|---|---|
resource | ResourceModel | String | Number | The resource to query for |
Reassigns an event from an old resource to a new resource
| Parameter | Type | Description |
|---|---|---|
oldResourceId | ResourceModel | String | Number | A resource to unassign from or its id |
newResourceId | ResourceModel | String | Number | A resource to assign to or its id |
Editing
Set value for the specified field(s), triggering engine calculations immediately. See Model#set() for arguments.
eventRecord.set('duration', 4);
// eventRecord.endDate is not yet calculated
await eventRecord.setAsync('duration', 4);
// eventRecord.endDate is calculated
| Parameter | Type | Description |
|---|---|---|
field | String | Object | The field to set value for, or an object with multiple values to set in one call |
value | * | Value to set |
silent | Boolean | Set to |
Other
This method assigns a resource to this event.
Will cause the schedule to be updated - returns a Promise
| Parameter | Type | Description |
|---|---|---|
resource | ResourceModel | String | Number | ResourceModel[] | String[] | Number[] | A new resource for this event, either as a full Resource record or an id (or an array of such). |
units | Number | The |
Indicates whether the event can perform the provided duration conversion. The event might not be able to convert units on early stages of data loading when the project has not loaded its conversion rates yet. So the method by default checks that the project has loaded the rates needed for conversion.
| Parameter | Type | Description |
|---|---|---|
duration | Number | Duration value |
fromUnit | DurationUnit | Duration value time unit |
toUnit | DurationUnit | Target time unit to convert the value to |
true is the conversion is possible and false otherwise.
Converts a duration value from one time unit to another. The method is a generator since it embeds into the Engine scheduling mechanics.
| Parameter | Type | Description |
|---|---|---|
duration | Number | Duration value |
fromUnit | DurationUnit | Duration value time unit |
toUnit | DurationUnit | Target time unit to convert the value to |
The converted duration value.
If given resource is assigned to this event, returns a AssignmentModel record.
Otherwise, returns null
| Parameter | Type | Description |
|---|---|---|
resource | ResourceModel | The instance of ResourceModel |
Returns the event ignoreResourceCalendar field value.
The event ignoreResourceCalendar field value.
Defines if the given event field should be manually editable in UI. You can override this method to provide your own logic.
By default, the method defines:
- earlyStartDate, earlyEndDate as not editable;
- endDate, duration and fullDuration fields as not editable for summary events except the manually scheduled ones;
- percentDone as not editable for summary events.
| Parameter | Type | Description |
|---|---|---|
fieldName | String | Name of the field |
Returns true if the field is editable, false if it is not and undefined if the event has
no such field.
Merges the event segments. The method merges two provided event segments (and all the segment between them if any).
| Parameter | Type | Description |
|---|---|---|
segment1 | EventSegmentModel | First segment to merge. |
segment2 | EventSegmentModel | Second segment to merge. |
Sets the calendar of the event. Will cause the schedule to be updated - returns a Promise
| Parameter | Type | Description |
|---|---|---|
calendar | CalendarModel | The new calendar. Provide |
Sets the constraint type and (optionally) constraining date to the event.
| Parameter | Type | Description |
|---|---|---|
constraintType | finishnoearlierthan | finishnolaterthan | mustfinishon | muststarton | startnoearlierthan | startnolaterthan | null | Constraint type, please refer to the constraintType for the valid values. |
constraintDate | Date | Constraint date. |
Updates the duration (and optionally unit) of the event. Will cause the schedule to be updated - returns a Promise
| Parameter | Type | Description |
|---|---|---|
duration | Number | New duration value |
unit | DurationUnit | New duration unit |
Updates the effort (and optionally unit) of the event.
Will cause the schedule to be updated - returns a Promise
| Parameter | Type | Description |
|---|---|---|
effort | Number | New effort value |
unit | DurationUnit | New effort unit |
Sets the end date of the event. Will cause the schedule to be updated - returns a Promise
Note, that the actually set end date may be adjusted, according to the calendar, by skipping the non-working time backward.
| Parameter | Type | Description |
|---|---|---|
date | Date | The new end date. |
keepDuration | Boolean | Whether to keep the duration (and update the start date), while changing the end date, or vice-versa. |
Sets the event ignoreResourceCalendar field value and triggers rescheduling.
| Parameter | Type | Description |
|---|---|---|
ignore | Boolean | Provide |
Either activates or deactivates the task depending on the passed value.
Will cause the schedule to be updated - returns a Promise
| Parameter | Type | Description |
|---|---|---|
inactive | Boolean |
|
Sets segments field value.
| Parameter | Type | Description |
|---|---|---|
segments | EventSegmentModel[] | EventSegmentModelConfig[] | Array of segments or null to make the event not segmented. |
Sets the start date of the event. Will cause the schedule to be updated - returns a Promise
Note, that the actually set start date may be adjusted, according to the calendar, by skipping the non-working time forward.
| Parameter | Type | Description |
|---|---|---|
date | Date | The new start date. |
keepDuration | Boolean | Whether to keep the duration (and update the end date), while changing the start date, or vice-versa. |
Splits the event into segments.
| Parameter | Type | Description |
|---|---|---|
from | Date | The date to split this event at. |
lag | Number | Split duration. |
DurationUnit | String | Split duration unit. |
This method unassigns a resource from this event.
Will cause the schedule to be updated - returns a Promise
| Parameter | Type | Description |
|---|---|---|
resource | ResourceModel | String | Number | The resource to unassign from, or its id. |
Scheduling
Shift the dates for the date range by the passed amount and unit
| Parameter | Type | Description |
|---|---|---|
amount | Number | The amount to shift |
unit | DurationUnitShort | The unit to shift by, see DateHelper for more information on valid formats. |
A promise which is resolved when shift calculations are done
Configuration
Events
Misc
Parent & children
Recurrence
Typedefs
2
Typedefs
2Predefined named colors:
Fields
25
Fields
25Common
Note about the event
Set this to true if this task should be shown in the Timeline widget
Scheduling
Shows the amount of effort that has already been done by resources assigned to the event.
For a summary event the value is calculated as sum of children actual effort values. Otherwise if the event has assignments the value is calculated as sum of assignments actual efforts. And if not the value is calculated as effort multiplied by percentDone value.
The calendar, assigned to the entity. Allows you to set the time when entity can perform the work.
All entities are by default assigned to the project calendar, provided as the calendar option.
Field defining the constraint boundary date, if applicable.
Field storing the event constraint alias or NULL if not constraint set. Valid values are:
- "finishnoearlierthan"
- "finishnolaterthan"
- "mustfinishon"
- "muststarton"
- "startnoearlierthan"
- "startnolaterthan"
The total projected cost for the event.
Amount of time to delay a nested event from its parent. Expressed in durationUnit units (defaults to days).
Example dataset:
{
"name" : "Parent",
"startDate" : "2023-08-24",
"children" : [
{ name : "One", "delayFromParent" : 0 } // starts 2023-08-24
{ name : "Two", "delayFromParent" : 2 } // starts 2023-08-26
]
}
Intended for loading & serializing data when using nested events, at runtime it is enforced using constraints. See NestedEvents for more information
The numeric part of the timespan's duration (the number of units).
UI fields representing this data field are disabled for summary events except the manually scheduled events. See isEditable for details.
A calculated field storing the early end date of the event. The early end date is the earliest possible date the event can finish. This value is calculated based on the earliest dates of the event predecessors and the event own constraints. If the event has no predecessors nor other constraints, its early end date matches the project start date plus the event duration.
UI fields representing this data field are naturally disabled since the field is readonly. See isEditable for details.
A calculated field storing the early start date of the event. The early start date is the earliest possible date the event can start. This value is calculated based on the earliest dates of the event predecessors and the event own constraints. If the event has no predecessors nor other constraints, its early start date matches the project start date.
UI fields representing this data field are naturally disabled since the field is readonly. See isEditable for details.
The numeric part of the event effort (the number of units).
This boolean flag defines what part the data should be updated in the FixedDuration scheduling
mode.
If it is true, then effort is kept intact when new duration is provided and
assignment units is updated.
If it is false, then assignment units is kept
intact when new duration is provided and effort is updated.
The unit part of the event effort, defaults to "h" (hours). Valid values are:
- "millisecond" - Milliseconds
- "second" - Seconds
- "minute" - Minutes
- "hour" - Hours
- "day" - Days
- "week" - Weeks
- "month" - Months
- "quarter" - Quarters
- "year"- Years
This field is readonly after creation, to change it use the setEffort call.
The end date of a time span (or Event / Task).
Uses DateHelper.defaultFormat to convert a supplied string to a Date. To specify another format, either change that setting or subclass TimeSpan and change the dateFormat for this field.
UI fields representing this data field are disabled for summary events except the manually scheduled events. See isEditable for details.
Note that the field always returns a Date.
When set to true the calendars of the assigned resources
are not taken into account when scheduling the event.
By default the field value is false resulting in that the event performs only when
its own calendar and some of the assigned
resource calendars allow that.
When set to true the event becomes inactive and stops taking part in the project scheduling (doesn't
affect linked events and affect its assigned resources allocation).
When set to true, the startDate of the event will not be changed by any of its incoming dependencies
or constraints.
The current status of a task, expressed as the percentage completed (integer from 0 to 100)
UI fields representing this data field are disabled for summary events. See isEditable for details.
Buffer time after event end. Specified in a human-friendly form as accepted by parseDuration:
// Create event model with a 1 hour buffer time after the event end
new EventModel({ startDate : '2020-01-01', endDate : '2020-01-02', postamble : '1 hour' })
Used by the EventBuffer feature.
Buffer time before event start. Specified in a human-friendly form as accepted by parseDuration:
// Create event model with a 30 minutes buffer time before the event start
new EventModel({ startDate : '2020-01-01', endDate : '2020-01-02', preamble : '30 minutes' })
Used by the EventBuffer feature.
This field defines the event scheduling mode. Based on this field some fields of the event will be "fixed" (should be provided by the user) and some - computed.
Possible values are:
-
Normalis the default (and backward compatible) mode. It means the event will be scheduled based on information about its start/end dates, event own calendar (project calendar if there's no one) and calendars of the assigned resources. -
FixedDurationmode means, that event has fixed start and end dates, but its effort will be computed dynamically, based on the assigned resources information. When duration of such event increases, its effort is increased too. The mode tends to preserve user provided duration so changing effort results adjusting assignment units and vise-versa assignment changes adjusts effort.
Segments of the event that appear when the event gets splitToSegments. Can be provided as an array of segment config objects or EventSegmentModel instances.
The start date of a time span (or Event / Task).
Uses DateHelper.defaultFormat to convert a supplied string to a Date. To specify another format, either change that setting or subclass TimeSpan and change the dateFormat for this field.
UI fields representing this data field are disabled for summary events except the manually scheduled events. See isEditable for details.
Note that the field always returns a Date.
This field is automatically set to true when the event is "unscheduled" - user has provided an empty
string in one of the UI editors for start date, end date or duration. Such event is not rendered,
and does not affect the schedule of its successors.
To schedule the event back, enter one of the missing values, so that there's enough information to calculate start date, end date and duration.
Note, that setting this field manually does nothing. This field should be persisted, but not updated manually.