Add a component to Agent Workspace

  • Release version: Xanadu
  • Updated August 1, 2024
  • 2 minutes to read

    • Use custom components to create a custom Workspace interface to fulfill the specific need of your company's agents.

    Communicating with customers through multiple channels can be time consuming. To be efficient in these omni-channel interactions, your agents need a single view of customer information to reduce context switching between multiple tools. By developing custom components for Workspace, your team can bring communications from multiple channels into one interface.

    Adding components to a Workspace

    Once deployed to your instance, you can add components to Workspace in these ways.

    Add a component to a Workspace modal
    Use a UI action to launch a custom component in a modal so an agent doesn't have to navigate to a different screen to accomplish a task. For more information, see Render a component in a modal.
    Add a component to a Workspace landing page using UI Builder

    Use the UI Builder to create custom landing pages for your agents. UI Builder is a drag-and-drop tool that lets you visually arrange workspace components. For more information, see Configuring Configurable Workspace.

    Configure properties in the now-ui.json file to use deployed components in the UI Builder. For instructions, see the ServiceNow Developer Site.

    Add a component to a Workspace record view
    You can add custom or standard components to the component area in the Workspace record view. For more information, see Forms.

    Add a component to UI Builder

    Set properties in a configuration file to add your component to the UI Builder in your instance.

    Before you begin

    Procedure

    1. In your project directory, open now-ui.json.
    2. Add the components.[component-name].uiBuilder object to the file.
      This object adds the component to the UI Builder.
      This object includes these key-value pairs:
      Key Data type Description
      components.[component-name].uiBuilder Object Object that adds the component to UI Builder.
      components.[component-name].uiBuilder.label String Required. The display name of the component in UI Builder.
      components.[component-name].uiBuilder.icon String Required. The name of the icon that appears in UI Builder.
      components.[component-name].uiBuilder.description String Required. A short description of the functionality of the component. 
      {
  "components": {
    "card": {
      "uiBuilder": {
        "label" : "Card",
        "icon" : "chat-fill", 
        "description" : "A visual card format for a record.",
        "associatedTypes": ["global.core"]
      },
    3. If your component includes properties, add the components.[component-name].properties array to the file.
      This adds the properties as configuration options for the component in UI Builder.
      This object includes these key-value pairs:
      Key Data type Description
      components.[component-name].properties Array <Object> An array of objects that includes all the properties of the component and all relevant information about those properties.
      components.[component-name].properties[].name String Name of the property in your component's code.
      components.[component-name].properties[].label String Display name of the property to display in UI Builder, if applicable.
      components.[component-name].properties[].description String A short description of what the property does or how to use it.
      components.[component-name].properties[].readOnly Boolean When true, prevents a user from configuring the property in UI Builder.

      Default: false.
      components.[component-name].properties[].required Boolean When true, the user must configure the property.

      Default: false.
      components.[component-name].properties[].defaultValue String The default value when the user does not provide one.
      components.[component-name].properties[].associatedTypes Array Describes where in the UI Builder toolbox the component appears. Value must be "global.core".
      components.[component-name].properties[].typeMetadata Object Extra configuration data that some data types require, such as reference properties and choice lists. 
      {
  "components": {
    "properties": [
		    {
			"name": "backgroundColor",
			"label": "Background Color",
			"description": "Background Color",
			"readOnly": false,
			"required": false,
			"defaultValue": "lightgray"
		    },
		    {
		       "name": "cardType",
			"label": "Type of card",
			"description": "Type of card",
			"readOnly": false,
			"required": false,
			"defaultValue": ""
		    }
			]
    4. Save the file.

    What to do next

    Deploy a component to an instance.