A ticket landed last quarter that I kept. Subject: map SubscriberId to customer.id. The CRM owner meant the person. Billing meant the account number. The order manager meant a string a vendor had invented in 2014 and never documented. Both suppliers had TMF622 on the slide. I opened the two example payloads. They did not match, and nobody in the room was surprised, which was the worrying part.
If you read SID Explained, you already have the objects on that ticket: a Party, a Customer, the product someone holds, the service they feel, the SIM underneath. eTOM named the work that gets a mobile plan from “I want this” to “it’s live.” TM Forum Open APIs are the calls that carry those objects from one system to another.
Frameworx already had a name for the layer. It is the Integration Framework. In the blueprint post I called it mortar, because the other three drawings are useless if the pipes don’t join. That’s the last time I’ll use the house. From here it’s an interface with a number on it.
You can read this on its own. The earlier posts make the ticket easier, mostly because Party and Customer stop being one word.
At a Glance
- Open APIs are agreed calls between telco systems. There isn’t a product called “Open API” that you switch on.
- TMF630 is the design-guidelines series. Start with the ordinary part: a resource name, an id, an href, and the usual create, read, update, and filter.
- TM Forum’s own scale line is a large set — more than a hundred REST, event, and domain APIs. A mobile order needs a short list, not the directory.
- The path later in this post is simplified. The shopping cart is optional. Plenty of operators never had one.
The number on the slide
“We’re TMF622” is a claim about a contract, and people use it as a claim about their whole payload. TMF622 is product ordering. There is a product order. It has items. It has a state. It points at the parties involved. The five extra fields a vendor added last year are theirs. The 2014 SubscriberId is still a local invention until someone maps it, in writing, to a field both sides recognise.
The shared shape of these contracts comes from TMF630, the REST API Design Guidelines. It’s a series, not a single page, and the revision on your wiki will move. I’m not going to nail this article to a version number. Part 1 is the part worth having in the first meeting: how you name a resource, how you create it, read it, update it, and how you filter a list.
A resource is something you can say out loud: productOrder, customer, serviceOrder. It has an id, and usually an href, so the next system can come back to the same thing on Thursday without another workshop. You fetch one, or you filter a list. The database behind it stays theirs. The field names are the part you have to share, or you get the ticket I started with.
Later parts of the same guidelines cover polymorphism and growth: @type, characteristics, the private bits every estate grows. Those parts are real. They are also how a meeting goes wrong, when the first hour is spent on a vendor’s extension and nobody has agreed what relatedParty points at. Extensions get their own post. If you need them before you can create a plain product order, say so. Don’t pretend the extension is the standard.
The question I actually ask, when someone waves a PDF, is small. Can two teams point at the same field and mean it?
A list you can remember
The directory is large. TM Forum’s own line is more than a hundred REST, event, and domain APIs. I won’t freeze a live count here. It changes, and it doesn’t help you design Jane’s plan. What helps is the dozen calls on a normal mobile order, and a clear eye for the ones people mention only to sound complete.
Party and Customer. TMF632 is the person or the company. TMF629 is the commercial relationship with you. The last post did the long version of why those differ. I’ll keep using both numbers so the ticket can’t collapse them. An employee, a roaming partner, a contact who hasn’t bought anything: TMF632. The buyer you bill: TMF629, and only once they are a buyer.
Product. TMF620 is the catalog. The offering, the price, the terms, in a form another system can read. TMF679 is the awkward question the catalog can’t answer on its own: this person, this place, this network, can we actually sell it? TMF622 is the product order. When someone says “the order API” in a workshop, this is usually the number they mean, even when they meant the service order and hadn’t noticed. TMF637 is product inventory, the instance they hold after the order completes. TMF663 is a shopping cart. Some digital channels have one. A shop form often doesn’t. I’ve watched a programme add a cart component because a reference picture had a box, and then spend two quarters integrating a step no channel called.
Service. TMF633 is the service catalog. TMF641 is the service order, the instruction to configure what she bought. TMF638 is what’s actually up. The customer-facing and resource-facing services from the SID post land here as records a system has to create.
Resource. TMF639 is inventory you already associate with something: the SIM, the MSISDN once it’s hers, the port. TMF685 is the pool you reserve from before that association exists. A free MSISDN in a pool and an MSISDN on Jane’s subscription are different objects. Estates that stuff both jobs into one “number API” spend the following year explaining how a number was sold and still available.
Account and billing. TMF666 is the account. TMF678 is the customer bill. TMF676 is the payment. People say “billing” and point at a platform. These are three calls, and they don’t happen in the same minute.
If you’re the one who will send the call: the number is not a path you invent. There is no GET /tmf622. The spec for that API says the resource names. The next article is the one with a request written out, on Party and Customer, because that’s where the SubscriberId ticket usually was.
If you’re the one writing the RFP: ask for a map onto this list. “Open API compliant” is a sentence. A missing qualification call, or a cart they can’t show in the channel you actually sell through, is something you can argue about on a Tuesday.
Jane, as calls
Same Jane. She wants a mobile plan, and you need it live. This path is simplified on purpose. If the shop already qualified her and you never call TMF679, say that out loud. If you have no cart, skip the box. I’m drawing a way to talk about the order. Your stack isn’t wrong for taking a different route.
She starts where the offer lives. TMF620 is how another system learns the plan exists, with price and terms, instead of a spreadsheet frozen in March.
Then someone asks whether she can have it. TMF679. Address, network, credit, whatever your rules actually are. The failure you want here is “the catalog said yes and the radio said no,” caught before anyone tells her it’s done.
Some journeys put a basket in between. TMF663 holds the offering while she adds a handset, or while a parent has to approve it. If the order is born from one form and one click, that call never happens. Leave it off your sequence rather than implementing an empty cart so the architecture slide stays symmetrical.
TMF622 is the product order. What she asked for gets a state you can say: acknowledged, in progress, completed, failed. On that order, the related party should be someone you can already name with TMF632, in the customer role you name with TMF629. This is the payload the two vendors both called TMF622. Same number. One of them had put the billing account where the other had put the person.
TMF641 is where the network gets told. Product was the sale. Service is the configuration: the access she experiences, and the bearer underneath it. I’ve sat in a review where the product order was green and nobody had sent a service order. The pack called it activation. The phone did not attach.
TMF637 is the product she now holds. Skip that write and the catalog slowly becomes your record of who has what, until a price change rewrites history. The SIM and the MSISDN are different records: reserve the number from the pool (TMF685) if it isn’t already hers, and keep the resource in TMF639. I left them off the arrow because operators sequence those calls differently. Pool, resource inventory, and product inventory are three records.
TMF678 is the bill that explains the charge. The account, TMF666, is often already open. A first-time buyer is the case you design for, not the template for every order. Payment, TMF676, happens when she pays: card today, a due date next month, or a dispute. I left it off the arrow. Taking the money matters. It isn’t the last step of switching the service on.
If the cell fails on Tuesday, leave this path alone. You already sold the product. Assurance is the work of getting the service back. Opening another TMF622 because the radio blinked is how orders sit “in progress” for a month and finance can’t tell a sale from a retry.
What I’m leaving on the table
Suppliers can both print TMF622 and still disagree in JSON, because one of them extended the order and then talked about the extension as if it were the baseline. @type is how you mark “this is our kind of product order.” Characteristics are where the private fields usually hide. Both get a proper example later.
There’s a second gap, about hearing rather than asking. TMF688 is how a system learns the order moved without polling it all afternoon. TMF921, intent, is a different kind of request: you describe the outcome, and something else works out the steps. That belongs with autonomous networks, not with Jane’s first plan. CAMARA and Open Gateway expose a thin slice of this to developers who will never open your order manager. Useful, and not this order.
I’m also stopping short of a sample body. A JSON blob, dropped in before anyone has agreed what relatedParty means, is how write-ups like this go wrong. Next time there’s a real call, against TMF632 and TMF629, and the test kit that tells you whether an implementation matches the contract.
Three questions for this week
- When we say TMF622, do we mean the product order in the spec, or our extra fields with the number painted on the slide?
- Does a cart exist in the channel people use, or did TMF663 show up because a picture had a gap in it?
- Which call reserves an MSISDN, and which call records it against Jane? If the answer is “the number system,” you don’t have an answer yet.
Key takeaways
- Open APIs are the calls. TMF630 is how those calls are shaped. Agree the ordinary fields before you argue about anyone’s extension.
- A short list is enough to start. Catalog, qualification, product order, service order, the inventories, the bill. Party and Customer stay two numbers.
- Call the path simplified, because it is. The cart is optional. Events, intent, and the test kit are the next arguments.
Terms in this post
Lookup only. The other numbers are on the figure.
| Term | Meaning in this post |
|---|---|
| Open API | An agreed call between systems. Frameworx calls this layer the Integration Framework |
| TMF630 | Design guidelines: resource name, id, href, create, read, update, filter |
| TMF622 | Product order. The call most people mean by “the order API” |
| TMF641 | Service order. The instruction to configure what was sold |
| TMF663 | Shopping cart. Optional. Many operators never had one |
| TMF685 | Resource pool. Reserve an MSISDN, or similar, before it is inventory |
| TMF632 | Party. The person or the company |
| TMF629 | Customer. That party, as a buyer, with you |
| TMF688 | Events. A system hears that the order moved, instead of polling it. Later post |
| TMF921 | Intent. You describe the outcome; something else works out the steps. Later post |
Next in this series: one real call. Party and Customer, a request you can read, and the kit that checks an implementation against the spec.
Leave a Reply