TM Forum Community

Hi TM Forum Team,

I am implementing TMF641 Service Ordering API (v4.1) for a telecom provisioning use case.

In our implementation, a single Service Order can contain multiple ServiceOrderItems. However, all ServiceOrderItems within the same request always represent the same business operation. Mixed operation types are not allowed in a single request.

For example:

- PRE_PROVISION
- ASSIGN
- PEERING_NUMBER

A request may contain multiple numbers, but they all belong to the same operation type.

Example:

{
  "operationType": "PRE_PROVISION",
  "serviceOrderItem": [
    {
      ...
    },
    {
      ...
    }
  ]
}

Instead of repeating the same value in every ServiceOrderItem, we would like to represent this operation only once at the ServiceOrder level.

My questions are:

1. Is there a standard TMF641 attribute that should be used for this purpose (for example, category or another existing attribute)?
2. Is it recommended to use a custom top-level attribute such as "operationType" or "type"?
3. If a custom attribute is added to the ServiceOrder resource, will it still be considered TMF641 compliant and pass CTK validation, or should custom business information be modelled using service/serviceCharacteristic instead?

Our goal is to remain as close as possible to the TMF641 standard while avoiding redundant data in every ServiceOrderItem.

Thank you for your guidance.

That makes sense. Using a custom top-level attribute seems like the cleanest approach.

Hi Gopal, that is not the way I read the specification.

Each ServiceOrderItem (i.e. the individual service requests) - have an action attribute that specifies add, modify,delete or noChange.

If you refer to the diagram on page 9 of the 641 v1.1 specification you will see the ServiceOrderItem entity.

Alongside that you have a state attribute that is meant to carry the requested 'state' of the service after the action. These are enumerated in ServiceOrderItemStateType.

Then - finally - in the actual ServiceRefOrValue construct you have a requested service state (also carried in a state) attribute. Here you can specify the state you want for the service from  ServiceStateType list. Simply extend that to include additional 'states' of the service as required. 

Peter's reading is the right starting point - action on ServiceOrderItem plus the requested state on ServiceRefOrValue is where TMF641 already puts intent, and extending the state enumeration is a safer move than inventing a header attribute.

I'd add the operational reason the header version bites, because it isn't really a compliance problem - it's a failure-handling one.

The moment operationType lives only on the ServiceOrder, every item's meaning depends on a field outside the item. That's fine while the order succeeds whole. It stops being fine the first time one number in a fifty-number PRE_PROVISION request fails validation and you need to resubmit just that one. Now you're either replaying the whole order and hoping downstream is idempotent, or you're constructing a single-item order whose header says something the original header didn't. Both are recoverable; neither is something you want to discover during a cutover weekend.

The second cost is downstream. Inventory, activation and assurance consumers generally read serviceOrderItem, not the order envelope. A header-only attribute means every consumer has to join back up to the parent to know what was asked for - and one of them eventually won't, and will infer the operation from the payload shape instead. That's the bug that surfaces months later as "why did this modify look like an add".

On PRE_PROVISION / ASSIGN / PEERING_NUMBER specifically - those read as orchestration verbs rather than service lifecycle transitions. If they genuinely map onto a requested end state, extending ServiceStateType is the honest model. If they don't, they're process steps, and modelling process as a data attribute on the order is what makes the API hard to version later.

Redundancy across items is a cheap price. A repeated value on fifty items costs bytes; a header that silently governs fifty items costs a retry story.

The question I'd settle before choosing: when one item in the request fails, is the contract all-or-nothing, or per-item? That answer, not CTK, decides where operationType belongs.