Examples

Basic create/update example

note

For this example, the following plugin is a dependency:

• build user vars plugin (>=v1.9)

In this example you will create blueprints for ciJob and image entities, and a relation between them. Then you will add some Groovy code to create new entities in Port every time the Jenkins pipeline is triggered:

Image blueprint

{
  "identifier": "image",
  "title": "Image",
  "icon": "Docker",
  "schema": {
    "properties": {
      "synkHighVulnerabilities": {
        "type": "string",
        "icon": "Snyk",
        "title": "Synk High Vaulnerabilities"
      },
      "synkMediumVulnerabilities": {
        "type": "string",
        "icon": "Snyk",
        "title": "Synk Medium Vaulnerabilities"
      },
      "imageTag": {
        "type": "string",
        "title": "Image Tag"
      },
      "gitRepoUrl": {
        "type": "string",
        "format": "url",
        "title": "Git Url",
        "description": "Git Url for the sourcecode"
      },
      "imageRegistry": {
        "type": "string",
        "format": "url",
        "title": "Image Registry",
        "description": "Docker registry"
      },
      "unitTestCoverage": {
        "type": "number",
        "title": "Unit Test coverage (%)",
        "description": "The unit test coverage pecentage"
      },
      "integTestCoverage": {
        "type": "number",
        "title": "Integ Test coverage (%)",
        "description": "The integration test coverage pecentage"
      },
      "size": {
        "type": "number",
        "title": "Image Size (GB)",
        "description": "The image size in Gigabyte"
      }
    },
    "required": []
  },
  "calculationProperties": {}
}

CI Job blueprint (including the image relation)

{
  "identifier": "ciJob",
  "title": "CI Job",
  "icon": "CICD",
  "schema": {
    "properties": {
      "triggeredBy": {
        "type": "string",
        "icon": "TwoUsers",
        "title": "Triggered By",
        "description": "The user who triggered the run"
      },
      "commitHash": {
        "type": "string",
        "title": "Commit Hash"
      },
      "jobBranch": {
        "type": "string",
        "icon": "Git",
        "format": "url",
        "title": "Job branch"
      },
      "runLink": {
        "type": "string",
        "format": "url",
        "title": "Action Run Link"
      }
    },
    "required": []
  },
  "relations": {
    "image": {
      "title": "Job Images",
      "target": "image",
      "required": false,
      "many": true
    }
  },
  "calculationProperties": {}
}

note

The variables token and API_URL are used in the following examples. Click here to see how they were defined.

After creating the blueprint, you can add the following snippet to your Jenkins build to create the new build entity:

// Use the `build users` plugin to fetch the triggering user's ID
wrap([$class: 'BuildUser']) {
        def user = env.BUILD_USER_ID
    }

    def body = """
        {
            "identifier": "new-cijob-run",
            "properties": {
                "triggeredBy": "${user}",
                "runLink": "${env.BUILD_URL}",
            },
            "relations": {
                "image": ["example-image"]
            }
        }
    """

    response = httpRequest contentType: "APPLICATION_JSON", httpMode: "POST",
            url: "${API_URL}/v1/blueprints/ciJob/entities?upsert=true&merge=true&create_missing_related_entities=true",
            requestBody: body,
            customHeaders: [
                [name: "Authorization", value: "Bearer ${token}"],
            ]

Selecting a Port API URL by account region

The baseUrl, port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters are used to select which instance or Port API will be used.

Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.

• If you use the EU region of Port (https://app.getport.io), your API URL is https://api.getport.io.
• If you use the US region of Port (https://app.us.getport.io), your API URL is https://api.us.getport.io.

note

Please notice that you have also created the image relation, and added a related image entity called example-image. This is the artifact of the ciJob, and you will update it later. The creation was done using the create_missing_related_entities=true flag in the API url, allowing the relation to be created even though the example-image entity doesn't exist yet.

Basic get example

The following example gets the new-cijob-run entity from the previous example, this can be useful if your CI process creates a build artifact and then references some of its data (for example, the run link of the latest ciJob).

Add the following code to your Jenkins build:

    response = httpRequest contentType: "APPLICATION_JSON", httpMode: "GET",
            url: "${API_URL}/v1/blueprints/ciJob/entities/new-cijob-run",
            customHeaders: [
                [name: "Authorization", value: "Bearer ${token}"],
            ]
    println(response.content)

Relation example

In the following example you will update the example-image entity that was automatically created when creating the ciJob entity shown in the previous example.

Add the following snippet to your Jenkins Pipeline:

def body = """
        {
            "identifier": "example-image",
            "properties": {
                "imageTag": "v1",
                "synkHighVulnerabilities": "0",
                "synkMediumVulnerabilities": "0",
                "gitRepoUrl": "https://github.com/my-org/my-cool-repo",
                "imageRegistry": "docker.io/cool-image",
                "size": "0.71",
                "unitTestCoverage": "20",
                "unitTestCoverage": "50"
            },
            "relations": {}
        }
        """
response = httpRequest contentType: "APPLICATION_JSON", httpMode: "POST",
url: "${API_URL}/v1/blueprints/image/entities?upsert=true&merge=true",
    requestBody: body,
    customHeaders: [
        [name: "Authorization", value: "Bearer ${token}"],
    ]

That's it! The entity is created or updated and is visible in the UI.