Open APIs

Hi Peter,

I think one important aspect that may not be fully explicit in the discussion is where contactMedium actually exists in the TMF model, even though TMF621 only allows references.

In TMF621 TroubleTicket, relatedParty is defined as:

RelatedPartyRefOrPartyRoleRef └─ partyOrPartyRole (oneOf)    ├─ PartyRef    └─ PartyRoleRef

Although these are references, the referenced entities themselves do support contactMedium.

1. PartyRef

PartyRef is a reference to either an Individual or an Organization.

• Individual → allOf Party

• Organization → allOf Party

And Party defines:

contactMedium[]

So, when you reference an Individual or Organization via PartyRef, you are implicitly referencing a Party that may already have contactMedium information defined.

2. PartyRoleRef

PartyRoleRef references a PartyRole (from TMF632).

• PartyRole is an entity in its own right

• PartyRole also defines contactMedium[]

This is explicitly intended to support cases where contact information depends on the role the party is playing, for example:

• customer contact

• billing contact

• technical contact

Key takeaway

Conceptually, the TMF model already supports:

• Contact details on Party (Individual / Organization)

• Contact details on PartyRole, when role-specific contact data is required

The real limitation here is not the information model, but the TMF621 TroubleTicket payload, which only allows references (PartyRef / PartyRoleRef) and does not allow embedding full Party or PartyRole objects inline.

On possible alternatives

What you may be looking for conceptually is something like partyRefOrValue.
However, the TroubleTicket schema only defines:

RelatedPartyRefOrPartyRoleRef

You would need something like:

RelatedPartyRefOrPartyRoleRefOrValue

Unfortunately, such a construct does not exist in TMF621.

This is indeed similar to the approach used in ProductOrder / ProductOrderItem, where productRefOrValue exists to support creation and modification during ordering. That flexibility, however, was not carried over to TroubleTicket.

Best regards,
Subhanshu

Hi Peter,
Subhanshus analysis is totally correct, you cannt include teh Party/PartyRole (and thus the ContactMedium) by value into the TroubleTicket API's payload.
But the solution is not to make it possible to include a Party or PartyRole by value, but to use the references you get in the TroubleTicket to access the Party resp. PartyRole API to retrieve that data, which then includes the ContactMedium.
The difference to Product Ordering API, which may include the Product by reference or value, is that when you order some Product, it probably is not yet in the Product Inventoty, so a reference is not enough. You then have to include the Product by value, and only when the order is fulfilled the Product will be persited in the inventory.
In contrast, TroubleTicket API assumes that data on the the person/organization already exists and thus can be retrieved from the Party API, so there is no need to redundantly store that information in the Trouble Ticket.
Does that kame sense for you?
Best Regards,
Lutz

Hi Peter,

I think one important aspect that may not be fully explicit in the discussion is where contactMedium actually exists in the TMF model, even though TMF621 only allows references.

In TMF621 TroubleTicket, relatedParty is defined as:

RelatedPartyRefOrPartyRoleRef └─ partyOrPartyRole (oneOf)    ├─ PartyRef    └─ PartyRoleRef

Although these are references, the referenced entities themselves do support contactMedium.

1. PartyRef

PartyRef is a reference to either an Individual or an Organization.

• Individual → allOf Party

• Organization → allOf Party

And Party defines:

contactMedium[]

So, when you reference an Individual or Organization via PartyRef, you are implicitly referencing a Party that may already have contactMedium information defined.

2. PartyRoleRef

PartyRoleRef references a PartyRole (from TMF632).

• PartyRole is an entity in its own right

• PartyRole also defines contactMedium[]

This is explicitly intended to support cases where contact information depends on the role the party is playing, for example:

• customer contact

• billing contact

• technical contact

Key takeaway

Conceptually, the TMF model already supports:

• Contact details on Party (Individual / Organization)

• Contact details on PartyRole, when role-specific contact data is required

The real limitation here is not the information model, but the TMF621 TroubleTicket payload, which only allows references (PartyRef / PartyRoleRef) and does not allow embedding full Party or PartyRole objects inline.

On possible alternatives

What you may be looking for conceptually is something like partyRefOrValue.
However, the TroubleTicket schema only defines:

RelatedPartyRefOrPartyRoleRef

You would need something like:

RelatedPartyRefOrPartyRoleRefOrValue

Unfortunately, such a construct does not exist in TMF621.

