Skip to content

W-14408363 improve exchange upload info bsj #83

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
bjoson-mulesoft wants to merge 6 commits into
base: latest
Choose a base branch
from
Draft

W-14408363 improve exchange upload info bsj #83

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e24ea27
Draft of additional ruleset upload info
bjoson-mulesoft Dec 27, 2023
6cde855
Added descs
bjoson-mulesoft Jan 2, 2024
24e644b
Added examples and other edits
bjoson-mulesoft Jan 3, 2024
fa14e77
Edits
bjoson-mulesoft Jan 4, 2024
e673bd9
Added placeholder text fro last 3 exchange json props
bjoson-mulesoft Jan 22, 2024
6bcd0cd
Added a descriptorVersion defn but need to get it validated
bjoson-mulesoft Jan 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 46 additions & 3 deletions modules/ROOT/pages/custom-rulesets-validate-and-publish.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,16 +20,59 @@ include::anypoint-cli::partial$api-governance.adoc[tag=governance-ruleset-valida
[[generate-ruleset-doc]]
== Generate the Ruleset Documentation

Use the following command to generate a documentation ZIP file for a ruleset YAML file. The resulting documentation ZIP file can then be used in an Exchange asset upload using the `--files.docs.zip` option.
Use the following command to generate a documentation ZIP file for a ruleset YAML file. The resulting documentation ZIP file can then be used in an Exchange asset upload using the `--files` flag with the `docs.zip` option.

include::anypoint-cli::partial$api-governance.adoc[tag=governance-document,leveloffset=+1]

[[publish-ruleset]]
== Publish the Custom Ruleset

You can publish (upload) a ruleset and its documentation to Exchange using Anypoint CLI. You cannot use the Exchange UI to upload ruleset assets.
You can publish (upload) a ruleset and its documentation to Exchange using Anypoint CLI. You can't use the Exchange UI to upload ruleset documentation.

You can upload the following in a single upload command:

[%header,cols="20a,40a,40a"]
|===
|Flag and Options|Result|Example
|The ruleset YAML using the `--files` flag with the `"ruleset.yaml"` option.
|This uploads the ruleset information included in the YAML file and ignores any other files detected in the same folder, such as the `exchange.json` file. You can use `--type=ruleset`. If you don't, the type is inferred from the `--files` flag `--ruleset.yaml` option.
|`--files='{"ruleset.yaml":"mynewruleset.yaml", "docs.zip": "ruleset.doc.zip"}'`

@sandrau sandrau Jan 30, 2024

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should docs.zip be here?

@bjoson-mulesoft bjoson-mulesoft Jan 30, 2024

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree as you've said that docs.zip is a feature provided by exchange for all assets. I was just trying to give examples of the things they can do vs. them needing to use the CLI reference to figure out what they need. I'll work with Jenny and Nanda to try and organize the examples and exchange.json reference content in appropriate/logical places in the doc.
I've made this PR a draft as a place to write and gather information for now. Stay tuned for more later on.
Thanks for your feedback!

|The ruleset ZIP using the `--files` flag with the `"ruleset.zip"` option.
|This uploads the ruleset information included in the YAML file and evaluates other files in the zip file, such as the `exchange.json` file. You can use `--type=ruleset`. If you don't, the type is inferred from the `--files` flag `"ruleset.zip"` option.
|`--files='{"ruleset.zip":"mynewruleset.zip"}'`
|The ruleset YAML and the ruleset documentation ZIP file using the `--files` flag with the `"ruleset.yaml"` and `"docs.zip"` options in the same `--files` flag.
|This uploads the ruleset YAML information plus the documentation for the ruleset. You must upload the documentation along with the ruleset. You cannot upload documentation separately later, but can add it manually.
|`--files='{"ruleset.yaml":"mynewruleset.yaml", "docs.zip": "ruleset.doc.zip"}'`
|The ruleset ZIP and the ruleset documentation ZIP file using the `--files` flag with the `"ruleset.zip"` option with the `"docs.zip"` option in the same `--files` flag.
|This uploads the ruleset ZIP file information, evaluating any `exchange.json` file properties, plus the documentation for the ruleset. You must upload the documentation along with the ruleset. You cannot upload documentation separately later, but can add it manually.
|`--files='{"ruleset.zip":"mynewruleset.zip", "docs.zip": "ruleset.doc.zip"}'`
|===

=== Guidelines for Ruleset Exchange JSON Files

You can use an `exchange.json` file to define the Exchange settings for rulesets. You can use any of the following properties:

[%header,cols="35a,65a"]
|===
|Property|Description
|main|The main file of your asset. Ensure that this matches the name of your ruleset when publishing a ruleset.

@sandrau sandrau Jan 30, 2024

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what does "the name of your ruleset" mean? I could publish anypoint-best-practices and have the ruleset file called ruleset.yaml, and it would work fine.. should it state your ruleset file relative path?

|name|The artifact name of your asset. You cannot change the name of an asset that's already published.
|organizationId|The Anypoint Platform organization or business group in which to publish the asset.
|groupId|The Anypoint Platform group in which to publish the asset.
|assetId|The Exchange asset ID assigned to the asset.
|version|The asset version.
|classifier|The asset type. Use the value `"ruleset"` when publishing a ruleset asset.
|dependencies| Rulesets can have fragments defined as dependencies.

@sandrau sandrau Jan 30, 2024

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would either not mention this or explain it more with an example...

|tags| Tags for a ruleset asset's details in Exchange.

@sandrau sandrau Jan 30, 2024

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this tags are not automatically applied to the asset :(

|descriptorVersion|The version of the descriptor model a ruleset is based on.
|===

For example:
----
{ "main":"ruleset.yaml", "name":"My Mule API Management Best Practices", "organizationId":"68ef9520-24e9-4cf2-b2f5-620025690913", "groupId":"68ef9520-24e9-4cf2-b2f5-620025690913", "assetId":"my-mule-api-management-best-practices", "version":"1.0.0", "classifier":"ruleset", "dependencies":[], "tags":["instances"], "descriptorVersion": "1.0.0" }
----

Use the following command to upload a ruleset and its documentation to Exchange.
Use the following command documentation as a reference as you upload the ruleset and its documentation to Exchange.

include::anypoint-cli::partial$exchange-assets.adoc[tag=exchange-asset-upload,leveloffset=+1]

Expand Down