﻿********************************************
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)
    - SharePoint farm administrator access, once, for step 11 (configure_sharepoint.ps1)    

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 farm configuration (REQUIRED - run once per farm)
    Run configure_sharepoint.ps1 on the SharePoint web front-end server where skybow
    Background Automation is installed - elevated, as a farm administrator, in Windows
    PowerShell 5.1 (PowerShell 7 cannot load the SharePoint snap-in). SharePoint must be
    served over HTTPS.

        .\configure_sharepoint.ps1

    No arguments are needed: it reads the site collection from the farm, and the skybow
    service identity and configuration file locations from the skybow installation on this
    machine.

    From the August 2026 update for SharePoint Subscription Edition, SharePoint refuses to
    register event receivers for a caller that has no application identity, whatever
    permissions that caller holds. Without this step, newly created triggered actions and
    calculations fail with "Access denied".

    The script lists what it will change and asks for confirmation first, then creates that
    identity for the whole farm, updates the skybow configuration files and restarts skybow.
    Afterwards, run "iisreset" on the farm's other SharePoint servers - the script lists them
    by name. It covers every site collection on the farm, including ones created later, so
    there is nothing to repeat when you add one.

    RENEWING THE CERTIFICATE
    The certificate the script creates is valid for five years, and the script prints its
    expiry date when it finishes. Before that date, run the script again on the same server,
    then "iisreset" on every SharePoint server: within 90 days of expiry it replaces the
    certificate and keeps the same application id. Running it earlier changes nothing. Add
    -RenewCertificate to replace the certificate sooner.

    NOTE: the identity is granted Full Control over all content on the farm, and can act
    without a signed-in user. That is what skybow needs to register event receivers on the
    lists your automations use, and it is the configuration this release was tested with.
    Passing -Right Manage narrows it, but whether SharePoint accepts an event receiver
    registration under Manage has not been established - so treat that as untested rather
    than as the safer choice.

    NOTE: it also allows SharePoint to call intranet addresses, which SharePoint list
    webhooks require. That relaxes a farm-wide protection against server-side request
    forgery: it applies to the whole farm, cannot be limited to skybow, and has no
    allow-list. The script prints how to restore it.

12. 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
********************************************