Add Documentation Note for Jenkins Integration with Pre-filtering Capability on Jenkins Builds

docs/build-your-software-catalog/sync-data-to-catalog/cicd/jenkins/_example_jenkins_build_blueprint.mdx

@@ -1,3 +1,5 @@
+<details>
+<summary><b>Build blueprint (click to expand)</b></summary>
 ```json showLineNumbers
 {
   "identifier": "jenkinsBuild",
@@ -47,3 +49,4 @@
   }
 }
 ```
+</details>

docs/build-your-software-catalog/sync-data-to-catalog/cicd/jenkins/_example_jenkins_build_configuration.mdx

@@ -0,0 +1,51 @@
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
+<details>
+<summary><b>Integration configuration (click to expand)</b></summary>
+```yaml showLineNumbers
+  createMissingRelatedEntities: true
+  deleteDependentEntities: true
+  resources:
+    - kind: build
+      selector:
+        query: "true"
+        maxBuildsPerJob: 100
+      port:
+        entity:
+          mappings:
+            identifier: .url | split("://")[1] | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") | gsub("/"; "-") | .[:-1]
+            title: .displayName
+            blueprint: '"jenkinsBuild"'
+            properties:
+              buildStatus: .result
+              buildUrl: .url
+              buildDuration: .duration
+              timestamp: '.timestamp / 1000 | todate'
+            relations:
+              parentJob: .url | split("://")[1] | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") | gsub("/"; "-") | .[:-1] | gsub("-[0-9]+$"; "")
+              previousBuild: >-
+                if .previousBuild then (.previousBuild.url | split("://")[1] |
+                sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") |
+                gsub("/"; "-") | .[:-1]) else null end
+```
+</details>
+
+<Tabs groupId="config" queryString="parameter">
+
+<TabItem label="Include Max Builds Per Job" value="includeMaxBuildsPerJob">
+
+The `maxBuildsPerJob` selector is an optional parameter that allows you to limit the number of builds to fetch for each job.
+By default, this selector is set to `100` which means the last 100 builds of each job will be fetched.
+
+```yaml
+  - kind: build
+    selector:
+      query: 'true'
+      # highlight-next-line
+      maxBuildsPerJob: 100
+```
+
+</TabItem>
+
+</Tabs>

docs/build-your-software-catalog/sync-data-to-catalog/cicd/jenkins/_example_jenkins_default_mapping_configuration.mdx

@@ -0,0 +1,61 @@
+<details>
+<summary><b>Default mapping configuration (click to expand)</b></summary>
+
+```yaml showLineNumbers
+createMissingRelatedEntities: true
+deleteDependentEntities: true
+resources:
+  - kind: job
+    selector:
+      query: 'true'
+    port:
+      entity:
+        mappings:
+          identifier: .url | split("://")[1] | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") | gsub("/"; "-") | .[:-1]
+          title: .fullName
+          blueprint: '"jenkinsJob"'
+          properties:
+            jobName: .name
+            url: .url
+            jobStatus: '{"notbuilt": "created", "blue": "passing", "red": "failing"}[.color]'
+            timestamp: .time
+            parentJob: .__parentJob
+
+
+  - kind: build
+    selector:
+      query: 'true'
+      maxBuildsPerJob: 100
+    port:
+      entity:
+        mappings:
+          identifier: >-
+            .url | split("://")[1] | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") | gsub("/"; "-") | .[:-1]
+          title: .displayName
+          blueprint: '"jenkinsBuild"'
+          properties:
+            buildStatus: .result
+            buildUrl: .url
+            buildDuration: .duration
+            timestamp: .timestamp / 1000 | todate
+          relations:
+            parentJob: .url | split("://")[1] | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") | gsub("/"; "-") | .[:-1] | gsub("-[0-9]+$"; "")
+            previousBuild: >-
+              if .previousBuild then (.previousBuild.url | split("://")[1] |
+              sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") |
+              gsub("/"; "-") | .[:-1]) else null end
+
+  - kind: user
+    selector:
+      query: 'true'
+    port:
+      entity:
+        mappings:
+          identifier: .user.id
+          title: .user.fullName
+          blueprint: '"jenkinsUser"'
+          properties:
+            url: .user.absoluteUrl
+            lastUpdateTime: if .lastChange then (.lastChange/1000) else now end | strftime("%Y-%m-%dT%H:%M:%SZ")
+```
+</details>

