A TM Forum API, Written Out: Party First, Then the Customer

The last post stopped where the ticket usually starts. Both vendors had TMF622 on the slide. I opened the two example payloads. One had put the billing account where the other had put the person. I kept the JSON out of that article on purpose. A body, dropped in before anyone has agreed what the person is, is how these write-ups go wrong.

This is that body. A TM Forum API tutorial with two creates and one read. Jane Doe is a person before she is a buyer. SID Explained already split Party from Customer. Open APIs Explained named the calls and then refused to paste them. You can follow this page with the requests in front of you.

At a Glance

There is no GET /tmf632. The number is the contract. The path is the resource: individual, then customer.
Create the person on TMF632 first. Create the buyer on TMF629 second, and point engagedParty at the person you just got back.
The Conformance Test Kit checks whether an implementation matches that contract. It doesn’t check whether your 2014 SubscriberId was mapped.

The body I would not paste

The argument in the room was about the product order. The mismatch was this pair. TMF632 is the person or the company. TMF629 is that party, as a buyer, with you. An employee, a roaming partner, a contact who has not bought anything: still TMF632. The buyer you bill: TMF629, and only once they are a buyer.

Jane wants a mobile plan. We’re not ordering it yet. We’re making a record the order can point at on Thursday without another workshop. Two creates. One read, to prove the second still points at the first. Then we stop. The product order is a later argument.

The path is not the number

TMF630 is still the ordinary part of the design guidelines: a resource you can say out loud, an id, an href, and the usual create and read. The server mints the id. You store the href. The number on the slide is not a URL. There is no GET /tmf632 and no GET /tmf629.

I’m writing the creates as POST /partyManagement/v5/individual and POST /customerManagement/v5/customer. Your gateway may put a host in front of that, or a /tmf-api prefix, or a different version. Those change. The resource names are the part two teams have to share.

@type shows up because the body has to say which concrete thing this is. On the first call it is Individual. On the second it is Customer. That is a label so the receiver knows which shape it was given. It is not the essay on extensions. Characteristics, private fields, and the rest of how a payload grows are the next post. If you need them before you can create a plain individual, say so. Don’t pretend the extra field is the standard.

Jane, before she buys anything

She is Jane Doe. She has an email. She does not yet have an account number, a plan, or a SIM. That is the whole of the first body.

POST /partyManagement/v5/individual

{
  "@type": "Individual",
  "givenName": "Jane",
  "familyName": "Doe",
  "contactMedium": [
    {
      "@type": "EmailContactMedium",
      "preferred": true,
      "emailAddress": "jane.doe@example.com"
    }
  ]
}

I’m leaving mediumType off. Some published examples still send it beside @type. The address is the part that has to be there.

The server answers with the record it stored. I’m keeping the fields that matter on Thursday and dropping the echo of the email. 1142 is an example. Your platform will mint its own.

{
  "id": "1142",
  "href": "/partyManagement/v5/individual/1142",
  "@type": "Individual",
  "givenName": "Jane",
  "familyName": "Doe"
}

The href is the address you keep. The next system comes back to that address. It doesn’t come back to the workshop where someone said “Jane.”

The failure I still see is shorter than the payload. The CRM had one table, so the person and the account number became the same row, and then the same JSON.

{
  "@type": "Individual",
  "givenName": "Jane",
  "familyName": "Doe",
  "SubscriberId": "SUB-2014-4491"
}

SubscriberId is the string from the ticket. The individual spec doesn’t have that field. Putting it here doesn’t make the mapping done. It hides the mapping inside a body both sides will call TMF632.

Then she is a customer

The second call is the commercial role. The name on the customer can be “Jane Doe.” It doesn’t have to be. A residential bill sometimes carries a different line from the legal name. One sentence is enough for that. Don’t open a naming policy in the same hour as the first create.

POST /customerManagement/v5/customer

{
  "@type": "Customer",
  "name": "Jane Doe",
  "engagedParty": {
    "@type": "PartyRef",
    "@referredType": "Individual",
    "id": "1142",
    "href": "/partyManagement/v5/individual/1142",
    "name": "Jane Doe"
  }
}

