Segment scheduling API

Level: advanced

The Creatio.Segmentation namespace includes the back-end API that lets you schedule segment population and start segment actualization from source code. Learn more about scheduled population: Manage segments using Segmentation Engine API.

To access the services in configuration source code, use the ClassFactory class. For example, ClassFactory.Get<ISegmentScheduleService>().

To schedule segment population via source code:

1. Set the "Population mode" (SysRefreshMode code) column of the segment to "Scheduled" ("1f1c3689-76bb-42cb-8bf5-4c5f7230ea24" ID) and save the segment. The ID is available in the SegmentConstants.ScheduledRefreshModeId property of the Terrasoft.Core.Segmentation namespace.
2. Set the schedule using the UpdateSchedule() or UpdateRecurringSchedule() method.
3. Activate the segment on the segment page or using the "Activate segment" business process.

Creatio creates the segment Quartz job only when the segment has the "Scheduled" population mode, the "Active" status, and a non-empty "Refresh cron expression" (RefreshCronExpression code) column value. You can complete these steps in any order.

ISegmentScheduleService interface

ISegmentScheduleService updates the population schedule of a segment. Available in version 10.1 and later. The service validates the schedule and saves it to the "Refresh cron expression" (RefreshCronExpression code), "Refresh time zone id" (RefreshTimeZoneId code), "Schedule start date" (ScheduleStartDate code), and "Schedule end date" (ScheduleEndDate code) columns of the "Segment" (SysDataSegment code) object. When the segment is saved, Creatio re-synchronizes the segment Quartz job. The schedule runs only while the segment is in the "Scheduled" population mode and has the "Active" status. You can update the schedule of an active segment. Creatio applies the new schedule immediately.

The methods do not throw exceptions for expected validation errors, for example, an invalid cron expression, a schedule that runs more often than once per minute, an invalid time zone, or an unknown segment. Instead, they return a ScheduleUpdateResult object. Other errors that occur when saving the segment, for example, a duplicate segment name or missing access permissions, throw exceptions. Learn more: ScheduleUpdateResult class.

Methods

ScheduleUpdateResult UpdateSchedule(
    Guid segmentId,
    string cronExpression,
    string timeZoneId,
    DateTime? startDate,
    DateTime? endDate)

Validates and applies a segment schedule defined by a Quartz cron expression.

Parameters

Parameter	Type	Description
segmentId	Guid	The ID of the "Segment" (SysDataSegment code) object record.
cronExpression	string	The Quartz cron expression that includes the seconds field, for example, "0 30 9 * * ?" (every day at 9:30). An empty value clears the schedule.
timeZoneId	string	The ID of the time zone in which Creatio interprets the cron expression. An empty value means UTC. Use a Windows time zone ID, for example, "Central European Standard Time," if Creatio runs on .NET Framework, and an IANA time zone ID, for example, "Europe/Berlin," if Creatio runs on .NET.
startDate	DateTime?	The date on which the schedule starts, in the time zone set by timeZoneId. "null" means no start limit.
endDate	DateTime?	The date on which the schedule ends, in the time zone set by timeZoneId. "null" means no end limit.

---

ScheduleUpdateResult UpdateRecurringSchedule(
    Guid segmentId,
    SegmentSchedulePeriod period,
    int hour,
    int minute,
    DayOfWeek dayOfWeek,
    string timeZoneId,
    DateTime? startDate,
    DateTime? endDate)

Validates and applies a daily or weekly segment schedule. Creatio builds the matching cron expression and calls the UpdateSchedule() method.

Parameters

Parameter	Type	Description
segmentId	Guid	The ID of the "Segment" (SysDataSegment code) object record.
period	SegmentSchedulePeriod	Determines how often to populate the segment. References the SegmentSchedulePeriod enumeration.
hour	int	The hour of the population time in the time zone set by timeZoneId. Available values: 0–23.
minute	int	The minute of the population time. Available values: 0–59.
dayOfWeek	DayOfWeek	The day of the week to populate the segment. Ignored if period is set to "Daily."
timeZoneId	string	The ID of the time zone in which Creatio runs the schedule. An empty value means UTC. Use a Windows time zone ID, for example, "Central European Standard Time," if Creatio runs on .NET Framework, and an IANA time zone ID, for example, "Europe/Berlin," if Creatio runs on .NET.
startDate	DateTime?	The date on which the schedule starts, in the time zone set by timeZoneId. "null" means no start limit.
endDate	DateTime?	The date on which the schedule ends, in the time zone set by timeZoneId. "null" means no end limit.

