Custom namespaces
Learn how to define and deploy custom namespaces to AEM as a Cloud Service.
Custom namespaces are the optional part of a JCR property preceding a :. AEM uses several namespaces such as:
jcrfor JCR system propertiescqfor AEM (formerly known as Adobe CQ) propertiesdamfor AEM properties specific to DAM assetsdcfor Dublin Core properties
… and many others.
Namespaces can be used to denote the scope and intent of a property. Creating a custom namespace, often your company name, helps clearly identify nodes or properties specific to your AEM implementation and contain data specific to your business.
Custom namespaces are managed in Sling Repository Initialization (repoinit) scripts, and deploys to AEM as a Cloud Service as OSGi configurations - and added to your AEM project’s ui.config project.
Transcript
So I want to quickly show you how to register custom namespaces with AEM as a cloud service. I’ll be showing you this on my local AEM.sdk, but all of this applies to AEM as the cloud service environments as well. So typically custom JCR namespaces are used to prefix properties, and let me jump over to tools, assets, and metadata schemas, and we can take a quick look at what this actually means. So for example, in the metadata schema editor, we have a series of fields, and these fields are mapped to JCR properties of the asset. And these properties are where the value of the field is stored to, and read from in AEM. So for instance, clicking on this title field here, you can see that it’s stored on the assets, JCR content, metadata, nodes, DC:title property.
So DC:title is the full property name. However, the DC part which precedes this colon is called the namespace. So the idea is a namespace can provide some context around what the property actually means, and who effectively owns it. So in terms of DC, this signifies that this is a Dublin Core Industry Standard Property for the title.
Click on description, we have the DC description, or the Dublin Core description. And if we scroll down a few other things, we have things like tags. Tags are named space with CQ which is the original name of the AEM product, so this is essentially signifying that this property is an AEM system property that contains tags, and things like created have other namespaces as well. So this is the JCR:created JCR being the Java content repository, or the data repository AEM uses distorts content. And this signifies that this created property is considered a system created property by the JCR. So what if we want to add our own namespace for a property? So let’s take a quick look at that. So I can simply drag a new field in.
Let’s just say this is going to be a wknd id. So this field is going to capture an ID that is a wknd business specific value, and we want to make sure that we denote it as such. So there’s a couple options we can use. One is we could simply just call this id, this is a little bit ambiguous because it’s not clear looking at that property name if it’s a wknd ID, or if it’s some sort of system ID, or really what sort of ID it is.
Another option is we could simply just put wknd ID is all one property name with no colon. So there would be no systematic namespace there, or what we can do is create a new namespace called wknd at our colon to delimite the namespace from the rest of the property name, and then put ID so we can :id would be the property name that contains the wknd id. So this is a couple advantages. One of the really big advantages is if you have XMP right back enabled on your assets, only properties that have namespaces will be written back. So for instance, if we had chosen to do wknd id with no colon, this would not get written back as part of the XMP right back. So this is all well and good wknd ID looks great. The trick here is in order to use wknd, we actually have to register it with AEM, and tell AEM that this is a valid namespace.
So even though we can save this if we actually tried reading and writing data to this field in our asset at this point, we’d receive some errors. So let’s go ahead and take a look at how we can register this wknd namespace with our AEM environment, so we can read and write from it. So the way this is done is through repo, and it configs that you would add to your AEM projects UI config project. So over here on the left that I have a weekend examples project open. I have opened up the UI config, and I’ve opened up the config OSGI folder. So this is going to apply to both AEM Author as well as AEM Publish, and this is typically where you’d want to register your namespaces. And what we’re going to do is create a new Repository Initializer Factory Configuration. So I can simply create a new file, and I’m going to paste this in.
We use that Repository Initializer Service name followed by our unique identifier. And since these are going to be a series of one line configs, we can use the config that json format. So let’s go ahead and save that. Within here, let me close this up. We’re going to define our configuration. So for this, it’s going to be a series of scripts. So we’ll create our script key. This is an array and so we could put any number of namespace declarations we wanted to in here. I’ll just do one for now, but we want to use the register namespace command, then parentheses, and within the parentheses we’re going to enter the namespace that we want to register. So in this case, let’s do wknd. So this will let us define any property using the wknd: prefix. Next up we have to provide a URI that the namespace is registered to. And this doesn’t actually have to resolve to anything. This is essentially a unique identifier that maps back to this wknd namespace.
So typically you’ll want to put whatever your company is, and you can version it as well if you want. So let’s call it virtual 1.0.
If you wanted to get more advanced, and have different namespaces for different uses in AEM, we could do something like this. So we could have a wknd say assets, namespace, and we would define a convention that any properties under wknd assets would be wknd asset properties. And perhaps we would use the wknd general namespace on things that apply to both assets and pages, or something like that. And of course we’d want to make the URI distinct, so we can we can create a semantic URI. There we go. So we could do something like this if we wanted to, but let’s go ahead and keep it simple. I’m going to remove this, and just register that wknd namespace. So at this point, all we have to do now is deploy our project to AEM.
So let’s go ahead and do that. And again, I’m using the STK, so I just have to run a quick Maven command, but you could deploy this to AEM as a cloud service through the cloud manager pipelines as well.
All right, we’ve deployed our application. Let’s go ahead and open up an asset here, and see if we can use our new property. We can ID that we applied to our metadata schema. Let’s go ahead and find some assets.
Let’s go ahead and open up the properties. We have our new metadata field. All right, and we can of course put anything we want in here, let’s just say we have a convention of wknd- number for our wknd id. Then we can save and close it.
Now when we open it back up, we were able to write to the wknd:id property, and we were able to read from it as well. And I can show you this in a little bit more detail. Again, since I am on the SDK, we can use CRXDE Lite. You could check this on repository browser on Amazon cloud service. Let’s go ahead and jump in here.
Go to the metadata and we should be able to see a wknd:id property here that’s been set.
So there you go. This is how easy it is to create a custom JCR namespace in AEM. Hope this helps you out. -
Resources
Code
The following code is used to configure a wknd namespace.
RepositoryInitializer OSGi configuration
/ui.config/src/main/content/jcr_root/apps/wknd-examples/osgiconfig/config/org.apache.sling.jcr.repoinit.RepositoryInitializer~wknd-examples-namespaces.cfg.json
{
"scripts": [
"register namespace (wknd) https://site.wknd/1.0"
]
}
This allows custom properties using the wknd namespace, as denoted as the first parameter after the register namespace instruction, to be use in AEM. For more advanced script definitions, review the examples in the Sling Repository Initialization (repoinit) documentation.
recommendation-more-help
4859a77c-7971-4ac9-8f5c-4260823c6f69