PLMGraph — Guide

PLMGraph reads a package export from Aras Innovator and draws the data model out of it: which item types exist, how they hang together, and which methods, forms and workflows depend on them. All of it happens in the browser.

The reason it exists is a question Aras answers badly: “What happens if I change this?” The admin UI shows you one item type after another. What is missing is the overview — and above all the connections that are not modelled as relationships but as a property with data_type = item, or as a string inside method code.

What it deliberately does not do

• Write anything back. PLMGraph produces no importable package and no AML to apply. A badly generated package can damage a production environment; a change list you work through by hand cannot.
• Connect to Aras. No OData, no OAuth, no agent, no credentials. The tool only ever knows the files you hand it.
• Run a server. No database, no account, no real-time collaboration. A model is a file.

These are not gaps, they are decisions. They keep the tool in a role where it cannot break anything: read, understand, document, design.

1. 1Open the example model — a small PLM core model with Part, Document and Change Request. It runs through the same parser as a real export, so it is a real model rather than a screenshot.
2. 2Click an item type. The inspector opens on the right with its properties, its incoming and outgoing edges, and the artifacts that point at it.
3. 3Press F. Focus mode hides everything outside the neighbourhood. Depth 1–3 is set in the toolbar. Esc brings the whole picture back.
4. 4Open Analyse → Schema hygiene. The example carries a few typical pieces of accumulated cruft on purpose.
5. 5Now load your own export: Import → Choose folder — or simply drag the folder or ZIP anywhere onto the window.

An import never overwrites the open model behind your back: if PLMGraph sees that you already have a model loaded, it asks whether the new export should be merged in as a re-import.

Aras ships the Package Import/Export Utilities. The export tool writes one or more packages into a folder. Whoever administers your Aras instance knows this tool — if you do not run it yourself, asking for “a package export of our solution” is enough.

The result typically looks like this:

AML-Packages/
  imports.mf                    ← manifest: which packages, which folder
  DTC/Import/
    ItemType/PhysicalPart.xml
    RelationshipType/PhysicalPart BOM.xml
    Method/php_GetKeyedName.xml
    Form/ …  List/ …  Life Cycle Map/ …
  a_param/Import/
    …

PLMGraph takes the top-level folder — or a ZIP of it, or just a handful of individual XML files. It does not rely on the folder structure: it collects every .xml recursively and reads .mf separately.

The manifest is not required, but it is valuable: it is the only way PLMGraph knows which item type comes from an Aras system package (com.aras.innovator.*) and which from your own solution. Without a manifest everything starts out as custom — the classification can be corrected per item type by hand.

If you do not have an export to hand

Three ways to get one without waiting for a colleague:

• Aras Labs on GitHub — over 160 community projects under the MIT licence, most of them published as import packages with exactly this structure. Small, but real.
• An Aras Innovator Community Edition of your own. The standard installation alone brings several hundred item types, and you can export as often as you like.
• The example model in the editor. Small and hand-made, but it shows all three kinds of edge and the artifacts.
• Generate test data — a synthetic export of any size, with the awkward parts real ones are full of: references that point nowhere, references written only as a name, polymorphism, data types that do not exist. Runs in the browser. It is not for importing into Aras, and says so in every file it writes.

If the terms are familiar, skip this section. Everyone else will find here what PLMGraph reads out of the export, and why it matters.

Aras has more than one way to connect two item types. PLMGraph draws all three — differently, because they mean different amounts.

Aras system properties such as created_by_id, owned_by_id or permission_id are item properties too — they sit on every item type and point at Identity, User or Permission. They deliberately produce no edge: otherwise every box would carry three to five extra lines to the same two nodes, and the actual business structure would drown in them. They are still listed in the inspector.

The toolbar, from the left

• File — new model, open model (⌘/Ctrl+O), save (⌘/Ctrl+S). A dot next to the file name means: unsaved changes.
• Import — choose a folder, or XML files/a ZIP. Drag and drop works anywhere on the window.
• System / Custom / Draft — filter by origin, each with a count. That is how a model with 800 item types quickly becomes the 40 that are yours.
• Artifacts — show or hide methods, forms and workflows as nodes of their own.
• Focus — show only the neighbourhood of the selection, depth 1–3.
• Analyse — schema hygiene, compare two states (with the risk analysis), check a package, import report.
• View — life cycle states, auto-layout (⌘/Ctrl+L), collapse or expand all properties, edge labels.
• Create — your own item type (draft), a note or an artifact.
• On the right: Export, the theme switch (dark / light / system), Search (⌘/Ctrl+K).

The node

A header with the name and its markers: rel for a relationship item type, poly for a polymorphic one, external for one that is only referenced, plus the origin. Below that the properties: a key icon for is_keyed, a link icon for item properties, a star for required fields, and on the right the data type and, where there is one, the target.