ScheduleUpdateResult class

The ScheduleUpdateResult class stores the result of a schedule update that the UpdateSchedule() and UpdateRecurringSchedule() methods return.

Properties

Property	Type	Description
IsSuccess	bool	Indicates whether Creatio applied the schedule.
Error	string	The validation error message. Filled only if IsSuccess is set to "false." Available values: "The refresh cron expression is not a valid Quartz cron expression." "The refresh cron expression fires more often than the allowed minimum interval." "The refresh time zone id is not a valid system time zone." "Segment '<segmentId>' was not found." Also returned if the current user has no permission to read the segment. "The schedule time must be a valid hour (0-23) and minute (0-59)." Returned only by the UpdateRecurringSchedule() method.

SegmentSchedulePeriod enumeration

The SegmentSchedulePeriod enumeration determines how often Creatio populates the segment when you set the schedule using the UpdateRecurringSchedule() method.

Available values

Value	Numeric value	Description
Daily	0	Populate the segment every day.
Weekly	1	Populate the segment once a week on the day set by the dayOfWeek parameter.

Usage example

The following example schedules a segment to be populated every Monday at 6:00 in the "Central European Standard Time" time zone. The example uses a Windows time zone ID, so it applies to Creatio on .NET Framework.

Schedule weekly segment population

using System;
using Creatio.Segmentation;
using Terrasoft.Core.Factories;

/* The ID of the "Segment" object record. */
Guid segmentId = new Guid("11111111-1111-1111-1111-111111111111");
var scheduleService = ClassFactory.Get<ISegmentScheduleService>();
ScheduleUpdateResult result = scheduleService.UpdateRecurringSchedule(
    segmentId,
    SegmentSchedulePeriod.Weekly,
    6,
    0,
    DayOfWeek.Monday,
    "Central European Standard Time",
    null,
    null);
if (!result.IsSuccess) {
    /* Handle the validation error. */
    var error = result.Error;
}

ISegmentActualizationJobManager interface

ISegmentActualizationJobManager starts and cancels segment actualization jobs. It also hands the population of a segment over to its schedule when the segment is activated or resumed. Creatio does not run actualization jobs of the same segment concurrently. If a job for the segment is already pending, Creatio drops the new request, and the pending job keeps its parameters.

void ScheduleActualization(
    Guid segmentId,
    bool excludeCurrentMembersBeforeActualization = false)

Registers and immediately starts a segment actualization job. The job always populates the segment, regardless of the population mode.

Parameters

Parameter	Type	Description
segmentId	Guid	The ID of the "Segment" (SysDataSegment code) object record.
excludeCurrentMembersBeforeActualization	bool	Whether to exclude all current segment members before actualization. If set to "true," Creatio marks all members as removed, then re-evaluates the entry rules. Members that still match the entry rules become active again. By default, "false."

---

void ScheduleActualization(
    Guid segmentId,
    bool excludeCurrentMembersBeforeActualization,
    bool skipPopulationWhenScheduled)

Registers and immediately starts a segment actualization job, and lets you skip population of a scheduled segment. Available in version 10.1 and later. The two-parameter overload is unchanged, so configurations compiled earlier keep the previous behavior.

Parameters

Parameter	Type	Description
segmentId	Guid	The ID of the "Segment" (SysDataSegment code) object record.
excludeCurrentMembersBeforeActualization	bool	Whether to exclude all current segment members before actualization. If set to "true," Creatio marks all members as removed, then re-evaluates the entry rules. Members that still match the entry rules become active again.
skipPopulationWhenScheduled	bool	Whether to skip population of a segment that has the "Scheduled" population mode and a non-empty "Refresh cron expression" (RefreshCronExpression code) column value. If set to "true," Creatio marks such a segment as ready to use without populating it, and the segment is populated at the next scheduled time. A segment without a schedule is populated immediately. Creatio sets the parameter to "true" when activating or resuming a segment.

---

void UnscheduleActualization(Guid segmentId)

Removes the actualization job of the segment. Throws InvalidOperationException if the segment has no job. The method does not remove the segment schedule. To remove the schedule, call the UpdateSchedule() method with an empty cronExpression value.

Parameters

Parameter	Type	Description
segmentId	Guid	The ID of the "Segment" (SysDataSegment code) object record.

---

See also

Manage segments using Segmentation Engine API

Segmentation Engine API endpoints

Customize quartz task scheduler