Documentation packaging allows our partners to create pre-built sets of documentation that the selected clients can then import into their Org models. It means that with the click of a button, a client can import hundreds or even thousands of documents that will be associated with the target metadata and easily available contextually in the client Org.
Article outline
Documentation package architecture
Prerequisites
Setting up the Space for documentation packaging
Setting up the Documentation package
Creating documentation package versions
Managing package visibility
Documentation package architecture
A documentation package is the grouping mechanism for all documentation (rich text notes, URL links, and diagram links) created in the context of your Org model implementation.
For each package, you can create multiple versions. The version files are what actually carries over the documentation and can be imported by the clients. The same package can have many different versions which contain a completely different set of attachments.
Every client implementation can only have 1 version of the package installed at any time. Importing a new version of the package will replace the old version. This process will update/add/remove documentation to match with the new version.
When you publish a new version of the package it is not automatically pushed to all spaces that have previously installed your package version. Instead, either the clients or your consultants need to be made aware and manually import the latest version of the package into the target client Space.
Prerequisites
In order to use this functionality you need:
Be a member of our partner program
Have corporate management enabled for your account
(contact success@elements.cloud if you need this)Corporate admin permission to set up the Space that will be used for packaging
Space admin permission on a Space to create the package & its versions
Org model edit rights to create documentation
Setting up the Space for documentation packaging
You have to choose which Space will be used for documentation packaging. This ensures that not everyone in your business can create a package for the clients without your approval.
Click on the gear icon in the upper-right corner of the toolbar. If you have corporate admin permission you should be able to access Corporate settings.
In the list of Spaces find the Space which you would like to use for documentation packaging. Select the 4th tab in the right panel called Packages and turn on this feature by selecting the toggle.
Setting up the Documentation package
The user with Space admin permission can then select the implementation in the Org model list for the enabled Space and create a documentation package against it.
In order to create a new package, click on the name of the implementation (the grouping for org models) and then select the third tab on the right. You can then either create a completely new package or link to an existing package. The latter option would allow you to curate 2 parallel versions of documentation for the same package.
You need to give your package a name and a short description. Then click "Create".
In the right panel for the implementation, you will find the details of the created package.
Creating documentation package versions
Before you create a documentation package version, make sure that:
You have added rich text notes or URLs to appropriate metadata in your Org Model
You have linked diagrams to target Org model metadata
You have published the diagrams which are referenced in the Org model
Once your documentation is ready, go to the list of org models, select the implementation, and open the 3rd tab in the right panel. Click on the big button "Create new documentation package version".
You will be prompted to give your version a number. Just like with Salesforce managed packages, you can give it a major, minor, and patch number to match it with your managed package version. We also added a 4th number "build" in case you want to manage versions of documentation even if the managed package version has not changed. However, this is just for documentation purposes and you can set any number you like.
Click "Create" when ready.
Once the version has been generated you can see the reference in the right panel for the selected implementation. You can click on the blue arrow against the version to download a CSV file with the names and types of all attachments in its scope and information on which metadata they are associated with.
Managing package visibility
You can manage your package visibility at any time from Corporate Management. If you have just created your first package and your first version then you need to make sure the package has been enabled before anyone can install it.
Click on the text button in the implementation's right panel to navigate to the appropriate screen in corporate management.
In the list of packages you can see all documentation packages that have been created in your corporate account. Every new package is disabled by default. To enable it (i.e. make it visible to users in Elements) simply toggle "Enable package" in the right panel.
Select the 2nd tab called "Access" to manage who can install it. By default any space in the Elements app can import an enabled package and its versions but you can disable that and add specific domains that will be able to do so instead.
In the "Versions" tab you can see all versions ever created for that package. You can also disable versions (i.e. they will no longer be available for installation) and see how many users are on each version.
If you roll over the version you can see which spaces this version is currently used in (domain: space name).