Zooming out simplifies the drawing in two steps — first the properties go, then the markers. That is not a loss of detail but the reason 800 nodes still stay fluid.

The inspector

The right-hand column, toggled with I. With nothing selected it shows the model as a whole: name, counts, groups, notes. With a selection it shows the item type: edit properties, override the origin, set a colour — plus two sections you get nowhere else:

• Impact — what hangs off this item type, incoming and outgoing.
• Used in artifacts — which methods and forms use it, split into declared and found in source code.

What happens on import

PLMGraph reads the files, sets manifests aside, looks for <Item> elements at any depth in the XML and builds item types, properties, the three kinds of edge and the artifacts out of them. It never throws: anything unclear ends up in the import report instead of aborting the import.

The import report

It opens by itself after every import and stays reachable via Analyse → Import report. It answers the question you ask of any import tool: is this complete?

• files read, skipped and failed, each with a reason
• the packages it found
• counts for item types, properties, edges, artifacts and links
• every reference it could not resolve — with origin, GUID, name and file
• unknown data types that were treated as string

Unresolvable references are usually not a failing of the tool but a genuine statement about the export: the target lives in a package that was not exported. That is precisely why it is listed.

Re-import

When you later load a newer export of the same model, PLMGraph merges the two and keeps your work: positions, colours, groups, notes and any origin classifications you set by hand. Item types missing from the new export are marked rather than deleted and put in front of you for confirmation. The merge itself goes through the Aras GUID, falling back to the name.

Search

⌘/Ctrl+K opens search across item types, properties and artifacts. A hit on a property jumps to the node and highlights the right row.

Filters

System, Custom and Draft can each be hidden. On a full Aras export that is the first thing to do: system packages off, and an illegible tangle turns into your model.

Focus

Select an item type, press F: everything outside the neighbourhood disappears. Depth 1 shows the direct neighbours, depth 3 also theirs. Esc leaves focus mode.

This is the practical answer to “what hangs off this item type” — and, combined with the image export, the fastest route to a slide that shows exactly one thing.

Layout

Auto-layout (⌘/Ctrl+L) rearranges the nodes. It runs only when you ask it to, never on its own — a diagram that reshuffles itself after every change is useless the moment you want to explain it to somebody. Positions you moved stay put, across saving and re-import alike.

It arranges what is on the canvas: the item types the filter lets through, and — when artifacts are shown — the methods, forms and workflows along with them, placed by the item types they point at. With more than one node selected it arranges only the selection.

An ER diagram answers “which item type points at this one?”. In day-to-day work the expensive question is “which method breaks if I rename this property?”. For that, PLMGraph reads methods, forms, workflows, life cycles, ACLs, actions, reports, SQL, lists, saved queries and views along with the schema and links them to the item types — with the trigger where the export names one, so a link reads “runs on onBeforeUpdate” rather than merely “is connected”.

Two kinds of link

The heuristic does not find everything: a type name assembled at run time stays invisible. And occasionally it finds too much: a comment containing the word “Part” produces a hit. Hence names under three characters and a list of harmless everyday words (item, file, value, name …) are excluded — and hence every find comes with the evidence next to it.

An item type that appears only in source code and is declared nowhere is the most dangerous case in the whole model: renaming it breaks things silently, without Aras saying anything. The hygiene check reports it separately.

Placing artifacts by hand

Artifacts do not have to come out of an export. Create → Artifact puts a method, form, workflow, life cycle, ACL, action, report, list or SQL onto the canvas. That is what designing looks like: noting that a method belongs here long before it exists anywhere.

A hand-placed artifact counts as a draft and is shown even while it points at nothing. Link it either by dragging from the artifact onto an item type, or through the drop-down in the inspector. A link made by hand counts as declared — you are asserting it, it is not a guess about source code — and says “Added by hand” as its evidence.

The inspector edits name, kind, language and source code, removes single links and deletes the artifact. Everything imported can be edited too: a name read out of an export can be wrong just as easily.

Everything else in an export describes structure — what exists and what points at what. A life cycle describes a process: which states a record can be in, and how it gets from one to the next. It is the one part of the data model that answers a question somebody asks who never opens the admin interface.

View → Show life cycle states unfolds it. Every life cycle map grows a chain of its states to the right, joined by transitions. A state marked with a ring is where a record starts; one with a padlock is a released state, the kind that locks a record. The label on a transition carries its name and — where there is one — the method that fires on the way. That last part is the point of the whole thing: “which method runs when this goes to Released” should not need a click.

The same thing reads as a list in the inspector when a life cycle is selected, including the identity allowed to make each move.

