Understanding Packaging

The package functionality has been designed with two goals in mind. First, packages make it easy to distribute business processes to other environments. Second, the risk of breaking a business process is minimal when updating a package. Because of these two goals, there are restrictions on the content and functionality of packages that you should keep in mind when making or updating a package.

Functional Restrictions

Because packages are the building blocks of any process, changing packages should be done in a controlled way and should not taken lightly.

• A package can have multiple versions. A version of a package contains a copy of the entities that were selected to be in the package and that were in the source environment when the version was added.
• Only consulting partners can create new packages and new package versions.
• Even though administrators can see packages in the BizzStream Marketplace, only consulting partners can install them.
• Any subsequent version contains at least all the entities of the previous version.
• An entity can only belong to one package.
• Only the latest version of a package can be installed.
• Installation of (updated) packages is a manual task.
• Other packages can be required be installed before the package itself .

Package Contents

A package can contain the following BizzStream entities:

• Document System
• Document Definition
• Groups
• Layouts
• Templates
• Menus
• Scripts
• Settings
• Translations

Some entities are (mutually) dependant, meaning that entity A cannot be used without entity B (and vice versa).

We have the entity Employee, which is a document definition. This document definition would be invisible if there was no document system in place. Therefore a document definition has a strong relationship with a document system. The relationship from a document system to a document definition is weak, meaning a document system can be part of a package without having any document definitions.

In the table below you can find the type of relationship between entities:

If you add an entity to the package that has a strong, bidirectional, relation with another entity, the other entity is automatically added to the package. If you add an entity to the package that has a unidirectional relation with another entity, the other entity is also added to the package.

Prefixes

When a package is installed, a prefix is automatically added to the name of the packaged entities to prevent collisions. For instance, the name of the document definition order changes into 9ZG9uvy9LoxYuqDPA_order when you install a package in an environment. Likewise, the name of the script updateOrder changes into 9ZG9uvy9LoxYuqDPA_updateOrder.

The prefix has the following implications:

• When making REST calls to document definitions that are deplyed via a package, the name of the document definition should include the prefix (e.g. 9ZG9uvy9LoxYuqDPA_order).
• When you include a script from a package in a script outside the package, you have to use the full name for the inclusion (e.g. 9ZG9uvy9LoxYuqDPA_updateOrder).
• When you use a document definition from a package in a script outside the package, you have to use the full name including the prefix (e.g. 9ZG9uvy9LoxYuqDPA_order).
• When you include a script from a package within the package or its required packages, you should not include the prefix in the name of the included script (e.g. updateOrder).
• When you use a document definition from a package in a script from the same package, you should not include the prefix in the document definition name (e.g. order).

DTAP Streets

You are strongly adviced to use a DTAP street for the developement and distribution of packages. The acronym DTAP stands for Development, Testing, Acceptance and Production. It expresses a phased approach of package testing and deployment.

In a DTAP street, there are four phases:

1. The package components are developed in an development environment.
2. Once the development is ready, the entities are imported to the test environment using the import wizard. The tests are conducted with a small dataset that covers all uses cases.
3. If the tests are successful, the entities are copied to an acceptance environment using the import wizard. The tests are conducted with a bigger dataset that mimics a production dataset.
4. If the entities are accepted, they are copied to the production environment. In this environment, the package is created.

Companies who use packages are adviced to use a simplified version of the DTAP street for updating packages:

1. Update the package in the acceptance environment and test the business process.
2. Update the production environment by importing the entities from the acceptance environment using the import wizard.

Best Practices

• Since there are strong relations between entities, packages can become large. A problem with large packages is that they are harder to maintain. You are therefore adviced to build small packages. Packages should be seen as building blocks for multiple business processes. The smaller the package, the more versatile it is.
• The entities in the packaged are locked in whole or in part so that they can be updated later. Therefore, you are adviced to use settings to store company specific properties. For example, when you store the URL of REST calls in settings, they can be easily changed between environments.