Skip to content

c3 Market Integration

Jump to bottom
Thuy Nguyen edited this page Jan 23, 2025 · 26 revisions

Product

The following describes how your self-developed product can be added to the official Axon Ivy Market.

Initiate

To publish your product in the Axon Ivy Market, you need another Maven artifact, the product artifact. The product artifact contains the product files. You will find these in the folder MY-PRODUCT-NAME-product. Replace the variable MY-PRODUCT-NAME in all files (README.md, README_DE.md, product.json, pom.xml) and also in the name of the folder.

Product Files

Product Documentation

The README.md is a markdown-formatted text file designed to promote, highlight your product's features and provide useful setup instructions. These README files are prominently displayed on your product detail page, making them a key tool to communicate with users.

Visuals Leverage

Enhance README files with visuals like screenshots or GIFs. Just add these images to the product directory (e.g. under doc/img/my-screen.png) and incorporate them into your README.md with a relative link ![My Fancy Feature](doc/img/my-screen.png).

Use alerts to make crucial information stand out. These visually distinctive blocks improve readability and highlight important details:

Important

Key information necessary for users to succeed.

Tip

Helpful insights to enhance user success.

And feel free to include emoticons as desired to enhance readability 😊✨📷.

Sections Maintenance

The Demo (## Demo) and Setup (## Setup) section headers will be shown as separate tabs on the product detail page. To ensure consistency and functionality:

  • Keep these section headers intact and in order.
  • Add subsections if needed, but avoid introducing additional top-level headings.

File Enhancement

README_DE.md offers the same content as README.md in German, enhance the experience for our German-speaking users. You don’t need to worry about creating the German version — Octopus team is responsible for managing and providing the translation.

However, we warmly welcome contributions! If you'd like to help with the translation, you don’t need to translate the entire file. Translating at least the first chapter (everything up to the ## Demo section) is a great start.

Guidelines for contributions:

  • If ## Demo or ## Setup sections are missing in README_DE.md, the English content will be displayed by default, which is fine.
  • If you translate these sections, they will appear in German on our Marketplace Website.

README Preview

We understand that providing well-prepared README files when introducing a new product or announcing a new feature can be a challenge. While GitHub renders your README file perfectly, issues such as broken formatting or missing styling may arise when it's published on your product's marketplace page. This discrepancy is often due to the differences in how the GitHub UI and the marketplace display Markdown content.

To help address this, we are introducing a README Preview Tool. This tool allows you to upload your Maven build output package (i.e., your MY-PRODUCT-NAME-product.zip) and instantly preview how your README file will appear on the marketplace. By doing so, you can ensure that your README's structure, styling, and content render as intended before releasing your product to customers.

With this tool, you can take the guesswork out of README formatting and deliver a polished, professional product experience for your customers.

How to use this tool:

  • Navigate to the product project directory from the terminal, and build the latest version (e.g. open-weather-connector-product of Open Weather) by the following command: mvn clean install command

  • Access to Release Preview Tools via this link: Release Preview Tool preview-page

  • Upload product artifact in ZIP format (e.g. open-weather-connector-product.zip) which is the output of maven build. upload

  • The page will render exactly what our product details look like after onboarding it to the market. preview-result

Variables Configuration

To guide users on configuring dynamic variables for your product, you can reference the config/variables.yaml file by mentioning it in README files. This helps those who download your product understand where to set up runtime configurations.

@variables.yaml@

Then, update the properties and target sections in the pom.xml file. This will instruct the system to recognize and render the variables block code appropriately.

<properties>
    <variables.yaml.file>../slack-connector/config/variables.yaml</variables.yaml.file>
</properties>

...

<target>
    ...
    <copy todir="${project.build.directory}">
	<fileset dir="." includes="README*.md" />
    </copy>
    <loadfile property="variables.yaml" srcFile="${variables.yaml.file}" encoding="UTF-8" failonerror="false" />
    <replace file="${project.build.directory}/README.md" token="@variables.yaml@" value="${variables.yaml}" />
    <replace file="${project.build.directory}/README_DE.md" token="@variables.yaml@" value="${variables.yaml}" />
</target>

Product Installer

The product.json describes the installation of your product to an Axon Ivy Designer. It will be processed, when a user clicks on the Install button in the Axon Ivy Market Website interface. The product.json must be written in JSON format. We suggest utilizing an editor like VS Code for this task.

How to adapt

The default product.json from the template outlines all valid installer scenarios. You must customize it as follows:

  • Pick the installer you want to use, and modify the groupId(s) (MY-GROUP-ID) and the artifactId(s) (MY-PRODUCT-NAME) to match your product.
  • Remove installer sections, you are not using.
  • Keep the dynamic ${version} attribute. It refers to the Maven attribute that needs to be installed and will be injected from the market based on the version selected by the customer. product-json

Custom Installation

You can test the installation in your local designer:

  • Install the state of your product in your local maven repo by running mvn clean install in the repository root.
  • In the Designer: use the CTRL+ALT+I key-combo to start the product installation from a custom source. Please note that this key-combo only functions if the Designer workspace already contains projects.
  • Provide the path to your product.json in URI compatible format (e.g. file:/home/myuser/dev/market/market/connector/slack-connector/slack-connector-product/product.json or file:/home/myuser/dev/market/market/util/db-utils/db-utils-product/product.json) and proceed to the installation process by pressing OK.
  • Before installing, expand the 'JSON' install block: replace all ${version} occurrences with your locally available version (e.g. 12.0.0-SNAPSHOT).

Market Integration

Publish

If you have made it to this point, you have already built your first market product. Please do not keep it private but create an onboard-to-market issue so that we can publish your product on the official Axon Ivy Market Homepage

Create a release & Celebrate

We can only provide approved versions of your product.

If you are happy with your product and its documentation, you simply need to initiate a release build pipeline from your 'actions'.

Release Build

The release build will:

  1. Deploy the maven artifacts to the GitHub package registry (which is mirrored under maven.axonivy.com)
  2. Tag your repository with the current version
  3. Create a new pull request to increment the version to the next development version, which you should then approve and merge.

It's immensely gratifying to share reusable workflow products with the Axon Ivy community!

Thank you very much for your valuable contribution!

Clone this wiki locally