Purpose of Onboarding connectors to SGC Central
SGC Central is a modern, unified management console designed to streamline the full lifecycle of Service Graph Connectors, from installation and configuration to operation and debugging with minimal effort. It is accessed through the SGC Central tab within the CMDB Workspace.
Onboarding a Service Graph Connector to SGC Central enables comprehensive lifecycle management of connection within the Workspace. This centralization provides a consistent experience across all connectors for configuration, monitoring, and troubleshooting. Once onboarded, connectors benefit from guided setups using playbooks, enhanced visibility into processing and connection health, and easier access to diagnostic tools and ETL management.
Pre-requisites
Before onboarding a connector to SGC Central, ensure the following requirements are met:
Common Connection Framework (CCF) Compliance
The connector must be implemented using the Common Connection Framework (CCF). CCF is a standardized model for managing Service Graph connections, offering a centralized structure for storing connection details, properties, data sources, and scheduled imports. It improves the visibility, consistency, and manageability of connections between ServiceNow and external data sources. Connectors must leverage CCF’s core tables and patterns to ensure compatibility with SGC Central.
Plugin dependencies
The following plugins must be installed and active in the development instance:
- CMDB Workspace (com.snc.cmdb.workspace)
- Integration Commons for CMDB (com.snc.cmdb.integration_util)
- IntegrationHub ETL (com.sn_int_studio)
- Playbook Experience (com.playbook_experience)
- Playbook Experience Components (com.servicenow_now_playbook_experience)
User Role
A user with the admin role is required to onboard a connector to SGC Central.
Implementation steps
Create process definition
SGC Central utilizes a playbook experience to streamline the onboarding connection of Service Graph Connectors, providing common screens and functionality for reuse. A key component is a SGC Central's process definition record, which serves as a template for new connectors. Connector teams duplicate this existing template to reuse pre-configured steps and functionality while customizing it for their specific onboarding requirements. This standard playbook template includes "Prerequisites" and "Setup" stages.
Duplicate the Process Definition Template
- Navigate to the navigation menu and open Process Automation Designer.
- Under the SGC Central application, select the existing process named SGC Create Connection Template. The playbook builder will load, displaying the default stages.
- Click the More actions menu (⋮), then select Duplicate to create a new process definition.
Note: duplicate the template within connector scope. - Enter new process definition details:
- Label: Enter the name of the new process definition.
- Application: Select the connector application being onboarded.
- Trigger type: Set to Record Create.
- Table: Set to Service Graph Connection Trigger.
- Click Duplicate.
Note: Once duplicated, you are ready to configure the new process. - Click Properties from the More actions menu.
- In the Additional Properties popup, open the Schedule tab.
- Define the trigger condition:
Condition: Trigger record → Service Graph Connector Metadata → Application = [Connector Application Name]
Configure Stages and Activities
The default template provides two stages: Prerequisites and Setup.
- Prerequisites Stage: Used for tasks preparing the instance or external environment, such as table access setup or permission updates.
- Setup Stage: Covers tasks related to configuring the connector connection and data import settings, including configuring and testing connections, setting configuration properties, configuring import schedules, and confirming connection setup.
You can add more stages by clicking Add Stage and specifying the Label, Order, and Condition (if any). For more information on Playbook, refer to Getting Started with Playbooks - Workflow Automation CoE.
Configure Key Activities
It is important to provide the activity properties, as the UI and functionality depend on these inputs. Each activity type expects different inputs; refer to the activity definition documentation for details.
- Click Configure Activity of the activity to open the side pane, which contains:
- Details: Label, Description, Activity Definition, Order, and Condition.
- Automation: Input parameters for the sub-flow or action.
- UI Layout: Playbook card UI inputs, including dynamic fields.
Tip: Use "Show additional options" to reveal hidden properties.
- Update Data Source Access
Used to grant table-level access for connectors, especially those needed for multi-instance support (e.g., sys_data_source, scheduled_import_set).
Activity Type: SGC update data source access AD
Steps to Configure:- Click Configure Activity to open the configuration pane.
- In the Details section, confirm or update the label, description, and order.
- Verify that the Activity Type is set to 'SGC update data source access AD'.
- Open the UI Layout section:
- Set the table property to specify the required table.
- Set UseTableFromPlaybook to true to use the table value dynamically.
- Enable showDescriptionFromPlaybook to display the activity description on the playbook card.
- Click Save and Close to save your configuration.
- Clear Cache
Prompts users to run a background script that clears table permission caches after modifying permissions.
Activity Type: SGC clear cache AD
Steps to Configure:- Click Configure Activity to open the configuration pane.
- In the Details section, confirm or update the label and order if necessary.
- Verify that the Activity Type is set to 'SGC clear cache AD'.
- Open the UI Layout section:
- Enable showDescriptionFromPlaybook to display the description.
- Click Save and Close to apply the changes.
- Configure and Test Connection
Enables creation and testing of a new connection using a system alias. Supports credential (e.g., OAuth, Token) and configuration parameters (e.g., Base URL, Tenant ID).
Activity Type: SGC Create new connection AD
Steps to Configure:- Click Configure Activity to open the configuration pane.
- In the Details section:
- Set the Title and Description for the connection activity.
- Verify that the Activity Type is set to 'SGC Create new connection AD'.
- In the Automation section:
- Configure the Trigger Records.
- Set the ParentSysAlias to the appropriate system alias for configuration template.
- Open the UI Layout section and make any optional UI adjustments as needed.
- Click Save and Close to complete the configuration.
Note: This activity outputs the SGC Connection record and the Sys Alias ID for use in subsequent steps.
- Set Configuration Properties
Displays editable connection properties (e.g., region filters, API versions, delta pulls) from the sn_sgc_central_conn_prop_config table.
Activity Type: SGC Configure connection property AD
Steps to Configure:- Click Configure Activity to open the configuration pane.
- In the Details section, update the title and description if needed.
- Verify that the Activity Type is 'SGC Configure connection property AD'.
- In the UI Layout section:
- Provide the Connection instance ID from the output of the Configure and Test Connection activity.
- Click Save and Close to finalize.
- Configure Import Schedule
Displays import schedules related to the connection, ensuring that one is active before continuing.
Activity Type: SGC Configure import schedule AD
Steps to Configure:- Click Configure Activity to open the configuration pane.
- In the Details section, validate or customize the label and description.
- Verify the Activity Type is 'SGC Configure import schedule AD'.
- In the UI Layout section:
- Provide the Connection instance ID to filter the associated import schedules.
- Click Save and Close to apply.
- Confirm Connection Setup
Finalizes the process by confirming successful setup and providing a link to the connection record.
Activity Type: SGC complete setup AD
Steps to Configure:- Click Configure Activity to open the configuration pane.
- In the Details section, ensure the label and description reflect the confirmation purpose.
- Verify the Activity Type is 'SGC complete setup AD'.
- Click Save and Close to complete the setup.
Finalize Configuration and Publish
- Ensure all activity properties are properly configured, then Save and Close each activity’s configuration pane.
- For specific onboarding needs, use Add Activity to insert new activities within stages. You can search and reuse shipped activity definitions or create custom ones for unique use cases.
- Once configuration is complete, click the Activate button to publish the new process definition so it runs when triggered.
Create Service Graph Connector Metadata
Creating connector metadata is a foundational step in establishing a Service Graph Connector within SGC Central. This metadata acts as the configuration blueprint, enabling SGC Central to identify, manage, and interact with your connector. It includes the connector's application scope, multi-instance support, a reference to the playbook process definition, and CCF compliance status. When a user initiates a new connection, SGC Central uses this metadata to present available connectors and guide the user through the appropriate setup.
- Type sn_cmdb_int_util_service_graph_connector_metadata.list into the navigation filter and press Enter.
- Review the list to ensure a metadata record for your connector does not already exist.
- If no existing record is found:
- Switch to the connector’s application scope.
- Click New to create a new record.
- If a record already exists for the connector:
- You may update it as needed.
- If no existing record is found:
- Fill in the fields (for new records or updates):
- Name: Name of the connector.
- Logo: Upload the connector’s logo image.
- Application: The application scope of the connector.
- Multi-instance Support: Boolean field indicating if the connector supports multi-instance connections.
- CCF Support: Boolean field indicating if the connector is CCF (Common Connection Framework) compliant.
Define Connection Property Configuration
Configuring connection properties is an important part of setting up a Service Graph Connector connection within SGC Central. These properties control various aspects, such as authentication details, data retrieval scope (e.g., AWS Regions, Kong Workspaces), or specific connector features. SGC Central uses the Connection property config table to store details about these fields, including group ordering, descriptions, mandatory fields, and default values, which determine how properties are displayed and configured.
- Type sn_sgc_central_conn_prop_config.list into the navigation filter and press Enter.
- Make sure you are in the connector’s application scope.
- For each connection property required by your connector, click New and fill in the following fields:
- Name: Internal name used for storing the property.
- Type: Set to 'Connection property'.
- Display Name: The label to be shown on the Connection Properties UI.
- Data Type: Type of the property value (e.g., string, integer, password). Refer to product documentation for supported types.
- Max Length: Maximum character length for the value.
- Default Value: Optional default value for the property.
- Description: Help text shown as a tooltip in the UI.
- Application: Connector’s application scope.
- Active: If selected, the property will be visible.
- Mandatory: Indicates whether the property value must be provided.
- Group: Name of the group to which the property belongs (e.g., "Configuration properties").
- Group Order: Order of the group. Determines precedence if multiple groups exist.
- Order: Display order of the property within its group.
Configure Record Tabs for Connection Details Page
When managing installed connections in SGC Central, users can view additional tabs beyond the default ones (like Details, Data Sources, Scheduled Imports, and Errors) depending on the connector. These custom tabs provide further connector-specific details. The inclusion and arrangement of these tabs are managed through the Connection Record Tabs (sn_sgc_central_connection_record_tabs) table. To display connector-specific configuration or monitoring information directly on the connection details page, you need to configure relevant entries in this table for your connector.
Create a UIB Subpage
- From the All menu, navigate to Now Experience Framework > UI Builder.
- From the list of experiences, select SGC Central.
- Search for and open the page named SGC Edit Connection Default. This will open the Edit Connection page in UI Builder Editor.
- In the Page Content panel (left side), locate the Dynamic Page component under Tabs.
- In the Config pane (right side), you’ll see the list of existing subpages.
- Click Edit Content at the bottom of the subpage list. This will open the subpage list in a full-page view.
- Create a New Subpage
- Click the + icon next to the Pages and Variants title.
- Choose Create a new page.
- Ensure you're in the connector’s application scope.
- Provide the following:
- Name: A unique name for your subpage.
- URL Path: This will be used as the route when linking the tab (e.g., /diagnosis).
- You can skip optional properties for now.
- Create the variant:
- In the "Tell us about your variant" section, you can leave the default settings as-is.
- Click Create to proceed.
- Design the subpage
- Open the new subpage in UI Builder Editor.
- Build the required UI and logic for your custom tab.
- Use the connectionId property from the parent page to reference the connection context (@content.props.connectionId).
Link the Subpage to the Tab
- Type sn_sgc_central_connection_record_tabs.list into the navigation filter and press Enter.
- Fill in the fields for the new record:
- Label: The display name of the tab on the Connection Details page (e.g., Diagnosis).
- Route: The URL path of the subpage you just created (e.g., /diagnosis).
- Application: The connector’s application scope.
- Order: Determines the display order of the tab. Tabs are shown in ascending order.
Once this configuration is complete, your custom tab will appear alongside the default tabs on the Connection Details page, enabling richer and connector-specific post-onboarding functionality.