engagedParty is the point of the call. It says which party is playing this role. The id and the href are the ones the first response gave you. @referredType says that party is an individual, not an organization. A company buyer is the same shape with a different referred type, and I’m not drawing that today.

Figure: Two creates. Teal is the order. Copper is the field that stores the href.

On copies of the customer spec still sitting in a lot of wikis, engagedParty is typed as a related party. The reference to implement is a party reference: this customer is this individual. If the asset on your desk still says related party, keep the href anyway. Don’t spend the meeting on which generation of the PDF you printed.

I’m not putting a status on this body. The user guide on your desk has a list, and that list moves. Inventing a polite word for the sample is how a tutorial becomes a lifecycle nobody agreed.

Read it back on Thursday

Ask for the customer the second call just created. The id in this line is the customer’s id. It is not 1142. People collapse those two, and the ticket comes back with a new subject.

GET /customerManagement/v5/customer/8831

{
  "id": "8831",
  "href": "/customerManagement/v5/customer/8831",
  "@type": "Customer",
  "name": "Jane Doe",
  "engagedParty": {
    "@type": "PartyRef",
    "@referredType": "Individual",
    "id": "1142",
    "href": "/partyManagement/v5/individual/1142",
    "name": "Jane Doe"
  }
}

The check is small. The href under engagedParty is the same address the party call returned. Two teams can open it and mean the same person. That is the replacement for the mapping workshop, for this one object. It isn’t the product order. We still haven’t sold the plan. TMF622 can wait until this pointer is boring.

Three tools, three jobs

The OpenAPI file is the contract for one API. You import it so the field names are the spec’s, not a slide’s. “Open APIs” in the last post meant the catalogue of calls. OpenAPI here means the file for TMF632, or the file for TMF629. They are easy to say in the same breath, and they are not the same thing.

Postman, or any client you already have, is how a person sends the two creates and the read. A collection is useful once the bodies above are the ones you mean. Exporting it does not turn the collection into the standard.

The Conformance Test Kit is the third thing, and it is not a nicer Postman. You download it with the API assets. Membership is what gets you the kit. There isn’t a public URL I can leave here that will still be the file next year, and I’m not pasting a config.json out of a forum thread. You point the kit at an implementation. It runs a suite and writes a report. A pass means that implementation matches the conformance profile for that API: the resource can be created, read, and shaped the way the profile says. It doesn’t mean your SubscriberId was mapped, and it doesn’t certify the estate.

A green kit, and the ticket still open

Both sides can conform and still disagree when the order is written. One of them puts the billing account where the other puts the person, and both reports are green, because the kit never saw the 2014 field. The kit doesn’t know SubscriberId. You do.

Standards are not laws. An estate can pass TMF632 and keep a local party table beside it for another decade. Coexistence is normal. What still breaks the order is calling that local column the standard because the report was green.

Who owns the map is a name, not a platform. If the answer is “the middleware,” you have the same ticket with a longer subject line.

Three questions for this week

When we create a buyer, which field holds the person, and can we open that href on Tuesday?
Are we about to POST a customer for someone who is only a contact, an employee, or a partner?
If the conformance report is green, who still owns the map from SubscriberId to customer.id?

Key takeaways

Two calls, in that order. Individual first. Customer second, pointing back through engagedParty.
Keep the href. The number on the slide is not a URL, and the customer id is not the party id.
The kit checks the contract. The mapping ticket is still yours.

Terms in this post

Lookup only. The calls are above.

Term	Meaning in this post
TMF630	Design guidelines. Resource name, id, href, create and read.
TMF632	Party. Create the individual here.
TMF629	Customer. The party in the role of buyer.
TMF622	Product order. The number both vendors printed. This post stops before that call.
engagedParty	On the customer, the reference back to that party.
PartyRef	The type of that reference. A pointer to the individual.
href	The address the server returned. Store it.
@type	Which concrete body this is: Individual or Customer.
CTK	Conformance Test Kit. It tests an implementation against the API profile.
OpenAPI	The contract file for one API. Not the catalogue of Open APIs.

Next in this series: what @type is for once the body is no longer plain. Extensions, how a system hears that the record changed, and how the caller is allowed in.

Previous: Open APIs Explained: The Calls That Move a Telco Order