W-23907611 docs: draft Policy Write documentation by luanamulesoft · Pull Request #548 · mulesoft/docs-general

luanamulesoft · 2026-08-18T13:24:47Z

Summary

Drafts documentation for the Policy Write initiative (MS2026-08-R2 / Dreamforce), covering all 8 in-scope user stories. Single PR for both affected exp- topics.

exp-governance-policy-library-apply.adoc — rewritten from a fully commented-out draft into an active topic: apply a universal policy template (F1), edit native policies with the two-tier schema/read-only fallback (F2), delete with confirmation (F3), enable/disable (F4), permissions (F5), the in-progress workflow lock (F7), and the read-only out-of-scope state (F6).
exp-services-view-details.adoc — Policies-tab section now notes native-policy management actions and read-only out-of-scope policies, cross-linked to the apply/manage topic.

Grounding

Content is grounded in the mulesoft-omni-app UI code. This is a draft — details that could not be verified in code are flagged inline with TODO(W-23907611) comments and must be confirmed with the PM before the DRAFT banner is removed and the topic is published:

The universal template list + per-gateway native mappings (APIM-owned, not in Omni code).
Which feature flags are ON for GA, per gateway.
The enable/disable gateway support matrix.
Human-readable required permission/role names.
Whether applying policies from the API Instance page is in scope for this release.

AWS write is out of scope for this release.

References

Work item: W-23907611
Gap analysis: Policy Write — Documentation Gap Report (2026-08-18): https://docs.google.com/document/d/1yMPhDBbW1T9AqoDSRus-IsJX-MgRkIjHOg4xAESPg_4/edit

🤖 Generated with Claude Code

Rewrite exp-governance-policy-library-apply.adoc from a fully commented-out draft into an active topic covering the Policy Write scope (MS2026-08-R2): apply a universal policy template, and edit/delete/enable-disable native policies, plus the in-progress workflow lock and read-only out-of-scope state. Update the Policies-tab section of exp-services-view-details.adoc to note the new native-policy management actions and read-only out-of-scope policies, and cross-link to the apply/manage topic. Content is grounded in the mulesoft-omni-app UI code. Details that could not be verified in code (universal template list + per-gateway native mappings, GA feature flags, enable/disable support matrix, permission role names, and the API Instance page apply entry point) are marked with TODO(W-23907611) comments for PM confirmation before publishing. Gap analysis: Policy Write — Documentation Gap Report (2026-08-18). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…-policy-write # Conflicts: # modules/ROOT/pages/exp-governance-policy-library-apply.adoc

…hose instances

Add coverage for the Activity log tab surfaced by the two additional scope PRDs (Policy Write / Unified Policy Catalog) and verified in code (ActivitiesTab.tsx, activitiesTab i18n). Applies are asynchronous and tracked (Apply/Update/Toggle/Remove; Running/Completed/Failed). Cross-linked from the apply flow and the instance Policies tab. Left as DRAFT with a TODO on the feature-flag/external-provider gating and no actor field (not a full audit trail). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…ections Consolidate the external/universal policies documentation from PR 556 into this branch, and apply the SME review corrections from PR 556: - Universal-derived native policies are editable, not view-only (glossary, exp-policies-universal, exp-policies-apply-manage) - Anypoint gateways are Omni (Flex) and Mule; fix gateway-type wording - Instance locking is Apigee/Azure-wide; Kong locks only the one policy - Policy naming is an Apigee-only feature - Acknowledge the additional supported native Kong policies alongside the universal use cases (soften absolute "view-only" statements) - Apigee roles are one option, not required (reword) Flag the internal-error edit-restriction case inline for PM/eng. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

luanamulesoft · 2026-08-28T17:56:33Z

+Having permissions is necessary but not sufficient to edit a policy. Anypoint supports editing the curated set of policies that back the universal use cases, plus several additional native Kong policies (see xref:exp-policies-universal.adoc[]); other recognized policies are view-only. Native policies created from a universal use case are editable like any other supported native policy. When *Edit Configuration* is unavailable, the UI explains why. Common reasons include:
+
+* Anypoint doesn't recognize the policy's template, or doesn't yet support managing policies with its schema.
+* The policy's configuration doesn't match its expected schema. To resolve this issue, open a support case.


