Installing and configuring Workflow Builder

Prerequisites

Before installing Workflow Builder, verify that the following requirements are met:

• BigFix Platform: a basic Platform setup is required; a baseline BigFix environment must be in place.
• BigFix UI: the BigFix UI must be installed and running. For details, see System Requirements and BigFix UI installation. The BigFix UI database requires Microsoft SQL Server 2025 (version 17.0). With an earlier version, the BigFix UI setup stops at the database step: the DSN connection test fails with Unsupported SQL Server version: SQL Server version <version> is not supported, minimum required version is SQL Server 2025 (17.0).
• Administrator access: a BigFix UI administrator account, to assign the application to roles in Administration (see Managing Roles), and command-line access to the BigFix UI server, to activate the application.
• Network connectivity: network connectivity between the BigFix UI and the host where the BigFix Workflow Service is deployed.
• Database access: a SQL Server login with administrative access to the BFEnterprise database, to run the one-time permission setup script (mssql-init.sql) that provisions the wrkflw schema, roles, and the application database user.

Installation roadmap

The installation consists of six stages, performed in order. Each stage is a section of this topic.

Stage 1: Get the BigFix content

1. In the BigFix Console, refresh the license from the License Overview dashboard.
2. Enable the Workflow Builder content site and gather it.
3. Subscribe computers to the site: at a minimum, the computer on which you plan to deploy the BigFix Workflow Service. To prepare for future use, you can subscribe all computers.
4. Grant site permissions to the operators who will install and configure Workflow Builder.

Site activation follows the standard BigFix procedure that applies to every BigFix site; for details, see Sites. After the site is gathered, its Fixlets and analyses appear under the Workflow Builder site.

Stage 2: Prepare the database login

The BigFix Workflow Service connects to SQL Server with a dedicated, least-privilege application login. The permission model is narrowed to the wrkflw schema: the runtime login (wrkflwDbUser) holds only the permissions the BigFix Workflow Service uses at runtime, scoped to SCHEMA::wrkflw or to objects inside it — no database-wide grants (no db_owner, db_datareader, db_datawriter, or db_ddladmin). Database operations are segregated into two roles in the schema: wrkflw_DDLRole (schema changes, needed only during installation and versioned upgrades) and wrkflw_DMLRole (runtime data access, held at all times). The BigFix Workflow Service's start and restart only verify the database; schema migrations run only during install or upgrade, after which you revoke DDL immediately.

These administration scripts are not run automatically; they simplify creating the least-privilege login and are intended for the BigFix SQL Server database administrator. The mssql-init.sql script is included in the installation package that the install Fixlet delivers.

1. Open mssql-init.sql in SQL Server Management Studio (SSMS), set the context to BFEnterprise, and execute the script in full. It provisions the wrkflw schema, the wrkflw_DDLRole and wrkflw_DMLRole roles, and the stored procedures sp_CreateWrkflwRestrictedUser, sp_SetWrkflwRestrictedUserDDLAccess, sp_TightenWrkflwRuntimeGrants, sp_DropWrkflwRestrictedUser, and supporting helpers.
2. Create the application login and user, and assign the initial DDL + DML roles. DDL is mandatory during the first start so that the migration can create the wrkflw.workflows and wrkflw.workflow_versions tables. Replace <YourStrongPassword> with your own password before executing:

   USE [BFEnterprise];
   GO
   -- Create application login/user and assign initial DDL + DML privileges
   EXEC dbo.sp_CreateWrkflwRestrictedUser
       @UserName = 'wrkflwDbUser',
       @Password = '<YourStrongPassword>',
       @AssignDDL = 1,
       @AssignDML = 1;
   GO

3. Create the zero-privilege stub user in the master database:

   -- Provision a zero-privilege stub user in master to satisfy the service's initial driver check.
   -- This user must remain permissionless: no server roles, no CREATE ANY DATABASE, no VIEW ANY DATABASE.
   USE [master];
   GO
   IF NOT EXISTS (SELECT 1 FROM sys.database_principals WHERE name = 'wrkflwDbUser')
       CREATE USER [wrkflwDbUser] FOR LOGIN [wrkflwDbUser];
   GO
   DENY VIEW ANY DATABASE TO [wrkflwDbUser];
   DENY CREATE ANY DATABASE TO [wrkflwDbUser];
   GO

Stage 3: Deploy the BigFix Workflow Service

