# Bundles

Bundles are curated data sets which combine assets such as pipelines, tools, and Base query templates. This is where you will find packaged assets such as Illumina-provided pipelines and sample data. You can create, share and use bundles in projects of your own [tenant](https://help.ica.illumina.com/get-started/gs-getstarted#tenant-setup) as well as projects in other tenants.

{% hint style="info" %}
There is a combined limit of 30 000 projects and bundles per tenant.
{% endhint %}

The following ICA assets can be included in bundles:

* [Data](https://help.ica.illumina.com/project/p-data) (link / unlink)
* [Samples](https://help.ica.illumina.com/project/p-samples) (link / unlink)
* [Reference Data ](https://help.ica.illumina.com/project/p-flow/f-referencedata)(add / delete)
* [Pipelines](https://help.ica.illumina.com/project/p-flow/f-pipelines) (link/unlink)
* [Tools](https://help.ica.illumina.com/home/h-toolrepository) and [Tool images](https://help.ica.illumina.com/home/h-dockerrepository) (link/unlink)
* [Base tables](https://help.ica.illumina.com/project/p-base/base-tables) (read-only) (link/unlink)
* [Base query templates](https://help.ica.illumina.com/project/p-base/base-query)
* [Bench docker images](https://help.ica.illumina.com/home/h-dockerrepository)

The main Bundles screen has two tabs: **My Bundles** and **Entitled Bundles**. The **My Bundles** tab shows all the bundles that you are a member of. This tab is where most of your interactions with bundles occur. The **Entitled Bundles** tab shows the bundles that have been specially created by Illumina or other organizations and shared with you to use in your projects. See [Access and Use an Entitled Bundle](https://help.ica.illumina.com/home/h-bundles#access-and-use-an-entitled-bundle).

{% hint style="warning" %}
Some bundles come with additional restrictions such as disabling bench access or internet access when running pipelines to protect the data contained in them. When you link these bundles, the restrictions will be enforced on your project. Unlinking the bundle will not remove the restrictions.

You can not link bundles which come with additional restrictions to [externally managed projects](https://help.ica.illumina.com/h-projects#externally-managed-projects).
{% endhint %}

{% hint style="warning" %}
As of ICA v.2.29, the content in bundles is linked in such a way that any updates to a bundle are automatically propagated to the projects which have that bundle linked.

If you have created bundle links in ICA versions prior to ICA v2.29 and want to switch them over to links with dynamic updates, you need to unlink and relink them.
{% endhint %}

## Linking an Existing Bundle to a Project

1. From the main navigation page, select **Projects > your\_project > Project Settings > Details**.
2. Click the **Edit** button at the top of the Details page.
3. Click the **+** button, under Linked bundles.
4. Click on the desired bundle, then click the **+Link Bundles** button.
5. Click **Save**.

The assets included in the bundle will now be available in the respective pages within the Project (e.g. Data and Pipelines pages). Any updates to the assets will be automatically available in the destination project.

To **unlink a bundle** from a project,

1. Select **Projects > your\_project > Project Settings > Details**.
2. Click the **Edit** button at the top of the Details page.
3. Click the (**-**) button, next to the linked bundle you wish to remove.

{% hint style="warning" %}
Bundles and projects have to be in the same region in order to be linked. Otherwise, the error *The bundle is in a different region than the project so it's not eligible for linking* will be displayed.
{% endhint %}

{% hint style="info" %}
The owning tenant of a project must have access to a bundle if you want to link that bundle to the project. You do not carry your access to a bundle over if you are invited to projects of other tenants.
{% endhint %}

{% hint style="info" %}
When linking a bundle which includes Base to a project that does not have Base enabled, there are two possibilities:

* **Base is not allowed due to entitlements**: The bundle will be linked and you will be given access to the data, pipelines, samples,... but you will not see the Base tables in your project.
* **Base is allowed, but not yet enabled for the project.** The bundle will be linked and you will be given access to the data, pipelines, samples,...but you will not see the Base tables in your project and Base remains disabled until you enable it.
  {% endhint %}

{% hint style="info" %}
You can not **unlink** bundles which were linked by external applications
{% endhint %}

## Create a New Bundle

To create a new bundle and configure its settings, do as follows.

1. From the main navigation, select **Bundles**.
2. Select **+ Create** .
3. Enter a **unique name** for the bundle.
4. From the Region drop-down list, select where the assets for this bundle should be stored.
5. Set the **status** of the bundle. When the status of a bundle changes, it cannot be reverted to a draft or released state.
   * **Draft**—The bundle can be edited.
   * **Released**—The bundle is released. Technically, you can still edit bundle information and add assets to the bundle, but should refrain from doing so.
   * **Deprecated**—The bundle is no longer intended for use. By default, deprecated bundles are hidden on the main Bundles screen (unless non-deprecated versions of the bundle exist). Select "Show deprecated bundles" to show all deprecated bundles. Bundles can not be recovered from deprecated status.
6. \[optional] Configure the following settings.
   * Categories—Select an existing category or enter a new one.
   * Short Description—Enter a description for the bundle.
   * Metadata Model—Select a metadata model to apply to the bundle.
7. Enter a **release version** for the bundle and optionally enter a description for the version.
8. \[Optional] Links can be added with a display name (max 100 chars) and URL (max 2048 chars).
   * Homepage
   * License
   * Links
   * Publications
9. \[Optional] Enter any information you would like to distribute with the bundle in the Documentation section.
10. Select Save.

{% hint style="warning" %}
There is no option to delete bundles, they must be deprecated instead.
{% endhint %}

{% hint style="info" %}
To **cancel** creating a bundle, select Bundles from the navigation at the top of the screen to return to your bundles overview.
{% endhint %}

## Edit an Existing Bundle

To make changes to a bundle:

1. From the main navigation, select **Bundles**.
2. Select a bundle.
3. Select **Edit**.
4. Modify the bundle information and documentation as needed.
5. Select **Save**.

{% hint style="info" %}
When the changes are saved, they also become available in all projects that have this bundle linked.
{% endhint %}

## Adding Assets to a Bundle

To add assets to a bundle:

1. Select a bundle.
2. On the left-hand side, select the type of asset (such as **Flow > pipelines**, **Base > Tables** or **Bench > Docker Images**) you want to add to the bundle.
3. Select **link** to add assets to the bundle.
4. Select the assets and confirm with the **link** button..

Assets must meet the following requirements before they can be added to a bundle:

* For samples and data, the [project](https://help.ica.illumina.com/home/h-projects) the asset belongs to must have data sharing enabled.
* The region of the project containing the asset must match the region of the bundle.
* You must have permission to access the project containing the asset.
* Pipelines and tools need to be in released status.
* [Samples](https://help.ica.illumina.com/project/p-samples) must be available in a `complete` state.
* [Tables](https://help.ica.illumina.com/project/p-base/base-tables) can not be linked to a bundle while Base creation for that bundle is in progress.

When you link folders to a bundle, a warning is displayed indicating that, depending on the size of the folder, linking may take considerable time. The linking process will run in the background and the progress can be monitored on the **Bundles > your\_bundle > activity > Batch Jobs** screen. To see more details and the progress, double-click the batch job and then double-click the individual item. This will show how many individual files are already linked.

{% hint style="info" %}
You can not add the same asset twice to a bundle. Once added, the asset will no longer appear in the asset selection list.
{% endhint %}

{% hint style="info" %}
You need to be in list view in order to **unlink** items from a bundle. Select the item and choose the unlink action at the top of the screen.
{% endhint %}

Which batch jobs are visible as activity depends on the user role.

## Create a New Bundle Version

When creating a new bundle version, you can only add assets to the bundle. You cannot remove existing assets from a bundle when creating a new version. If you need to remove assets from a bundle, it is recommended that you create a new bundle. All users wich currently have access to a bundle will automatically have access to the new version as well.

1. From the main navigation, select **Bundles**.
2. Select a bundle.
3. Select the + **Create new Version** button.
4. Make updates as needed and **update the version number**.
5. Select **Save**.

When you create a new version of a bundle, it will replace the old version in your list. To see the old version, open your new bundle and look at **Bundles > your\_bundle > Details > Versioning**. There you can open the previous version which is contained in your new version.

Assets such as data which were added in a previous version of your bundle will be marked in green, while new content will be black.

## Add Terms of Use to a Bundle

1. From the main navigation, Select **Bundles > your\_bundle > Bundle Settings > Legal** from the left hand navigation.
2. To add Terms of Use to a Bundle, do as follows:
   * Select **+ Create New Version**.
   * Use the editor to define Terms of Use for the selected bundle.
   * Click Save.
   * \[Optional] Require acceptance by clicking the checkbox next to Acceptance required.\
     `Acceptance required will prompt a user to accept the Terms of Use before being able to use a bundle or add the bundle to a project.`
3. To edit the Terms of Use, repeat Steps 1-3 and use a unique version name. If you select acceptance required, you can choose to keep the acceptance status as is or require users to reaccept the terms of use. When reacceptance is required, users need to reaccept the terms in order continue using this bundle in their pipelines. This is indicated when they want to enter projects which use this bundle.

## Collaborating on a Bundle

If you want to collaborate with other people on creating a bundle and managing the assets in the bundle, you can add users to your bundle and set their permissions. You use this to create a bundle together, not to use the bundle in your projects.

1. From the main navigation, select **Bundles > your\_bundle > Bundle Settings > Team**.
2. To invite a user to collaborate on the bundle, do as follows.

   * To add a user from your tenant, select **Someone of your tenant** and select a user from the drop-down list.
   * To add a user by their email address, select **By email** and enter their email address.
   * To add all the users of an entire workgroup, select **Add workgroup** and select a workgroup from the drop-down list.
   * Select the Bundle Role drop-down list and choose a role for the user or workgroup. This role defines the ability of the user or workgroup to view or edit bundle settings.
     * **Viewer**: view content without editing rights.
     * **Contributor**: view bundle content and link/unlink assets.
     * **Administrator**: full edit rights of content and configuration.
   * Repeat as needed to add more users.

   Users are not officially added to the bundle until they accept the invitation.
3. To change the permissions role for a user, select the Bundle Role drop-down list for the user and select a new role.
4. To revoke bundle permissions from a user, select the trash icon for the user.
5. Select **Save Changes**.

## Sharing a Bundle

Once you have finalized your bundle and added all assets and legal requirements, you can share your bundle with other tenants to use it in their projects.

Your bundle must be in released status to prevent it from being updated while it is shared.

1. Go to **Bundles > your\_bundle > Edit > Details > Bundle status** and set it to Released.
2. Save the change.

Once the bundle is released, you can share it. Invitations are sent to an individual email address, however **access is granted and extended to all users and all workgroups inside that tenant**.

1. Go to **Bundles > your\_bundle > Bundle Settings > Share**.
2. Click **Invite** and enter the email address of the person you want to share the bundle with. They will receive an email from which they can accept or reject the invitation to use the bundle. The invitation will show the bundle name, description and owner. The link in the invite can only be used once.

{% hint style="info" %}
Do not to create duplicate entries. You can only use one user/tenant combination per bundle.
{% endhint %}

You can follow up on the status of the invitation on the **Bundles > your\_bundle > Bundle Settings > Share** page.

* If they **reject** the bundle, the rejection date will be shown.\
  To re-invite that person again later on, **select their email address** in the list and choose **Remove**. You can then create a **new invitation**. If you do not remove the old entry before sending a new invitation, they will be unable to accept and get an error message stating that the user and bundle combination must be unique. They can also not re-use an invitation once it has been accepted or declined.
* If they **accept** the bundle, the acceptance date will be shown. They will in turn see the bundle under **Bundles > Entitled bundles**.\
  To **remove** access, **select their email address** in the list and choose Remove.

## Entitled Bundles

Entitled bundles are bundles created by Illumina or third parties for you to use in your projects. Entitled bundles can already be part of your tenant when it is part of your subscription. You can see your entitled bundles at **Bundles > Entitled Bundles**.

To use your shared entitled bundle, add the bundle to your project via Project Linking (**Projects > your\_project > Data > Manage > Link**). Content shared via entitled bundles is read-only, so you cannot add or modify the contents of an entitled bundle. If you lose access to an entitled bundle previously shared with you, the bundle is unlinked and you will no longer be able to access its contents.