@sparshagarwal-nonemu, can you confirm if we should document it or remove it?

luanamulesoft · 2026-08-28T18:06:33Z

 A lighter-weight instance deployment that does not route traffic through Omni Gateway. Choose unmanaged instances when a full managed path does not match your operating model.
+
+Universal (canonical) policy::
+A provider-agnostic policy you configure once and apply across a mix of gateway providers. Anypoint translates a universal policy into each provider's native policy. Universal is a creation experience, not a managed entity: after you apply it, only native policies exist. Those native policies behave like any other native policy on the provider. You can edit, remove, enable, or disable them where the provider supports those actions. In the UI, universal policies carry a *Universal* badge.


Applied feedback:
"Once the universal policy is applied as native, the native is not read-only. It can be editable or deleteable"

luanamulesoft · 2026-08-28T18:07:31Z

+= Applying and Managing Policies
+:keywords: apply policy, edit policy, remove policy, enable policy, disable policy, external gateways, api manager, anypoint platform
+
+Apply, edit, enable, disable, and remove policies on an API instance from the *Policies* tab in *Portfolio*. These actions work on Anypoint gateways (Omni and Mule), and on external providers such as Google Apigee, Azure API Management, and Kong Gateway, subject to per-provider support. See xref:exp-policies-provider-reference.adoc[].


Applied feedback:
"Anypoint gateways can be Omni (aka Flex) or Mule Gateways. Both apply here."

luanamulesoft · 2026-08-28T18:08:57Z

+* *Enable Policy* / *Disable Policy* toggle a policy on or off. Apigee and Azure API Management have no native enable/disable state, so these actions aren't available there. See xref:exp-policies-provider-reference.adoc#supported-actions-by-provider[Supported Actions by Provider].
+* *Remove Policy* detaches the policy from the instance. 
+
+While an operation is in progress, the provider locks further changes until it finishes. The scope of that lock differs by provider: Apigee and Azure API Management lock the entire instance, so no other policy operation on that instance can start until the current one completes; Kong Gateway locks only the policy being changed, so you can work with other policies on the same instance at the same time. You can track progress in the *Activity log*. See xref:exp-policies-provider-reference.adoc#instance-locking-during-operations[Instance Locking During Operations].


Applied feedback:
"This is true just for APIGee and Microsoft Azure"

luanamulesoft · 2026-08-28T18:12:18Z

+[[policy-naming-and-identity]]
+== Policy Naming and Identity
+
+Policy naming applies to Apigee only. Other providers don't use policy names, and you aren't required to enter one. On Apigee, the name is the policy's unique identity on the gateway, not just a label:


Applied feedback:
"The policy name is only a APIGee feature, other providers do not use policy names and the users are not required add a name to the policy"

luanamulesoft · 2026-08-28T18:40:19Z

+
+== How Policy Operations Work
+
+Every policy change on an external provider, such as apply, edit, enable, disable, or remove, runs asynchronously: Anypoint accepts the request and performs the work on the provider in the background. Because an accepted request isn't the same as an applied policy, confirm the outcome in the Activity log tab for the API instance. See xref:exp-policies-activity-log.adoc[].


For this feedback:
"Redundant? I already read this previously? I'd rather have more than have less, but again this paragraph is very similar to the one in the activity log section"
I rewrote the paragraph so it's not exactly the same, but left it as an introduction, as this is the Overview page.

luanamulesoft · 2026-08-28T18:42:12Z

+* `apigee.deployments.list`
+* `apigee.deployments.create`
+
+To get these permissions, you can use one of these predefined Apigee roles:


Applied feedback:
"Change use one of these predefined Apigee roles to one of these predefined Apigee roles can be used (or similar)."

luanamulesoft · 2026-08-28T18:44:40Z

