Microsoft SharePoint Integration Guide

Overview

The Microsoft SharePoint integration allows your NINA workflows to connect with SharePoint Online sites for comprehensive document management and collaboration. This integration enables you to manage sites, upload and download documents, search for files, list folder contents, retrieve metadata, and perform bulk operations directly from your automation workflows.

Status

The integration currently supports comprehensive SharePoint site and document management operations:

Currently Supported:

• Site Management: List all sites, search for specific sites, get detailed site information
• Document Operations: Upload, download, list, search, delete files, and retrieve file metadata
• Bulk Operations: Upload multiple files or download multiple files in batches (up to 50 per batch)
• Folder Management: Navigate folder structures, list folder contents with filtering
• Large File Support: Chunked upload for files larger than 4MB (up to 250MB)
• Search Capabilities: Full-text search across SharePoint sites and documents

Advanced Features:

• OAuth2 Authentication: Secure authentication via Microsoft Azure Active Directory
• Automatic Token Refresh: Seamless token refresh for uninterrupted operations
• Resource Locator: Dropdown selection for sites with searchable interface
• OData Filtering: Advanced filtering for file listings using OData expressions
• Pagination Support: Handle large result sets with configurable limits
• Base64 Encoding: Automatic base64 encoding/decoding for file content
• Rate Limiting: Built-in delays between batch operations to prevent throttling
• Timeout Configuration: Configurable timeouts for long-running operations (300-600 seconds)

Credential Configuration

Before using the Microsoft SharePoint integration in your workflows, you need to configure OAuth2 credentials through Microsoft Azure Active Directory.

Prerequisites

1. Azure Active Directory Account: You need an Azure AD account with appropriate permissions
2. Azure App Registration: You must register an application in Azure AD
3. API Permissions: The app must have the required Microsoft Graph API permissions

Creating an Azure AD App Registration

1. Sign in to Azure Portal: Navigate to Azure Portal

2. Navigate to Azure Active Directory: In the left sidebar, select Azure Active Directory

3. Go to App Registrations: Select App registrations → New registration

4. Configure the Application:

   • Name: Enter a descriptive name (e.g., "NINA SharePoint Integration")
   • Supported account types: Select "Accounts in this organizational directory only"
   • Redirect URI: Select "Web" and enter your NINA callback URL (provided by your admin)
   • Click Register

