Essential Properties on a nested pre-comp look like they should behave like any other property you can address by name. They do not, and nearly every “it does not work” report comes down to one fact: the values you set in the primary comp are defaults for a separate layer instance, and your data sheet has to talk to that instance, not to the comp.
This article is written for the developer who owns the data side of a Templater job. You have a spreadsheet, a JSON feed or a QUE integration, and a motion designer has handed you an After Effects project with promoted properties. You are the one who gets the message that says the video came out with placeholder text. We will work from symptoms back to causes, using only what Dataclay’s support documentation states, and we will mark the places where the documentation says nothing so you know where to test instead of trusting a rumor.
The model you need in your head before debugging anything
There are three objects, and confusing any two of them is the source of most trouble.
The first is the primary composition. It is a regular comp in which the designer has promoted properties to the Essential Properties panel and marked the comp as a primary composition. The values configured there are the source of the defaults.
The second is the pre-comp layer, which is a layer in another composition that is an instance of the primary. The documentation says that when the primary composition is nested as a pre-comp layer, the values set in the primary become the defaults for that layer. The layer then has its own instanced set of essential properties.
The third is the target composition, the comp Templater processes and renders. The documentation’s example labels it . The instance layer sits inside it.
Templater’s Dynamic Essential Properties feature, which needs Templater 3.5 or later, writes to the second object only. The documentation states directly that this method does not change the essential property values of the primary composition itself. So a developer who reads the project and sees the primary comp’s values changed in a file diff, or who expects the primary comp to show the new text when opened, has the wrong picture. The primary comp is the rest state. The instance is where a job’s data lands.
Now add the part that trips people more often than any other. The instance has to be recognized as dynamic, and the documentation gives three conditions for that. The layer must have an explicit name, because After Effects names a new pre-comp layer after its source comp, and the documentation says you must rename it so Templater recognizes it as dynamic and so you can refer to it in your data source. The layer name should not contain spaces. And the layer must have the Templater Settings effect applied to it.
If you receive a project from a designer and you are not sure the instance is set up, you can usually tell by looking at the layer in the timeline. Is it named something that is not the comp’s own name? Is the Templater Settings effect on it? Does it have a set of essential properties of its own, visible when you expand it? Three yes answers are a good sign, and any no is where to start.
Symptom: the video rendered with the designer’s placeholder text
This is the most common report, and the documentation gives enough to build a short checklist, in the order we would check it.
Check the key first. The key in your data source must use the layer name followed by @ and then either egp, for an object of properties, or a bracketed property name. For a spreadsheet, a single column header looks like layer name@[property name]. If the property is in a group, the group name goes in front, in the form layer name@[Group > Property]. The documentation’s example is a color property named Subheader Fill in a group called Colors on a layer called assembly, which becomes assembly@[Colors > Subheader Fill].
Look at the match between your header and the panel, character for character. The documentation says the name of each property key must be an exact match for the name of the property in the Essential Properties panel. That is the whole rule. There is no fuzzy matching described, so a trailing space, a different capital letter or a missing group prefix is a miss.
Then check the type. The documentation says the value must match the data type the panel uses. A color goes into a data source as a hex code. A numeric property takes a number. A boolean takes true or false. If the type does not match, Templater skips the key and writes an error to its log. The result looks the same as a wrong key from the outside, since the placeholder stays. The log is what tells the two apart. If you see an error line about the property, it is a type problem. If you see nothing at all, suspect the key or the layer.
Next check for an empty value. If a property key is not in your data for a job, or its value is null or undefined, Templater uses the default. That is a documented, deliberate behavior, and it is the reason a row with a blank cell produces a video with the designer’s placeholder. If your pipeline emits an empty string or a null for missing data, the placeholder text will appear. This is the one that surprises developers who are used to a missing value throwing an error. Here it does not. Decide whether a blank is an acceptable outcome, and validate upstream if it is not.
Last, check that the instance is the layer you think it is. If the project has more than one layer with the same source comp, or if the designer renamed the layer after you wrote the header, the key points at nothing. Ask for the exact layer name, and treat it as part of your interface the way you would treat an API field name.
Symptom: I changed the primary comp and the instance did not follow, or the reverse
The documentation describes how the defaults flow, and it is worth reading the sentence carefully. Each time the composition is reversioned, Templater reloads all the default essential property key and value pairs you set in your primary comp. Then it changes only the pairs found in the data for that job.
Read that as a rule about each job. At the start of a job, the defaults are the values currently configured in the primary comp. Then the data for that row is applied on top. So a change a designer makes to a default in the primary comp is something you would expect to see on the next job that does not override it, and a value your data supplies wins for that job.
What the documentation does not describe is anything about a value someone changed by hand on the instance layer in the timeline. It does not say whether a manual edit on the instance is kept, replaced by the default or ignored when Templater reloads. If your team has designers touching instance values directly, test this before you depend on it. Open the project, change a value on the instance by hand, run a one-row job with no data for that property, and look at what comes out.
The practical rule we would set with a design team follows from the documented flow. Defaults live in the primary comp, and only there. Job-specific values live in the data. Nobody edits the instance by hand in a file that goes to the render machine.
Symptom: it works for one instance and not for two
This one deserves a careful answer, because the documentation is not explicit and a developer will want to build on it.
What the documentation says is that the pre-comp layer exists as an instance of the primary and has its own instanced set of essential properties, and that the key syntax is built on the layer name. Those two facts together suggest that two instances of the same primary comp, each with its own layer name, can be addressed separately by keys that start with their respective names. We think that reading is natural. But the documentation does not show a two-instance example, so we will call it what it is, an inference that you should verify.
A quick way to verify is to build a file with one primary comp and two instances, name them differently, give them different default values, and run a one-row job that sets a value for only one of them. If the other keeps its default and the first changes, the addressing works the way the key syntax implies.
Here is how the sheet for that file could look. This is our example, not one from the documentation. The primary comp is a product card with a promoted text property called Product Name and a promoted color called Accent in a group called Colors. The two instances are named card_left and card_right.
The spreadsheet headers would be card_left@[Product Name], card_left@[Colors > Accent], card_right@[Product Name] and card_right@[Colors > Accent]. A row fills those four cells. In JSON, the same row would have a card_left@egp object with a Product Name key and a Colors object holding Accent, and a card_right@egp object built the same way. The documentation also allows individual keys like card_right@[Product Name] next to an egp object. If both name the same property, the individual key wins.
That precedence rule is worth designing around. It lets you put a stable set of properties in the egp object and override one of them with an individual key for special rows, such as a promotion where one card gets a different accent color. If your feed produces both, document which one the producer is allowed to send, so a stray individual key does not silently beat a carefully built object.
Symptom: it works in the preview and not in the render, or media will not change
Media properties have their own rules, and they are the area where the documentation is most pointed about what not to do.
To control a media asset with data, the designer must drag the entire media layer into the Essential Properties panel in the primary comp. After that the key takes a path to the media asset, and both local and remote paths are supported. In a spreadsheet, the documentation shows the cell content in the form of a property name and a path.
The documentation then adds a recommendation that matters to anyone building a video pipeline. It does not recommend reversioning video assets through Essential Properties. After Effects does not support Time Sculpting, audio files or videos with audio in video layers promoted to the Essential Properties panel, so for video footage you are pointed to the existing Templater method for versioning footage. If your feed supplies clips, plan on a regular dynamic footage layer for those, and keep Essential Properties for images, text, colors, numbers and booleans.
When a mismatched media value reaches Templater, the documentation says Templater respects the preference you have set for that scenario, rather than describing one fixed outcome. So the behavior depends on a setting on the machine, and two machines with different preferences can produce different results from the same row. If you run more than one render machine, compare their preferences first.
For the preview-versus-render question in general, the documentation does not describe a difference in how essential properties are applied. We can only tell you how to find out. Use the spot check feature, which the documentation says can be used to verify how data controls promoted properties. Our guide to generating spot checks explains how to export still frames or clips of specific frames from data-merged compositions. Check a handful of rows from your real feed before you start a long batch.
What the feature does not do
Two limits are stated and one is not, and a developer should know all three.
First, it works on one layer at a time. The documentation says that features like Time Sculpting affect more than a single layer, so Templater cannot change those layers using Dynamic Essential Properties, and it notes that reversioning this way may not be as dependable as the functionality Templater already offers. If your template depends on layout rules or time sculpting to adapt to text length, keep using those methods, alone or beside Essential Properties. Our posts on Time Sculpting and layout rules cover them.
Second, it applies to properties that have been promoted. If the designer did not promote a property, there is no handle for your data. Ask for it to be promoted, or use a regular dynamic layer for it.
The limit that is not stated is how deep a nested structure can go. The title of this page mentions nesting, and it is fair to ask. The documentation’s examples show a primary comp, an instance in a target comp, and a key on the instance. It does not describe an instance inside an instance, or promotion passed up through several comps, and it does not give a number. We will not make one up. If the project you have been given nests deeper than that, ask the designer to build the smallest version of the structure, run a single row through it with the log open, and see what the log says. Write the result down. It is the only authoritative answer for your version.
A short debugging order you can keep
When a value does not land, work through these in order, because each one is cheaper than the next.
Read the log for an error about the property, since a type mismatch is written there. Confirm the layer name in the file matches the prefix on your key, with no spaces. Confirm the Templater Settings effect is on that layer. Compare the key to the panel name character by character, including the group. Confirm your value type, a hex code for color and a real boolean for true or false. Confirm the cell is not empty or null. Then check which of the individual key and the egp object is supplying the value, in case one is overriding the other.
If you have gone through all of that and the value still does not change, you have found a case the documentation does not cover. Reduce the project to the smallest file that shows it, and send that to our support team. A small file with a clear row is a much easier thing to help with than a production project.
The bottom line
Essential Properties on a nested pre-comp are defaults on one side and a named instance on the other. The primary comp holds the rest state. The instance layer, named explicitly and carrying the Templater Settings effect, receives the data. Your keys must be exact, your types must match, and a blank is a request for the default, not an error. Test what the documentation leaves out, which is manual edits on an instance, two instances in one file and anything deeper than one level, before your pipeline depends on it.
For the product side of all this, see the Templater page, our post on Dynamic Essential Properties in Templater 3.5, and the overview of data sources you can use with Templater.
A few of the questions developers send us most often are answered here.
Frequently Asked Questions
Why does my instance keep the placeholder text even though my column has a value?
Check the key, the layer name and the type in that order. The key must be the layer name plus @[property name], with the group name included for grouped properties, and it must match the panel name exactly. If the type is wrong, Templater skips the key and logs an error. If the value is empty, null or undefined, the default from the primary comp is used by design.
Does Templater write the new values into the primary composition?
No. The documentation says this method does not change the essential property values of the primary composition itself. Templater changes the values on the pre-comp layer that is an instance of it. The primary comp holds the defaults, and Templater reloads them each time the composition is reversioned before applying the data for that job.
Can I address two instances of the same primary comp separately?
The key syntax is built on the layer name, so giving each instance its own name and prefixing each key with it is the natural approach. The documentation does not show a two-instance example, so build a small test file, set a value for only one instance, and confirm the other keeps its default before relying on it in production.
What if I use both a layer@egp object and an individual key for the same property?
The individual key takes precedence. The documentation states this for both JSON data sources and spreadsheets. It is a useful way to put a stable set of properties in the egp object and override a single one for special rows, but document which source your feed is allowed to send so one does not silently override the other.
Do I need Templater 3.5 or later?
Yes. The documentation states that controlling essential property values from your data is supported for Templater 3.5 or later. Support is documented from 3.5, so confirm the version on every render machine, since the Bot runs on whichever machines you have set up.
Can this feature swap video clips from a data feed?
It is not recommended. After Effects does not support Time Sculpting, audio files or videos with audio in video layers promoted to the Essential Properties panel, so the documentation points you to the existing Templater method for versioning video footage. Images and similar media layers can be controlled with a local or remote path.
