********************************************
skybow Background Automation Service
skybow 2026
********************************************

This document describes how to deploy skybow Background Automation to your SharePoint environment.

skybow Background Automation consists of: 
    - IIS Site: skybow Background Automation
    - Windows services:
        - skybow Scheduled Actions Job
        - skybow Queue Message Job
        - skybow Actions Job
        - skybow CleanUp Job
        - skybow HTTP Trigger Job
    - SharePoint SPFx Addin

Prerequsites
    - IIS (Internet Information Services)  
    - SQL Server instance
    - MSMQ (Message Queuing)
    - .NET Framework 4.8
    - PowerShell 5.0 or 5.1(Recommended)
    - User account for service identity:
        - This account will be prompted during the PowerShell deployment script (install_ba.ps1) and will be used as:
              - Application Pool identity for the IIS site
              - Log On account for all skybow Windows services
        -  Must have access to target SharePoint sites 
           (be site collection administrator or be in the owners SharePoint group for the target sites)
        - Access to SQL Server is required only if DefaultConnection does not specify a custom SQL user in the connection string.
        - Must have permissions in Microsoft Message Queuing (MSMQ) for the private queues (Send, Receive and Peek permissions)    

Supported SharePoint Versions:
    - SharePoint Server 2019
    - SharePoint Subscription Edition (SE)

Installation Locations
    - IIS site: C:\inetpub\wwwroot\skybowBackgroundAutomation
    - Windows services: C:\skybowBackgroundAutomation\Services

Installation Instructions:

1. Run the PowerShell deployment script (install_ba.ps1)
    Launch Windows PowerShell 5.x "Run as Administrator" (NOT PowerShell Core).  
    Navigate to the installation folder containing install_ba.ps1 and run install_ba.ps1 script:
    > cd "path to folder that contains install_ba.ps1"
    > .\install_ba.ps1

2. Follow on-screen prompts to complete the deployment.

3. Provide user credentials
    During the first installation, you will be prompted to provide credentials. This account will be used as:
        - Application Pool identity for the IIS site
        - Log On account for all five Windows services

4. Configure URLs for IIS site.
    Open IIS Manager -> Sites -> skybow Background Automation
    In the Actions panel, click "Bindings..." and add/edit site bindings.
    - HTTP (optional):
        - Type: http
        - IP address: All Unassigned (or specific IP)
        - Port: 9802
        - Host name: (optional)
    - HTTPS (strongly recommended):
        - Type: https
        - IP address: All Unassigned (or specific IP)
        - Port: 443
        - Host name: (optional, e.g., your public domain)
        - SSL certificate: Select a valid certificate trusted by SharePoint servers and clients
    - Click OK to save bindings.
    NOTE: SharePoint web front-end (WFE) servers must be able to reach the HTTPS URL.

5. Update the IIS web.config file:
    Open C:\inetpub\wwwroot\skybowBackgroundAutomation\web.config and set the following keys: 
        - DefaultConnection - Connection string to SQL database.
            Example with Windows Authentication:
                "Data Source=ServerName\InstanceName;Initial Catalog=skybow.BackgroundAutomation;Integrated Security=True"
            Example with SQL Authentication:
                "Data Source=ServerName\InstanceName;Initial Catalog=skybow.BackgroundAutomation;User ID=sqluser;Password=sqlpassword"
            NOTE: If no SQL credentials are specified and Integrated Security=True is used, the IIS application pool identity (for web.config) 
                 or the Windows service Log On account (for *.exe.config) will be used to connect to SQL.
        - WebHookEndPoint / ReceiverEndPoint - Public URLs for SharePoint to communicate with the IIS site.
            These URLs must be accessible from SharePoint WFE servers and must start with the public base URL of your IIS site.
            Example: 
              <add key="WebHookEndPoint" value="https://your-ba-service-url/api/webhooks/subscribe" />
              <add key="ReceiverEndPoint" value="https://your-ba-service-url/Services/RemoteEventReciever.svc" />
        - HttpTriggerEndPoint - Public URL format to call Triggered Actions with HTTP request trigger type
            These URLs must be accessible from SharePoint WFE servers and must start with the public base URL of your IIS site.
            Example:
            <add key="HttpTriggerEndPoint" value="https://your-ba-service-url/api/trigger/{referenceId}/invoke?code={apiKey}" />

