Contexts

By default, a self-service workflow trigger appears on Port's self-service page. Use the optional contexts array on the trigger node's config to control where that trigger appears. You can surface it in additional UI locations, such as entity creation flows or entity action menus, or hide it from the self-service page.

Each entry in contexts is discriminated by the on field. You can combine multiple contexts on a single trigger node.

Related documentation

• Workflows overview - how workflows and trigger nodes fit together.
• User inputs - input types, dataset filters, and form configuration.
• Trigger configuration - full self-service trigger node reference.

JSON structure

contexts is an optional array on the SELF_SERVE_TRIGGER node config, alongside userInputs, permissions, and other fields:

{
  "config": {
    "type": "SELF_SERVE_TRIGGER",
    "userInputs": {
      "properties": {
        "service": {
          "type": "string",
          "format": "entity",
          "blueprint": "service",
          "title": "Service"
        }
      },
      "required": ["service"]
    },
    "contexts": [
      {
        "on": "CREATE_ENTITY",
        "blueprintIdentifier": "microservice"
      },
      {
        "on": "ENTITY",
        "userInput": "service"
      }
    ],
    "variant": "DEFAULT"
  }
}

Context types

SELF_SERVICE_HUB

A published trigger appears on the self-service page unless you hide it. Add a SELF_SERVICE_HUB context with "visible": false to remove it from that page only. The trigger stays published, and users can still run it from the other places listed below.

In the workflow builder, open the trigger and use the Show in Self-Service Hub switch in the Contexts section. The switch is on by default. Turning it off saves a SELF_SERVICE_HUB context with visible set to false. Saving with the switch on leaves that context out, including when it was "visible": true.

Display only

Hiding a trigger from the self-service page leaves it published. Execute permissions and the published field still control who can run it. The self-service triggers API still returns hidden triggers, including their SELF_SERVICE_HUB context.

You can still run a hidden trigger from:

• An entity bolt menu, when the trigger has an ENTITY context.
• The Create new entity dialog, when the trigger has a matching CREATE_ENTITY context.
• Dashboard workflow cards.
• Global search.
• A shared workflow URL, which still opens the run form.
• The API, MCP, and AI agents.

A trigger can use SELF_SERVICE_HUB on its own, with no ENTITY or CREATE_ENTITY context. Use that when the trigger should stay off the self-service page and run only from dashboards, links, the API, MCP, or AI agents.

"visible": true is valid and shows the trigger, the same as omitting this context.

Field	Type	Required	Description
on	string	Yes	Must be SELF_SERVICE_HUB.
visible	boolean	Yes	false hides the trigger from the self-service page. true shows it.

Example

This trigger stays off the self-service page and still appears in the bolt menu for service entities:

{
  "identifier": "sync-service",
  "title": "Sync service",
  "nodes": [
    {
      "identifier": "trigger",
      "title": "Sync service",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "contexts": [
          {
            "on": "SELF_SERVICE_HUB",
            "visible": false
          },
          {
            "on": "ENTITY",
            "userInput": "service"
          }
        ],
        "userInputs": {
          "properties": {
            "service": {
              "type": "string",
              "format": "entity",
              "blueprint": "service",
              "title": "Service"
            }
          },
          "required": ["service"]
        }
      }
    }
  ],
  "connections": []
}

CREATE_ENTITY

When this context is present, the trigger appears as an option when a user clicks Create new entity for the specified blueprint. The behavior mirrors self-service actions with operation: CREATE: if multiple triggers or actions exist for the same blueprint, Port shows a menu so the user can choose one. The trigger form opens in place of the default entity creation form.

Field	Type	Required	Description
on	string	Yes	Must be CREATE_ENTITY.
blueprintIdentifier	string	Yes	Identifier of the blueprint whose Create new entity flow should offer this trigger.

Example

This trigger replaces the default creation form for the microservice blueprint with a guided provisioning workflow:

{
  "identifier": "provision-microservice",
  "title": "Provision microservice",
  "nodes": [
    {
      "identifier": "trigger",
      "title": "Provision microservice",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "contexts": [
          {
            "on": "CREATE_ENTITY",
            "blueprintIdentifier": "microservice"
          }
        ],
        "userInputs": {
          "properties": {
            "name": {
              "type": "string",
              "title": "Service name"
            },
            "team": {
              "type": "string",
              "format": "team",
              "title": "Owning team"
            }
          },
          "required": ["name", "team"]
        }
      }
    }
  ],
  "connections": []
}

ENTITY

When this context is present, the trigger appears in the bolt (⚡) actions menu on entity table rows and entity pages. It is shown only for entities whose blueprint matches the blueprint field of the referenced userInput.

