Skip to main content

Release Assets to the catalog

The Asset Catalog ("the catalog" from now on) is a globally available service that enables Flowstate users to reuse, share, and version control Assets between Solutions and organizations. When you are working in the Solution Editor and install a Skill such as ai.intrinsic.move_robot or a Service such as ai.intrinsic.pinch_gripper_opcua_service, you are installing it from the catalog.

While Intrinsic has released many first-party Skills, Services, and other Assets to the catalog for use by any Flowstate user, other organizations can also release their own Assets. Currently, these released Assets are only be visible to and usable by users within the same organization. However, Flowstate will soon enable organizations to share their Assets with any other user or organization.

This guide will help you understand when the Asset Catalog is the right tool to use, and how to use it.

note

The catalog today is in an early stage of development. The guide below reflects its current state, and we are continuously working to improve and expand its functionality. We will update this guide as new features becomes available.

Should I release an Asset to the catalog?​

Assets in the catalog can be thought of as "offerings" of one's organization, for use either by other users within the organization or (eventually) users in other organizations. Currently, only Intrinsic can share Assets in the catalog with other organizations, but we envision that the catalog will become an important driver of the Flowstate ecosystem by enabling collaboration between Asset developers and Solution builders.

You do not need to release your Asset to the catalog in order to use it. Locally developed Assets can be installed directly into Solutions using the inctl asset install ... command (or its integration into your VS Code development environment). This workflow should be sufficient for many use cases.

However, if you would like to:

  • reuse your Asset across multiple Solutions;
  • share your Asset with users who do not have access to its source definition;
  • and version control your Asset to provide stable behavior and improvements to it over time,

then it likely makes sense to use the catalog to distribute your Asset.

Released Assets are immutable

Except in rare circumstances*, an Asset that has been released to the catalog cannot be removed. This constraint protects users who rely on Assets in the catalog for production deployments. Because Assets in the catalog are permanent offerings, organizations should develop their policies and processes for releasing Assets carefully and consider which users within the organization should be given permission to release Assets.

Note: In the future, users will be able to delist an Asset, so that it will no longer appear when browsing the catalog. However, a delisted Asset will still exist in the catalog to support existing deployments that already use it.

*Users who need to delete an Asset from the catalog because of extenuating circumstances (e.g., safety, security, or legal concerns) can contact Intrinsic support for assistance.

Prerequisites for releasing an Asset​

Asset packages​

Every Asset ID consists of a package and a name. Your organization must be assigned an Asset package to release Assets into it. If you are unsure if your organization has already been assigned a package, please contact Intrinsic support.

Giving a user permission to release Assets​

After your organization is assigned a package, only users with the necessary permissions can release new or updated Assets into it. If you need to grant a new user permission to release Assets into your package, please contact Intrinsic support.

Releasing an Asset​

Once your organization has an assigned Asset package and your user has permission to release Assets into it, you are ready to go!

To release an Asset into the catalog, you will use the inctl asset release command. This command takes as input the Asset .tar bundle that is generated by Bazel when building your Asset.

In the example below, we will assume that you are releasing the stopwatch_service Service that you created in the Develop a service guide. (NOTE: You will not actually be able to release this Service to the catalog: Its ID has com.example as the package, and your organization does not have permission to release Assets into that package.)

Generate the Asset's .tar bundle​

To prepare your Asset for release, first build it in a terminal and record the file path at which Bazel generated your output .tar bundle:

TARGET=//stopwatch:stopwatch_service
bazel build $TARGET
STOPWATCH_SERVICE_BUNDLE=`bazel cquery --output=files $TARGET`

inctl asset release arguments​

When releasing an Asset to the catalog, you must choose a SemVer version for the Asset you are releasing. Your organization should develop a policy for choosing and incrementing this version. Specify the version of the Asset you are releasing via the --version argument.

Additional arguments for controlling the behavior of your Asset in the catalog:

  • --default: A boolean flag that determines whether this version of the Asset will be the default version that is installed when a user selects it in the frontend. An Asset can have only one default version.
Assets without a default version don't appear when browsing the catalog

If you have not yet released a default version of your Asset, it will not appear when browsing the catalog. See Managing already released Assets below if you want to make an already released Asset version the default.

  • --org_private: A boolean flag that determines whether the Asset version is private to the organization. An org-private version of an Asset will only be visible to and usable by members of the organization that owns the Asset, regardless of whether additional permissions have been granted on the Asset itself. This flag can be useful for releasing test or work-in-progress versions of Assets that are not yet ready for use outside of your organization. One possible workflow for an organization could be to first release an Asset version with the org-private flag set, then remove the flag after internal testing has validated that the version is ready for use by whoever has permission to use the Asset. Multiple versions of an Asset can be org-private. However, an Asset version cannot be marked as both default and org-private, since the default version of the Asset should be visible to everyone that has access to the Asset.

:::

An Asset can only be made org-private at release time

In order to prevent Asset versions from "disappearing" from the catalog after a Solution that uses them has already been deployed in production, the org-private flag cannot be set on an Asset version that has already been released.

Execute the release command​

Now that you have generated the Asset's .tar bundle and chosen the Asset's version, visibility in the catalog, etc., you are ready to execute inctl asset release to release your Asset to the catalog. (Last reminder: This action cannot be undone.)

ORGANIZATION=<your_organization>
inctl asset release $STOPWATCH_SERVICE_BUNDLE \
    --org=$ORGANIZATION \
    --version=0.0.1 \
    --default=false \
    --org_private=true

Managing already released Assets​

inctl additionally provides subcommands for viewing and managing released Assets. Brief descriptions of each command with an example are given below.

info

Help can be viewed for any of the following commands by typing inctl help asset <command>.

list_released​

inctl asset list_released lists Assets in the catalog, optionally with filters. (Reminder: Only Assets with default versions will appear.)

inctl asset list_released \
    --org=$ORGANIZATION \
    --asset_types="service"

list_released_versions​

inctl asset list_released_versions lists all of the versions of the specified Asset:

inctl asset list_released_versions com.example.stopwatch_service \
    --org=$ORGANIZATION

get_released​

inctl asset get_released retrieves information about the specified Asset version:

inctl asset get_released com.example.stopwatch_service.0.0.1 \
    --view=detail \
    --org=$ORGANIZATION

update_release_metadata​

inctl asset update_release_metadata updates release metadata for the specified Asset version, such as whether it is org-private or the default version of that Asset:

inctl asset update_release_metadata com.example.stopwatch_service.0.0.1 \
    --default=true \
    --org=$ORGANIZATION

The AssetCatalog gRPC service​

All of the inctl commands described above create a client to and interact with the AssetCatalog gRPC service being served from assets.intrinsic.ai:443.

Users who need to interact with the catalog programmatically can create their own client to that service. The AssetCatalog API is described at asset_catalog.proto.

Note that all interactions with the catalog must be properly authenticated, but authentication is beyond the scope of this guide. Please contact Intrinsic support if you need assistance.

Sharing Assets outside of one's organization​

Flowstate does not currently provide any self-serve mechanism for sharing Assets in the catalog outside of one's organization. If you have an Asset that you would like to share via the catalog with other organizations or with all Flowstate users, please contact Intrinsic support.