@oneuptime/common 12.0.8 → 12.0.9

package/Types/Permission.ts

@@ -1062,6 +1062,29 @@ enum Permission {
   DeleteProjectOnCallDutyPolicy = "DeleteProjectOnCallDutyPolicy",
   ReadProjectOnCallDutyPolicy = "ReadProjectOnCallDutyPolicy",
 
+  /*
+   * A project user's own on-call notification configuration - the rules that
+   * decide which of their verified methods a page reaches, and after how long.
+   *
+   * Every other permission in this family gates a resource the project owns.
+   * These two gate rows that belong to an individual member, which is why they
+   * exist separately rather than being folded into
+   * Read/EditProjectOnCallDutyPolicy: a policy says "page the on-call engineer",
+   * but whether that page actually arrives is decided by rows only that engineer
+   * could see or write. An unreachable teammate was therefore diagnosable by
+   * nobody but themselves, and the person carrying the incident had no way to
+   * find out before the page went unanswered.
+   *
+   * Read grants VISIBILITY of another member's rules and of the methods those
+   * rules point at - never the delivery token behind a method (see the column
+   * access control on UserWebhook and UserPush). Edit grants repair of the
+   * rules themselves. Neither grants the ability to add a notification method to
+   * somebody else's account; that asymmetry is deliberate and is explained on
+   * UserNotificationRule.
+   */
+  ReadProjectUserNotificationRule = "ReadProjectUserNotificationRule",
+  EditProjectUserNotificationRule = "EditProjectUserNotificationRule",
+
   // Resource Permissions (Team Permission)
   CreateProjectOnCallDutyPolicySchedule = "CreateProjectOnCallDutyPolicySchedule",
   EditProjectOnCallDutyPolicySchedule = "EditProjectOnCallDutyPolicySchedule",
@@ -1255,6 +1278,21 @@ enum Permission {
   EditNetworkSiteLink = "EditNetworkSiteLink",
   ReadNetworkSiteLink = "ReadNetworkSiteLink",
 
+  CreateNetworkDeviceLink = "CreateNetworkDeviceLink",
+  DeleteNetworkDeviceLink = "DeleteNetworkDeviceLink",
+  EditNetworkDeviceLink = "EditNetworkDeviceLink",
+  ReadNetworkDeviceLink = "ReadNetworkDeviceLink",
+
+  CreateNetworkDeviceLinkRule = "CreateNetworkDeviceLinkRule",
+  DeleteNetworkDeviceLinkRule = "DeleteNetworkDeviceLinkRule",
+  EditNetworkDeviceLinkRule = "EditNetworkDeviceLinkRule",
+  ReadNetworkDeviceLinkRule = "ReadNetworkDeviceLinkRule",
+
+  CreateNetworkTopologySuppression = "CreateNetworkTopologySuppression",
+  DeleteNetworkTopologySuppression = "DeleteNetworkTopologySuppression",
+  EditNetworkTopologySuppression = "EditNetworkTopologySuppression",
+  ReadNetworkTopologySuppression = "ReadNetworkTopologySuppression",
+
   CreateNetworkSiteAssignmentRule = "CreateNetworkSiteAssignmentRule",
   DeleteNetworkSiteAssignmentRule = "DeleteNetworkSiteAssignmentRule",
   EditNetworkSiteAssignmentRule = "EditNetworkSiteAssignmentRule",
@@ -5996,6 +6034,41 @@ export class PermissionHelper {
         group: PermissionGroup.OnCallDutyPolicy,
       },
 
+      /*
+       * isRolePermission is false on both of these deliberately, and it is not a
+       * stylistic choice. A true value would file them under
+       * getRolePermissionProps(), which is the list every default project role
+       * is built from - so the ability to read and rewrite a colleague's paging
+       * configuration would arrive silently with an existing role rather than
+       * being handed out on purpose. They are granular permissions an
+       * administrator opts into, held by nobody until somebody grants them.
+       *
+       * isAccessControlPermission is false because the rows these gate carry no
+       * label column; there is nothing for a label-scoped grant to narrow, and
+       * claiming otherwise would offer an administrator a scoping control that
+       * silently does nothing.
+       */
+      {
+        permission: Permission.ReadProjectUserNotificationRule,
+        title: "Read User Notification Rules",
+        description:
+          "This permission can read the on-call notification rules of any user in this project, and see which of their notification methods those rules point at. Delivery addresses are shown in a masked form and delivery credentials are never readable.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: false,
+        isRolePermission: false,
+        group: PermissionGroup.OnCallDutyPolicy,
+      },
+      {
+        permission: Permission.EditProjectUserNotificationRule,
+        title: "Edit User Notification Rules",
+        description:
+          "This permission can create, edit and delete the on-call notification rules of any user in this project, in order to repair a member who would otherwise never be paged. It does not permit adding or changing a user's notification methods.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: false,
+        isRolePermission: false,
+        group: PermissionGroup.OnCallDutyPolicy,
+      },
+
       {
         permission: Permission.CreateProjectOnCallDutyPolicySchedule,
         title: "Create On-Call Duty Policy Schedule",
@@ -7919,6 +7992,126 @@ export class PermissionHelper {
         isRolePermission: false,
         group: PermissionGroup.Monitor,
       },
+      {
+        permission: Permission.CreateNetworkDeviceLink,
+        title: "Create Network Device Link",
+        description:
+          "This permission can create Network Device Link in this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: false,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.DeleteNetworkDeviceLink,
+        title: "Delete Network Device Link",
+        description:
+          "This permission can delete Network Device Link of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.EditNetworkDeviceLink,
+        title: "Edit Network Device Link",
+        description:
+          "This permission can edit Network Device Link of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.ReadNetworkDeviceLink,
+        title: "Read Network Device Link",
+        description:
+          "This permission can read Network Device Link of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.CreateNetworkDeviceLinkRule,
+        title: "Create Network Device Link Rule",
+        description:
+          "This permission can create Network Device Link Rule in this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: false,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.DeleteNetworkDeviceLinkRule,
+        title: "Delete Network Device Link Rule",
+        description:
+          "This permission can delete Network Device Link Rule of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.EditNetworkDeviceLinkRule,
+        title: "Edit Network Device Link Rule",
+        description:
+          "This permission can edit Network Device Link Rule of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.ReadNetworkDeviceLinkRule,
+        title: "Read Network Device Link Rule",
+        description:
+          "This permission can read Network Device Link Rule of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.CreateNetworkTopologySuppression,
+        title: "Create Network Topology Suppression",
+        description:
+          "This permission can hide nodes from the Network Topology map in this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: false,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.DeleteNetworkTopologySuppression,
+        title: "Delete Network Topology Suppression",
+        description:
+          "This permission can restore hidden nodes to the Network Topology map of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.EditNetworkTopologySuppression,
+        title: "Edit Network Topology Suppression",
+        description:
+          "This permission can edit Network Topology Suppression of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
+      {
+        permission: Permission.ReadNetworkTopologySuppression,
+        title: "Read Network Topology Suppression",
+        description:
+          "This permission can read Network Topology Suppression of this project.",
+        isAssignableToTenant: true,
+        isAccessControlPermission: true,
+        isRolePermission: false,
+        group: PermissionGroup.Monitor,
+      },
       {
         permission: Permission.CreateNetworkSiteAssignmentRule,
         title: "Create Network Site Assignment Rule",

package/Types/Telemetry/EntityRelationshipType.ts

@@ -23,7 +23,7 @@ enum EntityRelationshipType {
    * this is NOT inferred from one resource's entity set — caller and
    * callee never share a resource. It is derived from parent/child span
    * pairs that cross a service boundary (see the
-   * TelemetryEntity:ComputeServiceDependencies worker cron).
+   * InventoryItem:ComputeServiceDependencies worker cron).
    */
   DependsOn = "depends-on",
 }

package/Types/Telemetry/EntitySource.ts

@@ -1,5 +1,5 @@
 /*
- * How a `TelemetryEntity` registry row came to exist. The registry started
+ * How a `InventoryItem` registry row came to exist. The registry started
  * as a forward-only catalog populated purely from OTLP resource attributes;
  * two later sources join it, and the three differ in exactly one way that
  * matters — who owns the row's lifecycle.

package/Types/Telemetry/EntityType.ts

@@ -7,7 +7,7 @@
  * entity data model (https://opentelemetry.io/docs/specs/otel/entities/).
  *
  * This is the broader *membership* vocabulary used by the `entityKeys`
- * column on signals and by the `TelemetryEntity` registry. It is distinct
+ * column on signals and by the `InventoryItem` registry. It is distinct
  * from `ServiceType`, which is the narrower discriminator for a signal's
  * single *primary* entity (`primaryEntityType`) and additionally covers
  * OneUptime-specific primary owners (Monitor, RealUserMonitor, Unknown,

package/Types/Telemetry/EntityTypeGroups.ts

@@ -57,7 +57,7 @@ export const INVENTORY_ENTITY_TYPES: ReadonlySet<EntityType> =
  * authority, not its type); this predicate is what the tests assert the TTL
  * map against, so a newly added type cannot quietly acquire a TTL.
  */
-export function isNonTelemetryEntityType(entityType: EntityType): boolean {
+export function isNonInventoryItemType(entityType: EntityType): boolean {
   return (
     MANUAL_ENTITY_TYPES.has(entityType) ||
     INVENTORY_ENTITY_TYPES.has(entityType)

package/Types/Workflow/Components/BaseModel.ts

@@ -21,11 +21,11 @@ export default class BaseModelComponent {
      * is called everywhere else in the product - when the column is "_id".
      * Both spellings work.
      *
-     * Query and record arguments now get a row editor backed by the model's
-     * real column list (ModelColumnEditor), so the names are offered rather
-     * than remembered. The hint stays because that editor keeps a JSON escape
-     * hatch for the queries rows cannot express, and because it is still the
-     * only thing explaining the two spellings.
+     * Query, Select and the write payload all get an editor backed by the
+     * model's real column list, so the names are offered rather than
+     * remembered. The hint stays because those editors keep a JSON escape
+     * hatch for values rows cannot express, and because it is still the only
+     * thing explaining the two spellings.
      */
     const columnHint: string = `Keys are column names on ${model.singularName}. The ID column is "_id" (the "id" spelling is accepted too).`;
 
@@ -38,8 +38,45 @@ export default class BaseModelComponent {
 
     const dataDescription: string = `${model.singularName} fields to write, as a JSON object. ${columnHint}`;
 
-    const documentationLink: Route = Route.fromString(
-      "/workflow/docs/DatabaseComponents.md",
+    /*
+     * Skip and Limit are the same on every component that has them, and they
+     * are not what decides what a step does - so they sit behind the "advanced"
+     * disclosure rather than competing with Query for attention.
+     *
+     * Limit is worded as a cap rather than as pagination. Read as pagination it
+     * is why "Items Deleted: 10" gets taken to mean ten records matched: the
+     * runtime defaults it to 10 and stops there (DeleteManyBaseModel,
+     * UpdateManyBaseModel), so a query matching five hundred records still only
+     * touches ten.
+     */
+    const skipDescription: string = `Skip the first X ${model.pluralName} the query matched. Defaults to 0.`;
+
+    const limitDescription: string = `The most ${model.pluralName} this step will touch. Defaults to 10, so a query that matches 500 records still only affects 10. Raise this if you mean all of them.`;
+
+    /*
+     * One file per operation, rather than one shared file for all eleven
+     * components. Shared, it had to describe Query, Select, the write payload,
+     * Items Updated and Items Deleted at once - so on Create One, which has
+     * none of those but the payload, most of it was about something else, and
+     * its one concrete instruction ("use the Select Fields picker") named an
+     * argument that component does not have.
+     *
+     * The route serves any filename in the docs directory, so these need no
+     * registration anywhere.
+     */
+    const findDocs: Route = Route.fromString("/workflow/docs/DatabaseFind.md");
+    const createDocs: Route = Route.fromString(
+      "/workflow/docs/DatabaseCreate.md",
+    );
+    const updateDocs: Route = Route.fromString(
+      "/workflow/docs/DatabaseUpdate.md",
+    );
+    const deleteDocs: Route = Route.fromString(
+      "/workflow/docs/DatabaseDelete.md",
+    );
+    // The triggers had no documentation link at all, so their card never rendered.
+    const triggerDocs: Route = Route.fromString(
+      "/workflow/docs/DatabaseTriggers.md",
     );
 
     if (model.enableWorkflowOn.read) {
@@ -51,7 +88,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.ArrowCircleDown,
         tableName: model.tableName!,
         componentType: ComponentType.Component,
-        documentationLink: documentationLink,
+        documentationLink: findDocs,
         arguments: [
           {
             type: ComponentInputType.Query,
@@ -111,7 +148,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.ArrowCircleDown,
         tableName: model.tableName!,
         componentType: ComponentType.Component,
-        documentationLink: documentationLink,
+        documentationLink: findDocs,
         arguments: [
           {
             type: ComponentInputType.Query,
@@ -132,16 +169,18 @@ export default class BaseModelComponent {
           {
             type: ComponentInputType.Number,
             name: "Skip",
-            description: `Skip the first X number of items. This can be helpful to implement pagination. Defaults to 0.`,
+            description: skipDescription,
             required: false,
             id: "skip",
+            isAdvanced: true,
           },
           {
             type: ComponentInputType.Number,
             name: "Limit",
-            description: `Limit to first X items. This can be helpful to implement pagination. Defaults to 10.`,
+            description: limitDescription,
             required: false,
             id: "limit",
+            isAdvanced: true,
           },
         ],
         returnValues: [
@@ -187,6 +226,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.Bolt,
         tableName: model.tableName!,
         componentType: ComponentType.Trigger,
+        documentationLink: triggerDocs,
         runWorkflowManuallyArguments: [
           {
             type: ComponentInputType.Text,
@@ -226,11 +266,11 @@ export default class BaseModelComponent {
         iconProp: IconProp.Trash,
         tableName: model.tableName!,
         componentType: ComponentType.Component,
-        documentationLink: documentationLink,
+        documentationLink: deleteDocs,
         arguments: [
           {
             type: ComponentInputType.Query,
-            name: "Delete by",
+            name: "Query",
             description: queryDescription,
             required: true,
             id: "query",
@@ -274,15 +314,15 @@ export default class BaseModelComponent {
         id: `${Text.pascalCaseToDashes(model.tableName!)}-delete-many`,
         title: `Delete Many ${model.pluralName}`,
         category: `${model.singularName}`,
-        description: `Database query to find many ${model.pluralName}`,
+        description: `Delete many ${model.pluralName} that match a query.`,
         iconProp: IconProp.Trash,
         tableName: model.tableName!,
         componentType: ComponentType.Component,
-        documentationLink: documentationLink,
+        documentationLink: deleteDocs,
         arguments: [
           {
             type: ComponentInputType.Query,
-            name: "Delete by",
+            name: "Query",
             description: queryDescription,
             required: true,
             id: "query",
@@ -291,16 +331,18 @@ export default class BaseModelComponent {
           {
             type: ComponentInputType.Number,
             name: "Skip",
-            description: `Skip the first X number of items. This can be helpful to implement pagination. Defaults to 0.`,
+            description: skipDescription,
             required: false,
             id: "skip",
+            isAdvanced: true,
           },
           {
             type: ComponentInputType.Number,
             name: "Limit",
-            description: `Limit to first X items. This can be helpful to implement pagination. Defaults to 10.`,
+            description: limitDescription,
             required: false,
             id: "limit",
+            isAdvanced: true,
           },
         ],
         returnValues: [
@@ -346,6 +388,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.Bolt,
         tableName: model.tableName!,
         componentType: ComponentType.Trigger,
+        documentationLink: triggerDocs,
         runWorkflowManuallyArguments: [
           {
             type: ComponentInputType.Text,
@@ -394,7 +437,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.Database,
         tableName: model.tableName!,
         componentType: ComponentType.Component,
-        documentationLink: documentationLink,
+        documentationLink: createDocs,
         arguments: [
           {
             id: "json",
@@ -409,8 +452,8 @@ export default class BaseModelComponent {
           {
             id: "model",
             name: `${model.singularName}`,
-            description: `${model.singularName} created in the database`,
-            type: ComponentInputType.JSON,
+            description: `${model.singularName} created in the database, including its new "_id"`,
+            type: ComponentInputType.BaseModel,
             required: false,
           },
         ],
@@ -446,7 +489,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.Database,
         tableName: model.tableName!,
         componentType: ComponentType.Component,
-        documentationLink: documentationLink,
+        documentationLink: createDocs,
         arguments: [
           {
             id: "json-array",
@@ -461,8 +504,8 @@ export default class BaseModelComponent {
           {
             id: "models",
             name: `${model.pluralName}`,
-            description: "Models created in the database",
-            type: ComponentInputType.BaseModel,
+            description: `${model.pluralName} created in the database`,
+            type: ComponentInputType.BaseModelArray,
             required: false,
           },
         ],
@@ -500,6 +543,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.Bolt,
         tableName: model.tableName!,
         componentType: ComponentType.Trigger,
+        documentationLink: triggerDocs,
         runWorkflowManuallyArguments: [
           {
             type: ComponentInputType.Text,
@@ -514,7 +558,7 @@ export default class BaseModelComponent {
           {
             type: ComponentInputType.Select,
             name: "Listen on",
-            description: `Workflow only executes when an upate happens to these fields on ${model.singularName}. If you leave this blank then the workflow will fire on any field that's updated on ${model.singularName}.`,
+            description: `Narrows this trigger to updates that touch these fields on ${model.singularName}. Leave it blank to fire on any change. When an update arrives without a record of which fields moved, this filter is skipped and the workflow runs anyway.`,
             required: false,
             id: "listen-on",
             placeholder: 'Example: {"columnName": true, ...}',
@@ -555,7 +599,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.ArrowCircleUp,
         tableName: model.tableName!,
         componentType: ComponentType.Component,
-        documentationLink: documentationLink,
+        documentationLink: updateDocs,
         arguments: [
           {
             type: ComponentInputType.Query,
@@ -615,7 +659,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.ArrowCircleUp,
         tableName: model.tableName!,
         componentType: ComponentType.Component,
-        documentationLink: documentationLink,
+        documentationLink: updateDocs,
         arguments: [
           {
             type: ComponentInputType.Query,
@@ -636,16 +680,18 @@ export default class BaseModelComponent {
           {
             type: ComponentInputType.Number,
             name: "Skip",
-            description: `Skip the first X number of items. This can be helpful to implement pagination. Defaults to 0.`,
+            description: skipDescription,
             required: false,
             id: "skip",
+            isAdvanced: true,
           },
           {
             type: ComponentInputType.Number,
             name: "Limit",
-            description: `Limit to first X items. This can be helpful to implement pagination. Defaults to 10.`,
+            description: limitDescription,
             required: false,
             id: "limit",
+            isAdvanced: true,
           },
         ],
         returnValues: [

package/Types/Workflow/Components/Discord.ts

@@ -21,6 +21,7 @@ const components: Array<ComponentMetadata> = [
           "Need help creating a webhook? Check docs here: https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks",
         type: ComponentInputType.URL,
         required: true,
+        isSensitive: true,
         placeholder:
           "https://discord.com/api/webhooks/1234567890/XXXXXXXXXXXXXXXXXXXXXXXX",
       },

package/Types/Workflow/Components/Email.ts

@@ -64,6 +64,7 @@ const components: Array<ComponentMetadata> = [
         description: "SMTP Password to send emails from",
         required: false,
         id: "smtp-password",
+        isSensitive: true,
       },
       {
         type: ComponentInputType.Number,
@@ -74,14 +75,22 @@ const components: Array<ComponentMetadata> = [
       },
       {
         type: ComponentInputType.Boolean,
-        name: "Use TLS/SSL",
+        name: "Use Implicit TLS",
         description:
-          "Check this box if you would like to use TLS/SSL to send emails",
+          "Enable for implicit TLS, usually on port 465. Leave disabled for STARTTLS, usually on port 587.",
         required: false,
         id: "secure",
       },
     ],
-    returnValues: [],
+    returnValues: [
+      {
+        id: "error",
+        name: "Error",
+        description: "Error, if there is any.",
+        type: ComponentInputType.Text,
+        required: false,
+      },
+    ],
     inPorts: [
       {
         title: "In",

package/Types/Workflow/Components/JavaScript.ts

@@ -40,6 +40,13 @@ const components: Array<ComponentMetadata> = [
         required: false,
         id: "returnValue",
       },
+      {
+        type: ComponentInputType.Text,
+        name: "Error",
+        description: "Error message when the script follows the Error port",
+        required: false,
+        id: "error",
+      },
     ],
     inPorts: [
       {

package/Types/Workflow/Components/MicrosoftTeams.ts

@@ -18,10 +18,11 @@ const components: Array<ComponentMetadata> = [
         id: "webhook-url",
         name: "Teams Incoming Webhook URL",
         description:
-          "Need help creating a webhook? Check docs here: https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook",
+          "Create a channel webhook with Teams Workflows. See: https://support.microsoft.com/en-us/teams/apps-service/create-incoming-webhooks-with-workflows-for-microsoft-teams",
         type: ComponentInputType.URL,
         required: true,
-        placeholder: "https://xxxxx.webhook.office.com/xxxxxxxxx",
+        isSensitive: true,
+        placeholder: "https://...environment.api.powerplatform.com/...",
       },
       {
         id: "text",

package/Types/Workflow/Components/Slack.ts

@@ -21,6 +21,7 @@ const components: Array<ComponentMetadata> = [
           "Need help creating a webhook? Check docs here: https://api.slack.com/messaging/webhooks",
         type: ComponentInputType.URL,
         required: true,
+        isSensitive: true,
         placeholder:
           "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
       },

package/Types/Workflow/Components/Telegram.ts

@@ -21,6 +21,7 @@ const components: Array<ComponentMetadata> = [
           "Need help creating a bot? Check docs here: https://core.telegram.org/bots#how-do-i-create-a-bot",
         type: ComponentInputType.Text,
         required: true,
+        isSensitive: true,
         placeholder: "1234567890:ABCdefGHIjklMNOpqrsTUVwxyZ",
       },
       {

package/Types/Workflow/TemplateSyntax.ts

@@ -366,6 +366,50 @@ export const looksLikeReferencePath: LooksLikeReferencePathFunction = (
   return !NON_REFERENCE_CHARACTERS.test(withoutAccessors);
 };
 
+/*
+ * The reference syntax, written once.
+ *
+ * Four places built these strings by hand - the value picker, the variable
+ * picker, the templates file and the docs - which is how the builder ended up
+ * with no single place to read the shape off, and why a reference typed by hand
+ * is so easy to get subtly wrong. Everything that offers a reference to a
+ * builder now goes through these.
+ */
+
+export type ComponentReturnValueReferenceFunction = (
+  componentId: string,
+  returnValueId: string,
+  /** Optional drill-in past the return value, e.g. ["model", "_id"]. */
+  path?: Array<string> | undefined,
+) => string;
+
+export const componentReturnValueReference: ComponentReturnValueReferenceFunction =
+  (
+    componentId: string,
+    returnValueId: string,
+    path?: Array<string> | undefined,
+  ): string => {
+    const deeper: string = path && path.length > 0 ? `.${path.join(".")}` : "";
+
+    return `{{local.components.${componentId}.returnValues.${returnValueId}${deeper}}}`;
+  };
+
+export type VariableReferenceFunction = (variableName: string) => string;
+
+/** A variable belonging to this workflow. */
+export const variableReference: VariableReferenceFunction = (
+  variableName: string,
+): string => {
+  return `{{local.variables.${variableName}}}`;
+};
+
+/** A variable belonging to the project, available to every workflow in it. */
+export const globalVariableReference: VariableReferenceFunction = (
+  variableName: string,
+): string => {
+  return `{{global.variables.${variableName}}}`;
+};
+
 export type ParseReferencePathFunction = (path: string) => ParsedReferencePath;
 
 /**