feat: onboarding attachments (#252)

Sandeepan-Ghosh-0312 · web-flow · commit 0900e2d80d16 · 2026-04-01T14:42:35.000+05:30
diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml
@@ -59,6 +59,7 @@ jobs:
           echo "data_fabric_test_choiceset_id=${{ secrets.UIPATH_DATA_FABRIC_TEST_CHOICESET_ID_DEV || secrets.UIPATH_DATA_FABRIC_TEST_CHOICESET_ID }}" >> $GITHUB_OUTPUT
           echo "data_fabric_test_record_id=${{ secrets.UIPATH_DATA_FABRIC_TEST_RECORD_ID_DEV || secrets.UIPATH_DATA_FABRIC_TEST_RECORD_ID }}" >> $GITHUB_OUTPUT
           echo "data_fabric_test_attachment_field=${{ secrets.UIPATH_DATA_FABRIC_TEST_ATTACHMENT_FIELD_DEV || secrets.UIPATH_DATA_FABRIC_TEST_ATTACHMENT_FIELD }}" >> $GITHUB_OUTPUT
+          echo "orchestrator_attachment_id=${{ secrets.UIPATH_ORCHESTRATOR_ATTACHMENT_ID_DEV || secrets.UIPATH_ORCHESTRATOR_ATTACHMENT_ID }}" >> $GITHUB_OUTPUT
 
       - name: Create Integration Test Configuration
         if: github.base_ref == 'main'
@@ -78,6 +79,7 @@ jobs:
           DATA_FABRIC_TEST_RECORD_ID=${{ steps.config.outputs.data_fabric_test_record_id }}
           DATA_FABRIC_TEST_ATTACHMENT_FIELD=${{ steps.config.outputs.data_fabric_test_attachment_field }}
           ORCHESTRATOR_TEST_PROCESS_KEY=${{ steps.config.outputs.orchestrator_test_process_key }}
+          ORCHESTRATOR_ATTACHMENT_ID=${{ steps.config.outputs.orchestrator_attachment_id }}
           EOF
 
       - name: Run Integration Tests
diff --git a/docs/oauth-scopes.md b/docs/oauth-scopes.md
@@ -15,6 +15,12 @@ This page lists the specific OAuth scopes required in external app for each SDK
 |--------|-------------|
 | `getAll()` | `OR.Jobs` or `OR.Jobs.Read` |
 
+## Attachments
+
+| Method | OAuth Scope |
+|--------|-------------|
+| `getById()` | `OR.Folders` or `OR.Folders.Read` |
+
 ## Buckets
 
 | Method | OAuth Scope |
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -91,6 +91,7 @@ plugins:
           - api/interfaces/QueueServiceModel.md: Queue service methods
           - api/interfaces/BucketServiceModel.md: Bucket service methods
           - api/interfaces/TaskServiceModel.md: Task service methods
+          - api/interfaces/attachments/index.md: Attachment service methods
           - api/interfaces/entity/index.md: Entity service methods
           - api/interfaces/ChoiceSetServiceModel.md: Choice set service methods
           - api/interfaces/MaestroProcessesServiceModel.md: Maestro process methods
@@ -182,6 +183,8 @@ nav:
               - Session: api/interfaces/SessionStream.md
               - Exchanges: api/interfaces/ExchangeServiceModel.md
               - Messages: api/interfaces/MessageServiceModel.md
+          - Attachments:
+            - api/interfaces/attachments/index.md
           - Assets: api/interfaces/AssetServiceModel.md
           - Buckets: api/interfaces/BucketServiceModel.md
           - Entities:
diff --git a/package.json b/package.json
@@ -76,6 +76,16 @@
                 "default": "./dist/jobs/index.cjs"
             }
         },