docs/build-your-software-catalog/sync-data-to-catalog/cicd/jenkins/_example_jenkins_job_blueprint.mdx

@@ -1,3 +1,5 @@
+<details>
+<summary><b>Job blueprint (click to expand)</b></summary>
 ```json showLineNumbers
 {
   "identifier": "jenkinsJob",
@@ -45,3 +47,4 @@
   "relations": {}
 }
 ```
+</details>

docs/build-your-software-catalog/sync-data-to-catalog/cicd/jenkins/_example_jenkins_job_configuration.mdx

@@ -0,0 +1,23 @@
+<details>
+<summary><b>Integration configuration (click to expand)</b></summary>
+```yaml showLineNumbers
+  createMissingRelatedEntities: true
+  deleteDependentEntities: true
+  resources:
+    - kind: job
+      selector:
+        query: "true"
+      port:
+        entity:
+          mappings:
+            identifier: .url | split("://")[1] | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("/"; "-") | .[:-1]
+            title: .fullName
+            blueprint: '"jenkinsJob"'
+            properties:
+              jobName: .name
+              url: .url
+              jobStatus: '{"notbuilt": "created", "blue": "passing", "red": "failing"}[.color]'
+              timestamp: .time
+              parentJob: .__parentJob
+```
+</details>

docs/build-your-software-catalog/sync-data-to-catalog/cicd/jenkins/_example_jenkins_stage_blueprint.mdx

@@ -0,0 +1,65 @@
+<details>
+<summary><b>Stage blueprint (click to expand)</b></summary>
+
+```json showLineNumbers
+{
+  "identifier": "jenkinsStage",
+  "description": "This blueprint represents a stage in a Jenkins build",
+  "title": "Jenkins Stage",
+  "icon": "Jenkins",
+  "schema": {
+    "properties": {
+      "status": {
+        "type": "string",
+        "title": "Stage Status",
+        "enum": [
+          "SUCCESS",
+          "FAILURE",
+          "UNSTABLE",
+          "ABORTED",
+          "IN_PROGRESS",
+          "NOT_BUILT",
+          "PAUSED_PENDING_INPUT"
+        ],
+        "enumColors": {
+          "SUCCESS": "green",
+          "FAILURE": "red",
+          "UNSTABLE": "yellow",
+          "ABORTED": "darkGray",
+          "IN_PROGRESS": "blue",
+          "NOT_BUILT": "lightGray",
+          "PAUSED_PENDING_INPUT": "orange"
+        }
+      },
+      "startTimeMillis": {
+        "type": "number",
+        "title": "Start Time (ms)",
+        "description": "Timestamp in milliseconds when the stage started"
+      },
+      "durationMillis": {
+        "type": "number",
+        "title": "Duration (ms)",
+        "description": "Duration of the stage in milliseconds"
+      },
+      "stageUrl": {
+        "type": "string",
+        "title": "Stage URL",
+        "description": "URL to the stage"
+      }
+    },
+    "required": []
+  },
+  "mirrorProperties": {},
+  "calculationProperties": {},
+  "relations": {
+    "parentBuild": {
+      "title": "Jenkins Build",
+      "target": "jenkinsBuild",
+      "required": true,
+      "many": false
+    }
+  }
+}
+```
+
+</details>

docs/build-your-software-catalog/sync-data-to-catalog/cicd/jenkins/_example_jenkins_stage_configuration.mdx