6. Start the IIS site
    On first load, the system will connect to the SQL Server and automatically create the "skybow.BackgroundAutomation" database.

7. Update skybow.***.exe.config files for all skybow Windows services
    Navigate to "C:\skybowBackgroundAutomation\Services\".
    Update the *.exe.config files for ALL FIVE skybow services.
    Match the DefaultConnection and EndPoint values used in Step 5.

8. Optional: Configure Email Notifications (SMTP)
    skybow Background Automation can send automatic email notifications 
    if background calculations or actions are disabled due to continuous execution errors.
    To enable notifications, configure the following settings in:
        - IIS web.config file:
            C:\inetpub\wwwroot\skybowBackgroundAutomation\web.config
        - ALL FIVE Windows service *.exe.config files:
            C:\skybowBackgroundAutomation\Services\
    Configuration details:
        - SmtpServerHost - SMTP server hostname.
        - SmtpServerPort - SMTP server port (587 recommended for TLS).
        - SmtpServerUserName / SmtpServerPassword - SMTP authentication credentials.
        - SmtpFromAddress - Sender email address used for notifications.
        - SmtpFromDisplayName - Display name shown in outgoing emails.
        - MaintainerEmail -  Email address that receives notifications if a background calculation 
          or triggered/scheduled action is disabled due to repeated errors
    NOTE: This configuration is optional. If not configured, background processing will continue normally, but no email notifications will be sent.
    
9. Restart all skybow Windows services
    - Press Win + R → type: services.msc
    - Locate and restart each of the following:
        - skybow Scheduled Actions Job  
        - skybow Queue Message Job  
        - skybow Actions Job  
        - skybow CleanUp Job
        - skybow HTTP Trigger Job

10. Verify message queues (MSMQ)
    During the first start, the skybow services automatically create the required private queues in Microsoft Message Queuing.
    Verify private queues in Computer Management -> Services and Applications -> Message Queuing -> Private Queues.
    If not created automatically, manually create:
        - skybowssnotificationsqueue
        - skybowssscheduledactionsqueue
    Ensure the skybow service account has "Send", "Receive", and "Peek" permissions.

11. SharePoint Integration (SPFx Add-in)
   The final step is to deploy the skybow Background Services SharePoint Framework (SPFx) add-in.
   1) Locate the Addin folder and deploy the app using one of the following options:
        - skybow CDN (recommended)
            Select the appropriate package:
              - skybow-background-services-SE.sppkg (for SharePoint Subscription Edition)
              - skybow-background-services-2019.sppkg (for SharePoint Server 2019)
            Upload and deploy the selected .sppkg file to the SharePoint App Catalog.
        - Local SharePoint Version
            Use this option if external CDN access is restricted or offline deployment is required.
              - Follow the instructions in Addin/Local SharePoint Version/readme.txt
              - After completing those steps, upload and deploy the corresponding .sppkg file to the SharePoint App Catalog.
   2) Add the app to the target SharePoint site.
   3) Open any list or document library on that site and click "skybow Background Services" in the command bar. 
   4) Configure the Service URL: 
      If the background service URL has not been set for the site collection, the Configure Background Automation Service URL dialog will open automatically.
   5) In the dialog:
      - Enter the public URL of the skybow Background Automation IIS site
      - Click the Check button
      - Once the "Success" message appears, click Apply to save the configuration.
   NOTE: Configure Background Automation Service URL only needs to be performed once per site collection.

NOTE: During future deployments, the configs will automatically back up and merge your current web.config and service *.exe.config files to preserve your configuration changes.

********************************************
skybow 2026 - All Rights Reserved
********************************************