5. Note Important Values:

   • Application (client) ID: Copy this value (you'll need it as clientId)
   • Directory (tenant) ID: Copy this value from the Overview page (you'll need it as tenantId)

6. Create a Client Secret:

   • Navigate to Certificates & secrets → Client secrets → New client secret
   • Add a description (e.g., "NINA Integration Secret")
   • Select an expiration period
   • Click Add
   • IMPORTANT: Copy the secret Value immediately (it won't be shown again) - you'll need it as clientSecret

7. Configure API Permissions:

   • Navigate to API permissions → Add a permission
   • Select Microsoft Graph → Delegated permissions
   • Add the following permissions:
     • Sites.ReadWrite.All - Read and write items in all site collections
     • Files.ReadWrite.All - Have full access to user files
     • offline_access - Maintain access to data you have given it access to
   • Click Add permissions
   • Click Grant admin consent (requires admin privileges)

Authentication Method

The Microsoft SharePoint integration uses OAuth2 authentication:

Field	Description	Example
Client ID	Application (client) ID from Azure app registration	a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6
Client Secret	Client secret value from Azure app registration	abc123~DEF456_GHI789.JKL012
Tenant ID	Directory (tenant) ID from Azure AD	x9y8z7w6-v5u4-t3s2-r1q0-p9o8n7m6l5k4
Scope	OAuth2 scope permissions	Sites.ReadWrite.All Files.ReadWrite.All offline_access
Auth URL	Microsoft OAuth2 authorization endpoint	https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
Access Token URL	Microsoft OAuth2 token endpoint	https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token

Important Notes:

• Client secrets expire and must be renewed periodically in Azure AD
• The integration automatically handles token refresh using the refresh token
• Admin consent is required for organization-wide permissions
• Ensure the redirect URI in Azure AD matches your NINA instance callback URL
• The {tenantId} placeholder in URLs is automatically replaced with your actual tenant ID

Creating a Microsoft SharePoint Credential

1. Navigate to the Credentials section in NINA

2. Click Add New Credential

3. Fill in the credential details:

   • Name: A descriptive name (e.g., "SharePoint Production")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "Microsoft SharePoint"
   • Auth Type: "OAuth2" (only option available)
   • Client ID: Paste your Application (client) ID
   • Client Secret: Paste your client secret value
   • Tenant ID: Paste your Directory (tenant) ID
   • Scope: Use default or customize (Sites.ReadWrite.All Files.ReadWrite.All offline_access)
   • Auth URL: Use default or customize (with {tenantId} placeholder)
   • Access Token URL: Use default or customize (with {tenantId} placeholder)

4. Click Authorize to initiate OAuth2 flow

5. Sign in with your Microsoft account and grant permissions

6. Click Save to store the credential

Supported Resources and Operations

The Microsoft SharePoint integration supports the following resources and operations:

Site

Operation	Description
List	List all SharePoint sites accessible to the user
Search	Search for SharePoint sites by query
Get	Get detailed information about a specific site by ID or URL

Document

Operation	Description
Download	Download a single document from SharePoint (base64 encoded)
Bulk Download	Download multiple documents in a single batch (max 50 files)
Upload	Upload a single document to SharePoint (with chunked upload for large files)
Bulk Upload	Upload multiple documents in a single batch (max 50 files)
List	List files in a SharePoint folder with optional filtering
Search	Search for files in SharePoint by query
Delete	Delete a file from SharePoint
Get Metadata	Retrieve metadata for a specific file

Parameter Merging

The Microsoft SharePoint integration takes full advantage of NINA's parameter merging capabilities:

Parameter Sources (in order of precedence)

1. Node Parameters: Parameters configured directly in the SharePoint Integration Node
2. Extracted Parameters: Parameters automatically extracted from the input data
3. Input Data: The complete input data from upstream nodes

When a SharePoint Integration Node executes:

• It combines parameters from all sources
• Node parameters take precedence over extracted parameters
• The combined parameters are used to execute the SharePoint operation

Examples

Listing SharePoint Sites

Retrieve all SharePoint sites accessible to the user:

Node Configuration:

{
  "resource": "site",
  "operation": "list",
  "parameters": {
    "returnAll": false,
    "limit": 50,
    "timeout": 300
  }
}

This lists up to 50 SharePoint sites with a 5-minute timeout.

Searching for Sites

Search for specific SharePoint sites:

Node Configuration:

{
  "resource": "site",
  "operation": "search",
  "parameters": {
    "query": "marketing",
    "limit": 20
  }
}

This searches for sites matching "marketing" and returns up to 20 results.

Getting Site Details

Retrieve detailed information about a specific site:

Node Configuration:

{
  "resource": "site",
  "operation": "get",
  "parameters": {
    "siteId": "contoso.sharepoint.com,abc123,def456"
  }
}

You can also use a SharePoint site URL:

{
  "resource": "site",
  "operation": "get",
  "parameters": {
    "siteId": "https://contoso.sharepoint.com/sites/marketing"
  }
}

Uploading a Single File

Upload a file to SharePoint (automatically uses chunked upload for files > 4MB):

Node Configuration:

{
  "resource": "document",
  "operation": "upload",
  "parameters": {
    "siteId": {
      "mode": "list",
      "value": "contoso.sharepoint.com,abc123,def456"
    },
    "folderPath": "/Shared Documents/Reports",
    "fileName": "monthly-report.pdf",
    "fileContent": "JVBERi0xLjcKCjEgMCBvYmoKPDwvVHlwZS9DYX...",
    "timeout": 600
  }
}

Note: fileContent must be base64 encoded. The integration automatically decodes it before upload.

Bulk Uploading Files

Upload multiple files in a single operation:

Input Data from Previous Node:

{
  "documents": {
    "site": "contoso.sharepoint.com,abc123,def456",
    "folder": "/Shared Documents/Archive",
    "files": [
      {
        "fileName": "report-2024-01.pdf",
        "fileContent": "JVBERi0xLjcKCjEgMCBvYmo..."
      },
      {
        "fileName": "report-2024-02.pdf",
        "fileContent": "JVBERi0xLjcKCjIgMCBvYmo..."
      },
      {
        "fileName": "report-2024-03.pdf",
        "fileContent": "JVBERi0xLjcKCjMgMCBvYmo..."
      }
    ]
  }
}

Node Configuration:

{
  "resource": "document",
  "operation": "bulkUpload",
  "parameters": {
    "siteId": "{{documents.site}}",
    "folderPath": "{{documents.folder}}",
    "files": "{{documents.files}}",
    "timeout": 600
  }
}

This uploads all 3 files with built-in rate limiting (100ms delay between requests).

Downloading a Single File

Download a file from SharePoint:

Node Configuration:

{
  "resource": "document",
  "operation": "download",
  "parameters": {
    "siteId": "contoso.sharepoint.com,abc123,def456",
    "itemId": "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
    "timeout": 300
  }
}

Response:

{
  "id": "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
  "name": "monthly-report.pdf",
  "size": 2048576,
  "webUrl": "https://contoso.sharepoint.com/sites/marketing/Shared%20Documents/monthly-report.pdf",
  "content": "JVBERi0xLjcKCjEgMCBvYmoKPDwvVHlwZS9DYX...",
  "mimeType": "application/pdf",
  "downloadUrl": "https://..."
}

The content field contains the base64-encoded file data.

Bulk Downloading Files

Download multiple files in a single operation:

Node Configuration:

{
  "resource": "document",
  "operation": "bulkDownload",
  "parameters": {
    "siteId": "contoso.sharepoint.com,abc123,def456",
    "itemIds": [
      "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
      "01BCDEFGHIJKLMNOPQRSTUVWXYZ0987654321",
      "01CDEFGHIJKLMNOPQRSTUVWXYZ1122334455"
    ],
    "timeout": 600
  }
}

Response:

{
  "files": [
    {
      "id": "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
      "name": "report1.pdf",
      "size": 1024000,
      "content": "JVBERi0x...",
      "mimeType": "application/pdf"
    },
    {
      "id": "01BCDEFGHIJKLMNOPQRSTUVWXYZ0987654321",
      "name": "report2.pdf",
      "size": 2048000,
      "content": "JVBERi0y...",
      "mimeType": "application/pdf"
    }
  ],
  "errors": [
    {
      "itemId": "01CDEFGHIJKLMNOPQRSTUVWXYZ1122334455",
      "error": "File not found"
    }
  ],
  "total": 3,
  "success": 2,
  "failed": 1
}

Listing Files in a Folder

List all files in a specific SharePoint folder:

Node Configuration:

{
  "resource": "document",
  "operation": "list",
  "parameters": {
    "siteId": "contoso.sharepoint.com,abc123,def456",
    "folderPath": "/Shared Documents/Reports",
    "returnAll": false,
    "limit": 100
  }
}

Listing Files with OData Filter

Use OData filtering to list only specific files:

Node Configuration:

{
  "resource": "document",
  "operation": "list",
  "parameters": {
    "siteId": "contoso.sharepoint.com,abc123,def456",
    "folderPath": "/Shared Documents",
    "filter": "startswith(name,'report') and size gt 1000000",
    "limit": 50
  }
}

This lists files whose names start with "report" and are larger than 1MB.

Searching for Files

Search across a SharePoint site:

Node Configuration:

{
  "resource": "document",
  "operation": "search",
  "parameters": {
    "siteId": "contoso.sharepoint.com,abc123,def456",
    "query": "quarterly financial report",
    "limit": 25
  }
}

Getting File Metadata

Retrieve detailed metadata for a file:

Node Configuration:

{
  "resource": "document",
  "operation": "getMetadata",
  "parameters": {
    "siteId": "contoso.sharepoint.com,abc123,def456",
    "itemId": "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
  }
}

Response:

{
  "id": "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
  "name": "monthly-report.pdf",
  "size": 2048576,
  "createdDateTime": "2024-01-15T10:30:00Z",
  "lastModifiedDateTime": "2024-01-20T14:45:00Z",
  "webUrl": "https://contoso.sharepoint.com/...",
  "createdBy": {
    "user": {
      "displayName": "John Doe",
      "email": "[email protected]"
    }
  },
  "lastModifiedBy": {
    "user": {
      "displayName": "Jane Smith",
      "email": "[email protected]"
    }
  },
  "file": {
    "mimeType": "application/pdf",
    "hashes": {
      "quickXorHash": "abc123..."
    }
  }
}

Deleting a File

Remove a file from SharePoint:

Node Configuration:

{
  "resource": "document",
  "operation": "delete",
  "parameters": {
    "siteId": "contoso.sharepoint.com,abc123,def456",
    "itemId": "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
  }
}

Response:

{
  "success": true,
  "message": "File deleted successfully",
  "itemId": "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
}

Integration in Workflow Context

The Microsoft SharePoint integration is particularly effective for document management and collaboration workflows:

Common Workflow Patterns:

1. Document Archival:

   • Schedule Node → Email Node (fetch attachments) → Script Node (process) → SharePoint Node (bulkUpload) → Email Node (confirmation)

2. Automated Report Distribution:

   • Report Generation Node → Script Node (format) → SharePoint Node (upload) → SharePoint Node (list) → Teams Node (notify with link)

3. Document Backup:

   • SharePoint Node (list) → SharePoint Node (bulkDownload) → S3 Node (backup) → Database Node (log) → Slack Node (notify)

4. Compliance Scanning:

   • SharePoint Node (search) → SharePoint Node (download) → Virus Scan Node → DLP Node → SharePoint Node (delete if needed) → SIEM Node (log)

5. Collaborative Workflow:

   • Form Submission Node → SharePoint Node (upload) → SharePoint Node (getMetadata) → Approval Node → Email Node (notify reviewers)

6. Document Synchronization:

   • SharePoint Site A Node (list) → SharePoint Site A Node (download) → SharePoint Site B Node (upload) → Database Node (sync log)

Advanced Features

Resource Locator with Site Dropdown

The integration provides a searchable dropdown for site selection:

{
  "siteId": {
    "mode": "list",
    "value": "selected-site-id-from-dropdown"
  }
}

Alternatively, you can provide the site ID directly:

{
  "siteId": {
    "mode": "id",
    "value": "contoso.sharepoint.com,abc123,def456"
  }
}

Large File Handling

The integration automatically uses chunked upload for files larger than 4MB:

• Small files (< 4MB): Simple PUT request
• Large files (4MB - 250MB): Upload session with 10MB chunks
• Maximum file size: 250MB (Microsoft Graph API limit)

Automatic Token Refresh

The integration handles OAuth2 token refresh automatically:

1. Detects 401 Unauthorized responses
2. Uses refresh token to obtain new access token
3. Retries the original request with new token
4. Transparent to the workflow execution

Timeout Configuration

Different operations support configurable timeouts:

• Site operations: Default 300 seconds (5 minutes)
• Document download: Default 300 seconds (5 minutes)
• Document upload: Default 600 seconds (10 minutes)
• Bulk operations: Default 600 seconds (10 minutes)

Rate Limiting

Bulk operations include built-in rate limiting:

• 100ms delay between individual operations in bulk upload/download
• Prevents Microsoft Graph API throttling
• Maximum batch size: 50 files per operation

OData Filtering

The list operation supports OData filter expressions:

Common filter expressions:
- startswith(name,'prefix')
- endswith(name,'.pdf')
- size gt 1000000 (size greater than 1MB)
- size lt 5000000 (size less than 5MB)
- folder ne null (folders only)
- file ne null (files only)
- createdDateTime ge 2024-01-01T00:00:00Z

Best Practices

1. Use Site IDs Consistently: Once you have a site ID, store it for reuse rather than searching repeatedly.

2. Batch Operations: Use bulkUpload and bulkDownload operations when working with multiple files to reduce API calls.

3. Respect Batch Limits: Stay within the 50-file limit for bulk operations to avoid timeouts and resource exhaustion.

4. Monitor File Sizes: Be aware of the 250MB file size limit and 4MB chunked upload threshold.

5. Use Appropriate Timeouts: Increase timeout values for large file operations or bulk operations with many files.

6. Leverage OData Filters: Use OData filtering in list operations to reduce result sets and improve performance.

7. Handle Errors Gracefully: Bulk operations return partial results with errors array - process both successes and failures.

8. Base64 Encoding: Ensure file content is properly base64 encoded before passing to upload operations.

9. Clean Up Regularly: Use the delete operation to remove obsolete files and maintain organization.

10. Use Metadata Operations: Call getMetadata instead of download when you only need file information, not content.

11. Normalize Folder Paths: The integration handles path normalization, but consistent formatting improves readability.

12. Store Item IDs: After upload, store returned item IDs for future operations (download, delete, getMetadata).

Site ID Formats

SharePoint site IDs come in two formats:

Format 1: Composite ID

hostname,siteId,webId
Example: contoso.sharepoint.com,abc123-def456,ghi789-jkl012

Format 2: URL

https://hostname/sites/sitename
Example: https://contoso.sharepoint.com/sites/marketing

The integration automatically converts URLs to the proper API format.

Response Structure

Site List Response

{
  "value": [
    {
      "id": "contoso.sharepoint.com,abc123,def456",
      "displayName": "Marketing Site",
      "name": "marketing",
      "webUrl": "https://contoso.sharepoint.com/sites/marketing",
      "createdDateTime": "2024-01-01T00:00:00Z"
    }
  ],
  "@odata.nextLink": "..."
}

File List Response

{
  "value": [
    {
      "id": "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
      "name": "document.pdf",
      "size": 2048576,
      "createdDateTime": "2024-01-15T10:30:00Z",
      "lastModifiedDateTime": "2024-01-20T14:45:00Z",
      "webUrl": "https://...",
      "file": {
        "mimeType": "application/pdf"
      }
    }
  ],
  "@odata.nextLink": "..."
}

Bulk Operation Response

{
  "files": [
    {
      "id": "...",
      "name": "...",
      "size": 1024000
    }
  ],
  "errors": [
    {
      "fileName": "failed.pdf",
      "error": "Upload failed: File too large"
    }
  ],
  "total": 5,
  "success": 4,
  "failed": 1
}

Troubleshooting

Common Issues and Solutions

Issue	Possible Solution
OAuth2 authorization fails	Verify client ID, client secret, and tenant ID are correct; check Azure AD app registration
Access denied errors	Ensure API permissions (Sites.ReadWrite.All, Files.ReadWrite.All) are granted with admin consent
Token expired	The integration auto-refreshes tokens; if issues persist, re-authorize the credential
Site not found	Verify site ID format is correct; try using the site URL instead
File upload fails	Check file size (max 250MB); ensure content is base64 encoded; verify folder path exists
Batch operation timeout	Reduce batch size or increase timeout parameter; check network connectivity
Rate limiting (429 errors)	Built-in delays should prevent this; if it occurs, increase delays between workflow runs
Large file upload fails	Files > 250MB are not supported; split or compress the file
Search returns no results	Verify query syntax; check if search indexing is complete for recently uploaded files
Invalid folder path	Ensure folder path uses forward slashes; path is case-sensitive
Download content not valid base64	Content is pre-encoded; don't double-encode when using downstream

Error Response Format

Microsoft Graph API returns standardized error responses:

{
  "error": {
    "code": "itemNotFound",
    "message": "The resource could not be found.",
    "innerError": {
      "request-id": "abc123-def456-ghi789",
      "date": "2024-01-20T14:45:00"
    }
  }
}

Common Error Codes

Status Code	Description
400	Bad Request - Invalid parameters or request format
401	Unauthorized - Invalid or expired access token
403	Forbidden - Insufficient permissions
404	Not Found - Site, folder, or file does not exist
409	Conflict - Resource already exists or version conflict
413	Payload Too Large - File exceeds size limits
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Microsoft service error
503	Service Unavailable - Microsoft service temporarily unavailable

Security Considerations

1. Client Secret Protection: Store client secrets securely; rotate regularly; never commit to version control.

2. Principle of Least Privilege: Only request necessary API permissions; avoid using admin-level permissions unnecessarily.

3. Token Security: Access and refresh tokens are stored encrypted in NINA's credential system.

4. Audit Logging: Enable Azure AD audit logging to track all SharePoint access via the integration.

5. Conditional Access: Configure Azure AD Conditional Access policies for additional security controls.

6. File Content Security: Be cautious when downloading files from external sources; implement virus scanning.

7. Data Classification: Respect data classification labels when uploading sensitive documents.

8. Shared Links: Avoid creating public shared links for sensitive documents through the API.

9. Retention Policies: Ensure uploaded documents comply with organizational retention policies.

10. Network Security: Use HTTPS for all communications (enforced by Microsoft Graph API).

File Size Limits

• Small file upload (simple upload): < 4MB
• Large file upload (chunked upload): 4MB - 250MB
• Maximum file size: 250MB (Microsoft Graph API limit)
• Chunk size (large uploads): 10MB per chunk
• Bulk operation limit: 50 files per batch

API Permissions Required

The integration requires the following Microsoft Graph API delegated permissions:

Permission	Description	Required For
Sites.ReadWrite.All	Read and write items in all site collections	All site and document operations
Files.ReadWrite.All	Have full access to user files	All document operations
offline_access	Maintain access to data	Token refresh functionality

Additional Resources

• Microsoft Graph API Documentation
• SharePoint REST API Reference
• Azure AD App Registration Guide
• Microsoft Graph Permissions Reference
• OData Query Parameters
• Upload Large Files to SharePoint
• Microsoft Graph Best Practices
• Troubleshooting Microsoft Graph