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:
- SGC Central (sn_sgc_central)
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 Process Automation > Workflow Studio > Playbooks.
- Check the existing process named SGC Create Connection Template with SGC Central as application. Select Duplicate to create a new process definition.
- 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.
Note: Most of the configurations shipped as part of the default template of SGC Central are already set. You might only need to modify a very few configurations and verify the rest according to your specific use case. For example, you will need to update the "parentSysAlias" property in the "Configure and Test Connection" activity to reference the connection template on the default sys_alias for the connector, which displays the fields required to create a new connection.
- 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). If your connector doesn't require this activity you can delete it by clicking on Delete Activity.
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. If your connector doesn't require this activity you can delete it by clicking on Delete Activity.
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, description 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 changes as needed.
- Click Save and Close to complete the configuration.
Note: This activity outputs the SGC Connection record and the Sys Alias ID of the connection created 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. If your connector doesn't require any connection properties you can delete it by clicking on Delete Activity.
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 from the output of the Configure and Test Connection activity 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'.
- 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 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, and CCF compliance status. When a user wants to create 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: This can be the name that you would like to identify the connections belong to
which connector. - Logo: Upload the connector’s logo image.
- Application: Make sure you are in connector scope while creating this record.
- Multi-instance Support: Boolean field indicating if the connector supports multi-instance connections or only a single connection.
- CCF Support: Boolean field indicating if the connector is CCF (Common Connection Framework) compliant.
- Name: This can be the name that you would like to identify the connections belong to
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.
Note: Switch to the application scope of your connector before you start this step.
Steps:
- 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: This should be the same as the name of the property in Service Graph Connection Properties (sn_cmdb_int_util_service_graph_connection_property) table. This is the 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: Details about this property. This will be shown as help text in an info icon with the property in SGC Central UI.
- Application: Connector’s application scope.
- Active: Whether this property should be displayed in the UI. This provides an option to hide the property from the UI later if it is not needed.
- Mandatory: Indicates whether the property value must be provided.
- Group: This is to categorize properties into groups. The name provided here will be shown in the UI to group the properties (e.g., "Configuration properties").
- Group Order: This value is used to decide the display order of groups. Determines precedence if multiple groups exist.
- Order: Display order of the property within its group.
Configure Record Tabs for Connection Details Page
The connection edit flow displays 4 default tabs: Details, Data Sources, Scheduled Imports, and Errors. When managing installed connections in SGC Central, you can add custom tabs to display connector-specific configuration or monitoring information. These additional tabs are managed through the Connection Record Tabs (sn_sgc_central_connection_record_tabs) table.
Default Tab Order: The default tabs use the following order values:
- Details: 100
- Data Sources: 200
- Scheduled Imports: 300
- Errors: 400
To add custom tabs that appear alongside or between these defaults, configure entries in the Connection Record Tabs table with appropriate order values.
Add a Custom Tab to the Connection Details Page
SGC Central ships with a pre-built Connection Properties page that displays connection properties specific to your connector. Many connectors can reuse this page for that specific use case without creating a custom UIB subpage. If your connector needs additional tabs for different use cases (e.g., Diagnosis, Monitoring), you will need to create custom UIB subpages (see the optional section below).
Configure the Connection Record Tabs Table
- 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.
- For Connection Properties tab: Use the pre-defined route connection-properties (to display connector-specific connection properties)
- For other use cases: Use the route you defined when creating your custom UIB page (e.g., diagnosis, monitoring)
- 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.
Create a Custom UIB Subpage for Additional Use Cases
If your connector requires tabs for use cases beyond displaying connection properties (e.g., Diagnosis, Monitoring, Advanced Configuration), you will need to create custom UIB subpages.
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).
- Set App Configuration of your subpage to empty.
- Select Open variant collection record in Developer menu.
- Set App Configuration of UX Screens and UX App Routes to empty in the related lists.
- Select Open variant collection record in Developer menu.
- After creating your custom subpage, follow the same steps as described in the "Configure the Connection Record Tabs Table" section above, using your custom route.
