salesforce Dreamforce On-Demand
Contact Us 1-800-596-4880
  1. Homepage
  2. API Governance
  3. Creating Custom Governance Rulesets

  4. Validating and Publishing Custom Rulesets

Validating and Publishing Custom Rulesets

After you create a custom ruleset:

  1. Validate the ruleset.

  2. Generate the documentation for the ruleset.

  3. Publish your custom ruleset to Exchange as a new asset.

For an example sequence of commands to validate and publish your rulesets, see Example Command Sequence to Validate and Publish.

As with custom code and configurations, rulesets are not considered supported MuleSoft products. For help with issues with custom rulesets, post an issue in the AMF Custom Validator Github repository.

Validate the Ruleset

To validate your governance ruleset as you create it and before you publish it, use the following command:

governance:ruleset:validate

> governance:ruleset:validate [flags] <governance-ruleset>

This command validates the ruleset definitions passed using the governance-ruleset parameter. You can pass one of the following as the governance-ruleset parameter:

  • A ruleset definition YAML file

  • A ZIP file that contains an API project with an exchange.json file that specifies the ruleset as the main file

  • A folder that contains an API project with an exchange.json file that specifies the ruleset as the main file

This command accepts only the default flags.

Example commands:

anypoint-cli-v4 governance:ruleset:validate ~/myrulesetfolder/myruleset.yaml

anypoint-cli-v4 governance:ruleset:validate ~/myrulesetfolder/myruleset.zip

anypoint-cli-v4 governance:ruleset:validate ~/myrulesetfolder/myrulesetfolder

Example output for a valid ruleset:

Ruleset User/myuser/myrulesetfolder/myruleset.yaml
Ruleset conforms with Dialect

Example output for a nonvalid ruleset:

Ruleset does not conform with Dialect
ModelId: file:///Users/myuser/myrulesetfolder/prof-1-bad.yaml
Profile: Validation Profile 1.0
Conforms: false
Number of results: 1

Level: Violation

- Constraint: http://a.ml/amf/default_document#/declarations/profileNode_profile_required_validation
  Message: Property 'profile' is mandatory
  Severity: Violation
  Target: file:///Users/myuser/myrulesetfolder/prof-1-bad.yaml#/encodes
  Property: http://schema.org/name
  Range: [(3,0)-(11,19)]
  Location: file:///Users/myuser/myrulesetfolder/prof-1-bad.yaml

Generate the Ruleset Documentation

Use the following command to generate a documentation ZIP file for a ruleset YAML file. Upload the resulting documentation ZIP file along with its associated ruleset file using the anypoint-cli-v4 exchange asset upload command.

governance:document

> governance:document [flags] <ruleset> <doc-file>

This command creates the documentation for the API Governance ruleset definition ZIP file specified in ruleset. It puts the documentation in the doc-file ZIP file for you to upload and publish to Exchange.

This command accepts only the default flags.

Example command:

anypoint-cli-v4 governance:document /myrulesetfolder/mynewruleset.yaml /myrulesetfolder/ruleset.doc.zip

Example output:

validation name [ 'security-fields-operation-empty' ]
validation name [ 'access-tokens-oauth2-cleartext' ]
validation name [ 'insecure-oauth2-grants' ]
validation name [ 'api-keys-in-cookie' ]
validation name [ 'api-keys-in-query' ]
validation name [ 'api-keys-in-header' ]
validation name [ 'api-negotiates-authentication' ]
validation name [ 'insecure-basic-auth' ]
validation name [ 'bearer-token-cleartext' ]
validation name [ 'http-token-cleartext' ]
validation name [ 'oauth1-deprecated' ]
validation name [ 'oauth2-redirections-non-encrypted' ]
validation name [ 'unknown-security-scheme' ]
validation name [ 'valid-server-urltemplate' ]
validation name [ 'valid-oauth2-redirection-urls' ]
Saving to myRulesetFolder/ruleset.doc.zip

Publish the Custom Ruleset

You can publish (upload) a ruleset and its documentation to Exchange using the following Anypoint CLI command.

exchange:asset:upload

> exchange:asset:upload [flags] <assetIdentifier>

This command uploads a rest-api, soap-api, http-api, raml-fragment, custom, app, template, example, policy, extension, external-library, connector asset, or ruleset using the ID passed in <assetIdentifier>.

Use the following format for the assetIdentifier argument:

([groupID]/)assetID/version

If group_id is not specified, it defaults to the currently selected organization ID.

Flag Description

--name

Asset name (required if no pom file is specified)

For example:

exchange:asset:upload --name "Raml Asset" --description "RAML" --properties='{"apiVersion":"v1", "mainFile": "api.raml"}' --files='{"raml.zip":"​/file-path/raml.zip"}'

--description

