Skip to main content

Examples

Mapping projects​

In the following example you will ingest your Azure Devops projects and their default team (Optional) to Port, you may use the following Port blueprint definitions and integration configuration:

Project blueprint

  {
    "identifier": "project",
    "title": "Project",
    "icon": "AzureDevops",
    "schema": {
      "properties": {
        "state": {
          "title": "State",
          "type": "string",
          "icon": "AzureDevops",
          "description": "The current lifecycle state of the project."
        },
        "revision": {
          "title": "Revision",
          "type": "string",
          "icon": "AzureDevops",
          "description": "The revision number, indicating how many times the project configuration has been updated."
        },
        "visibility": {
          "title": "Visibility",
          "type": "string",
          "icon": "AzureDevops",
          "description": "Indicates whether the project is private or public"
        },
        "defaultTeam": {
          "title": "Default Team",
          "type": "string",
          "icon": "Team",
          "description": "Default Team of the project"
        },
        "link": {
          "title": "Link",
          "type": "string",
          "format": "url",
          "icon": "AzureDevops",
          "description": "Link to azure devops project"
        }
      },
      "required": []
    },
    "mirrorProperties": {},
    "calculationProperties": {},
    "aggregationProperties": {},
    "relations": {}
  }
Ocean integration configuration 
resources:
  - kind: project
    selector:
      query: 'true'
      defaultTeam: "false"
    port:
      entity:
        mappings:
          identifier: '.id | gsub(" "; "")'
          blueprint: '"project"'
          title: .name
          properties:
            state: '.state'
            revision: '.revision'
            visibility: '.visibility'
            defaultTeam: '.defaultTeam.name'
            link: '.url | gsub("_apis/projects/"; "")'

To Learn more
  • Click Here for the Azure Devops project object structure.
  • Click Here for the Azure Devops project object structure when defaultTeam is set to true.

Mapping repositories, file contents, repository policies and pull requests​

In the following example you will ingest your Azure Devops repositories, their README.md file contents and pull requests to Port, you may use the following Port blueprint definitions and integration configuration:

Project blueprint

  {
    "identifier": "project",
    "title": "Project",
    "icon": "AzureDevops",
    "schema": {
      "properties": {
        "state": {
          "title": "State",
          "type": "string",
          "icon": "AzureDevops",
          "description": "The current lifecycle state of the project."
        },
        "revision": {
          "title": "Revision",
          "type": "string",
          "icon": "AzureDevops",
          "description": "The revision number, indicating how many times the project configuration has been updated."
        },
        "visibility": {
          "title": "Visibility",
          "type": "string",
          "icon": "AzureDevops",
          "description": "Indicates whether the project is private or public"
        },
        "defaultTeam": {
          "title": "Default Team",
          "type": "string",
          "icon": "Team",
          "description": "Default Team of the project"
        },
        "link": {
          "title": "Link",
          "type": "string",
          "format": "url",
          "icon": "AzureDevops",
          "description": "Link to azure devops project"
        }
      },
      "required": []
    },
    "mirrorProperties": {},
    "calculationProperties": {},
    "aggregationProperties": {},
    "relations": {}
  }