Deploy the BigFix Workflow Service to the selected target device by using the install Fixlet from the Workflow Builder site, named Install BigFix WorkFlow Builder Acceptor <version> (WIN). The database user from stage 2 must exist before you deploy. After the deployment and activation, complete the permission hardening in Stage 5: Harden the database login. For the manual command-line procedure, see Manual installation.

Stage 4: Activate the application in the BigFix UI

You activate Workflow Builder from the command line of the BigFix UI server by running BFUI.exe --configure-wfb. The command also sets up the mutual TLS (mTLS) connection between the BigFix UI and the BigFix Workflow Service.

Configure the mTLS connection between the BigFix UI and the BigFix Workflow Service:

1. On the BigFix Workflow Service host, get the basic authentication bootstrap credentials from workflow-data\configs\mtls-bootstrap.txt in the installation directory.
2. On the BigFix UI host, open Windows PowerShell and navigate to <BigFix UI installation location>\cmd\bfui.
3. Run BFUI.exe --configure-wfb.
4. When prompted, enter the configuration values listed in the following table.
5. After the configuration completes successfully, restart the BigFix UI service if it is already running. For details, see Starting BigFix UI in the BigFix UI documentation.

Stage 5: Harden the database login

Perform this stage after the BigFix Workflow Service has been deployed (stage 3) and activated (stage 4), so that the first start has already created the tables.

After the BigFix Workflow Service has started once, confirm that the migration completed: the log shows DB verify connection ok, running migration, AutoMigrate completed: workflows, workflow_versions, and startup ready. Then lock the login down to its steady-state runtime rights:

1. Validate that the tables exist:

   USE [BFEnterprise];
   SELECT TABLE_SCHEMA, TABLE_NAME
   FROM INFORMATION_SCHEMA.TABLES
   WHERE TABLE_SCHEMA = 'wrkflw'
   ORDER BY TABLE_NAME;
   -- Expected output: workflows, workflow_versions

2. Revoke DDL. After this step the runtime login must never hold wrkflw_DDLRole again unless a versioned upgrade is in progress:

   USE [BFEnterprise];
   GO
   -- Revoke DDL access from runtime user
   EXEC dbo.sp_SetWrkflwRestrictedUserDDLAccess
       @UserName = 'wrkflwDbUser',
       @Enable = 0;
   GO

3. Verify that wrkflwDbUser is bound exclusively to wrkflw_DMLRole:

   SELECT r.name AS role_name
   FROM sys.database_role_members drm
   JOIN sys.database_principals r ON r.principal_id = drm.role_principal_id
   JOIN sys.database_principals u ON u.principal_id = drm.member_principal_id
   WHERE u.name = 'wrkflwDbUser';
   -- Expected result: wrkflw_DMLRole (wrkflw_DDLRole must NOT be listed)

4. Tighten the grants to object level. The procedure verifies that both tables exist, revokes SELECT/INSERT/UPDATE/DELETE on SCHEMA::wrkflw from wrkflw_DMLRole, and re-grants those verbs on OBJECT::wrkflw.workflows and OBJECT::wrkflw.workflow_versions only, so any table accidentally added to the schema later is not reachable by the application. VIEW DEFINITION on the schema is left intact for the startup verification:

   USE [BFEnterprise];
   GO
   EXEC dbo.sp_TightenWrkflwRuntimeGrants;
   GO

5. Verify the resulting grants:

   SELECT pr.name AS principal_name,
          p.class_desc,
          p.permission_name,
          p.state_desc,
          OBJECT_SCHEMA_NAME(p.major_id) + '.' + OBJECT_NAME(p.major_id) AS object_name
   FROM sys.database_permissions p
   JOIN sys.database_principals pr ON pr.principal_id = p.grantee_principal_id
   WHERE pr.name = 'wrkflw_DMLRole'
   ORDER BY p.class_desc, object_name, p.permission_name;
   -- Expected: OBJECT_OR_COLUMN grants on wrkflw.workflows and wrkflw.workflow_versions,
   --           plus SCHEMA grant of VIEW DEFINITION on wrkflw. No schema-level SELECT/INSERT/UPDATE/DELETE.

6. Restart the BigFix Workflow Service (sc stop BigFixWorkFlow, then sc start BigFixWorkFlow) and confirm in wrkflw_svc.log that the startup verification succeeds.

Stage 6: Grant user access

Workflow Builder is available to both Master Operators and Non-Master Operators — the BigFix operator types — provided that the Workflow Builder application is assigned to them. The platform permissions of each operator then determine which features are available.