Engineering / Computers / Part 7 of 9
Custom Properties & Configurations
Custom properties are where CAD meets the rest of the business. Part numbers, materials, finishes, revisions and project codes flow from here into bills of materials, drawings, purchasing and the ERP system. It is the least glamorous corner of the API and, in most organisations, by some distance the most valuable.
- Part 7 · Applied
- Document vs configuration
- Raw vs evaluated
- Schema governance
KL-ENG-COMP-1507 · KEVOS® Knowledge Library · Australian English
A property that is wrong in a model is wrong in the bill of materials, on the drawing, in the purchase order and in the ERP record. Errors here propagate further than geometry errors and are caught later. Automation that audits and enforces a property schema pays back faster than almost anything else you can build.
01Two scopes, and why the distinction matters
Properties exist at two levels, and confusing them is the most common defect in property automation.
Document-level properties
Belong to the file as a whole. Appropriate for anything true of every configuration
— drawn-by, project code, source standard, design authority.Configuration-specific properties
Belong to one configuration. Appropriate for anything that varies between them
— part number, description, length, mass, finish. In a family of sizes this is
almost everything that matters.Cut-list properties
A third scope in weldments and sheet metal, attached to cut-list folders. Reached
through the folder feature rather than the document, and easy to miss entirely when
auditing a weldment.The manager is obtained from the document extension, naming the configuration you want. An empty string returns the document-level manager; a configuration name returns that configuration's.
ICustomPropertyManager docProps =
swModel.Extension.get_CustomPropertyManager(""); // document level
foreach (string configName in (string[])swModel.GetConfigurationNames())
{
ICustomPropertyManager cfgProps =
swModel.Extension.get_CustomPropertyManager(configName);
// ... audit or update this configuration
}A tool that checks only document-level properties will report a perfectly configured family of parts as having no part numbers at all, because the part numbers are configuration-specific. Always audit both scopes, and report which scope each result came from.
02Reading properties
Every property has two values, and the difference between them is the source of most confusion.
The raw value
What is stored — which may be a literal string, or an expression linking to a dimension, a mass property or another property. This is what you must preserve if you rewrite a property you did not author.
The evaluated value
What the expression currently resolves to. This is what appears on the drawing and in the bill of materials, and it is what an audit should compare against a requirement.
The current read call returns both, together with flags indicating whether the value resolved and whether it is linked. A cached option controls whether values come from stored data or are re-evaluated; cached reads are faster across many configurations, and non-cached reads are correct when something has just changed.
There is no dedicated "does this property exist" call. Read the names and test membership, or attempt a read and interpret the result. Checking against the name list is clearer and avoids relying on the failure behaviour of a read.
03Writing properties
Two calls write, and choosing between them correctly avoids most of the trouble in property automation.
| Add3 | Set2 | |
|---|---|---|
| Property does not exist | Creates it | Fails |
| Property exists | Behaviour follows the add option supplied | Updates the value |
| Type is specified | Yes — text, date, number, yes/no or double | No — keeps the existing type |
| Use when | You cannot be certain the property exists | You have already confirmed it exists and the type is right |
The add call takes an option controlling what happens when the property already exists — replace the value, create only if new, or delete and recreate. That option is the real behaviour switch, and it should be chosen deliberately for each tool rather than copied from an example.
int result = cfgProps.Add3(
"PartNumber",
(int)swCustomInfoType_e.swCustomInfoText,
"KV-1042-03",
(int)swCustomPropertyAddOption_e.swCustomPropertyReplaceValue);
if (result != (int)swCustomInfoAddResult_e.swCustomInfoAddResult_AddedOrChanged)
log.Add($"property write failed, code {result}");The result code distinguishes success from a generic failure and from a type mismatch against either the existing property or the type you specified. Code that ignores the return value will report a successful run over a hundred files while having changed nothing. Test it, log it, and count the failures in your summary.
Writing a literal over a property whose raw value was an expression destroys the link silently. If a tool may encounter authored expressions, read the raw value first and skip anything that is linked unless breaking the link is the explicit purpose of the tool.
04Deleting, and the discipline around it
Deletion is a single call taking the property name, in whichever scope's manager you are holding. The technical part is trivial; the operational part is not.
- Report before you delete. Run the tool in a reporting mode first and circulate the list. Properties nobody recognises are often relied upon by a downstream system nobody remembers configuring.
- Delete from the right scope. Deleting a document-level property does not remove a configuration-specific property of the same name, and the visible result may not change at all.
- Record what was removed. Name, scope, raw value and file, written to a log. This is the only route back if a deletion turns out to have been wrong.
- Never delete on a partial match. Name comparison should be exact and case-defined. A prefix rule will eventually catch something it should not.
There is no undo across a batch of files. A tool that deletes properties across a directory tree should be treated as a data-migration operation: dry run, review, backup, execute, verify. If that sounds disproportionate, consider what a wrongly removed part number costs once it has reached a purchase order.
05A property audit tool
The highest-return tool most engineering businesses can build. It reads everything, changes nothing, and produces a defect list that funds everything after it.
| Class | Meaning | Usual response |
|---|---|---|
| Missing | Required property absent from the scope | Add it — the safest automated correction |
| Empty | Present but blank | Needs a human; the value is not derivable |
| Wrong scope | Present, but at document level where the schema requires configuration level | Move it, preserving the value |
| Wrong type | Text where a number is required, or the reverse | Recreate with the correct type, preserving the value |
| Not permitted | Value outside the controlled list | Review; often reveals a list that needs extending |
| Unresolved link | Expression that no longer evaluates | Investigate — usually a renamed dimension or deleted feature |
Build the audit as its own tool and keep it that way. A corrective tool can consume its output, but the two should remain separable so the audit can be run at any time by anyone, including on files nobody wants modified.
06Treat the schema as a controlled document
The technical work here is straightforward. What makes property automation succeed or fail is whether the organisation has agreed what the properties are.
Write the schema down
Name, scope, type, whether it is mandatory, permitted values, and which downstream system consumes it. One table. Without it, every tool encodes a different opinion.
Fix the names first
Property names are matched exactly. A schema containing both a singular and a plural form of the same idea guarantees permanent inconsistency.
Name the consumer
Recording which system reads each property tells you what a change will break, and stops properties nobody uses accumulating indefinitely.
Version it
When the schema changes, existing files do not. A version marker in the schema, and a migration plan, prevent an audit reporting thousands of false exceptions.
Put it in the templates
Properties present in the part, assembly and drawing templates cost nothing to maintain and remove the largest source of missing-property exceptions at the origin.
Audit continuously
A weekly scheduled run that emails the exception count turns data quality into a tracked measure rather than a periodic crisis.