> For the complete documentation index, see [llms.txt](https://docs.durohub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.durohub.com/library-configuration/cpn-behavior.md).

# CPN Behavior Rules

The [CPN Schema Reference](https://docs.durohub.com/library-configuration/cpn-schema-reference.md) describes how a scheme is **written**. This page describes how a scheme **behaves**: what CPN you get when you create a component, make a copy, create a variant, or move a component into a variant group.

Every example on this page can be reproduced with the [`component`](https://docs.durohub.com/core-concepts/components.md#creating-components) mutations. Where a rule depends on the shape of the scheme, the examples sit in tabs, one per shape.

## How a CPN is built

A CPN is the element values joined in scheme order, **with nothing in between**. Constants are the separators: if you want a dash, the scheme has a constant `-`.

An element that has no value is left out completely. It adds nothing to the CPN and is not stored.

{% tabs %}
{% tab title="Plain" %}

```yaml
elements:
  - { type: list, name: category, required: true, values: '${{ duro.categories }}' }
  - { type: constant, name: sep, value: '-' }
  - { type: numeric_counter, name: sequence, required: true, attachedTo: [category],
      format: { min_value: 1, max_value: 99999 } }
```

Category `450` → `450-00001`.
{% endtab %}

{% tab title="Optional suffix" %}

```yaml
  # ...category, sep and sequence as in "Plain", then:
  - type: group
    name: variant_group
    required: false
    elements:
      - { type: constant, name: dash, value: '-' }
      - { type: list, name: variant_code, values: ['01', '02', '03'] }
```

| Supplied             | CPN            |
| -------------------- | -------------- |
| nothing              | `450-00001`    |
| `variant_code: "02"` | `450-00002-02` |

The dash lives inside the group, so it disappears with the group.
{% endtab %}

{% tab title="Separator outside the group" %}

```yaml
  # ...category and sequence, then:
  - { type: constant, name: dash, value: '-' }   # outside the group
  - type: group
    name: variant_group
    required: false
    elements:
      - { type: list, name: variant_code, values: ['01', '02', '03'] }
```

| Supplied             | CPN            |
| -------------------- | -------------- |
| nothing              | `450-00001-`   |
| `variant_code: "02"` | `450-00002-02` |

A constant always appears, so a separator placed in front of an optional piece is left dangling when that piece is absent. Put the separator **inside** the optional group.
{% endtab %}
{% endtabs %}

## Supplying element values

Pass element values in `identifierOverride.elements` when you create a component. Each entry names one element, **by its own name**, and the entries form a flat list: the children of a group are listed by their own names, not nested under the group.

```graphql
mutation CreateWithSuffix {
  component {
    create(inputs: [{
      name: "Bracket"
      categoryId: "category-uuid"
      identifierOverride: {
        elements: [{ elementName: "variant_code", value: "02" }]
      }
    }]) {
      id
      identifier { displayValue }
    }
  }
}
```

| Element                                              | What you supply                             | Notes                                                                                                                                                                               |
| ---------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Category list (named in `element_mappings.category`) | Nothing. Pass `categoryId` on the component | The category's code fills the element. Supplying a different value fails with `CATEGORY_ELEMENT_CONFLICT`.                                                                          |
| Other list                                           | One of its values                           | Matched case-insensitively against `code`, `id`, `name` and the plain value. A value outside the list fails with `INVALID_ELEMENT_VALUE`, and the message lists the allowed values. |
| Counter                                              | Usually nothing; Duro assigns it            | Supplying a value is an **override** and needs `allow_override: true`. See [Counters](#counters).                                                                                   |
| Constant                                             | Nothing                                     | It always shows its fixed value.                                                                                                                                                    |
| Group                                                | Its children's values, by their own names   | See [Optional groups](#optional-groups) and [Reusable groups](#reusable-groups).                                                                                                    |

Choosing a list value, such as a category or a suffix, is never an override and is always allowed. Only a counter value needs `allow_override`.

Each element may appear once per input (`DUPLICATE_ELEMENT_IN_INPUT`), and an empty string is never a value (`EMPTY_ELEMENT_VALUE`). An element name that is not in the scheme fails with `INVALID_ELEMENT_VALUE`.

## Optional elements and groups

An element or group is optional only when the scheme says `required: false`. Everything else is required, including every element inside a group: when a group is present, all of its pieces are.

### Optional groups

An optional group is **present** when you supply a value for any of its children, and **absent** otherwise. An absent group adds nothing to the CPN.

{% tabs %}
{% tab title="Group with a list" %}
Scheme: `450-00001` with an optional `-` + `variant_code` (`01`–`03`).

| Supplied             | CPN            |
| -------------------- | -------------- |
| nothing              | `450-00001`    |
| `variant_code: "02"` | `450-00002-02` |
| {% endtab %}         |                |

{% tab title="Counter-only group" %}
A group that holds only constants and a counter has nothing for you to choose, so you switch it on by naming the group itself:

```graphql
identifierOverride: {
  elements: [{ elementName: "auto_group", value: { action: "CREATE_NEW" } }]
}
```

Scheme: `450-00001` with an optional `-` + counter `auto_counter` (`01`–`99`).

| Supplied                             | CPN            |
| ------------------------------------ | -------------- |
| nothing                              | `450-00001`    |
| `auto_group: { action: CREATE_NEW }` | `450-00002-01` |

Duro assigns the group's counter as usual. A bare `{ action: "CREATE_NEW" }` is the only group-level value a non-reusable group accepts; anything else fails with `GROUP_NOT_REUSABLE` or `INVALID_ELEMENT_VALUE`.
{% endtab %}

{% tab title="Clearing a group" %}
Supplying `null` for an optional group or element removes it:

```graphql
elements: [{ elementName: "variant_group", value: null }]
```

`null` on a required element fails with `CANNOT_CLEAR_REQUIRED_ELEMENT`. That includes the children of a group: clear the group, not its child.
{% endtab %}
{% endtabs %}

### Optional counters

An optional counter that is not inside a group is **never assigned automatically**. It appears only when you supply its value, and supplying it is an override. To get an automatically numbered optional suffix, put the counter in an optional group and switch the group on, as in the **Counter-only group** tab above.

## Counters

The [schema reference](https://docs.durohub.com/library-configuration/cpn-schema-reference.md#numeric-counter) covers ranges, padding and gap-filling. These rules cover how counters behave over time.

* **Scope.** A counter keeps one sequence for each combination of the values it is `attachedTo`.
* **Attach to required elements only.** A counter cannot be `attachedTo` an optional element, because it would have nothing to count against when that element is left off. Saving a scheme that does this is rejected: `Element "sequence" attachedTo references optional element "color"`. Put optional pieces after the counter instead.
* **Inside a group.** A counter in an optional group is assigned only when the group is present. A counter in a required group is always assigned.
* **Overrides.** A supplied counter value is used as given after a range check (`INVALID_PROVIDED_COUNTER_VALUE`). It is recorded, so it is never handed out again. It may repeat a number already used in the same sequence, as long as the whole CPN is still unique.
* **Rollback.** A create that fails uses up no counter values.
* **Running out.** When no value is left, the create fails with `COUNTER_EXHAUSTED`. A batch that needs more values than remain fails with `INSUFFICIENT_COUNTERS`.
* **Alpha counters are not padded.** `A`…`Z` is followed by `AA`, so the CPN gets one character longer at that point. Use `min_value: "AA"` for a fixed width.

## Reusable groups

A reusable group is a shared piece, such as a product family code, that many CPNs carry. Each distinct value of the group is an **instance**. You either start a new instance or join an existing one:

{% tabs %}
{% tab title="Start a new instance" %}

```graphql
elements: [{
  elementName: "family_group"
  value: { action: "CREATE_NEW", elements: [{ elementName: "family", value: "3" }] }
}]
```

Supply the group's non-counter children under `elements`. The group's own counter is always assigned by Duro, so every `CREATE_NEW` makes a new instance, even with the same children: family `3` gives `300001`, then `300002`. To put a part in an instance that already exists, join it instead.

Supplying a counter or constant child fails with `COUNTER_CANNOT_BE_PROVIDED`, and a missing child fails with `REQUIRED_GROUP_ELEMENT_MISSING`.
{% endtab %}

{% tab title="Join an existing instance" %}

```graphql
elements: [{
  elementName: "family_group"
  value: { action: "REUSE_EXISTING", generatedCode: "300001" }
}]
```

`generatedCode` is the instance's value as it appears in the CPN. The new CPN carries exactly that value: `300001-450-00002`. A code with no instance fails with `REUSABLE_INSTANCE_NOT_FOUND`.
{% endtab %}
{% endtabs %}

## Copies and variants

There are two ways to make a new component from an existing one. They differ in what they mean, and so in the CPN they give.

* **Make a copy** (`component.duplicate`) makes a **new, unrelated part** that starts from the source's data. It gets a new CPN, built as though you were creating it fresh.
* **Create variant** (`component.createVariant`) makes **another version of the same part** and puts both in one variant group. When the scheme marks a variant element (`element_mappings.variant`), the new CPN keeps the source's number and takes the next variant value.

```graphql
mutation MakeCopy($id: ID!) {
  component {
    duplicate(componentId: $id) { id identifier { displayValue } }
  }
}

mutation MakeVariant($id: ID!) {
  component {
    createVariant(targetComponentId: $id, inputs: [{ name: "Bracket, black" }]) {
      components { id identifier { displayValue } }
    }
  }
}
```

### Make a copy

A copy keeps the source's list values, such as the category, and assigns every counter fresh. Every optional piece, such as a variant suffix, is left off, whether it is an optional group or an optional element, because a new part has no variants yet. A reusable group is the exception: the copy joins the source's instance.

{% tabs %}
{% tab title="Plain" %}
`450-00002` → `450-00003`
{% endtab %}

{% tab title="Optional suffix" %}
`450-00002-02` → `450-00003`

The suffix is dropped and the copy is a plain new part. Add a suffix later if it needs one.

An optional list on its own is dropped the same way: `RES-001A` → `RES-002`.
{% endtab %}

{% tab title="Counter suffix" %}
`450-00001-01` → `450-00003`
{% endtab %}

{% tab title="Required suffix" %}
A required piece cannot be dropped. A required list keeps its value, and a required counter is assigned fresh from its minimum.

* Required list suffix: `RES-001-A` → `RES-002-A`
* Required counter suffix: `412-00001-03` → `412-00002-00`
  {% endtab %}

{% tab title="Reusable group" %}
`300001-450-00001` → `300001-450-00002`

The copy joins the same family instance and takes the next sequence number.
{% endtab %}

{% tab title="Freeform source" %}
A source with a freeform CPN has no elements to carry over, so the copy gets a new CPN generated by the scheme.
{% endtab %}
{% endtabs %}

### Create variant

When `element_mappings.variant` names the variant element, a variant keeps **every** other value of the source, its counters included, and assigns only the variant element fresh.

{% tabs %}
{% tab title="Counter variant" %}
Scheme: `category` `-` `sequence` `-` counter `variant` attached to `[category, sequence]`, with `element_mappings.variant: variant`.

`412-00001-00` → `412-00001-01` → `412-00001-02`
{% endtab %}

{% tab title="Suffix in an optional group" %}
Scheme: `450-00001` with an optional `-` + counter `auto_counter`, and `element_mappings.variant: auto_counter`.

`450-00001-01` → `450-00001-02`

Other values in the group, such as a color code, are kept.
{% endtab %}

{% tab title="No variant mapping" %}
Without `element_mappings.variant`, Duro cannot tell which piece is the variant, so Create variant gives the same CPN that [Make a copy](#make-a-copy) would:

`450-00005-02` → `450-00013`

The new component is still added to the source's variant group. Only the CPN differs. To get variant numbering, map the variant element in the scheme.
{% endtab %}
{% endtabs %}

To choose the new CPN yourself, pass `identifierOverride.elements` in the variant's input. Those elements are used as given, exactly as on a create, and the override rules apply.

### Conform

Conforming a component to a variant group gives it the group's base number and the next variant value, built the same way as Create variant. The component must be in **Design** status. It is left unchanged when its CPN already has the group's base, or when the scheme has no variant mapping.

`412-00002-00`, conformed to the group of `412-00001-00` → `412-00001-02` (when `-01` is taken)

Removing a component from a variant group never changes its CPN.

## Editing a CPN

A component's CPN can be changed only while the component is in **Design** status (`cpn_override_not_allowed_past_design`).

When a component changes category, its CPN is rebuilt for the new category:

* The category element takes the new code.
* Counters attached to the category are assigned fresh.
* Other list values, and counters not attached to the category, are kept.
* A reusable group is kept.
* A non-reusable group, such as an optional suffix, is dropped.

A scheme with no category element, or a freeform CPN, keeps its CPN.

## Uniqueness and base-number warnings

A CPN is unique within its library, ignoring case, for good: an archived component keeps its CPN reserved. A clash fails with `IDENTIFIER_ALREADY_EXISTS` (`FREEFORM_IDENTIFIER_EXISTS` for a freeform CPN), and two items in one batch that come out the same fail with `DUPLICATE_IN_BATCH`.

When the scheme has a variant mapping, Duro also compares **base numbers**: the CPN without its variant element. A new CPN whose base matches an existing component's gets a **warning**, not an error, suggesting it belongs in that component's variant group. Without a variant mapping, the base number is the whole CPN.

## Errors

| Code                                                       | When                                                                                                                                                 |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `REQUIRED_ELEMENT_MISSING`                                 | A required list or group has no value.                                                                                                               |
| `EMPTY_ELEMENT_VALUE`                                      | A value is an empty string.                                                                                                                          |
| `INVALID_ELEMENT_VALUE`                                    | A list value is not in the list, an element name is not in the scheme, or a group got a value it does not accept. The message lists what is allowed. |
| `CANNOT_CLEAR_REQUIRED_ELEMENT`                            | `null` was supplied for a required element.                                                                                                          |
| `DUPLICATE_ELEMENT_IN_INPUT`                               | The same element is named twice.                                                                                                                     |
| `GROUP_NOT_REUSABLE`                                       | A non-reusable group got `REUSE_EXISTING`, or `CREATE_NEW` with elements.                                                                            |
| `REUSE_EXISTING_MISSING_CODE`                              | `REUSE_EXISTING` has no `generatedCode`.                                                                                                             |
| `REUSABLE_INSTANCE_NOT_FOUND`                              | No instance has that `generatedCode`.                                                                                                                |
| `COUNTER_CANNOT_BE_PROVIDED`                               | `CREATE_NEW` on a reusable group supplied a counter or constant child.                                                                               |
| `REQUIRED_GROUP_ELEMENT_MISSING`                           | `CREATE_NEW` on a reusable group is missing a required child.                                                                                        |
| `INVALID_PROVIDED_COUNTER_VALUE`                           | A supplied counter value is out of range or has the wrong characters.                                                                                |
| `INVALID_SETTINGS_COMBINATION`                             | A counter value was supplied, but the scheme has `allow_override: false`.                                                                            |
| `INVALID_FREEFORM_IDENTIFIER`                              | A freeform CPN is not allowed, is mixed with other elements, or does not match `freeform_validation`.                                                |
| `CATEGORY_ELEMENT_CONFLICT`                                | The category element's value disagrees with `categoryId`.                                                                                            |
| `CATEGORY_ID_REQUIRED_WITH_ELEMENT`                        | The category element was supplied without a `categoryId`.                                                                                            |
| `IDENTIFIER_ALREADY_EXISTS` / `FREEFORM_IDENTIFIER_EXISTS` | The CPN is already used in the library.                                                                                                              |
| `DUPLICATE_IN_BATCH`                                       | Two items in one request produce the same CPN.                                                                                                       |
| `COUNTER_EXHAUSTED` / `INSUFFICIENT_COUNTERS`              | The counter has no values, or too few, left.                                                                                                         |

See [Error Handling](https://docs.durohub.com/advanced-topics/error-handling.md) for the error format.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.durohub.com/library-configuration/cpn-behavior.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
