Suggestion Function（建议函数 (Suggestion Function)）

A key challenge in scheduling and resource allocation workflows is knowing where and when specific events can occur or where they can be moved. Most schedules have limitations and not all schedule options are equally appropriate; by building these limitations and criteria into logic, tools can help users quickly evaluate choices. The Suggestion Functions feature helps guide user behavior by visually indicating the suitability of potential schedule object puck placement based on logic defined by your organization.

Each Suggestion Function is backed by a TypeScript function. The output of the rule logic can be used to highlight areas where an assignment can be made or, by contrast, areas where assignments cannot be made. Application builders have the option to enforce these suggestions through a setting in the Workshop widget configuration. When turned on, this feature will force placement of the puck to the closest highlighted region.

:::callout{theme="neutral"} The results of the Suggestion Functions in the Scheduling Gantt Chart are static. The function is run during initial application load and any actions made afterwards are not accounted for. This has implications for whether this feature is suitable for your workflow. :::

Below are two examples of how Suggestion Functions can be used effectively.

In the following image, the Suggestion Function has been written to suggest the preferred location of the individual who is being assigned (in this case, “Susan”). The green area indicates that Garden City is Susan’s preferred location, while Sandbar, indicated in grey, is not preferred.

In the below example, an application is used to assign flights to pilots. The vertical slice of time (in green), indicates to the scheduler that they should not adjust the start/end time of the flight, but only the individual who is the pilot.

Functions interface

The types below represent the necessary information to write a Search Function when triggered from either a row or a puck, which includes details about the search group.

/*
   Suggestion functions take in a list of puck primary keys as well as
   the Gantt's start/end time and returns a mapping of puck primary keys
   to a mapping of row primary keys to an array of time slots. 
*/


type ISuggestion = (
    scheduleObjectPrimaryKeys: string[],
    domainStart: Timestamp,
    domainEnd: Timestamp,
) => FunctionsMap<string, FunctionsMap<string, Array<ISuggestionSlot>>>

/* Suggestion types */

export interface IDomain {
    start: Long;
    end: Long;
}

/* rating is used to determine the highlight color in widget UI. Based on
   scale of -1 to 1. Closer to 1 and the highlight will be darker shade of
   green. Closer to -1 and the highlight will be red. 
*/

export interface ISuggestionSlot {
    domain: IDomain;
    rating: Float;
}

export type IValidSlots = Array<ISuggestionSlot>;
export type ISlotMappings = FunctionsMap<string, IValidSlots>;
export type ISuggestionResult = FunctionsMap<string, ISlotMappings>;


/*
  In workflows where schedule objects have a set start/end time and may only change
  assigned resources (vertical slice highlighted), the ALL_ROWS_ID can be used 
  as a shortcut. 
*/

export const ALL_ROWS_ID = "__ALL_ROWS";

---

中文翻译

---

建议函数 (Suggestion Function)

在调度和资源分配工作流中，一个关键挑战在于了解特定事件可以在何时何地发生，或者可以被移动到何处。大多数调度方案都存在限制，且并非所有调度选项都同样合适；通过将这些限制和标准融入逻辑中，工具可以帮助用户快速评估选择。建议函数 (Suggestion Function) 功能通过根据您组织定义的逻辑，直观地显示潜在调度对象 (schedule object) 图钉 (puck) 放置位置的适宜性，从而引导用户行为。

每个建议函数都由一个 TypeScript 函数支持。规则逻辑的输出可用于高亮显示可以分配任务的区域，或者相反，高亮显示无法分配任务的区域。应用程序构建者可以选择通过 Workshop 小组件配置中的设置来强制执行这些建议。启用此功能后，它将强制将图钉放置到最近的高亮区域。

:::callout{theme="neutral"} 调度甘特图 (Scheduling Gantt Chart) 中建议函数的结果是静态的。该函数在初始应用程序加载时运行，之后执行的任何操作均不计入在内。这会影响此功能是否适合您的工作流。 :::

以下两个示例展示了如何有效使用建议函数。

在下图中，建议函数被编写为建议被分配人员（本例中为“Susan”）的偏好位置。绿色区域表示 Garden City 是 Susan 的偏好位置，而灰色表示的 Sandbar 则不是偏好位置。

在下面的示例中，一个应用程序用于将航班分配给飞行员。垂直的时间切片（绿色）向调度员表明，他们不应调整航班的开始/结束时间，而只能调整飞行员这个人选。

函数接口 (Functions interface)

以下类型表示编写一个从行或图钉触发的搜索函数 (Search Function) 所需的信息，其中包含有关搜索组的详细信息。

/*
   建议函数接收一个图钉主键列表以及
   甘特图的开始/结束时间，并返回一个映射，
   该映射将图钉主键映射到行主键，
   再映射到时间段数组。
*/


type ISuggestion = (
    scheduleObjectPrimaryKeys: string[],
    domainStart: Timestamp,
    domainEnd: Timestamp,
) => FunctionsMap<string, FunctionsMap<string, Array<ISuggestionSlot>>>

/* 建议类型 */

export interface IDomain {
    start: Long;
    end: Long;
}

/* rating 用于确定小组件 UI 中的高亮颜色。基于
   -1 到 1 的标度。越接近 1，高亮颜色将越深的绿色。
   越接近 -1，高亮颜色将为红色。 
*/

export interface ISuggestionSlot {
    domain: IDomain;
    rating: Float;
}

export type IValidSlots = Array<ISuggestionSlot>;
export type ISlotMappings = FunctionsMap<string, IValidSlots>;
export type ISuggestionResult = FunctionsMap<string, ISlotMappings>;


/*
  在调度对象具有固定开始/结束时间且仅可能更改
  分配资源的工作流中（垂直切片高亮），可以使用 ALL_ROWS_ID 
  作为快捷方式。 
*/

export const ALL_ROWS_ID = "__ALL_ROWS";