Asset description

--properties

Asset properties

For example:

  • --properties='{"mainFile":"main.raml"}'

  • --properties='{"apiVersion":"v1"}'

  • --properties='{"assetLink":"http://api.com"}'

  • --properties='{"mainFile":"main.raml","apiVersion":"v1","assetLink":"http://api.com","contactEmail":"api@mulesoft.com","contactName":"Marc"}'

--files

Asset file, identified as classifier.packaging or packaging and its file path, for example, --files='{"oas.zip":"​/my-api.raml"}'

To send multiple files, you typically use the same flag multiple times:

--files='{"oas.zip": "my-demo-oas.zip"}' --files='{"custom.zip": "~/my-custom-file.zip"}'

An exception to this is when you upload ruleset documentation with a ruleset. Both sets of classifiers and packaging options must be entered in a single --files flag:

--files='{"ruleset.yaml":"/myRulesetFolder/mynewruleset.yaml","docs.zip":"/myRulesetFolder/ruleset.doc.zip"}'

Examples:

To upload a POM file and a RAML specification:

exchange:asset:upload --files'{"pom.xml": "directory/pom-file.xml"}' --files='{"raml.raml": "./my-api.raml"}'

To upload a ruleset and its documentation:

anypoint-cli-v4 exchange asset upload my-auth-best-practices/1.0.0 --name "My Best Practices Ruleset" --description "This ruleset enforces my best practices for APIs." --files='{"ruleset.yaml":"/myRulesetFolder/mynewruleset.yaml","docs.zip":"/myRulesetFolder/ruleset.doc.zip"}'

--type

Asset type

Required if no file is specified.

Supported Values:

  • rest-api

  • soap-api

  • http-api

  • raml-fragment

  • custom

  • connector

  • template

  • example

  • policy

  • app

  • extension

  • external-library

  • ruleset

If it is uploaded, the type is inferred from the classifier of the file.

Depending on the type of asset, some possible classifier values are:

  • REST API

    • oas (with zip, yaml, or json as packaging)

    • raml (with zip or raml as packaging)

  • RAML Fragment

    • raml-fragment (with zip or raml as packaging)

  • SOAP API

    • wsdl (with zip, wsld, or xml as packaging)

  • Custom

    • custom

    • docs (with doc.zip as packaging)

  • Application

    • mule-application (with jar as packaging)

  • Policy

    • mule-policy (with jar as packaging) + policy-definition (with yaml as packaging)

  • Example

    • mule-application-example (with jar as packaging)

  • Template

    • mule-application-template (with jar as packaging)

  • Extension

    • mule-plugin (with jar as packaging)

  • Connector

    • studio-plugin (with zip as packaging) + file with no classifier and packaging jar

  • External Library

    • external-library (with jar as packaging)

  • Ruleset

    • ruleset (with zip or yaml as packaging)

--categories

Categories (value should be a string in JSON format)

'{"key": "value"}'

For example:

'{"Department": "IT"}'

--fields

Fields (value should be a string in JSON format)

'{"key": "value"}'

For example:

'{"releaseDate": "2020-01-01T20:00:00.000Z"}'

--keywords

Keywords (comma-separated)

For example:

raml,rest-api,someKeyword

--tags

Tags (comma-separated)

For example:

api,tag1,tag2

--dependencies

Asset dependencies (comma-separated)

For example:

groupID:assetID:version,groupID2:assetID:version

--status

Asset status

Supported Values:

  • development

  • published

Default value:

  • published

Example Command Sequence to Validate and Publish

Use the following example sequence to get started validating your ruleset, generating its documentation, and uploading both to Exchange. Replace the details, such as the folder name, ruleset file name, and ruleset documentation ZIP file name, with your own.

anypoint-cli-v4 governance:ruleset:validate /myRulesetFolder/mynewruleset.yaml (1)

anypoint-cli-v4 governance:document /myRulesetFolder/mynewruleset.yaml /myRulesetFolder/ruleset.doc.zip (2)

anypoint-cli-v4 exchange asset upload my-auth-best-practices/1.0.0 --name "My Best Practices Ruleset" --description "This ruleset enforces my best practices for APIs." --files='{"ruleset.yaml":"/myRulesetFolder/mynewruleset.yaml", "docs.zip": "/myRulesetFolder/ruleset.doc.zip"}' (3)
1 Validates the ruleset locally. The ruleset file is mynewruleset.yaml in the /myRulesetFolder/ folder.
2 Generates the documentation ZIP file, ruleset.doc.zip, for the ruleset myruleset.yaml. Both files are in the /myRulesetFolder/ folder.
3 Uploads the ruleset, mynewruleset.yaml, and its documentation, ruleset.doc.zip. Both files are in the /myRulesetFolder/ folder.

See Also