This is indeed similar to the approach used in ProductOrder / ProductOrderItem, where productRefOrValue exists to support creation and modification during ordering. That flexibility, however, was not carried over to TroubleTicket.

Best regards,
Subhanshu

We are effectively looking for a solution related the a certain role the contact is playing: the phone number to be used can be really linked to the role.

I fully agree with the analysis that, when dealing with contacts internally in the company where you can 'manage' your contacts. We effectively do this by using TMF632-like functionality to create contacts as a party, allocate an ID etc.

However in a B2B, Wholesale context:
1) the contact is rather managed by the external party
2) we get a limited part of the contact information, only relevant for the process / transaction, only what regulation allows
For example, for a new installation via a product order we might require a phone number to get access to a technical room, we might also get a name but maybe not.
This kind of information is short-lived, valid only during the order processing or during a ticket resolution process. 

I understood that there is an alignment track defined to the alignment between MEF & .TMF. 
MEF went for a different approach with a totally separate class for contact / contact medium information (see W123.1 in LSO Cantata & LSO Sonata):
7.2.9.13. Type RelatedContactInformation
Description: Contact information of an individual or organization playing a role for this Order Item. The rule for mapping a represented attribute value to a role is to use the lowerCamelCase
pattern e.g.
Buyer Order Item Contact: role=buyerOrderItemContact
Buyer Implementation Contact: role=buyerImplementationContact
Buyer Technical Contact: role=buyerTechnicalContact

Name Type M/O Description MEF57.2

emailAddress: string M - Email address
name: string M - Name of the contact
number: string M - Phone number
numberExtension: string O - Phone number extension
organization: string O - The organization or company that the contact belongs to
postalAddress: FieldedAddressRepresentation O -Identifies the postal address of the person or office to be contacted.
role: string M A -role the party plays in a given context.

I am personally not so in favor of MEF's approach with a totally separate class as semantically there is a party & a party role, only maybe with incomplete info, not 'managed'.
Probably the best way is to enforce the external party, prior to creating a ticket or product order, to first create any contact via TMF632, store the ID's.
However I feel like this is heavy & potentially difficult as you might even consider there is not enough info to create a valid party... MEF's process does also not contain such contact creation step.

TMF should supported multiple use cases and different settings. I wonder if the best way forward would not rather simply be that TMF621 and TMF622 would add also on Product Order and Ticket top level:

RelatedPartyRefOrPartyRoleRefOrValue

Hi Peter,
Subhanshus analysis is totally correct, you cannt include teh Party/PartyRole (and thus the ContactMedium) by value into the TroubleTicket API's payload.
But the solution is not to make it possible to include a Party or PartyRole by value, but to use the references you get in the TroubleTicket to access the Party resp. PartyRole API to retrieve that data, which then includes the ContactMedium.
The difference to Product Ordering API, which may include the Product by reference or value, is that when you order some Product, it probably is not yet in the Product Inventoty, so a reference is not enough. You then have to include the Product by value, and only when the order is fulfilled the Product will be persited in the inventory.
In contrast, TroubleTicket API assumes that data on the the person/organization already exists and thus can be retrieved from the Party API, so there is no need to redundantly store that information in the Trouble Ticket.
Does that kame sense for you?
Best Regards,
Lutz

Hi Peter,

I think one important aspect that may not be fully explicit in the discussion is where contactMedium actually exists in the TMF model, even though TMF621 only allows references.

In TMF621 TroubleTicket, relatedParty is defined as:

RelatedPartyRefOrPartyRoleRef └─ partyOrPartyRole (oneOf)    ├─ PartyRef    └─ PartyRoleRef

Although these are references, the referenced entities themselves do support contactMedium.

1. PartyRef

PartyRef is a reference to either an Individual or an Organization.

• Individual → allOf Party

• Organization → allOf Party

And Party defines:

contactMedium[]

So, when you reference an Individual or Organization via PartyRef, you are implicitly referencing a Party that may already have contactMedium information defined.

2. PartyRoleRef

PartyRoleRef references a PartyRole (from TMF632).

• PartyRole is an entity in its own right

• PartyRole also defines contactMedium[]

This is explicitly intended to support cases where contact information depends on the role the party is playing, for example:

• customer contact

• billing contact

• technical contact

Key takeaway

Conceptually, the TMF model already supports:

• Contact details on Party (Individual / Organization)

• Contact details on PartyRole, when role-specific contact data is required

