Define Output Filenames using Expressions
Contents
A critical phase of the development cycle is releasing the documentation that is to be used for the fabrication and assembly of the PCB. In many companies it is common practice to use a standard naming scheme for all design documents, in line with the company's documentation numbering scheme. To support this Altium Designer 13.2 and 13.3 introduce support for user-defined output filenames and folder names using a concatenation of special strings and user-defined project parameters, such as:
=ProjectAssyNumber + '_' +ProjectName + '-' + ProjectRevision + '.PDF'
or
=VariantName + '_' + OutputName + '.PDF'
Specifying Expression-based Output Names and Folder Names
Expression-based output names and folder names are defined in Output Job files, for both PDF and Folder Structure type outputs.
Certain elements from the Output in the Outjob can be used in the output name, such as the current name of this Output, and the Variant Name. The image below shows which elements can be used, refer to the Supported Special Strings table below for more details.
The Expression-based output name is specified in the Settings dialog for the chosen output, click the Change link for the Output Container to configure this. Note that in the following image the output and folder naming works as follows:
- The outputs are stored in a manually named folder called Output
- The Containing Folder (the folder for all outputs from the Jobs allocated to the output container currently being configured) is named from the Variant that is being used to generate the outputs, in this example Model.4G
- The Output Folders (the folder for the individual outputs) are named from the designer-defined Name of each Job
- The individual outputs are named using a concatenation of the ProjectName, the VariantName and the value of a Variant Parameter, in this case the Variant Parameter named VarRevNo
Concatenation Rules
The user-defined output name is built up by concatenating the required elements. The concatenation process obeys the following rules:
| Element | Function | Example | Returns |
|---|---|---|---|
| = (equals) | Indicates that the following string is an expression that must be interpreted. | =ProjectName | DB31 for the example Altium Designer project named DB31.PrjPcb |
| + (plus) | Used to concatenate the elements required in the output name. | =ProjectName + '-' + ProjectRevision + '.PDF' | DB31-07.PDF for the example Altium Designer project named DB31.PrjPcb |
| ' ' (single quotes) | Used to include a fixed string anywhere within the output name. Illegal characters are listed below. | ='AcmeEngineering' +_+ ProjectName + '.PDF' | AcmeEngineering_DB31.PDF for the example Altium Designer project named DB31.PrjPcb |
Illegal Characters and Syntax Errors
The following characters are not permitted in user-defined output names:
< > : " / \ | ? *
If there is a syntax error in an expression, for example an unbalanced quote such as =ProjectName+.PDF' instead of =ProjectName+'.PDF', this will give the result #NAME. When you see this, look carefully for missing quotes or invalid or mis-typed special strings.
Supported Parameters
User-defined Project-level parameters and variant parameters are supported, support for Document parameters will be added in the future. Project parameters are defined in the Parameters tab of the Options for Project dialog (Project » Project Options). Variant parameters can be defined for each variant in the Variant Management dialog (Project » Variants).
Parameter names cannot include spaces, for example the parameter PartNumber can be used, but the parameter Part Number can not.
Supported Special Strings
Special Strings is the term used in Altium Designer to define interpreted strings. Most of these strings can be interpreted on-screen by placing a text string with a value of =SpecialStringName, for example =CurrentDate. They are always interpreted during output generation.
Currently supported Special Strings that can be used in Output filenames include:
| Special String | Returns |
|---|---|
| CurrentDate | The current date, as retrieved from the Operating System, in the ISO 8601 format yyyy-mm-dd. Example: 2013-01-25 |
| CurrentTime | The current time, as retrieved from the Operating System, in the format hh_mm. Example: 14_55. |
| DataSource | The Data Source used for this Output in the Output Job file. |
| OutputName | The user-defined name of this Output in the Output Job file. Only functions when the Separate File for Each Output option is selected in the Output file naming settings. |
| ProjectName | Displays the actual name of the project, excluding the extension. |
| VariantName | The name of an assembly variant defined for this project in the Variant Management dialog. The value used depends on the Variant chosen in the Output Job for the Output whose filename is being defined. |
| ProjectParameterName | The value of the Project Parameter named <ProjectParameterName> |
| VariantParameterName | The value of the Variant Parameter named <VariantParameterName> |
Naming Collated Output Files
For collated output files, only those special strings that are not restricted to a specific output can be used. For example OutputName cannot be used for a collated output file as it applies to a specific output in the Output Job file. VariantName and DataSource also cannot be used. Use of one of these Special strings in a collated output file will result in the actual string being used as the filename.