Securing the Double Agent: Changing a Component’s Scope

Posted on BY

As someone who loves movies with a good twist, nothing keeps me on the edge of my seat quite like a double agent in a suspenseful spy film. You never know which team they’re going to end up on. Today’s mission, should you choose to accept it, is to move a custom component in a configurable workspace from an enemy scope to the desired scope. In other words, secure the double agent! 🕵️

Part 1: The Backstory

When building a custom component, it can be very easy to mess up the component’s scope. Following along with the now-cli docs, it is not immediately apparent that you can specify a scope that already exists in your instance. If you’re like me, you’ll end up with a component that has its own scope and is not tied to the app you’re wanting it in. For the sake of this article, let’s say you made the same mistake I did and need to convert the component to your app scope.

Part 2: The Mission

Now it’s time to secure that double agent and get him on your side. There are two places we will need to go to fix the scope:

  • The enemy scope’s application files
  • The now-ui.json file in your component code

Application Files

Note: this step is only necessary if you have already deployed your component

In your instance, you’ll want to search for the new, automatically created app with the component’s scope. Once you’ve selected it, go to the app record. There are four* application files we will want to delete:

  • UX Source Code (sys_ux_lib_source_script)
  • UX Macroponent Definition (sys_ux_macroponent)
  • Builder Component (sys_uib_toolbox_component)
  • UX Component Definition (sys_ux_lib_component)

*Note that if your scope has more than one component (see Cracking the Code: Two Components, One App Scope for an example), you will have extra copies of the UX Macroponent Definition, Builder Component, and UX Component Definition for each of the additional components in your scope.

now-ui.json File

In your component code, there is a now-ui.json file that defines the components that live in a single scope. If a scope isn’t specified, it will automatically be set to x_{{vendor_prefix}}_{{project_name}}. Here is what our now-ui.json file might look like initially:

{
	"components": {
		"x-123456-mission-impossible": {
			"innerComponents": [],
			"uiBuilder": {
				"associatedTypes": ["global.core", "global.landing-page"],
				"label": "Mission Impossible",
				"icon": "magnifying-glass-fill",
				"description": "Demo Component Wrapper",
				"category": "primitives"
			}
		}
	},
	"scopeName": "x_123456_mission_i"
}

In this example, let’s say that the scope defaulted to “x_123456_mission_i” but my desired app scope is actually “x_123456_mission”. Here is how our now-ui.json file would look after we make the change:

{
	"components": {...},
	"scopeName": "x_123456_mission"
}

Part 3: The Resolution

Now that we’ve made the changes we need to, it’s time to re-deploy our component. Once it’s deployed, we can go back to our instance and verify that the component is now pointing to the correct scope. If we go to the macroponent definition in the sys_ux_macroponent table, we will see that our custom component is stored under the correct application scope. Looks like that double agent component is now working for us.

Mission Accomplished!