The real limitation here is not the information model, but the TMF621 TroubleTicket payload, which only allows references (PartyRef / PartyRoleRef) and does not allow embedding full Party or PartyRole objects inline.

On possible alternatives

What you may be looking for conceptually is something like partyRefOrValue.
However, the TroubleTicket schema only defines:

RelatedPartyRefOrPartyRoleRef

You would need something like:

RelatedPartyRefOrPartyRoleRefOrValue

Unfortunately, such a construct does not exist in TMF621.

This is indeed similar to the approach used in ProductOrder / ProductOrderItem, where productRefOrValue exists to support creation and modification during ordering. That flexibility, however, was not carried over to TroubleTicket.

Best regards,
Subhanshu

We are effectively looking for a solution related the a certain role the contact is playing: the phone number to be used can be really linked to the role.

I fully agree with the analysis that, when dealing with contacts internally in the company where you can 'manage' your contacts. We effectively do this by using TMF632-like functionality to create contacts as a party, allocate an ID etc.

However in a B2B, Wholesale context:
1) the contact is rather managed by the external party
2) we get a limited part of the contact information, only relevant for the process / transaction, only what regulation allows
For example, for a new installation via a product order we might require a phone number to get access to a technical room, we might also get a name but maybe not.
This kind of information is short-lived, valid only during the order processing or during a ticket resolution process. 

I understood that there is an alignment track defined to the alignment between MEF & .TMF. 
MEF went for a different approach with a totally separate class for contact / contact medium information (see W123.1 in LSO Cantata & LSO Sonata):
7.2.9.13. Type RelatedContactInformation
Description: Contact information of an individual or organization playing a role for this Order Item. The rule for mapping a represented attribute value to a role is to use the lowerCamelCase
pattern e.g.
Buyer Order Item Contact: role=buyerOrderItemContact
Buyer Implementation Contact: role=buyerImplementationContact
Buyer Technical Contact: role=buyerTechnicalContact

Name Type M/O Description MEF57.2

emailAddress: string M - Email address
name: string M - Name of the contact
number: string M - Phone number
numberExtension: string O - Phone number extension
organization: string O - The organization or company that the contact belongs to
postalAddress: FieldedAddressRepresentation O -Identifies the postal address of the person or office to be contacted.
role: string M A -role the party plays in a given context.

I am personally not so in favor of MEF's approach with a totally separate class as semantically there is a party & a party role, only maybe with incomplete info, not 'managed'.
Probably the best way is to enforce the external party, prior to creating a ticket or product order, to first create any contact via TMF632, store the ID's.
However I feel like this is heavy & potentially difficult as you might even consider there is not enough info to create a valid party... MEF's process does also not contain such contact creation step.

TMF should supported multiple use cases and different settings. I wonder if the best way forward would not rather simply be that TMF621 and TMF622 would add also on Product Order and Ticket top level:

RelatedPartyRefOrPartyRoleRefOrValue

Hi Peter,
Subhanshus analysis is totally correct, you cannt include teh Party/PartyRole (and thus the ContactMedium) by value into the TroubleTicket API's payload.
But the solution is not to make it possible to include a Party or PartyRole by value, but to use the references you get in the TroubleTicket to access the Party resp. PartyRole API to retrieve that data, which then includes the ContactMedium.
The difference to Product Ordering API, which may include the Product by reference or value, is that when you order some Product, it probably is not yet in the Product Inventoty, so a reference is not enough. You then have to include the Product by value, and only when the order is fulfilled the Product will be persited in the inventory.
In contrast, TroubleTicket API assumes that data on the the person/organization already exists and thus can be retrieved from the Party API, so there is no need to redundantly store that information in the Trouble Ticket.
Does that kame sense for you?
Best Regards,
Lutz

Hi Peter,

I think one important aspect that may not be fully explicit in the discussion is where contactMedium actually exists in the TMF model, even though TMF621 only allows references.

In TMF621 TroubleTicket, relatedParty is defined as:

RelatedPartyRefOrPartyRoleRef └─ partyOrPartyRole (oneOf)    ├─ PartyRef    └─ PartyRoleRef

Although these are references, the referenced entities themselves do support contactMedium.

1. PartyRef

PartyRef is a reference to either an Individual or an Organization.

• Individual → allOf Party

• Organization → allOf Party

And Party defines:

contactMedium[]

So, when you reference an Individual or Organization via PartyRef, you are implicitly referencing a Party that may already have contactMedium information defined.

2. PartyRoleRef

PartyRoleRef references a PartyRole (from TMF632).

• PartyRole is an entity in its own right

• PartyRole also defines contactMedium[]

This is explicitly intended to support cases where contact information depends on the role the party is playing, for example:

• customer contact

• billing contact

• technical contact

Key takeaway

Conceptually, the TMF model already supports:

• Contact details on Party (Individual / Organization)

• Contact details on PartyRole, when role-specific contact data is required

The real limitation here is not the information model, but the TMF621 TroubleTicket payload, which only allows references (PartyRef / PartyRoleRef) and does not allow embedding full Party or PartyRole objects inline.

On possible alternatives

What you may be looking for conceptually is something like partyRefOrValue.
However, the TroubleTicket schema only defines:

RelatedPartyRefOrPartyRoleRef

You would need something like:

RelatedPartyRefOrPartyRoleRefOrValue

Unfortunately, such a construct does not exist in TMF621.

This is indeed similar to the approach used in ProductOrder / ProductOrderItem, where productRefOrValue exists to support creation and modification during ordering. That flexibility, however, was not carried over to TroubleTicket.

Best regards,
Subhanshu

One option could be requiring the external party to offer a party mgmt/contact info API and retrieve the relevant info using the received id/reference.

This approach is a bit more involved but also has some benefits: external party can manage/update the info internally; you could decide to retrieve and persist the info or simply retrieve it on the fly when necessary.

We are effectively looking for a solution related the a certain role the contact is playing: the phone number to be used can be really linked to the role.

I fully agree with the analysis that, when dealing with contacts internally in the company where you can 'manage' your contacts. We effectively do this by using TMF632-like functionality to create contacts as a party, allocate an ID etc.

However in a B2B, Wholesale context:
1) the contact is rather managed by the external party
2) we get a limited part of the contact information, only relevant for the process / transaction, only what regulation allows
For example, for a new installation via a product order we might require a phone number to get access to a technical room, we might also get a name but maybe not.
This kind of information is short-lived, valid only during the order processing or during a ticket resolution process. 

I understood that there is an alignment track defined to the alignment between MEF & .TMF. 
MEF went for a different approach with a totally separate class for contact / contact medium information (see W123.1 in LSO Cantata & LSO Sonata):
7.2.9.13. Type RelatedContactInformation
Description: Contact information of an individual or organization playing a role for this Order Item. The rule for mapping a represented attribute value to a role is to use the lowerCamelCase
pattern e.g.
Buyer Order Item Contact: role=buyerOrderItemContact
Buyer Implementation Contact: role=buyerImplementationContact
Buyer Technical Contact: role=buyerTechnicalContact

Name Type M/O Description MEF57.2

emailAddress: string M - Email address
name: string M - Name of the contact
number: string M - Phone number
numberExtension: string O - Phone number extension
organization: string O - The organization or company that the contact belongs to
postalAddress: FieldedAddressRepresentation O -Identifies the postal address of the person or office to be contacted.
role: string M A -role the party plays in a given context.

I am personally not so in favor of MEF's approach with a totally separate class as semantically there is a party & a party role, only maybe with incomplete info, not 'managed'.
Probably the best way is to enforce the external party, prior to creating a ticket or product order, to first create any contact via TMF632, store the ID's.
However I feel like this is heavy & potentially difficult as you might even consider there is not enough info to create a valid party... MEF's process does also not contain such contact creation step.

TMF should supported multiple use cases and different settings. I wonder if the best way forward would not rather simply be that TMF621 and TMF622 would add also on Product Order and Ticket top level:

RelatedPartyRefOrPartyRoleRefOrValue

Hi Peter,
Subhanshus analysis is totally correct, you cannt include teh Party/PartyRole (and thus the ContactMedium) by value into the TroubleTicket API's payload.
But the solution is not to make it possible to include a Party or PartyRole by value, but to use the references you get in the TroubleTicket to access the Party resp. PartyRole API to retrieve that data, which then includes the ContactMedium.
The difference to Product Ordering API, which may include the Product by reference or value, is that when you order some Product, it probably is not yet in the Product Inventoty, so a reference is not enough. You then have to include the Product by value, and only when the order is fulfilled the Product will be persited in the inventory.
In contrast, TroubleTicket API assumes that data on the the person/organization already exists and thus can be retrieved from the Party API, so there is no need to redundantly store that information in the Trouble Ticket.
Does that kame sense for you?
Best Regards,
Lutz