+        "./attachments": {
+            "import": {
+                "types": "./dist/attachments/index.d.ts",
+                "default": "./dist/attachments/index.mjs"
+            },
+            "require": {
+                "types": "./dist/attachments/index.d.ts",
+                "default": "./dist/attachments/index.cjs"
+            }
+        },
         "./queues": {
             "import": {
                 "types": "./dist/queues/index.d.ts",
diff --git a/packages/cli/src/constants/messages.ts b/packages/cli/src/constants/messages.ts
@@ -139,6 +139,7 @@ export const MESSAGES = {
     //Action schema validations
     INVALID_PROPERTY_TYPE: 'Invalid type. Must be one of: string, integer, number, boolean, array, object',
     INVALID_PROPERTY_FORMAT: 'Invalid format. Must be one of: uuid, date',
+    INVALID_TYPE_FOR_FORMAT: 'Format is only supported for type string',
     MISSING_ITEMS_ARRAY: 'Array properties must have an "items" field',
     NESTED_ARRAYS_NOT_SUPPORTED: 'Nested arrays are not allowed. Array items cannot be of type array',
     SECTION_TYPE_INVALID: 'Section type must be "object"',
diff --git a/packages/cli/src/types/action-app.ts b/packages/cli/src/types/action-app.ts
@@ -13,6 +13,7 @@ export enum JsonDataType {
   boolean = 'boolean',
   array = 'array',
   object = 'object',
+  file = 'file',
 }
 
 export enum JsonFormatType {
@@ -36,6 +37,7 @@ export enum VBDataType {
   dateOnly = 'System.DateOnly',
   guid = 'System.Guid',
   object = 'System.Object',
+  iresource = 'UiPath.Platform.ResourceHandling.IResource',
 }
 
 export const JsonSchemaPropertySchema: z.ZodType<JsonSchemaProperty> = z.lazy(() =>
@@ -47,6 +49,7 @@ export const JsonSchemaPropertySchema: z.ZodType<JsonSchemaProperty> = z.lazy(()
       JsonDataType.boolean,
       JsonDataType.array,
       JsonDataType.object,
+      JsonDataType.file,
     ], { message: MESSAGES.ERRORS.INVALID_PROPERTY_TYPE }),
     required: z.boolean().optional(),
     description: z.string().optional(),
@@ -64,6 +67,14 @@ export const JsonSchemaPropertySchema: z.ZodType<JsonSchemaProperty> = z.lazy(()
   }, {
     message: MESSAGES.ERRORS.MISSING_ITEMS_ARRAY
   })
+  .refine((data) => {
+    if (data.format && data.type!== JsonDataType.string) {   // for preventing format being used with non string type
+      return false;
+    }
+    return true;
+  }, {
+    message: MESSAGES.ERRORS.INVALID_TYPE_FOR_FORMAT,
+  })
   .refine((data) => {
     if (data.type === JsonDataType.array && data.items) {   // for preventing nested arrays
       return data.items.type !== JsonDataType.array;
diff --git a/packages/cli/src/utils/action-schema.ts b/packages/cli/src/utils/action-schema.ts
@@ -47,6 +47,7 @@ function mapJsonTypeToSystemType(type: JsonDataType, format?: JsonFormatType): V
     case JsonDataType.number: return VBDataType.decimal;
     case JsonDataType.boolean: return VBDataType.boolean;
     case JsonDataType.object: return VBDataType.object;
+    case JsonDataType.file: return VBDataType.iresource;
     default: 
       throw new Error(`${MESSAGES.ERRORS.UNSUPPORTED_JSON_DATA_TYPE} ${type}`);
   }
diff --git a/rollup.config.js b/rollup.config.js
@@ -159,6 +159,11 @@ const serviceEntries = [
     input: 'src/services/orchestrator/jobs/index.ts',
     output: 'jobs/index'
   },
+  {
+    name: 'attachments',
+    input: 'src/services/orchestrator/attachments/index.ts',
+    output: 'attachments/index'
+  },
   {
     name: 'queues',
     input: 'src/services/orchestrator/queues/index.ts',
diff --git a/scripts/docs-post-process.mjs b/scripts/docs-post-process.mjs
@@ -9,7 +9,7 @@
  */
 
 import { mkdirSync, readFileSync, writeFileSync, unlinkSync, existsSync } from 'fs';
-import { join, dirname, relative } from 'path';
+import { join, dirname, relative, sep } from 'path';
 
 const DOCS_DIR = join(process.cwd(), 'docs');
 
@@ -24,6 +24,12 @@ const sections = [
     header: '---\ntitle: Entities\n---\n',
     removeSource: true,
   },
+  {
+    source: 'api/interfaces/AttachmentServiceModel.md',
+    dest: 'api/interfaces/attachments/index.md',
+    header: '---\ntitle: Attachments\n---\n',
+    removeSource: true,
+  },
   {
     source: 'api/interfaces/ConversationalAgentServiceModel.md',
     dest: 'conversational-agent/index.md',
@@ -59,7 +65,7 @@ for (const { source, dest, header, removeSource } of sections) {
 
       const [linkPath, anchor] = link.split('#');
       const resolved = join(sourceDir, linkPath);
-      const rewritten = relative(destDir, resolved);
+      const rewritten = relative(destDir, resolved).split(sep).join('/');
 
       return `](${anchor ? `${rewritten}#${anchor}` : rewritten})`;
     },
diff --git a/src/models/orchestrator/attachments.constants.ts b/src/models/orchestrator/attachments.constants.ts
@@ -0,0 +1,7 @@
+/**
+ * Maps fields for Attachment entities to ensure consistent naming
+ */
+export const AttachmentsMap: { [key: string]: string } = {
+  creationTime: 'createdTime',
+  lastModificationTime: 'lastModifiedTime'
+};
diff --git a/src/models/orchestrator/attachments.models.ts b/src/models/orchestrator/attachments.models.ts
@@ -0,0 +1,28 @@
+import {
+  AttachmentResponse,
+  AttachmentGetByIdOptions,
+} from './attachments.types';
+
+/**
+ * Service for managing UiPath Orchestrator Attachments.
+ *
+ * Attachments are files that can be associated with Orchestrator jobs.
+ */
+export interface AttachmentServiceModel {
+  /**
+   * Gets an attachment by ID
+   *
+   * @param id - The UUID of the attachment to retrieve
+   * @param options - Optional query parameters (expand, select)
+   * @returns Promise resolving to the attachment
+   * {@link AttachmentResponse}
+   * @example
+   * ```typescript
+   * import { Attachments } from '@uipath/uipath-typescript/attachments';
+   *
+   * const attachments = new Attachments(sdk);
+   * const attachment = await attachments.getById('12345678-1234-1234-1234-123456789abc');
+   * ```
+   */
+  getById(id: string, options?: AttachmentGetByIdOptions): Promise<AttachmentResponse>;
+}
diff --git a/src/models/orchestrator/attachments.types.ts b/src/models/orchestrator/attachments.types.ts
@@ -0,0 +1,54 @@
+import { BaseOptions } from "../common/types";
+import type { BucketGetUriResponse } from "./buckets.types";
+
+/**
+ * Attachment response from the API
+ */
+export interface AttachmentResponse {
+  /**
+   * UUID of the attachment
+   */
+  id: string;
+  
+  /**
+   * Name of the attachment
+   */
+  name: string;
+
+  /**
+   * Optional job key to link the attachment to a job when creating it.
+   */
+  jobKey?: string;
+
+  /**
+   * Optional category for the attachment when linking to a job.
+   */
+  attachmentCategory?: string;
+
+  /**
+   * When the attachment was last modified
+   */
+  lastModifiedTime?: string;
+
+  /**
+   * User ID who last modified the attachment
+   */
+  lastModifierUserId?: number;
+
+  /**
+   * When the attachment was created
+   */
+  createdTime?: string;
+
+  /**
+   * User ID who created the attachment
+   */
+  creatorUserId?: number;
+
+  blobFileAccess: BucketGetUriResponse;
+}
+
+/**
+ * Options for getting an attachment by ID
+ */
+export interface AttachmentGetByIdOptions extends BaseOptions {};
diff --git a/src/models/orchestrator/index.ts b/src/models/orchestrator/index.ts
@@ -11,3 +11,5 @@ export * from './processes.types';
 export * from './processes.models';
 export * from './queues.types';
 export * from './queues.models';
+export * from './attachments.types';
+export * from './attachments.models';
diff --git a/src/services/orchestrator/attachments/attachments.ts b/src/services/orchestrator/attachments/attachments.ts
@@ -0,0 +1,52 @@
+import { ValidationError } from '../../../core/errors';
+import {
+  AttachmentResponse,
+  AttachmentGetByIdOptions,
+} from '../../../models/orchestrator/attachments.types';
+import { AttachmentServiceModel } from '../../../models/orchestrator/attachments.models';
+import { pascalToCamelCaseKeys, addPrefixToKeys, transformData } from '../../../utils/transform';
+import { ORCHESTRATOR_ATTACHMENT_ENDPOINTS } from '../../../utils/constants/endpoints';
+import { ODATA_PREFIX } from '../../../utils/constants/common';
+import { track } from '../../../core/telemetry';
+import { AttachmentsMap } from '../../../models/orchestrator/attachments.constants';
+import { BaseService } from '../../..//services/base';
+import { BucketMap } from '../../../models/orchestrator/buckets.constants';
+
+export class AttachmentService extends BaseService implements AttachmentServiceModel {
+  /**
+   * Gets an attachment by ID
+   * @param id - The UUID of the attachment to retrieve
+   * @param options - Optional query parameters (expand, select)
+   * @returns Promise resolving to the attachment
+   *
+   * @example
+   * ```typescript
+   * import { Attachments } from '@uipath/uipath-typescript/attachments';
+   *
+   * const attachments = new Attachments(sdk);
+   * const attachment = await attachments.getById('12345678-1234-1234-1234-123456789abc');
+   * ```
+   */
+  @track('Attachments.GetById')
+  async getById(id: string, options: AttachmentGetByIdOptions = {}): Promise<AttachmentResponse> {
+    if (!id) {
+      throw new ValidationError({ message: 'id is required for getById' });
+    }
+
+    // Prefix all keys in options with $ for OData
+    const keysToPrefix = Object.keys(options);
+    const apiOptions = addPrefixToKeys(options, ODATA_PREFIX, keysToPrefix);
+
+    const response = await this.get<AttachmentResponse>(
+      ORCHESTRATOR_ATTACHMENT_ENDPOINTS.GET_BY_ID(id),
+      {
+        params: apiOptions,
+      }
+    );
+
+    // Transform response from PascalCase to camelCase, then apply field maps
+    const camelCased = pascalToCamelCaseKeys(response.data) as AttachmentResponse;
+    camelCased.blobFileAccess = transformData(camelCased.blobFileAccess, BucketMap);
+    return transformData(camelCased, AttachmentsMap);
+  }
+}
diff --git a/src/services/orchestrator/attachments/index.ts b/src/services/orchestrator/attachments/index.ts
@@ -0,0 +1,20 @@
+/**
+ * Attachments Module
+ *
+ * Provides access to UiPath Orchestrator for attachements.
+ *
+ * @example
+ * ```typescript
+ * import { Attachments } from '@uipath/uipath-typescript/attachments';
+ *
+ * const attachments = new Attachments(sdk);
+ * const attachment = await attachments.getById(<attachmentId>);
+ * ```
+ *
+ * @module
+ */
+
+export { AttachmentService as Attachments, AttachmentService } from './attachments';
+
+export * from '../../../models/orchestrator/attachments.types';
+export * from '../../../models/orchestrator/attachments.models';
diff --git a/src/services/orchestrator/index.ts b/src/services/orchestrator/index.ts
@@ -3,3 +3,4 @@ export * from './buckets';
 export * from './jobs';
 export * from './processes';
 export * from './queues';
+export * from './attachments';
diff --git a/src/utils/constants/endpoints/orchestrator.ts b/src/utils/constants/endpoints/orchestrator.ts
@@ -67,3 +67,10 @@ export const ASSET_ENDPOINTS = {
   GET_ALL: `${ORCHESTRATOR_BASE}/odata/Assets/UiPath.Server.Configuration.OData.GetAssetsAcrossFolders`,
   GET_BY_ID: (id: number) => `${ORCHESTRATOR_BASE}/odata/Assets(${id})`,
 } as const;
+
+/**
+ * Orchestrator Attachment Service Endpoints
+ */
+export const ORCHESTRATOR_ATTACHMENT_ENDPOINTS = {
+  GET_BY_ID: (id: string) => `${ORCHESTRATOR_BASE}/odata/Attachments(${id})`,
+} as const;
diff --git a/tests/.env.integration.example b/tests/.env.integration.example
@@ -48,4 +48,7 @@ ORCHESTRATOR_TEST_PROCESS_KEY=
 DATA_FABRIC_TEST_ENTITY_ID=
 DATA_FABRIC_TEST_CHOICESET_ID=
 DATA_FABRIC_TEST_RECORD_ID=
-DATA_FABRIC_TEST_ATTACHMENT_FIELD=
+DATA_FABRIC_TEST_ATTACHMENT_FIELD=
+
+# Orchestrator attachment ID (UUID) for attachment getById tests
+ORCHESTRATOR_ATTACHMENT_ID=
diff --git a/tests/integration/config/test-config.ts b/tests/integration/config/test-config.ts
@@ -18,6 +18,7 @@ export interface IntegrationConfig {
   dataFabricTestChoiceSetId?: string;
   dataFabricTestRecordId?: string;
   dataFabricTestAttachmentField?: string;
+  orchestratorAttachmentId?: string;
 }
 
 function isValidUrl(value: string): boolean {
@@ -67,6 +68,7 @@ function validateConfig(rawConfig: Record<string, unknown>): IntegrationConfig {
     dataFabricTestChoiceSetId: typeof rawConfig.dataFabricTestChoiceSetId === 'string' ? rawConfig.dataFabricTestChoiceSetId : undefined,
     dataFabricTestRecordId: typeof rawConfig.dataFabricTestRecordId === 'string' ? rawConfig.dataFabricTestRecordId : undefined,
     dataFabricTestAttachmentField: typeof rawConfig.dataFabricTestAttachmentField === 'string' ? rawConfig.dataFabricTestAttachmentField : undefined,
+    orchestratorAttachmentId: typeof rawConfig.orchestratorAttachmentId === 'string' ? rawConfig.orchestratorAttachmentId : undefined,
   };
 }
 
@@ -100,6 +102,7 @@ export function loadIntegrationConfig(): IntegrationConfig {
     dataFabricTestChoiceSetId: process.env.DATA_FABRIC_TEST_CHOICESET_ID || undefined,
     dataFabricTestRecordId: process.env.DATA_FABRIC_TEST_RECORD_ID || undefined,
     dataFabricTestAttachmentField: process.env.DATA_FABRIC_TEST_ATTACHMENT_FIELD || undefined,
+    orchestratorAttachmentId: process.env.ORCHESTRATOR_ATTACHMENT_ID || undefined,
   };
 
   cachedConfig = validateConfig(rawConfig);
diff --git a/tests/integration/config/unified-setup.ts b/tests/integration/config/unified-setup.ts
diff --git a/tests/integration/shared/orchestrator/attachments.integration.test.ts b/tests/integration/shared/orchestrator/attachments.integration.test.ts
diff --git a/tests/unit/services/orchestrator/attachments.test.ts b/tests/unit/services/orchestrator/attachments.test.ts
diff --git a/tests/utils/constants/attachments.ts b/tests/utils/constants/attachments.ts
diff --git a/tests/utils/constants/index.ts b/tests/utils/constants/index.ts
diff --git a/tests/utils/mocks/attachments.ts b/tests/utils/mocks/attachments.ts
diff --git a/tests/utils/mocks/index.ts b/tests/utils/mocks/index.ts
diff --git a/vitest.integration.config.ts b/vitest.integration.config.ts

Original file line number	Diff line number	Diff line change
`@@ -47,6 +47,7 @@ function mapJsonTypeToSystemType(type: JsonDataType, format?: JsonFormatType): V`
`47`	`47`	`case JsonDataType.number: return VBDataType.decimal;`
`48`	`48`	`case JsonDataType.boolean: return VBDataType.boolean;`
`49`	`49`	`case JsonDataType.object: return VBDataType.object;`
	`50`	`+ case JsonDataType.file: return VBDataType.iresource;`
`50`	`51`	`default:`
`51`	`52`	throw new Error(`${MESSAGES.ERRORS.UNSUPPORTED_JSON_DATA_TYPE} ${type}`);
`52`	`53`	`}`