Automating Component Creation for Your Customizable Data Mapping

The transform definition includes a feature called on_component_not_found. This key allows users to control what action OpsLevel takes when it encounters data for a component that doesn't exist in the system yet.
The on_component_not_found parameter is required and accepts three values: skip, create, and suggest. OpsLevel detects components by matching both the opslevel_kind and opslevel_identifier fields. This guide demonstrates these three scenarios using various JSON responses as seen below.

Prerequisites

Before following this guide, you should:

• Read the parent document Mapping Integration Data to Custom Properties
• Understand how data enters OpsLevel through either:
  • The testing tool on the integration page, or
  • The Setting Up a Pull Configuration for Your Customizable Data Mapping document

Option 1: skip

When you set on_component_not_found to skip, OpsLevel ignores any new components discovered in your data. This is straightforward—OpsLevel takes no action.

---
transforms:
  on_component_not_found: skip

This option works best when you want full manual control over part of your catalog. You'll need to create components beforehand for them to appear in OpsLevel. For example, you might use this for team components.

Option 2:create

When you set on_component_not_found to create, OpsLevel automatically creates any new components discovered in synced data.

---
transforms:
  on_component_not_found: create

Consider the following JSON data from the Jira API:

{
  "issues": [
    {
      "key": "c53bd80c-a56d-46c8-8835-26dc9db6be5d",
      "id": "APB-1001",
      "fields": {
        "status": {
          "name": "Open"
        }
      }
    }
  ]
}

After modifying the transform definition and sending data to OpsLevel, you'll see a new component appear. This component will have a tooltip indicating it's a managed component. In the Customizable Data Mapping feature, a managed component is one that has been created or modified by an external data source through your integration.
You've already seen examples of managed properties. This concept now extends to entire components. Managed components cannot be deleted through the UI. Instead, they must be excluded or have expired to be removed.

Use this option to manage data that you always want to see in OpsLevel.

Option 3:suggest

When you set on_component_not_found to suggest, OpsLevel automatically creates managed suggestions for any new components discovered in synced data.

---
transforms:
  on_component_not_found: suggest

Consider the following JSON data, containing a list of dependencies and their current versions:

{
  "dependencies": [
    {
      "key": "bea915e4-06ec-40db-be03-ac3bf8bbb55c",
      "id": "PR_kwDOAJy2Ks6iLnzV",
      "version": "18.2.1"
    }
  ]
}

After modifying the transform definition, OpsLevel will create a suggestion when it receives the dependency data. You'll see any properties you specified within the suggestion.

Since this is a managed suggestion, any changes to properties in the transform definition will appear on the suggestion. Excluding the suggestion will remove it entirely. The component type is also locked to "Library".

Let's add another property called "key", update the version in the JSON to the latest version and send that data to OpsLevel.

{
  "dependencies": [
    {
      "key": "bea915e4-06ec-40db-be03-ac3bf8bbb55c",
      "id": "PR_kwDOAJy2Ks6iLnzV",
      "version": "19.1.1"
    }
  ]
}

As a result, the status has been updated on the suggestion and a new property has appeared.

When you accept this suggestion, the resulting component won't be marked as managed. This happens because the suggestion was created by the mapping, but the component was created through human intervention. I've also named the library "React", to be more human readable.

The suggestion option works well as a catch-all for users who aren't sure what data they want in their catalog. It's also helpful if you're having trouble establishing clear rules about what should and shouldn't be included.