Packaging architecture

How does it work?

A documentation package is the grouping mechanism for all documentation (rich text notes, images, url links and process diagram links) created for your Org model metadata.

For each package you can create multiple versions. The version files are what actually carries over the documentation and can be imported into the target Org. The same package can have many different versions which contain completely different set of documents.



A documentation package version contains information on the documentation itself and also on the metadata source item. When importing a version of a package to an Org model, the system is first trying to find metadata with a matching API name. If found, it creates an attachment. If the target Org model has all the same metadata as the source Org model, then after import they will share the same documentation.




You can create multiple versions of the same documentation package. This is especially useful for ISVs who constantly evolve their managed packages. You can update the documentation for each new version of your managed package.

A client can only have one version of the same documentation package installed in their Org model at a time. If they install a different version of the same documentation package then that new version will replace the old version and associated documentation.

This logic is explained below:



Let’s assume that in the process of installing version 1 of the documentation package you imported 3 attachments: A1, B1 and C1.

If you edit/update an attachment which came from the documentation package then you effectively make it a local attachment and you remove any linkage between that attachment and its package of origin.

Let’s now imagine that you install a new version of the documentation package (version2). In a hypothetical scenario outlined above:

  • Attachment Aa stays in the Org model because it was edited by you
  • A new attachment A2 is created (this could very well be the exact same attachment as before which is present in both versions 1 & 2)
  • Attachment B1 is replaced with a newer version B2 (because the package provider changed something in that attachment)
  • Attachment C1 is removed completely because it is not in scope of the version 2 of the documentation package

Documentation packaging and diagrams

To include diagrams in your documentation packages you need to:

  • Link diagram boxes to org model nodes. By linking a specific box you are referencing both the step/item, the entire diagram in which it resides, and the entire source map;
  • Publish the source map so you have a released version.



When the client imports a package version which includes diagram links:

  • The copy of the source map (published version copy) will be created in the client Space in the draft state;
  • All links between org model nodes (based on API name) and target diagram boxes will be re-established;
  • The source map will be created only once (unless the partner updated the published version and hence the ISV source map has a different version number).