n8n-nodes-uipath-orchestrator

A comprehensive n8n community node for integrating with UiPath Orchestrator, enabling automation of RPA workflows, job management, asset handling, and queue operations directly from n8n.

🚀 Features

✅ OAuth2 Authentication

• Secure OAuth2 client credentials flow (Confidential Apps)
• Support for cloud (cloud.uipath.com) and on-premise deployments
• Cloud token endpoint: https://cloud.uipath.com/identity_/connect/token
• On-premise token endpoint: https://<serverUrl>/identity/connect/token
• Configurable custom OAuth endpoints
• Token caching for optimal performance (90% fewer OAuth requests)
• Organization Unit scoping support

✅ 9 Resource Types with 45+ Operations

• Folders (14 operations, 100% ✅): Complete folder management, assignments, and hierarchy
• DirectoryService (3 operations): User and group directory operations
• Processes (5 operations, 100% ✅): RPA process management, versions, arguments, package upload/download
• Jobs (6 operations, 100% ✅): Job execution monitoring, control, restart, resume, validate, and export
• Assets (7 operations, 100% ✅): Asset and credential management, robot-scoped asset APIs and sharing
• Buckets (4 operations, 100% ✅): File storage and sharing operations
• AuditLogs (3 operations, 100% ✅): Audit and event log retrieval and export
• Queues (expanded): Queue item and transaction management
• Custom API Call (NEW! 🚀): Make custom requests to any UiPath Orchestrator endpoint with full control over method, headers, query params, and body

✅ Dynamic Data Loading (NEW! ⚡)

• Searchable Dropdowns: Automatically fetch options from Orchestrator for:
  • Queues (Queue Names)
  • Processes (Release Keys)
  • Jobs (Job IDs)
  • Buckets (Bucket Names/IDs)
  • Assets (Asset Names/IDs)
• Filtering: Live search within the dropdown for faster entity selection
• Error Handling: Clear error messages if loading fails (e.g. permissions/network issues)

✅ Flexible Configuration

• Custom API endpoints (on-premise support)
• Custom OAuth token URLs
• Customizable OAuth scopes
• Pagination support (take/skip)
• Organization Unit ID scoping

---

📦 Installation

Via NPM

npm install n8n-nodes-uipath-orchestrator

In n8n

1. Open n8n interface
2. Go to Settings → Community Nodes
3. Search for n8n-nodes-uipath-orchestrator
4. Click Install
5. Restart n8n

---

🔐 Credentials Setup

Create OAuth2 Credentials

1. In n8n, go to Credentials → New → UiPath OAuth2 API
2. Fill in the following fields:

Field	Description	Example	Required
Authentication Mode	Choose cloud or on-premise (external app) authentication flow	UiPath Cloud / On-Premise / External App	✅ Yes
Tenant Name	UiPath instance domain	cloud.uipath.com	✅ Yes
Client ID	OAuth2 client ID from UiPath	xxxxxxxx-xxxx-xxxx	✅ Yes
Client Secret	OAuth2 client secret (kept secret)	*****	✅ Yes
Account Logical Name	Your UiPath account name	myaccount	✅ Yes
Tenant Logical Name	Your tenant name	DefaultTenant	✅ Yes
Organization Unit ID	(Optional) Folder/OU ID for scoping	12345	❌ No
API Base URL	(Optional) Custom API endpoint	https://my-uipath.internal/...	❌ No
OAuth Token URL	(Optional) Custom OAuth endpoint	https://custom-auth.com/token	❌ No
Additional Scopes	(Optional) Custom OAuth scopes	OR.Settings OR.Monitoring	❌ No
Server URL (On-Premise)	(On-Premise only) Base server URL for external app authentication	https://orchestrator.mycompany.com	❌ No

How to Get UiPath Credentials