Repository blueprint
{
  "identifier": "azureDevopsRepository",
  "title": "Repository",
  "icon": "AzureDevops",
  "schema": {
    "properties": {
      "url": {
        "title": "URL",
        "format": "url",
        "type": "string",
        "icon": "Link"
      },
      "readme": {
        "title": "README",
        "type": "string",
        "format": "markdown",
        "icon": "Book"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "project": {
      "title": "Project",
      "target": "project",
      "required": true,
      "many": false
    }
  }
}
Pull request blueprint
{
  "identifier": "azureDevopsPullRequest",
  "title": "Pull Request",
  "icon": "AzureDevops",
  "schema": {
    "properties": {
      "creator": {
        "title": "Creator",
        "type": "string"
      },
      "status": {
        "title": "Status",
        "type": "string",
        "enum": [
          "completed",
          "abandoned",
          "active"
        ],
        "enumColors": {
          "completed": "yellow",
          "abandoned": "red",
          "active": "green"
        }
      },
      "reviewers": {
        "type": "array",
        "title": "Reviewers",
        "items": {
          "type": "string",
          "format": "user"
        }
      },
      "createdAt": {
        "title": "Create At",
        "type": "string",
        "format": "date-time"
      },
      "link": {
        "title": "Link",
        "format": "url",
        "type": "string"
      },
      "leadTimeHours": {
        "title": "Lead Time in hours",
        "type": "number"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "repository": {
      "title": "repository",
      "target": "azureDevopsRepository",
      "required": false,
      "many": false
    }
  }
}
Ocean integration configuration 
resources:
  - kind: project
    selector:
      query: 'true'
      defaultTeam: "false"
    port:
      entity:
        mappings:
          identifier: '.id | gsub(" "; "")'
          blueprint: '"project"'
          title: .name
          properties:
            state: '.state'
            revision: '.revision'
            visibility: '.visibility'
            defaultTeam: '.defaultTeam.name'
            link: '.url | gsub("_apis/projects/"; "")'
  - kind: repository
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: '.project.name + "/" + .name | gsub(" "; "")'
          title: .name
          blueprint: '"azureDevopsRepository"'
          properties:
            url: .url
            readme: file://README.md
          relations:
            project: .project.id | gsub(" "; "")
  - kind: repository-policy
    selector:
      query: .type.displayName=="Minimum number of reviewers"
    port:
      entity:
        mappings:
          identifier: '.__repository.project.name + "/" + .__repository.name | gsub(" "; "")'
          blueprint: '"azureDevopsRepository"'
          properties:
            minimumApproverCount: .settings.minimumApproverCount
  - kind: repository-policy
    selector:
      query: .type.displayName=="Work item linking"
    port:
      entity:
        mappings:
          identifier: '.__repository.project.name + "/" + .__repository.name | gsub(" "; "")'
          blueprint: '"azureDevopsRepository"'
          properties:
            workItemLinking: .isEnabled and .isBlocking
  - kind: pull-request
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: >-
            .repository.project.name + "/" + .repository.name + (.pullRequestId
            | tostring) | gsub(" "; "")
          blueprint: '"azureDevopsPullRequest"'
          properties:
            creator: .createdBy.uniqueName
            status: .status
            reviewers: '[.reviewers[].uniqueName]'
            createdAt: .creationDate
            leadTimeHours: >-
              (.creationDate as $createdAt | .status as $status | .closedDate as $closedAt |
              ($createdAt | sub("\\..*Z$"; "Z") | strptime("%Y-%m-%dT%H:%M:%SZ") | mktime) as $createdTimestamp |
              ($closedAt | if . == null then null else sub("\\..*Z$"; "Z") |
              strptime("%Y-%m-%dT%H:%M:%SZ") | mktime end) as $closedTimestamp |
              if $status == "completed" and $closedTimestamp != null then
              (((($closedTimestamp - $createdTimestamp) / 3600) * 100 | floor) / 100)
              else null end)
          relations:
            repository: '.repository.project.name + "/" + .repository.name | gsub(" "; "")'
To Learn more
  • Refer to the setup section to learn more about the integration configuration setup process.
  • We leverage JQ JSON processor to map and transform Azure Devops objects to Port entities.
  • Click Here for the Azure Devops repository object structure.
  • Click Here for the Azure Devops repository-policy object structure.
  • Click Here for the Azure Devops pull-request object structure.

After creating the blueprints and saving the integration configuration, you will see new entities in Port matching your repositories alongside their README.md file contents and pull requests.

Mapping pipelines​

In the following example you will ingest your Azure Devops pipelines to Port, you may use the following Port blueprint definitions and integration configuration:

Project blueprint

  {
    "identifier": "project",
    "title": "Project",
    "icon": "AzureDevops",
    "schema": {
      "properties": {
        "state": {
          "title": "State",
          "type": "string",
          "icon": "AzureDevops",
          "description": "The current lifecycle state of the project."
        },
        "revision": {
          "title": "Revision",
          "type": "string",
          "icon": "AzureDevops",
          "description": "The revision number, indicating how many times the project configuration has been updated."
        },
        "visibility": {
          "title": "Visibility",
          "type": "string",
          "icon": "AzureDevops",
          "description": "Indicates whether the project is private or public"
        },
        "defaultTeam": {
          "title": "Default Team",
          "type": "string",
          "icon": "Team",
          "description": "Default Team of the project"
        },
        "link": {
          "title": "Link",
          "type": "string",
          "format": "url",
          "icon": "AzureDevops",
          "description": "Link to azure devops project"
        }
      },
      "required": []
    },
    "mirrorProperties": {},
    "calculationProperties": {},
    "aggregationProperties": {},
    "relations": {}
  }
Pipeline blueprint
{
  "identifier": "azureDevopsPipeline",
  "title": "Pipeline",
  "icon": "AzureDevops",
  "schema": {
    "properties": {
      "url": {
        "type": "string",
        "format": "url",
        "title": "URL"
      },
      "revision": {
        "type": "number",
        "title": "Revision"
      },
      "folder": {
        "title": "Folder",
        "type": "string"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "project": {
      "title": "Project",
      "target": "project",
      "required": true,
      "many": false
    }
  }
}
Ocean integration configuration
resources:
  - kind: project
    selector:
      query: 'true'
      defaultTeam: "false"
    port:
      entity:
        mappings:
          identifier: '.id | gsub(" "; "")'
          blueprint: '"project"'
          title: .name
          properties:
            state: '.state'
            revision: '.revision'
            visibility": '.visibility'
            defaultTeam: '.defaultTeam.name'
            link: '.url | gsub("_apis/projects/"; "")'
  - kind: pipeline
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id | tostring
          title: .name
          blueprint: '"azureDevopsPipeline"'
          properties:
            url: .url
            revision: .revision
            folder: .folder
          relations:
            project: '.__projectId | gsub(" "; "")'

To Learn more
  • Refer to the setup section to learn more about the integration configuration setup process.
  • We leverage JQ JSON processor to map and transform Azure Devops objects to Port entities.
  • Click Here for the Azure Devops pipeline object structure.

After creating the blueprints and saving the integration configuration, you will see new entities in Port.

Mapping teams and members​

In the following example you will ingest your Azure Devops teams and their members to Port, you may use the following Port blueprint definitions and integration configuration:

Project blueprint

  {
    "identifier": "project",
    "title": "Project",
    "icon": "AzureDevops",
    "schema": {
      "properties": {
        "state": {
          "title": "State",
          "type": "string",
          "icon": "AzureDevops",
          "description": "The current lifecycle state of the project."
        },
        "revision": {
          "title": "Revision",
          "type": "string",
          "icon": "AzureDevops",
          "description": "The revision number, indicating how many times the project configuration has been updated."
        },
        "visibility": {
          "title": "Visibility",
          "type": "string",
          "icon": "AzureDevops",
          "description": "Indicates whether the project is private or public"
        },
        "defaultTeam": {
          "title": "Default Team",
          "type": "string",
          "icon": "Team",
          "description": "Default Team of the project"
        },
        "link": {
          "title": "Link",
          "type": "string",
          "format": "url",
          "icon": "AzureDevops",
          "description": "Link to azure devops project"
        }
      },
      "required": []
    },
    "mirrorProperties": {},
    "calculationProperties": {},
    "aggregationProperties": {},
    "relations": {}
  }
Repository blueprint
{
  "identifier": "azureDevopsRepository",
  "title": "Repository",
  "icon": "AzureDevops",
  "schema": {
    "properties": {
      "url": {
        "title": "URL",
        "format": "url",
        "type": "string",
        "icon": "Link"
      },
      "readme": {
        "title": "README",
        "type": "string",
        "format": "markdown",
        "icon": "Book"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "project": {
      "title": "Project",
      "target": "project",
      "required": true,
      "many": false
    }
  }
}
Team blueprint
{
  "identifier": "azureDevopsTeam",
  "title": "Azure Devops Team",
  "icon": "AzureDevops",
  "schema": {
    "properties": {
      "url": {
        "icon": "Link",
        "title": "URL",
        "type": "string",
        "format": "url"
      },
      "description": {
        "title": "Description",
        "type": "string",
        "icon": "DefaultProperty"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "project": {
      "title": "Project",
      "target": "project",
      "required": true,
      "many": false
    }
  }
}
Member blueprint
{
  "identifier": "azureDevopsMember",
  "title": "Azure Devops Member",
  "icon": "AzureDevops",
  "schema": {
    "properties": {
      "email": {
        "title": "Email",
        "type": "string",
        "format": "user",
        "icon": "DefaultProperty"
      },
      "url": {
        "icon": "Link",
        "title": "URL",
        "type": "string",
        "format": "url"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "team": {
      "title": "team",
      "target": "azureDevopsTeam",
      "required": false,
      "many": false
    }
  }
}
Ocean integration configuration 
resources:
  - kind: project
    selector:
      query: 'true'
      defaultTeam: "false"
    port:
      entity:
        mappings:
          identifier: '.id | gsub(" "; "")'
          blueprint: '"project"'
          title: .name
          properties:
            state: '.state'
            revision: '.revision'
            visibility: '.visibility'
            defaultTeam: '.defaultTeam.name'
            link: '.url | gsub("_apis/projects/"; "")'
  - kind: repository
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: '.project.name + "/" + .name | gsub(" "; "")'
          title: .name
          blueprint: '"azureDevopsRepository"'
          properties:
            url: .url
            readme: file://README.md
          relations:
            project: .project.id | gsub(" "; "")
  - kind: repository-policy
    selector:
      query: .type.displayName=="Minimum number of reviewers"
    port:
      entity:
        mappings:
          identifier: '.__repository.project.name + "/" + .__repository.name | gsub(" "; "")'
          blueprint: '"azureDevopsRepository"'
          properties:
            minimumApproverCount: .settings.minimumApproverCount
  - kind: repository-policy
    selector:
      query: .type.displayName=="Work item linking"
    port:
      entity:
        mappings:
          identifier: '.__repository.project.name + "/" + .__repository.name | gsub(" "; "")'
          blueprint: '"azureDevopsRepository"'
          properties:
            workItemLinking: .isEnabled and .isBlocking
  - kind: team
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"azureDevopsTeam"'
          properties:
            url: .url
            description: .description
          relations:
            project: .projectId | gsub(" "; "")
  - kind: member
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .identity.uniqueName + "-" + .__teamId
          title: .identity.displayName
          blueprint: '"azureDevopsMember"'
          properties:
            url: .identity.url
            email: .identity.uniqueName
          relations:
            team: .__teamId
To Learn more
  • Refer to the setup section to learn more about the integration configuration setup process.
  • We leverage JQ JSON processor to map and transform Azure Devops objects to Port entities.
  • Click Here for the Azure Devops team object structure.
  • Click Here for the Azure Devops team member object structure.

After creating the blueprints and saving the integration configuration, you will see new entities in Port matching your teams alongside their members.

Mapping Work Items​

In the following example you will ingest your Azure Devops work items to Port, you may use the following Port blueprint definitions and integration configuration:

Work item blueprint
{
  "identifier": "workItem",
  "title": "Work Item",
  "icon": "AzureDevops",
  "schema": {
    "properties": {
      "type": {
        "title": "Type",
        "type": "string",
        "icon": "AzureDevops",
        "description": "The type of work item (e.g., Bug, Task, User Story)",
        "enum": ["Issue", "Epic", "Task"],
        "enumColors": {
          "Issue": "green",
          "Epic": "orange",
          "Task": "blue"
        }
      },
      "state": {
        "title": "State",
        "type": "string",
        "icon": "AzureDevops",
        "description": "The current state of the work item (e.g., New, Active, Closed)"
      },
      "reason": {
        "title": "Reason",
        "type": "string",
        "description": "The title of the work item"
      },
      "effort": {
        "title": "Effort",
        "type": "number",
        "description": "The estimated effort for the work item"
      },
      "description": {
        "title": "Description",
        "type": "string",
        "format": "markdown",
        "description": "A detailed description of the work item"
      },
      "link": {
        "title": "Link",
        "type": "string",
        "format": "url",
        "icon": "AzureDevops",
        "description": "Link to the work item in Azure DevOps"
      },
      "createdBy": {
        "title": "Created By",
        "type": "string",
        "icon": "User",
        "description": "The person who created the work item"
      },
      "changedBy": {
        "title": "Changed By",
        "type": "string",
        "icon": "User",
        "description": "The person who last changed the work item"
      },
      "assignedTo": {
        "title": "Assigned To",
        "type": "string",
        "icon": "User",
        "description": "The person assigned to this work item"
      },
      "createdDate": {
        "title": "Created Date",
        "type": "string",
        "format": "date-time",
        "description": "The date and time when the work item was created"
      },
      "changedDate": {
        "title": "Changed Date",
        "type": "string",
        "format": "date-time",
        "description": "The date and time when the work item was last changed"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "project": {
      "title": "Project",
      "target": "project",
      "required": true,
      "many": false
    }
  }
}
Ocean integration configuration 
resources:
  - kind: work-item
    selector:
      query: 'true'
      wiql: '[System.WorkItemType] = "Task" order by [System.CreatedDate] desc'
    port:
      entity:
        mappings:
          identifier: .id | tostring
          title: .fields."System.Title"
          blueprint: '"workItem"'
          properties:
            type: .fields."System.WorkItemType"
            state: .fields."System.State"
            effort: .fields."Microsoft.VSTS.Scheduling.Effort"
            description: .fields."System.Description"
            link: .url
            reason: .fields."System.Reason"
            createdBy: .fields."System.CreatedBy".displayName
            changedBy: .fields."System.ChangedBy".displayName
            assignedTo: .fields."System.AssignedTo".displayName
            createdDate: .fields."System.CreatedDate"
            changedDate: .fields."System.ChangedDate"
          relations:
            project: .__projectId | gsub(" "; "")

To Learn more
  • Click Here for the Azure Devops work item object structure.
  • Click Here for WIQL clauses

Mapping boards​

The example below shows how to ingest Azure DevOps Boards into Port.
You can use the following Port blueprint definitions and integration configuration:

Board blueprint
{
  "identifier": "board",
  "title": "Board",
  "icon": "AzureDevops",
  "schema": {
    "properties": {
      "link": {
        "title": "Link",
        "type": "string",
        "format": "url",
        "icon": "AzureDevops",
        "description": "Link to the board in Azure DevOps"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "project": {
      "title": "Project",
      "target": "project",
      "required": true,
      "many": false
    }
  }
}
Ocean integration configuration
resources:
  - kind: board
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id | gsub(" "; "")
          title: .name
          blueprint: '"board"'
          properties:
            link: .url
          relations:
            project: .__project.id | gsub(" "; "")

To Learn More
  • Click here for the Azure DevOps board object structure.

After creating the blueprints and saving the integration configuration, you will see new entities in Port matching your Azure DevOps boards.

Mapping releases​

The example below shows how to ingest Azure DevOps Releases into Port.
You can use the following Port blueprint definitions and integration configuration:

Release blueprint
  {
    "identifier": "release",
    "title": "Release",
    "icon": "AzureDevops",
    "schema": {
      "properties": {
        "status": {
          "title": "Status",
          "type": "string",
          "icon": "DefaultProperty",
          "description": "The current status of the release"
        },
        "reason": {
          "title": "Reason",
          "type": "string",
          "description": "The reason for the release creation"
        },
        "createdDate": {
          "title": "Created Date",
          "type": "string",
          "format": "date-time",
          "description": "The date and time when the release was created"
        },
        "modifiedDate": {
          "title": "Modified Date",
          "type": "string",
          "format": "date-time",
          "description": "The date and time when the release was last modified"
        },
        "createdBy": {
          "title": "Created By",
          "type": "string",
          "icon": "User",
          "description": "The person who created the release"
        },
        "modifiedBy": {
          "title": "Modified By",
          "type": "string",
          "icon": "User",
          "description": "The person who last modified the release"
        },
        "definitionName": {
          "title": "Definition Name",
          "type": "string",
          "description": "The name of the release definition"
        },
        "link": {
          "title": "Link",
          "type": "string",
          "format": "url",
          "icon": "AzureDevops",
          "description": "Link to the release in Azure DevOps"
        }
      },
      "required": []
    },
    "mirrorProperties": {},
    "calculationProperties": {},
    "aggregationProperties": {},
    "relations": {
      "project": {
        "title": "Project",
        "target": "project",
        "required": true,
        "many": false
      }
    }
  }
Ocean integration configuration
resources:
  - kind: release
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .projectReference.id + "-" + (.id | tostring) | gsub(" "; "")
          title: .name
          blueprint: '"release"'
          properties:
            status: .status
            reason: .reason
            createdDate: .createdOn
            modifiedDate: .modifiedOn
            createdBy: .createdBy.uniqueName
            modifiedBy: .modifiedBy.uniqueName
            definitionName: .releaseDefinition.name
            link: ._links.web.href | gsub("_release?releaseId="; "")
          relations:
            project: .projectReference.id | gsub(" "; "")


To Learn more
  • Click here for the Azure DevOps release object structure.

After creating the blueprints and saving the integration configuration, you will see new entities in Port matching your releases.

Mapping supported resources​

The above examples shows a specific use cases, but Port's Azure Devops integration supports the ingestion of many other Azure Devops objects, to adapt the examples above, use the Azure Devops API reference to learn about the available fields for the different supported objects:

Available Azure DevOps resources

The following resources can be used to map data from Azure DevOps, it is possible to reference any field that appears in the API responses linked below for the Azure Devops integration api reference.

When adding the ingestion of other resources, remember to add an entry to the resources array and change the value provided to the kind key accordingly.