feat: add external id to documents and templates (#1227)

## Description

Adds the external ID column to documents and templates with an option to
configure it in the API or UI.

External ID's can be used to link a document or template to an external
system and identify them via webhooks, etc.

packages/lib/server-only/document/create-document.ts

@@ -11,6 +11,7 @@ import { triggerWebhook } from '../webhooks/trigger/trigger-webhook';
 
 export type CreateDocumentOptions = {
   title: string;
+  externalId?: string | null;
   userId: number;
   teamId?: number;
   documentDataId: string;
@@ -21,6 +22,7 @@ export type CreateDocumentOptions = {
 export const createDocument = async ({
   userId,
   title,
+  externalId,
   documentDataId,
   teamId,
   formValues,
@@ -50,6 +52,7 @@ export const createDocument = async ({
     const document = await tx.document.create({
       data: {
         title,
+        externalId,
         documentDataId,
         userId,
         teamId,

packages/lib/server-only/document/update-document-settings.ts

@@ -18,6 +18,7 @@ export type UpdateDocumentSettingsOptions = {
   documentId: number;
   data: {
     title?: string;
+    externalId?: string | null;
     globalAccessAuth?: TDocumentAccessAuthTypes | null;
     globalActionAuth?: TDocumentActionAuthTypes | null;
   };
@@ -91,6 +92,7 @@ export const updateDocumentSettings = async ({
   }
 
   const isTitleSame = data.title === document.title;
+  const isExternalIdSame = data.externalId === document.externalId;
   const isGlobalAccessSame = documentGlobalAccessAuth === newGlobalAccessAuth;
   const isGlobalActionSame = documentGlobalActionAuth === newGlobalActionAuth;
 
@@ -118,6 +120,21 @@ export const updateDocumentSettings = async ({
     );
   }
 
+  if (!isExternalIdSame) {
+    auditLogs.push(
+      createDocumentAuditLogData({
+        type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_EXTERNAL_ID_UPDATED,
+        documentId,
+        user,
+        requestMetadata,
+        data: {
+          from: document.externalId,
+          to: data.externalId || '',
+        },
+      }),
+    );
+  }
+
   if (!isGlobalAccessSame) {
     auditLogs.push(
       createDocumentAuditLogData({
@@ -165,6 +182,7 @@ export const updateDocumentSettings = async ({
       },
       data: {
         title: data.title,
+        externalId: data.externalId || null,
         authOptions,
       },
     });

packages/lib/server-only/template/create-document-from-template.ts

@@ -33,6 +33,7 @@ export type CreateDocumentFromTemplateResponse = Awaited<
 
 export type CreateDocumentFromTemplateOptions = {
   templateId: number;
+  externalId?: string | null;
   userId: number;
   teamId?: number;
   recipients: {
@@ -58,6 +59,7 @@ export type CreateDocumentFromTemplateOptions = {
 
 export const createDocumentFromTemplate = async ({
   templateId,
+  externalId,
   userId,
   teamId,
   recipients,
@@ -147,6 +149,7 @@ export const createDocumentFromTemplate = async ({
     const document = await tx.document.create({
       data: {
         source: DocumentSource.TEMPLATE,
+        externalId,
         templateId: template.id,
         userId,
         teamId: template.teamId,

packages/lib/server-only/template/update-template-settings.ts

@@ -15,6 +15,7 @@ export type UpdateTemplateSettingsOptions = {
   templateId: number;
   data: {
     title?: string;
+    externalId?: string | null;
     globalAccessAuth?: TDocumentAccessAuthTypes | null;
     globalActionAuth?: TDocumentActionAuthTypes | null;
     publicTitle?: string;
@@ -99,6 +100,7 @@ export const updateTemplateSettings = async ({
     },
     data: {
       title: data.title,
+      externalId: data.externalId || null,
       type: data.type,
       publicDescription: data.publicDescription,
       publicTitle: data.publicTitle,

packages/lib/types/document-audit-logs.ts

@@ -35,6 +35,7 @@ export const ZDocumentAuditLogTypeSchema = z.enum([
   'DOCUMENT_RECIPIENT_COMPLETED', // When a recipient completes all their required tasks for the document.
   'DOCUMENT_SENT', // When the document transitions from DRAFT to PENDING.
   'DOCUMENT_TITLE_UPDATED', // When the document title is updated.
+  'DOCUMENT_EXTERNAL_ID_UPDATED', // When the document external ID is updated.
   'DOCUMENT_MOVED_TO_TEAM', // When the document is moved to a team.
 ]);
 
@@ -355,6 +356,17 @@ export const ZDocumentAuditLogEventDocumentTitleUpdatedSchema = z.object({
   }),
 });
 
+/**
+ * Event: Document external ID updated.
+ */
+export const ZDocumentAuditLogEventDocumentExternalIdUpdatedSchema = z.object({
+  type: z.literal(DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_EXTERNAL_ID_UPDATED),
+  data: z.object({
+    from: z.string().nullish(),
+    to: z.string().nullish(),
+  }),
+});
+
 /**
  * Event: Field created.
  */
@@ -450,6 +462,7 @@ export const ZDocumentAuditLogSchema = ZDocumentAuditLogBaseSchema.and(
     ZDocumentAuditLogEventDocumentRecipientCompleteSchema,
     ZDocumentAuditLogEventDocumentSentSchema,
     ZDocumentAuditLogEventDocumentTitleUpdatedSchema,
+    ZDocumentAuditLogEventDocumentExternalIdUpdatedSchema,
     ZDocumentAuditLogEventFieldCreatedSchema,
     ZDocumentAuditLogEventFieldRemovedSchema,
     ZDocumentAuditLogEventFieldUpdatedSchema,

packages/lib/utils/document-audit-logs.ts

@@ -332,6 +332,10 @@ export const formatDocumentAuditLogAction = (auditLog: TDocumentAuditLog, userId
       anonymous: 'Document title updated',
       identified: 'updated the document title',
     }))
+    .with({ type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_EXTERNAL_ID_UPDATED }, () => ({
+      anonymous: 'Document external ID updated',
+      identified: 'updated the document external ID',
+    }))
     .with({ type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_SENT }, () => ({
       anonymous: 'Document sent',
       identified: 'sent the document',