Set up trigger

After specifying your automation’s basic details, the next step in the automation definition process is to choose a trigger for the automation. Triggers are events in your software catalog that initiate an automation when they occur.

Port supports two types of triggers:

Entity: Triggered when an entity of a specified blueprint is modified.
If you select an entity trigger, you will need to specify the relevant blueprint.
Action run: Triggered when an action run of a specified action is modified.
If you select an action run trigger, you will need to specify the corresponding action.

In the second tab of the creation form, the Trigger tab, choose the automation's trigger.

Available triggers

The following trigger events are available for each type:

Entity
Action run

Trigger	Description	JSON event type identifier
Entity creation	Triggered when any entity based on the selected blueprint is created.	`ENTITY_CREATED`
Entity update	Triggered when any entity based on the selected blueprint is updated.	`ENTITY_UPDATED`
Entity deletion	Triggered when any entity based on the selected blueprint is deleted.	`ENTITY_DELETED`
Any entity change	Triggered when any entity based on the selected blueprint is changed: created, updated, or deleted.	`ANY_ENTITY_CHANGE`
Timer expiration	Triggered when the selected timer property set on an entity based on the selected blueprint expires.	`TIMER_PROPERTY_EXPIRED`

Trigger	Description	JSON event type identifier
Action run creation	Triggered when an action run is created. In other words, whenever the specified action is executed.	`RUN_CREATED`
Action run update	Triggered when an action run is updated: patched or approved. Note that sending logs to the action run will not count as a trigger.	`RUN_UPDATED`
Any action run change	Triggered when an action run is changed: created, patched, or approved.	`ANY_RUN_CHANGE`

Limitations

Regarding the Any entity change trigger:

When a mirror property on the entity changes, the automation will not be triggered.
However, if the target of the relation changes from one entity to another, the automation will be triggered.
When a calculation property based on a mirror property changes, the automation will not be triggered.

When a related entity is deleted, the automation will not be triggered on the entity that has a relation to the deleted entity.

Example scenario

Consider an automation that triggers when a developmentenv entity's namespace relation becomes null:

Example automation (click to expand)

{
  "identifier": "delete_developmentenv_entity_on_relation_change",
  "title": "Delete developer env when namespace becomes null",
  "trigger": {
    "type": "automation",
    "event": {
      "type": "ANY_ENTITY_CHANGE",
      "blueprintIdentifier": "developmentenv"
    },
    "condition": {
      "type": "JQ",
      "expressions": [
        ".diff.after.relations.namespace == null",
        ".diff.before.relations.namespace != null"
      ],
      "combinator": "and"
    }
  },
  "invocationMethod": {
    "type": "WEBHOOK",
    "url": "https://api.getport.io/v1/blueprints/developmentenv/entities/{{ .event.context.entityIdentifier}}",
    "synchronized": true,
    "method": "DELETE",
    "headers": {
      "Content-type": "application/json",
      "RUN_ID": "{{ .run.id }}"
    }
  },
  "publish": true
}

This automation will not be triggered in the following cases:

When a related entity of a developmentenv entity is deleted (causing the relation to become null).
When the source value of a developmentenv entity's mirror property changes.

Conditions

Once you choose your Trigger and the relevant Blueprint or Action, you can optionally define a Condition at the bottom of the widget. This condition allows you to filter entities for which the automation will be triggered.

The following condition example contains a single expression that will cause the automation to trigger only for entities with a status property set to Active:

"condition": {
  "type": "JQ",
  "expressions": [
    ".diff.after.properties.status == \"Active\""
  ],
  "combinator": "and"
}

The data that is available to you when writing expressions contains useful information about the entity and the event that triggered the automation.

Here is an example of what this object could look like for an automation that triggers whenever a service entity is updated:

Automation JSON file example (Click to expand)

