Scripting API

Reports

from ArtisanPlugin.Scripting import DraftingApi as drafting

A report is the sheet that leaves the CAD room: a layout page carrying the views of the piece, the title block the workshop and the client read, and - when the template asks for it - the metal, gem, process and extras tables and the gems map. There are two paths to one, and both end in a Rhino layout page you print to PDF with DocumentApi.ReportPdf. The automatic route builds the standard A4 sheet with no input at all; the template route imports a layout you drew yourself and fills its tags.

The automatic A4 report

ok = drafting.CreateReport()                     # -> bool

Takes no arguments. Builds the standard A4 report page for the current design - logo, four detail views (top, perspective, front, side), and a title block with the design name, metal and weight, finger size, notes and date - exactly the sheet the ArtisanReport command produces from the ribbon.

It is implemented by running the command itself, so the output stays identical to the interactive one and picks up future improvements automatically. It returns True when the command reports success and False otherwise; it does not return the page, so find the result among the document’s layout pages after the call.

Listing the templates

names = drafting.ReportTemplates()               # -> IReadOnlyList[str]

Returns the report template names available to CreateReportFromTemplate: the *.3dm files in the configured report-templates folder, without their extension, in the order the folder yields them. The list is read-only and purely informational - no scripting call adds a template, you save one from the Report panel.

The first entry is the panel’s default selection, and it is what CreateReportFromTemplate uses when you pass no template.

Template-based reports

page = drafting.CreateReportFromTemplate(
    template = None,
    style = None, clientId = None, po = None,
    cadDesigner = None, description = None,
    customFields = None,
    sphericalGemsMap = False)                    # -> str, e.g. "Report 1"

The Report panel’s Create button, headless: it imports the template’s layout into the document as the next Report N page, zooms every detail view onto the model, and replaces the template’s tags with the document’s data.

Parameter	Default	Meaning
`template`	`None`	A name from `ReportTemplates()`, matched case-insensitively and trimmed. `None` or blank = the first template, the panel’s default selection
`style`	`None`	Title-block style / reference. `None` keeps the value the document already carries
`clientId`	`None`	Title-block client id. `None` keeps the document’s value
`po`	`None`	Title-block purchase order. `None` keeps the document’s value
`cadDesigner`	`None`	Title-block CAD designer. `None` keeps the document’s value
`description`	`None`	Title-block description. `None` keeps the document’s value
`customFields`	`None`	A `{field name: value}` mapping feeding the `[MY_FIELD]` style tags; merged over the custom fields the document already has
`sphericalGemsMap`	`False`	`True` draws the `GEM_MAP` marker with the spherical projection instead of the planar one

None means leave alone, not clear: only the fields you actually pass are written. Pass an empty string to blank a field.

The tag system

A template is an ordinary 3dm layout whose texts carry tags. At create time each tag is substituted with the document’s data:

Tag	Filled with
`[CLIENT_ID]`, `[PO]`, `[STYLE]`, `[CAD_DESIGNER]`, `[DESCRIPTION]`	The title-block fields above
The metal tags	The document’s metals
`[PRODUCT_SIZE]`	The finger / product size
`[MY_FIELD]`	Your `customFields` entries - the tag is the dictionary key wrapped in brackets, so `customFields = {"BATCH": "0421"}` fills every `[BATCH]` in the template
`METAL_LIST`, `GEM_LIST`, `PROCESS_LIST`, `EXTRA_LIST`	The corresponding breakdown table, drawn where the marker sits
`GEM_MAP`	The gems map, drawn where the marker sits, planar or spherical per `sphericalGemsMap`

Custom fields are the extension point: anything the standard title block does not cover, you add as a [MY_FIELD] text in the template and feed by name.

The list markers read the cost breakdown. When no breakdown has been computed yet, it is recomputed silently before the tags are filled - the panel would ask first, the API does not.

What it returns and leaves behind

The return value is the name of the new layout page as a string, e.g. "Report 1" - pages are numbered sequentially, so a second call on the same document gives "Report 2". Feed it straight to the PDF printer:

from ArtisanPlugin.Scripting import DocumentApi as docapi

page = drafting.CreateReportFromTemplate("Workshop A4", clientId = "ACME", po = "PO-1187")
docapi.ReportPdf(r"C:\out\report.pdf", pageName = page)

Besides the layout page, the call persists the title-block fields into the document: whatever you pass in style, clientId, po, cadDesigner, description and customFields is merged into the document’s saved report info and saved there, so the Report panel shows it afterwards and later reports reuse it.

Errors

With no templates in the folder it throws InvalidOperationException: “No report templates available. Save one from the Report panel first.”

With a name that matches no file it throws ArgumentException: “Unknown report template ‘X’. Templates: …”, listing the available names.

Both calls mutate the document; wrap them in a Transaction if you want the page, its filled tags and the saved fields to undo in one step.