When the user opens the trigger from an entity's bolt menu, Port pre-fills the referenced userInput with that entity's identifier. If the userInput defines a dataset filter, Port evaluates it to decide whether the trigger should appear for that specific entity.

Triggers with an ENTITY context are grouped in the bolt menu by their parent workflow's category.

Field	Type	Required	Description
on	string	Yes	Must be ENTITY.
userInput	string	Yes	Key of a userInputs.properties entry that is an entity-selection input (see limitations).

Example

This trigger appears in the bolt menu for service entities and pre-fills the service input when launched from an entity page or row:

{
  "identifier": "deploy-service",
  "title": "Deploy service",
  "category": "Deployments",
  "nodes": [
    {
      "identifier": "trigger",
      "title": "Deploy service",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "contexts": [
          {
            "on": "ENTITY",
            "userInput": "service"
          }
        ],
        "userInputs": {
          "properties": {
            "service": {
              "type": "string",
              "format": "entity",
              "blueprint": "service",
              "title": "Service"
            },
            "version": {
              "type": "string",
              "title": "Version"
            },
            "environment": {
              "type": "string",
              "title": "Environment",
              "enum": ["staging", "production"]
            }
          },
          "required": ["service", "version", "environment"]
        }
      }
    }
  ],
  "connections": []
}

Example with dataset filter

Only production services see this trigger in the bolt menu. Port evaluates the dataset on the server when deciding visibility per entity:

{
  "identifier": "promote-service",
  "title": "Promote service",
  "nodes": [
    {
      "identifier": "trigger",
      "title": "Promote to production",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "contexts": [
          {
            "on": "ENTITY",
            "userInput": "service"
          }
        ],
        "userInputs": {
          "properties": {
            "service": {
              "type": "string",
              "format": "entity",
              "blueprint": "service",
              "title": "Service",
              "dataset": {
                "combinator": "and",
                "rules": [
                  {
                    "property": "environment",
                    "operator": "=",
                    "value": "staging"
                  }
                ]
              }
            }
          },
          "required": ["service"]
        }
      }
    }
  ],
  "connections": []
}

See entity user input for more on dataset configuration.

Multiple ENTITY contexts

A single trigger can define multiple ENTITY contexts when you need the bolt menu on entities tied to different user inputs (for example, a primary resource and a related resource). Each ENTITY context must reference a different userInput key.

{
  "config": {
    "type": "SELF_SERVE_TRIGGER",
    "contexts": [
      { "on": "ENTITY", "userInput": "service" },
      { "on": "ENTITY", "userInput": "environment" }
    ],
    "userInputs": {
      "properties": {
        "service": {
          "type": "string",
          "format": "entity",
          "blueprint": "service",
          "title": "Service"
        },
        "environment": {
          "type": "string",
          "format": "entity",
          "blueprint": "environment",
          "title": "Environment"
        }
      }
    }
  }
}

Variant

variant is an optional enum on the trigger node config (not on individual context entries). It controls how the trigger is styled in the bolt menu.

Value	Description
DEFAULT	Standard appearance. Used when omitted.
ALERT	Red, destructive styling. Use for dangerous operations such as deletion or irreversible changes.

variant affects presentation in the bolt menu only; it does not change trigger behavior elsewhere (for example, on the self-service page or in Create new entity flows).

Example

{
  "config": {
    "type": "SELF_SERVE_TRIGGER",
    "variant": "ALERT",
    "contexts": [
      {
        "on": "ENTITY",
        "userInput": "service"
      }
    ],
    "userInputs": {
      "properties": {
        "service": {
          "type": "string",
          "format": "entity",
          "blueprint": "service",
          "title": "Service"
        }
      },
      "required": ["service"]
    }
  }
}

Limitations and validations

• userInput must be entity-selection type - For ENTITY contexts, userInput must reference a property in userInputs.properties that is a string with "format": "entity", or an array whose items use "format": "entity". Other input types are not supported.

• Unique userInput per ENTITY context - A trigger may define multiple ENTITY contexts, but each must reference a different userInput key.

• Blueprint must match the entity - An ENTITY context appears in the bolt menu only for entities whose blueprint matches the blueprint on the referenced userInput.

• No duplicate CREATE_ENTITY per blueprint - Multiple CREATE_ENTITY contexts on the same node for the same blueprintIdentifier are not allowed.

• One SELF_SERVICE_HUB context per trigger - A trigger can include at most one SELF_SERVICE_HUB context. A second one is rejected.

• visible must be a boolean - visible is required on a SELF_SERVICE_HUB context. The context is rejected when visible is missing, is not a boolean, or when the object includes any other field.

When a referenced userInput includes a dataset filter, Port evaluates it server-side per entity to determine whether the trigger appears in that entity's bolt menu. This matches how conditions work for Day-2 self-service actions tied to a blueprint.