{
  "action": "UPDATE",
  "resourceType": "entity",
  "trigger": {
    "by": {
      "orgId": "org_BneDtWovPqXaA2VZ",
      "userId": "auth0|62ceaea697ca00f09d7c4f45"
    },
    "origin": "UI",
    "at": "2024-06-09T12:28:18.477Z"
  },
  "context": {
    "blueprintIdentifier": "service",
    "entityIdentifier": "example-service-identifier",
    "propertyIdentifier": null
  },
  "diff": {
    "before": {
      "identifier": "example-service-identifier",
      "title": "Example service",
      "icon": null,
      "blueprint": "service",
      "team": [
        "Rocket"
      ],
      "properties": {
        "latestVersion": "12.8.2",
        "language": "TypeScript",
        "one_hop_service_language": "Ruby",
        "two_hops_service_language": "Ruby",
        "repo": "https://github.com/some-org/example-service"
      },
      "relations": {
        "using": "rogue-service"
      },
      "createdAt": "2024-06-09T09:57:52.931Z",
      "createdBy": "60EsooJtOqimlekxrNh7nfr2iOgTcyLZ",
      "updatedAt": "2024-06-09T09:57:52.931Z",
      "updatedBy": "60EsooJtOqimlekxrNh7nfr2iOgTcyLZ"
    },
    "after": {
      "identifier": "example-service-identifier",
      "title": "Example service renamed",
      "icon": "Microservice",
      "blueprint": "service",
      "team": [
        "Rocket"
      ],
      "properties": {
        "latestVersion": "12.8.22",
        "language": "Python",
        "one_hop_service_language": "Ruby",
        "two_hops_service_language": "Ruby",
        "repo": "https://github.com/some-org/example-service"
      },
      "relations": {
        "using": "rogue-service"
      },
      "createdAt": "2024-06-09T09:57:52.931Z",
      "createdBy": "60EsooJtOqimlekxrNh7nfr2iOgTcyLZ",
      "updatedAt": "2024-06-09T12:28:18.628Z",
      "updatedBy": "auth0|62ceaea697ca00f09d7c4f45"
    }
  }
}

The example above is for an automation that uses the ENTITY_UPDATED trigger event. The diff object contains data from before and after the update.

The other trigger events have the same structure, with the following differences:

ENTITY_CREATED - In the diff object, before will be null, and after will contain the new entity data.
ENTITY_DELETED - In the diff object, before will contain the entity data before deletion, and after will be null.
ANY_ENTITY_CHANGE - The diff object will contain before and after data according to the entity change.
TIMER_PROPERTY_EXPIRED - In the diff object, there will be an after object containing the entity data.

Trigger JSON structure

In some cases, you may prefer to define the trigger using a JSON object.
The trigger is defined under the trigger object in the automation's JSON structure.

{
  "identifier": "unique_id",
  "title": "Title",
  "icon": "icon_identifier",
  "description": "automation description",
  "trigger": {
    "type": "automation",
    "event": {
      "type": "event_type",
      // Only one of "blueprintIdentifier" or "actionIdentifier" should be present depending on the trigger type
      "blueprintIdentifier": "blueprint_id",
      // OR
      "actionIdentifier": "action_id"
    },
    "condition": {
      "type": "JQ",
      "expressions": ["expression1", "expression2"],
      "combinator": "and"
    }
  },
  "invocationMethod": {
    "type": "WEBHOOK",
    "url": "https://example.com"
  },
  "publish": false
}

The table below describes the fields in the JSON structure under the trigger key (fields in bold are required):

Field	Description
`type`	The automation's trigger type. Should be set to `automation`.
`event`	An object containing data about the event that triggers the automation.
`event.type`	The trigger event type.
`event.blueprintIdentifier` or `event.actionIdentifier`	If using an entity trigger - the identifier of the blueprint whose entities will trigger the automation. If using an action run trigger - the identifier of the action whose runs will trigger the automation.
`condition`	An optional object containing `jq` expressions used to determine which entities the automation will be triggered for.
`condition.type`	The type of condition. Should be set to `JQ`.
`condition.expressions`	An array of expressions used to filter the entities for which the automation will be triggered.
`condition.combinator`	The combinator used to combine the expressions. Should be set to `and` or `or`.

Available triggers​

Limitations​

Example scenario

Conditions​

Trigger JSON structure​

Available triggers

Limitations

Conditions

Trigger JSON structure