powerAPS-Modules

Disclaimer

THE SAMPLE CODE ON THIS REPOSITORY IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THE USAGE OF THIS SAMPLE IS AT YOUR OWN RISK AND THERE IS NO SUPPORT RELATED TO IT.

---

Description

This repository contains the core PowerShell modules that enable communication between COOLORANGE powerJobs/powerEvents and Autodesk Platform Services (APS) endpoints. These modules provide the foundational API connectivity for integrating Autodesk Vault with cloud services including Autodesk Construction Cloud (ACC), BIM 360, and Fusion.

The powerAPS modules serve as the communication layer that abstracts APS API complexity and provides PowerShell-friendly cmdlets for authentication, data management, and cloud service interactions.

---

Prerequisites

Note: powerJobs Processor version 26.0.4 or greater and powerEvents version 26.0.7 or greater are required.

These modules are designed to work with:

• powerJobs Processor (Vault Job Processor side automation)
• powerEvents (powerJobs Client) (Vault Client side extensions)
• Autodesk Vault Professional 2023 or later

---

Related Repositories

The powerAPS-Modules serve as the foundation that all powerAPS-* repos depend on for APS connectivity.

---

Installation

Important: Files downloaded from GitHub may be blocked by Windows. You must unblock all files before installation:

1. Right-click each downloaded file → Properties
2. Check "Unblock" at the bottom → Apply → OK
3. Or use PowerShell: Get-ChildItem -Recurse | Unblock-File

1. Download or clone this repository
2. Unblock all downloaded files (see important note above)
3. Copy all files from the powerAPS directory to:
   C:\ProgramData\coolOrange\powerAPS\
4. Restart any running powerJobs Processor, Vault Job Processor or Vault Explorer instances

---

Integration with coolOrange powerAPS Module

The modules in this repository work in conjunction with coolOrange's powerAPS module, which provides the core authentication and connection infrastructure for Autodesk Platform Services integration. This official module is included with powerJobs Processor v26.0.4+ and powerEvents v26.0.7+.

---

Core powerAPS Module Overview

The main powerAPS module provides essential cmdlets and objects that serve as the foundation for all APS communication:

Connect-APS Cmdlet

The primary authentication cmdlet that establishes OAuth 2.0 connections to Autodesk Platform Services:

# Basic authentication using signed-in Autodesk ID
Connect-APS

# Custom app authentication  
Connect-APS -ClientId "your-client-id" -ClientSecret "your-secret" -CallbackUrl "http://localhost:8080/"

# Job processor impersonation
Connect-APS -User $job.SubmittedByAutodeskId

APSConnection Global Object

After successful authentication, the $global:APSConnection object provides:

• Authorization headers for API calls
• Hub information and access
• User context and impersonation details
• Token management and automatic refresh

---

Authentication Workflows

Authentication on the Vault Client

For powerEvents and Vault Explorer extensions:

# Import powerAPS modules from this repository
Import-Module C:\ProgramData\coolOrange\powerAPS\powerAPS.Modules.psd1 -Force

# Establish connection (may open browser for consent)
$connected = Connect-APS -ClientId "your-app-client-id" -ClientSecret "your-app-secret" -CallbackUrl "http://localhost:8080/callback"if ($connected) {
    # Use modules from this repository for specific operations
    $hub = Get-ApsAccHub "My Company"
    $projects = Get-ApsProject -hub $hub
}

Authentication on the Vault Job Processor

For powerJobs Processor workflows:

# Import powerAPS modules from this repository  
Import-Module C:\ProgramData\coolOrange\powerAPS\powerAPS.Modules.psd1 -Force

# Connect using job submitter's credentials (no browser interaction)
Connect-APS -User $job.SubmittedByAutodeskId -ClientId "your-app-client-id" -ClientSecret "your-app-secret" -ErrorAction Stop

# Perform operations using modules from this repository
$projectProperties = GetVaultAccProjectProperties $file._FolderPath
$hub = Get-ApsAccHub $projectProperties["Hub"]

---

Token Management & Session Persistence

Automatic Token Refresh

The powerAPS module handles token lifecycle automatically:

• 15-day minimum validity for authenticated sessions
• Automatic background refresh on API calls
• Extended validity as long as sessions are used regularly
• Secure token storage integrated with Vault database

---

Access Scopes & Permissions

The powerAPS module's Connect-APS cmdlet grants comprehensive access scopes:

data:read data:write data:create data:search viewables:read
bucket:create bucket:read bucket:update bucket:delete  
user-profile:read user:read user:write account:read account:write
code:all openid

This enables the modules in this repository to perform:

• Full data management operations (CRUD)
• File upload/download and storage management
• User and account information retrieval
• Project and hub administration
• Search and discovery across all accessible content

---

Integration Patterns

Job Submission Pattern

# Client-side: Submit job with user context
Add-VaultJob -Name "powerAPS.ACC.Publish.PDF" -Parameters @{
    "FileVersionId" = $file.Id
    "EntityId" = $file.Id  
    "EntityClassId" = $file._EntityTypeID
    "SubmittedByAutodeskId" = $APSConnection.User  # Pass user context
}

# Server-side: Job processor uses submitted user context
Connect-APS -User $job.SubmittedByAutodeskId -ClientId "your-app-client-id" -ClientSecret "your-app-secret" -ErrorAction Stop
# Job now runs with same permissions as submitting user

---

Support and Documentation

For additional information:

• COOLORANGE Documentation: https://doc.coolorange.com
• powerAPS Reference: https://doc.coolorange.com/projects/poweraps/en/stable/
• APS Developer Portal: https://aps.autodesk.com/