Entity

Entity is an input type used to reference existing entities from the software catalog when triggering actions.

💡 Common entity usage

The entity input type can be used to reference any existing entity from the software catalog, for example:

• Cloud regions
• Clusters
• Configurations

In the live demo self-service hub page, we can see the scaffold new service action whose Domain input is an entity input. 🎬

Sorting entities

When using the entity input type, a user executing the action will see a dropdown list of entities from the specified blueprint.
By default, the entities are sorted in ascending order based on the entity's title.

In some cases, you may have a large number of entities and want to sort them based on a specific property.
The entities can be sorted in either ascending or descending order based on a specified property, provided that the property is not of type object or array.

This is done in the action form when creating the entity input, for example:

When executing the action, the entities will be sorted based on the specified property, in the selected order.
In this case, they are sorted by Last Update, descending:

This can also be done when using Port's API, see the sort key in the JSON structure below.

Entity input structure

The entity is represented by the unique entity format and the blueprint key that accompanies it, as shown in the following section:

{
  "myEntityInput": {
    "title": "My entity input",
    "icon": "My icon",
    "description": "My entity input",
    "type": "string",
    "format": "entity",
    "blueprint": "myBp",
    "sort": {
      "property": "propertyIdentifier",
      // order should have either "ASC" or "DESC" value
      "order": "ASC/DESC"
    }
  }
}

Structure table

Field	Description	Notes
"format":"entity"	Used to specify that this is an entity input	Required
"blueprint":"myBp"	Used to specify the identifier of the target blueprint that entities will be queried from	Required. Must specify an existing blueprint identifier
sort	Used to specify the sorting order of the entities in the dropdown	Optional. Default is by entity's title, ascending
sort.property	The identifier of the property by which to sort the entities
sort.order	Can be either ASC (ascending) or DESC (descending)

API definition

Basic

{
  "myEntityInput": {
    "title": "My entity input",
    "icon": "My icon",
    "description": "My entity input",
    "type": "string",
    "format": "entity",
    "blueprint": "myBlueprint",
    "sort": {
      "property": "propertyIdentifier",
      // order should have either "ASC" or "DESC" value
      "order": "ASC/DESC"
    }
  }
}

Array

{
  "EntityArrayInput": {
    "title": "My entity array input",
    "icon": "My icon",
    "description": "My entity array input",
    "type": "array",
    "items": {
      "type": "string",
      "format": "entity",
      "blueprint": "myBlueprint"
    }
  }
}

Check out Port's API reference to learn more.

Terraform definition

Basic

resource "port_action" "myAction" {
  # ...action properties
  user_properties = {
    string_props = {
      "myEntityInput" = {
        title       = "My entity input"
        description = "My entity input"
        format      = "entity"
        blueprint   = "myBlueprint"
      }
    }
  }
}

Array

resource "port_action" "myAction" {
  # ...action properties
  user_properties = {
    array_props = {
      "EntityArrayInput" = {
        title       = "My entity array input"
        description = "My entity array input"
        string_items = {
          format = "entity"
        }
      }
    }
  }
}