Skip to main content

Setup trigger

Automation triggers events in your software catalog that you want to act upon.
Port supports two types of triggers:

  • Entity: Triggered when an an entity of a specified blueprint is modified.
  • Action run: Triggered when an action run of a specified action is modified.

Available triggers​

The following trigger events are available for each type:

TriggerDescriptionJSON event type identifier
Entity creationTriggered when any entity based on the selected blueprint is created.ENTITY_CREATED
Entity updateTriggered when any entity based on the selected blueprint is updated.ENTITY_UPDATED
Entity deletionTriggered when any entity based on the selected blueprint is deleted.ENTITY_DELETED
Any entity changeTriggered when any entity based on the selected blueprint is created, updated, or deleted.ANY_ENTITY_CHANGE
Timer expirationTriggered when the selected timer property set on an entity based on the selected blueprint expires.TIMER_PROPERTY_EXPIRED

Trigger JSON structure​

An automation's trigger is defined under the trigger key:

{
  "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):

FieldDescription
typeThe automation's trigger type. Should be set to automation.
eventAn object containing data about the event that triggers the automation.
event.typeThe 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.
conditionAn optional object containing jq expressions used to determine which entities the automation will be triggered for.
condition.typeThe type of condition. Should be set to JQ.
condition.expressionsAn array of expressions used to filter the entities for which the automation will be triggered.
condition.combinatorThe combinator used to combine the expressions. Should be set to and or or.

Conditions​

You can use the condition key to filter the 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:

{
  "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.