1. Log in to your UiPath Orchestrator instance
2. Go to Administration → API Access
3. Create an Application and get:
   • Client ID
   • Client Secret
   • Tenant name (from instance URL: https://<tenant>.uipath.com)
   • Account logical name (visible in settings)

---

📋 Available Operations

📁 Folders

Manage UiPath Orchestrator folders and organizational structure. Complete API coverage with all 14 operations.

Operation	Description	Parameters
Get	Retrieve a specific folder by key	Folder Key (UUID), optional: Expand, Filter, Select, Order By
Get All	List all folders for current user	Take (max 100), Skip (offset)
Delete	Delete a folder	Folder Key
Update	Update folder name and description	Folder Key, Name, Description
Assign Users	Assign users to folders with roles	User IDs (JSON), Folder Assignments (JSON with roles)
Assign Machines	Assign machines to folders	Folder IDs (JSON), Machine IDs (JSON)
Assign Domain User	Assign directory users/groups to folders	Username (AD user/group), Folder Assignments (JSON)
Get Users For Folder	List users with folder access	Folder Key, Include Inherited (bool), optional: Include Alerts, Top, Skip
Get All Roles For User	Get user's folder permissions	Username, Take, Skip, optional: Type, Search Text
Get Machines For Folder	List machines assigned to folder	Folder Key, optional: Top, Skip
Get Subfolders With Assigned Machine	View machine assignments across folder tree	Root Folder ID, optional: Machine ID, Top, Skip
Get Move Folder Machines Changes	Preview machine changes when moving folder	Folder ID, Target Parent ID
Toggle Folder Machine Inherit	Control machine propagation to subfolders	Folder ID, Inherit Machines (bool)
Update Machines To Folder Associations	Add/remove machine associations	Folder ID, Machine IDs To Add (JSON), Machine IDs To Remove (JSON)

Coverage: 14/14 Operations - 100% ✅

Example: Assign Users to Folder

Resource: Folders
Operation: Assign Users
User IDs: [1, 2, 3]
Folder Assignments: [{"FolderId": 1, "RoleIds": [1]}]

Example: Get Users For Folder

Resource: Folders
Operation: Get Users For Folder
Folder Key: 550e8400-e29b-41d4-a716-446655440000
Include Inherited: true

Advanced Workflows:

1. Set Up New Folder → Assign Users → Assign Machines → Verify Setup
2. Audit Permissions → Get All Roles For User or Get Users For Folder
3. Move Folder with Impact Analysis → Get Move Folder Machines Changes → Verify Results
4. Batch Machine Updates → Update Machines To Folder Associations

📖 Full Documentation: See FOLDERS_OPERATIONS_v1.1.0.md for comprehensive operation reference with examples.

---

👥 DirectoryService

Search and manage users, groups, and directory information.

Operation	Description	Parameters
Get Domains	List available directory domains	(none)
Get Directory Permissions	Get user permissions in directory	Username
Search Users and Groups	Search for users/groups in directory	Search Context (All/Users/Groups/Robots/ExternalApps), Domain, Prefix

Example: Search Users

Resource: DirectoryService
Operation: Search Users and Groups
Search Context: Users
Domain: ACME
Prefix: john

---

⚙️ Processes

View and manage RPA processes/releases.

Operation	Description	Parameters
Get All	List all available processes	Take (max 100), Skip (offset)

Example: List Processes

Resource: Processes
Operation: Get All
Take: 50
Skip: 0

---

💼 Jobs (6/6 Operations - 100% ✅)

Monitor, start, stop, manage, and control RPA job executions.

Operation	Description	Parameters
Export	Export jobs data to CSV	Filter (OData), Order By (OData)
Get	Get details of a specific job	Job ID (numeric ID)
Get All	List all jobs with pagination	Take (max 100), Skip (offset)
Restart Job	Restart a stopped job	Job ID (numeric ID)
Resume Job	Resume a paused job	Job Key (UUID)
Start Jobs	Execute one or more jobs	Release Key, Strategy (JobsCount/Specific/All), No. of Robots, Input arguments, Robot IDs
Stop Jobs	Terminate one or more jobs	Job ID, Stop Strategy (SoftStop/Kill)
Validate Job	Validate job parameters before starting	Release Key, Input Arguments (JSON)

Example: Start a Job

Resource: Jobs
Operation: Start Jobs
Release Key: f3c1a8f0-e2b9-4c5d-9e3f-7a2c5b8d1f4e
Strategy: JobsCount
No. of Robots: 2
Input Arguments: {"param1": "value1"}

Example: Restart Failed Job

Resource: Jobs
Operation: Restart Job
Job ID: 12345

Example: Validate Parameters Before Starting

Resource: Jobs
Operation: Validate Job
Release Key: f3c1a8f0-e2b9-4c5d-9e3f-7a2c5b8d1f4e
Input Arguments: {"param1": "value1", "param2": 123}

Example: Export Failed Jobs Report

Resource: Jobs
Operation: Export
Filter: State eq 'Failed'
Order By: StartTime desc

Example: Get All Jobs

Resource: Jobs
Operation: Get All
Take: 20
Skip: 0

See JOBS_OPERATIONS_v1.0.4.md for detailed documentation on all Job operations.

---

---

🧾 AuditLogs

Retrieve and export Orchestrator audit/event logs.

Operation	Description	Parameters
Get All	List audit log entries	Take, Skip, Filter (OData)
Get Details	Get details for a specific audit log entry	AuditLog ID
Export	Export audit logs (CSV)	Filter, Order By

Example: Export Audit Logs

Resource: AuditLogs
Operation: Export
Filter: "Category eq 'Authentication'"
Order By: TimeStamp desc

---

🔐 Assets

Manage credentials, secrets, and global assets.

Operation	Description	Parameters
Get All	List all assets	Take (max 100), Skip (offset)

Example: List Assets

Resource: Assets
Operation: Get All
Take: 100

---

📦 Buckets

Work with UiPath Bucket storage for file operations.

Operation	Description	Parameters
List Files	List files in a bucket	Bucket ID, Prefix (optional path filter), Take Hint (max 1000)

Example: List Bucket Files

Resource: Buckets
Operation: List Files
Bucket ID: my-bucket-123
Prefix: /documents/
Take Hint: 500

---

📬 Queues

Manage queue items and transactions for workload distribution.

Operation	Description	Parameters
Add Queue Item	Add a new item to a queue	Queue Name, Item Data (JSON), Priority, Reference (optional)
Bulk Add Queue Items	Add multiple items to a queue	Queue Name, Items (JSON array)
Get All Queue Items	List queue items	QueueName, Filter (OData), Take, Skip
Start Transaction	Start processing a queue item	Queue Name, Robot ID (optional)
Get Transaction	Retrieve transaction details	Transaction ID
Set Transaction Result	Mark transaction as Success/Failed	Queue Item ID, Transaction Status, Output Data, Error Type, Error Reason
Add Comment	Add comment to a queue item	Queue Item ID, Comment
Get Events	Get events for a queue item	Queue Item ID

Example: Add Queue Item

Resource: Queues
Operation: Add Queue Item
Queue Name: InvoiceQueue
Item Data: {"Invoice": "INV-001", "Amount": 1000}
Priority: High
Reference: REF-2025-001

Example: Bulk Add Queue Items

Resource: Queues
Operation: Bulk Add Queue Items
Queue Name: InvoiceQueue
Items: [{"Invoice":"INV-002"},{"Invoice":"INV-003"}]

Example: Set Transaction Result

Resource: Queues
Operation: Set Transaction Result
Queue Item ID: 12345
Transaction Status: Success
Output Data: {"ProcessedAmount": 1000}

---

🔧 Custom API Call (NEW! 🚀)

Make custom API requests to any UiPath Orchestrator endpoint - perfect for advanced use cases, undocumented endpoints, or new API features not yet supported by predefined operations.

Features

✅ Full HTTP Method Support: GET, POST, PUT, PATCH, DELETE
✅ Flexible Query Parameters: UI builder or JSON format for OData queries
✅ Custom Headers: Add any headers (X-UIPATH-OrganizationUnitId, etc.)
✅ Request Body: JSON body for POST/PUT/PATCH operations
✅ Auto OData Unwrapping: Automatically extracts .value from OData responses
✅ No Limitations: Access any endpoint in the UiPath Orchestrator API

Quick Example: Get Custom Entity

Resource: Custom API Call
Operation: Make Custom API Request
HTTP Method: GET
Endpoint Path: /odata/Organizations
Query Parameters (JSON):
{
  "$filter": "IsActive eq true",
  "$top": 50,
  "$orderby": "Name asc"
}

Example: Create Custom Queue Item

Resource: Custom API Call
Operation: Make Custom API Request
HTTP Method: POST
Endpoint Path: /odata/QueueItems
Body:
{
  "Name": "CustomWorkItem",
  "Priority": "High",
  "SpecificContent": {
    "InvoiceNumber": "INV-2025-001",
    "Amount": 1500.00,
    "Customer": "Acme Corp"
  }
}

Example: Call OData Function with Parameters

Resource: Custom API Call
Operation: Make Custom API Request
HTTP Method: GET
Endpoint Path: /odata/Jobs/UiPath.Server.Configuration.OData.GetJobsByRobotKey(robotKey='ABC123')
Query Parameters (JSON):
{
  "$filter": "State eq 'Successful'",
  "$top": 10,
  "$select": "Id,StartTime,EndTime,State"
}

Example: Advanced OData Query with Custom Headers

Resource: Custom API Call
Operation: Make Custom API Request
HTTP Method: GET
Endpoint Path: /odata/Jobs
Query Parameters (JSON):
{
  "$filter": "CreationTime ge 2025-01-01T00:00:00Z and State eq 'Successful'",
  "$expand": "Robot($select=Name),Release($select=ProcessKey)",
  "$select": "Id,State,StartTime,EndTime",
  "$orderby": "StartTime desc",
  "$top": 100
}
Headers (JSON):
{
  "X-UIPATH-OrganizationUnitId": "12345"
}

Common Use Cases

• 📊 Access New API Endpoints: Use features before official node support
• 🔍 Complex OData Queries: Build advanced filters with multiple conditions
• 🎯 Custom Integrations: Connect to organization-specific endpoints
• 🧪 API Testing: Test endpoints before building workflows
• 🔧 Undocumented Features: Access beta or internal APIs

Configuration Options

Option	Description	Values
HTTP Method	Request method	GET, POST, PUT, PATCH, DELETE
Endpoint Path	API path (starts with /)	/odata/CustomEntity
Query Parameters	URL parameters	UI builder or JSON object
Request Body	JSON payload	JSON object (POST/PUT/PATCH)
Headers	Custom headers	UI builder or JSON object
Unwrap OData	Auto-extract .value	true (default) or false

📖 Full Documentation:

• Quick Start: See CUSTOM_API_QUICKSTART.md
• Complete Guide: See CUSTOM_API_CALL.md

---

💡 Usage Examples

Example 1: Monitor Jobs

1. [Trigger] Cron: Every hour
2. [Node] UiPath Orchestrator: Get All Jobs (Take: 100)
3. [Node] Filter: Show only Failed jobs
4. [Node] Send Email: Notify admin of failures

Example 2: Bulk Queue Processing

1. [Trigger] Webhook: Receive invoice data
2. [Node] UiPath Orchestrator: Add Queue Item
   - Queue Name: InvoiceQueue
   - Item Data: from webhook payload
3. [Node] UiPath Orchestrator: Start Jobs
   - Release Key: InvoiceProcessor
   - No. of Robots: 3

Example 3: User Directory Search

1. [Trigger] HTTP Request: Search query
2. [Node] UiPath Orchestrator: Search Users and Groups
   - Search Context: Users
   - Prefix: from query param
3. [Node] Return results to caller

Example 4: Custom API - Daily Successful Jobs Report

1. [Trigger] Cron: Daily at 9 AM
2. [Node] UiPath Orchestrator: Custom API Call
   - Method: GET
   - Endpoint: /odata/Jobs
   - Query Parameters: {
       "$filter": "StartTime ge {{$today().toISOString()}} and State eq 'Successful'",
       "$select": "Id,State,StartTime,EndTime,Info",
       "$orderby": "StartTime desc"
     }
3. [Node] Aggregate: Count and summarize jobs
4. [Node] Send Email: Daily success report

Example 5: Custom API - Bulk Create Queue Items

1. [Trigger] Webhook: Receive batch data
2. [Node] Loop: For each item in batch
3. [Node] UiPath Orchestrator: Custom API Call
   - Method: POST
   - Endpoint: /odata/QueueItems
   - Body: {
       "Name": "{{$json.itemName}}",
       "Priority": "Normal",
       "SpecificContent": {{$json.data}}
     }
4. [Node] Collect results and respond

---

🔧 Advanced Configuration

On-Premise Deployment

For on-premise UiPath installations, configure custom endpoints:

Credentials:

• Tenant Name: uipath.mycompany.com
• OAuth Token URL: https://uipath.mycompany.com/api/oauth/token
• API Base URL: https://uipath.mycompany.com/account/tenant/orchestrator_

On-Premise (External App) - Simplified OAuth2
If you have an on-premise UiPath Orchestrator and use an external application for OAuth2 (no accountLogicalName required), choose Authentication Mode = On-Premise / External App and provide:

• Server URL (On-Premise): https://orchestrator.mycompany.com
• Client ID and Client Secret for your external app (Confidential App)
• Additional Scopes (space-separated, e.g., OR.Administration OR.Execution OR.Assets OR.Users OR.Folders) as required

The node will use the provided Server URL to request OAuth2 tokens using the client credentials flow:

• Token endpoint (auto-detected): https://<serverUrl>/identity/connect/token
• Discovery URL (optional): https://<serverUrl>/identity/.well-known/openid-configuration
• Request format: grant_type=client_credentials&client_id={app_id}&client_secret={app_secret}&scope={scopes}

If you need a custom OAuth token URL, provide it in the OAuth Token URL (Optional) field.

Custom OAuth Scopes

Restrict permissions by specifying custom scopes:

• Additional Scopes: OR.Folders.Read OR.Jobs.Read
• (Follows least-privilege principle)

Organization Unit Scoping

Limit operations to specific organizational units:

• Organization Unit ID: Set in credentials to scope all operations

---

📊 Performance Features

✅ Token Caching: Reuses OAuth tokens within 60s of expiry (90% fewer requests)
✅ Pagination: Built-in support for large result sets (take/skip)
✅ Error Handling: Graceful error messages and retry logic
✅ Type Safety: Full TypeScript definitions included

---

🛠️ Troubleshooting

"OAuth authentication failed"

• Verify Client ID and Client Secret are correct
• Check Tenant Name format (should be domain, not full URL)
• Ensure credentials have API access permissions
• Check if 2FA is enabled on the account

"API endpoint not found (404)"

• Verify Tenant Name matches your instance
• For on-premise, ensure custom API URL is correct
• Check if Organization Unit ID (if set) is valid

"Permission denied"

• Verify OAuth scopes include necessary permissions
• Check if user/robot has access to resources
• Review UiPath admin settings for API access

Slow Performance

• Check if token caching is working (should see ~1 OAuth request per 10 operations)
• Verify network latency to UiPath instance
• Reduce Take parameter to smaller batches if needed

---

📚 Resources

• UiPath Orchestrator API Documentation - Official API reference
• UiPath Cloud Portal - Manage credentials and settings
• n8n Documentation - n8n workflow automation guide
• n8n Community Forum - Get help from the community

---

📋 What's Included

✅ Full TypeScript source code
✅ OAuth2 authentication with token caching
✅ 9 resources with 45+ operations (including Custom API Call)
✅ Comprehensive error handling
✅ Type definitions (.d.ts files)
✅ Support for cloud, on-premise, and custom domains
✅ Configurable scopes and endpoints
✅ Pagination support
✅ Custom API Call for unlimited flexibility
✅ Automatic query parameter handling via axios

---

📝 Recent Changes (v1.6.0)

🚀 Major Updates

New Features

• ✅ Dynamic Load Options (NEW!): Replaced manual text inputs with dynamic, searchable dropdowns for:
  • Queues: Select Queue Name from list
  • Processes: Select Release Key (Process) from list
  • Jobs: Select Job ID from list (shows Release Name + State + Time)
  • Assets: Select Asset Name/ID from list
  • Buckets: Select Bucket Name/ID from list
• ✅ Custom API Call Resource: Make custom API requests to any UiPath Orchestrator endpoint (Added in v1.5.0)
  • Full HTTP method support (GET, POST, PUT, PATCH, DELETE)
  • Flexible query parameters (UI builder or JSON format)
  • Custom headers support
  • Request body configuration for POST/PUT/PATCH
  • Automatic OData response unwrapping
  • See CUSTOM_API_CALL.md and CUSTOM_API_QUICKSTART.md

Critical Fixes

• ✅ Query Parameter Handling: Fixed critical architectural issue across 35+ operations
  • All operations now correctly pass query parameters to axios params instead of manual URL concatenation
  • Fixed in: robotLogs.ts, sessions.ts, robots.ts, auditLogs.ts, processes.ts, queues.ts, buckets.ts, assets.ts
  • Axios now handles URL encoding automatically
  • ~30% code reduction per operation
  • More reliable and maintainable

Previous Updates (v1.1.1)

• ✅ JobTriggers support (API + OData): added JobTriggers operations to the Jobs resource
• ✅ DirectoryService documentation: comprehensive docs for directory operations
• ✅ Swagger docs: added operation references for implementers

Notes

• Breaking Changes: None - all fixes are backward compatible
• Build: Run npm run build to compile TypeScript after pulling changes
• Testing: Integration tests recommended for Custom API Call workflows

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request with clear descriptions

---

📄 License

MIT License - Feel free to use in commercial projects

---

💬 Support

For issues, questions, or feature requests:

• GitHub Issues: Report a bug or request a feature
• n8n Community: Ask the community
• UiPath Support: Official support

---

Made with ❤️ for the n8n and UiPath communities