Deliberately a lens on the same diagram, not a second view. The interesting questions run across the boundary: a transition fires a method, that method reads a property, that property sits on an item type which hangs off this life cycle. Split into two separate pictures, exactly those connections are the ones you lose.

Workflows are not unfolded. Aras has a serviceable graphical workflow editor of its own, so a second view of the same thing would add little; its life cycle editor is the weaker of the two, which is why this half came first.

Analyse → Schema hygiene checks the whole model and lists what stands out. Deliberately findings, not “errors”: much of it was a deliberate decision. The report says what it noticed and leaves the judgement to you — which is why every rule also states why it reports.

The report can be downloaded as Markdown. A header with the counts, then a table per rule: that is a handover document, not a screenshot.

Two rules know about Aras conventions and therefore do not report them: the leading underscore on your own properties (_assembly) is normal, and Aras names relationship item types “<source> <target>” with a space by convention (PhysicalPart BOM).

Analyse → Compare two states: load a second package export or a saved model. PLMGraph puts the two side by side and colour-codes the diagram to show what is new, changed or unchanged. Item types, properties, relationships and artifacts are all compared.

The usual reasons:

• What was built on Dev that is not on Prod yet?
• What did the last solution update actually change?
• What did a colleague touch during the last sprint?

The change list can be exported as Markdown — as the basis for a sign-off or a handover record. Explicitly not an importable package: a person decides what gets taken over, and carries it out in Aras.

Direction: the loaded model is the before state, the state you choose is the after state. You usually have the familiar one open and want to know what is different elsewhere.

The change list says what is different. The second tab of the same dialog says what it costs. Two different questions, and the second is the one people lose sleep over: a removed property is a line in a table until you know that three methods read it.

The whole point rests on one asymmetry in Aras. A declared reference is checked by the server: remove a property a form field points at and you get a complaint. A reference in source code is checked by nobody. Remove a property a method reads as a string and you get silence — and an error at run time, months later. Every line of the risk analysis says which of the two it is.

The severity follows the impact, not the change. The same removed property is a housekeeping item when nothing reads it and the highest severity when a method does. Ten rules, in the order they hurt:

The report can be downloaded as Markdown, with the extent of the search in the header: how many item types, artifacts and references were looked through. That is deliberate — a short report should not read as an all-clear.

What is not in the export cannot be seen. An integration outside Aras, a report in a BI tool, a script on a server: none of it is in any package, and none of it appears here.

Analyse → Check a package asks a different question again: not “what is different between two equals” but “will this package apply cleanly to what I have, and what does it cost if it does”. The direction is the other way round from the comparison — the loaded model is the target, the export you choose is the package to be delivered.

Only what the package contains is examined. Everything else in the target is none of its business.

This checks against an export of the target, not against the running instance. An export is a photograph: whatever has been changed in the target since it was taken is invisible here. A clean report says “nothing found in what was compared”. It does not say “the import is safe”, and it never will — that would need a connection to the instance, which PLMGraph deliberately does not have.

Nor can it see whether the target’s data survives. A property that gets shorter is a line in the report and a truncated column in reality; which rows are affected is in the database, and no export contains that.

Analyse → Documentation writes a first draft from what is currently known: the model in numbers, everything you added by hand, the life cycles, the hygiene findings — and, where a comparison or a package check is loaded, those as well.

Generated documents and edited documents are usually a choice between two evils. A generated one gets regenerated and takes your notes with it; a hand-written one goes stale the day after it is written. The way out is to make the boundary visible:

<!-- plmgraph:begin overview -->
… regenerated every time …
<!-- plmgraph:end overview -->

Anything written here survives.

Refresh the generated parts replaces only what sits between the markers. Everything else is left exactly as it was, and a section that has newly become relevant is appended at the end rather than pushed into the middle of a sentence somebody wrote. So the numbers stay current and the reasoning stays yours — which is the right division of labour, because a tool can produce the first and has no business inventing the second.

The document lives in the model, not in a file beside it, so it travels with the .json and survives saving, closing and re-importing. It can be exported as Markdown at any time.

The column beside the inspector

View → Show the documentation column puts the same document beside the diagram. The dialog is for reading the whole thing and reworking it; the column is for the other half of the job — noticing something while looking at the diagram and writing it down before it is forgotten. A dialog is the wrong shape for that, because it covers the very thing that prompted the thought.

The line at the bottom is the quick way in: type, press Enter, and the note is appended at the end of the document — outside the generated markers, so refreshing never touches it. The chevron folds the column to a strip; the View menu removes it altogether. The left edge can be dragged to any width you like, and a double-click on it goes back to the default. That width is kept in the browser rather than in the model: how wide a column is on this screen is nobody else’s business.

The change log

Every change to the model is recorded with a timestamp and one readable line — “Property Part.weight renamed to Part.mass”. The clock icon in the column shows the list; What was done here is the section it writes into the document, newest first.