@@ -0,0 +1,83 @@
+<details>
+<summary><b>Integration configuration (click to expand)</b></summary>
+
+:::note Control Stage Fetching
+To prevent overwhelming your Ocean instance with potentially thousands of stages from Jenkins, the integration requires you to specify a specific job. This ensures that Ocean only retrieves stages related to that job, keeping things focused and efficient.
+
+**Important**: The integration will also fetch stages from all nested jobs within the specified job.
+:::
+
+```yaml showLineNumbers
+- kind: stage
+  selector:
+    query: 'true'
+    # Example jobUrl - replace with your own Jenkins job URL
+    jobUrl: http://your-jenkins-server/job/your-project/job/your-job
+  port:
+    entity:
+      mappings:
+        identifier: >-
+          ._links.self.href  | sub("^.*?/"; "") | gsub("%20"; "-") |
+          gsub("%252F"; "-") | gsub("/"; "-")
+        title: .name
+        blueprint: '"jenkinsStage"'
+        properties:
+          status: .status
+          startTimeMillis: .startTimeMillis
+          durationMillis: .durationMillis
+          stageUrl: env.OCEAN__INTEGRATION__CONFIG__JENKINS_HOST  + ._links.self.href
+        relations:
+          parentBuild: >-
+            ._links.self.href | sub("/execution/node/[0-9]+/wfapi/describe$";
+            "") | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") |
+            gsub("/"; "-")
+# Additional stage configurations follow the same pattern.
+- kind: stage
+  selector:
+    query: 'true'
+    # Example jobUrl - replace with your own Jenkins job URL
+    jobUrl: http://your-jenkins-server/job/your-project/job/another-job
+  port:
+    entity:
+      mappings:
+        identifier: >-
+          ._links.self.href  | sub("^.*?/"; "") | gsub("%20"; "-") |
+          gsub("%252F"; "-") | gsub("/"; "-")
+        title: .name
+        blueprint: '"jenkinsStage"'
+        properties:
+          status: .status
+          startTimeMillis: .startTimeMillis
+          durationMillis: .durationMillis
+          stageUrl: env.OCEAN__INTEGRATION__CONFIG__JENKINS_HOST  + ._links.self.href
+        relations:
+          parentBuild: >-
+            ._links.self.href | sub("/execution/node/[0-9]+/wfapi/describe$";
+            "") | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") |
+            gsub("/"; "-")
+
+- kind: stage
+  selector:
+    query: 'true'
+    # Example jobUrl - replace with your own Jenkins job URL
+    jobUrl: http://your-jenkins-server/job/your-project/job/third-job
+  port:
+    entity:
+      mappings:
+        identifier: >-
+          ._links.self.href  | sub("^.*?/"; "") | gsub("%20"; "-") |
+          gsub("%252F"; "-") | gsub("/"; "-")
+        title: .name
+        blueprint: '"jenkinsStage"'
+        properties:
+          status: .status
+          startTimeMillis: .startTimeMillis
+          durationMillis: .durationMillis
+          stageUrl: env.OCEAN__INTEGRATION__CONFIG__JENKINS_HOST  + ._links.self.href
+        relations:
+          parentBuild: >-
+            ._links.self.href | sub("/execution/node/[0-9]+/wfapi/describe$";
+            "") | sub("^.*?/"; "") | gsub("%20"; "-") | gsub("%252F"; "-") |
+            gsub("/"; "-")
+```
+</details>

docs/build-your-software-catalog/sync-data-to-catalog/cicd/jenkins/_example_jenkins_user_blueprint.mdx

@@ -0,0 +1,32 @@
+<details>
+<summary><b>User blueprint (click to expand)</b></summary>
+
+```json showLineNumbers
+{
+  "identifier": "jenkinsUser",
+  "description": "This blueprint represents a jenkins user",
+  "title": "Jenkins User",
+  "icon": "Jenkins",
+  "schema": {
+      "properties": {
+          "url": {
+              "type": "string",
+              "title": "URL",
+              "format": "url"
+          },
+          "lastUpdateTime": {
+              "type": "string",
+              "format": "date-time",
+              "title": "Last Update",
+              "description": "Last updated timestamp of the user"
+          }
+      },
+      "required": []
+  },
+  "mirrorProperties": {},
+  "calculationProperties": {},
+  "relations": {}
+}
+```
+
+</details>

docs/build-your-software-catalog/sync-data-to-catalog/cicd/jenkins/_example_jenkins_user_configuration.mdx

@@ -0,0 +1,21 @@
+<details>
+<summary><b>Integration configuration (click to expand)</b></summary>
+```yaml showLineNumbers
+createMissingRelatedEntities: true
+deleteDependentEntities: true
+resources:
+  - kind: user
+    selector:
+      query: "true"
+    port:
+      entity:
+        mappings:
+          identifier: .user.id
+          title: .user.fullName
+          blueprint: '"jenkinsUser"'
+          properties:
+            url: .user.absoluteUrl
+            lastUpdateTime: if .lastChange then (.lastChange/1000) else now end | strftime("%Y-%m-%dT%H:%M:%SZ")
+
+```
+</details>