+* IP Allowlist
+* JWT Validation
+
+These are the primary policies you can create and edit across providers. Anypoint also supports several additional native Kong policies. See xref:exp-policies-provider-reference.adoc#supported-policies-and-native-equivalents[Supported Policies and Native Equivalents]. Other recognized policies are view-only. See xref:exp-policies-apply-manage.adoc#policy-edit-restrictions[Policy Edit Restrictions].


Applied feedback:
"Every other recognized policy is view-only
Not entirely true, we also have a bunch of other Kong policies (already mentioned before in the docs)"

luanamulesoft · 2026-08-28T18:46:24Z

+
+Use a universal policy to implement a use case across multiple native gateways from a single starting point. Only native policies remain on each provider. No separate universal object exists, so you can't edit or remove it.
+
+After creation, the resulting native policies behave like any other native policy on each provider. From the *Policies* tab, you can edit, remove, enable, or disable them where the provider supports those actions. There is no universal object to manage separately.


Appplied feedback:
"Because the resulting native policies came from a universal template, they display as view-only.
Not true. In fact, the opposite should be true. Native policies coming from universal application most generally would be editable. I would just not mention the view-only part."

luanamulesoft · 2026-08-28T18:47:19Z

+
+|Scope
+|Multi-provider, applied to the instances you select.
+|Anypoint native (Omni and Mule), applied automatically by matching rules.


Applied feedback:
"Anypoint and Mule.

Same thing as before. Anypoint is not a gateway type, Omni (aka Flex) is. You can say Anypoint native (Omni and Mule) or similar instead"

luanamulesoft requested a review from a team as a code owner August 18, 2026 13:24

luanamulesoft and others added 9 commits August 18, 2026 16:53

Merge remote-tracking branch 'origin/latest' into W-23907611-document…

fefd751

…-policy-write # Conflicts: # modules/ROOT/pages/exp-governance-policy-library-apply.adoc

Jenny added updates for the write policies for API gateway scanners

46c5e56

Amazon out of scope for write policy support in R2 release. Removed t…

5024057

…hose instances

Update exp-policies-apply-manage.adoc

e9452c4

Update exp-policies-overview.adoc

ae4be75

fixed apply policy steps

a85d106

changed title

afc8785

luanamulesoft commented Aug 28, 2026

View reviewed changes

Navigation Menu

Uh oh!

W-23907611 docs: draft Policy Write documentation - #548

W-23907611 docs: draft Policy Write documentation#548
luanamulesoft wants to merge 10 commits into
latestfrom
W-23907611-document-policy-write

luanamulesoft commented Aug 18, 2026

Uh oh!

luanamulesoft Aug 28, 2026

Uh oh!

luanamulesoft Aug 28, 2026

Uh oh!

luanamulesoft Aug 28, 2026

Uh oh!

luanamulesoft Aug 28, 2026

Uh oh!

luanamulesoft Aug 28, 2026

Uh oh!

luanamulesoft Aug 28, 2026

Uh oh!

luanamulesoft Aug 28, 2026

Uh oh!

luanamulesoft Aug 28, 2026

Uh oh!

luanamulesoft Aug 28, 2026

Uh oh!

luanamulesoft Aug 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		== How Policy Operations Work

		Every policy change on an external provider, such as apply, edit, enable, disable, or remove, runs asynchronously: Anypoint accepts the request and performs the work on the provider in the background. Because an accepted request isn't the same as an applied policy, confirm the outcome in the Activity log tab for the API instance. See xref:exp-policies-activity-log.adoc[].


		Use a universal policy to implement a use case across multiple native gateways from a single starting point. Only native policies remain on each provider. No separate universal object exists, so you can't edit or remove it.

		After creation, the resulting native policies behave like any other native policy on each provider. From the Policies tab, you can edit, remove, enable, or disable them where the provider supports those actions. There is no universal object to manage separately.

Uh oh!

Conversation

luanamulesoft commented Aug 18, 2026

Summary

Grounding

References

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants