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 surface the same trigger in additional UI locations, such as entity creation flows or entity action menus.

Each entry in contexts defines a UI surface where the trigger should appear. Contexts are discriminated by the on field. You can combine multiple contexts on a single trigger node to reach users where they already work in the catalog.

Related documentation

• Workflows overview - how workflows and trigger nodes fit together.
• User inputs - input types, dataset filters, and form configuration (the same concepts apply to workflow trigger userInputs).
• 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

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.

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.