The filtering is the whole design. Moving nodes around, folding properties away, filters, focus mode, selection, the display toggles — none of it is recorded. All of it is saved to the file; none of it is worth reading back afterwards. A log that records every drag is a log nobody opens twice.

Two consequences worth knowing. Successive edits to the same field within a minute become one entry, which keeps the value from before the first of them — otherwise typing a name would leave one entry per keystroke. And ⌘/Ctrl+Z takes the entry back out again: the log rides inside the model, and undo restores the model as it was before the change. An undone change did not happen, in the log as everywhere else.

The log knows what you did in this file. It is not a history of the Aras instance, and it starts at the moment of the import — what happened before that is in the export, and the honest route to it is a comparison against the earlier state.

PLMGraph is not only a viewer. You can edit item types and properties, create new ones and draw edges — for the design stage, before anything exists in Aras.

• Create → Item type (draft) — new item types carry the origin draft and so are always distinguishable from imported ones.
• Life cycles — create one under Create → Artifact, then add its states and transitions in the inspector, or draw a transition by dragging from one state to another. Exactly one state is the start state; deleting a state takes its transitions with it.
• Create → Artifact — method, form, workflow, life cycle, ACL, action, report, list or SQL. See Artifacts.
• Draw edges — from one node to another. A dialog asks what kind of relationship you mean. Dragging from an artifact onto an item type links the two directly, with no dialog: there is only one thing it can mean.
• Groups — select several item types, then “Create group” in the inspector. Groups can be collapsed; 30 nodes become one named box.
• Create → Note — free text on the canvas, for decisions and open questions.
• Colours — per item type in the inspector, for groupings that cut across the origin. The colour tints the node itself, lightly: at the zoom level where you want the grouping, area is the only thing the eye still reads. Selection, a missing item type and the diff outrank it — those are statements about the model, a colour is a note to yourself.

Undo and redo (⌘/Ctrl+Z, ⌘/Ctrl+⇧+Z) cover all of it, fifty steps deep.

The model

⌘/Ctrl+S saves a JSON file — wherever you put it. That file is the model: versionable, e-mailable, checkable into a repository. The browser also keeps a working copy, so a tab closed by accident costs you nothing.

The browser's working copy (IndexedDB) is not a backup. Browsers clear it without warning. Anything that matters, save to a file.

Images

• PNG — double pixel density, for slides and tickets.
• SVG — vector. It is generated from the rendered HTML and uses foreignObject: correct in browsers, only partially supported in vector editors such as Inkscape.
• PDF — one page, scaled to fit.

What gets exported is always what is currently visible. Filters and focus mode count — which is the route to an image that carries exactly one statement.

Documentation

• Markdown — one table per item type with every property, data type, key and target. For a wiki or a requirements document.
• Mermaid ER — an ER diagram as text, which GitHub, GitLab and many wikis render directly.
• DBML — for dbdiagram.io and related tools.

Inside text fields only the ⌘/Ctrl shortcuts apply — F and I simply type letters there.

A package export is a complete blueprint of your PLM system. Some customers would not be allowed to load it into a web tool at all. So:

• The export is read in the browser and never leaves it.
• There is no server that could receive it — PLMGraph is a static site with no database and no user account.
• Once the page has loaded there is no further network traffic. You can verify that in developer tools.
• No analytics, no trackers, no third-party cookies.
• If you want to be completely sure: load the page, disconnect from the network, then import. It works unchanged.

The honest answer is uncomfortable and easy to fudge, so here it is straight: PLMGraph does not read a version number. There is no version check anywhere in it. What it reads is the AML structure of a package export — item types, properties, relationship types, and the items that point at them.

So instead of a compatibility promise made from a sample of three, here is what has actually been read and checked, and what has never been met:

Read from real exports

Implemented, never yet met

If an export of yours does not read correctly, that is worth more to this tool than any feature request. The import report names every file that was skipped and every reference that could not be resolved — send that, or the export itself if you may, to support@plmgraph.com. The parser has been built from a handful of packages; every further one makes it less wrong.

What PLMGraph cannot do, or does only with a caveat — so that you do not have to find out yourself:

• No writing back to Aras. No package, no AML, no connection. That stays as it is.
• Source-code hits are a heuristic. Nobody finds dynamically assembled type names — this tool included.
• Polymorphism has not been verified against a real export. The parser expects Morphae items; an export that actually uses polymorphism has not come our way yet.
• No mobile use. A schema diagram on a phone is not a serious way to work.
• Very large models are measured up to about 800 item types and 4000 properties. Beyond that nothing is promised.

Every assumption about the XML format is marked ASSUMPTION: in the source and summarised in docs/aras-xml-notes.md — including the places where a real export has already disproved them.