Open APIs

Hi,

TMF 681 samples show content related parameters are passed using characteristics name:value pairs.

{
	"id": "1708",
	"href": "https://serverlocation/tmf-api/communicationManagement/v4/communicationMessage/1708",
	"subject": "News: the latest promotion for you",
	"scheduledSendTime": "2020-02-10T00:00:00+01:00",
	"state": "initial",
	"description": "this is communication message for promotion",
	"content": "Dear $Parameter1, Here is the information of the promotion $Parameter2",
	"messageType": "SMS",
	"characteristic": [
		{
			"name": "$Parameter1",
			"value": "Mr. Jones",
			"valueType": "string"
		},
		{
			"name": "$Parameter2",
			"value": "4G_LTE Discount 30%",
			"valueType": "string"
		}
	],
	"attachment": [
		{
			"url": "https://serverlocation/files/1",
			"name": "File_XYZ_001"
		}
	],
	"sender": {
		"id": "10099",
		"name": "ABC Company",
		"phoneNumber": "10086"
	},
	"receiver": [
		{
			"id": "10234",
			"name": "Customer",
			"phoneNumber": "008613811112222",
			"party": {
				"id": "991",
				"href": "https://serverlocation/tmf-api/partyManagement/v4/individual/1",
				"role": "customer",
				"name": "John White",
				"@referredType": "Individual"
			}
		}
	]
}​

Say the content related parameter needs a complex object (for example product order related object from TMF 622) in order to construct the message - how is this recommended to be passed?
Could this be sent as a characteristic name:value, with valueType being an object and value carrying the JSON object like productOrder?

if not, what is the suggested guideline for sending content related parameters in 681 message?

Best regards, Raj
------------------------------
Rajkumar Bagavathiappan
BT Group plc
------------------------------

The alternative is to subclass the message type to include significant data as first-class fields of the payload.

I'm particularly interested in how far can you take characteristic values? I had always thought of them as essentially scalars - or at least simple non-hierarchical records.

What do others think?

------------------------------
Alasdair MacLeod
BT Group plc
------------------------------

Hi Rajkumar and Alasdair
After studying the user guide for TMF681, I am concerned that the semantics are incompletely specified.
There are hidden assumptions:

• The final communication message is a human-readable string (e.g. contents of an SMS)
• The message is constructed by the implementation of the API, using the content and the characteristics, with parameter substitution
• The responsibility is on the consumer to provide the raw content (with parameters) in the national language that makes sense for the receiver of the message

I don't think it makes sense to send a complex object as input to the API - what do we expect the implementation to do with (say) a product order?
I also don't understand how the message can become an app notification, without additional details - in order to send (e.g. to WhatsApp) there must be some way of specifying the target app and also any relevant metadata that the app might need in order to process the notification.

@Knut Johannessen what do you think?​

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
------------------------------

Original Message:
Sent: Feb 14, 2022 13:57
From: Alasdair MacLeod
Subject: TMF 681 - communication message - template parameters

The alternative is to subclass the message type to include significant data as first-class fields of the payload.

I'm particularly interested in how far can you take characteristic values? I had always thought of them as essentially scalars - or at least simple non-hierarchical records.

What do others think?

------------------------------
Alasdair MacLeod
BT Group plc
------------------------------

Jonathon, All,

I think there are three ways the API could be used:
1. The content field is the verbatim text to send.
2. The content field is a template and characteristics are explicit and direct substitution variables. <-- the example in the spec
3. The message is a more general request to send some message to some recipient and the content and subject might be determined by the messaging service.

I suggested (3) in this thread : https://engage.tmforum.org/communities/community-home/digestviewer/viewthread?GroupId=31&MessageKey=92e8f6e6-5821-4097-ab00-3a989ec22162&CommunityKey=d543b8ba-9d3a-4121-85ce-5b68e6c31ce5&tab=digestviewer

I am not convinced of the utility of use case (2) - if everything is explicitly defined up front in the request then why can't the client do the "mail merge" and just send the verbatim text to the recipient? I'm not saying it's an invalid use case - just not seeing the value over (1).

The pattern we employ in BT is close to (3) - systems send a messaging request including the relevant business entity to the messaging system and leave it to the messaging system to select the particular message/template to use and what data to extract from the entity. e.g. we might request an order acknowledgement be sent - we ship a copy of the order to the messaging system and the messaging system is responsible for extracting as much or as little data from the order as needed for the message - and the message content will vary by medium (e.g. SMS vs Email). When the business changes the format or content of the message we need only change the messaging system, the client is not impacted.  This is the context for discussions of an order payload embedded in the TMF681 message. We leave is to the messaging system to decide on the exact message and to extract the required data from the order payload. As I say - this is not a client concern.

------------------------------
Alasdair MacLeod
BT Group plc
------------------------------

Original Message:
Sent: Feb 14, 2022 15:34
From: Jonathan Goldberg
Subject: TMF 681 - communication message - template parameters

Hi Rajkumar and Alasdair
After studying the user guide for TMF681, I am concerned that the semantics are incompletely specified.
There are hidden assumptions:

• The final communication message is a human-readable string (e.g. contents of an SMS)
• The message is constructed by the implementation of the API, using the content and the characteristics, with parameter substitution
• The responsibility is on the consumer to provide the raw content (with parameters) in the national language that makes sense for the receiver of the message

I don't think it makes sense to send a complex object as input to the API - what do we expect the implementation to do with (say) a product order?
I also don't understand how the message can become an app notification, without additional details - in order to send (e.g. to WhatsApp) there must be some way of specifying the target app and also any relevant metadata that the app might need in order to process the notification.

@Knut Johannessen what do you think?​

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
------------------------------


Original Message:
Sent: Feb 14, 2022 13:57
From: Alasdair MacLeod
Subject: TMF 681 - communication message - template parameters

The alternative is to subclass the message type to include significant data as first-class fields of the payload.

I'm particularly interested in how far can you take characteristic values? I had always thought of them as essentially scalars - or at least simple non-hierarchical records.

What do others think?

------------------------------
Alasdair MacLeod
BT Group plc

Hi Alasdair

Use case 3 is clearly not supported currently by the API, since the API model does not support passing an arbitrary object when POSTing the message.

I don't see how this is use case is feasible. If the message system can receive a product order (your example), a trouble ticket, a customer bill, etc., you are expecting the message system to be familiar with the entire API model. Surely it's the responsibility of the consumer, which originated the need for sending the message, to decide what data needs to be sent. So (for example) an Order Handling system might want to notify the customer that the order has been completed, Order Handling is the consumer of the message service and it "knows" what parts of the order it wants to embed within the message.

For use case 2, I can see the value of parameter substitution if a message text ID was sent as input instead of the message content. In that case, we could imagine a "bank" of message texts, that could be sensitive to end-user natural language and to channel, and the parameters would be embedded within each text. But also this is not supported in the current model.

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
------------------------------

Original Message:
Sent: Feb 14, 2022 16:23
From: Alasdair MacLeod
Subject: TMF 681 - communication message - template parameters

Jonathon, All,

I think there are three ways the API could be used:
1. The content field is the verbatim text to send.
2. The content field is a template and characteristics are explicit and direct substitution variables. <-- the example in the spec
3. The message is a more general request to send some message to some recipient and the content and subject might be determined by the messaging service.

I suggested (3) in this thread : https://engage.tmforum.org/communities/community-home/digestviewer/viewthread?GroupId=31&MessageKey=92e8f6e6-5821-4097-ab00-3a989ec22162&CommunityKey=d543b8ba-9d3a-4121-85ce-5b68e6c31ce5&tab=digestviewer

I am not convinced of the utility of use case (2) - if everything is explicitly defined up front in the request then why can't the client do the "mail merge" and just send the verbatim text to the recipient? I'm not saying it's an invalid use case - just not seeing the value over (1).

The pattern we employ in BT is close to (3) - systems send a messaging request including the relevant business entity to the messaging system and leave it to the messaging system to select the particular message/template to use and what data to extract from the entity. e.g. we might request an order acknowledgement be sent - we ship a copy of the order to the messaging system and the messaging system is responsible for extracting as much or as little data from the order as needed for the message - and the message content will vary by medium (e.g. SMS vs Email). When the business changes the format or content of the message we need only change the messaging system, the client is not impacted.  This is the context for discussions of an order payload embedded in the TMF681 message. We leave is to the messaging system to decide on the exact message and to extract the required data from the order payload. As I say - this is not a client concern.

------------------------------
Alasdair MacLeod
BT Group plc
------------------------------


Original Message:
Sent: Feb 14, 2022 15:34
From: Jonathan Goldberg
Subject: TMF 681 - communication message - template parameters

Hi Rajkumar and Alasdair
After studying the user guide for TMF681, I am concerned that the semantics are incompletely specified.
There are hidden assumptions:

• The final communication message is a human-readable string (e.g. contents of an SMS)
• The message is constructed by the implementation of the API, using the content and the characteristics, with parameter substitution
• The responsibility is on the consumer to provide the raw content (with parameters) in the national language that makes sense for the receiver of the message

I don't think it makes sense to send a complex object as input to the API - what do we expect the implementation to do with (say) a product order?
I also don't understand how the message can become an app notification, without additional details - in order to send (e.g. to WhatsApp) there must be some way of specifying the target app and also any relevant metadata that the app might need in order to process the notification.

@Knut Johannessen what do you think?​

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.


Original Message:
Sent: Feb 14, 2022 13:57
From: Alasdair MacLeod
Subject: TMF 681 - communication message - template parameters

The alternative is to subclass the message type to include significant data as first-class fields of the payload.

I'm particularly interested in how far can you take characteristic values? I had always thought of them as essentially scalars - or at least simple non-hierarchical records.

What do others think?

------------------------------
Alasdair MacLeod
BT Group plc

Hello All,
I would tend to agree with Jonathan. 
In a past life I was asked to do something similar involving attaching a Diagnostic Test Result object as part of a notification relating to a closed Trouble Ticket.

The main issue I had with the notion was that it created a dependency for the Test Result schema and the Trouble Ticket schema creating a rather odd hybrid API that was a mixture of two resource types. But also the Test Result object was 20 times bigger than the Trouble Ticket Status Notification it was "attached" to.

Our resolution was to do one of two things. Either include in the Trouble Ticket resource a subset of the relevant Diagnostic Test information. Or require the receiving application of the notification to do a GET on the Diagnostic Test result resource to gather the information if they so desired.

------------------------------
Derrick Evans
------------------------------

Original Message:
Sent: Feb 15, 2022 04:31
From: Jonathan Goldberg
Subject: TMF 681 - communication message - template parameters

Hi Alasdair

Use case 3 is clearly not supported currently by the API, since the API model does not support passing an arbitrary object when POSTing the message.

I don't see how this is use case is feasible. If the message system can receive a product order (your example), a trouble ticket, a customer bill, etc., you are expecting the message system to be familiar with the entire API model. Surely it's the responsibility of the consumer, which originated the need for sending the message, to decide what data needs to be sent. So (for example) an Order Handling system might want to notify the customer that the order has been completed, Order Handling is the consumer of the message service and it "knows" what parts of the order it wants to embed within the message.

For use case 2, I can see the value of parameter substitution if a message text ID was sent as input instead of the message content. In that case, we could imagine a "bank" of message texts, that could be sensitive to end-user natural language and to channel, and the parameters would be embedded within each text. But also this is not supported in the current model.

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
------------------------------


Original Message:
Sent: Feb 14, 2022 16:23
From: Alasdair MacLeod
Subject: TMF 681 - communication message - template parameters

Jonathon, All,

I think there are three ways the API could be used:
1. The content field is the verbatim text to send.
2. The content field is a template and characteristics are explicit and direct substitution variables. <-- the example in the spec
3. The message is a more general request to send some message to some recipient and the content and subject might be determined by the messaging service.

I suggested (3) in this thread : https://engage.tmforum.org/communities/community-home/digestviewer/viewthread?GroupId=31&MessageKey=92e8f6e6-5821-4097-ab00-3a989ec22162&CommunityKey=d543b8ba-9d3a-4121-85ce-5b68e6c31ce5&tab=digestviewer

I am not convinced of the utility of use case (2) - if everything is explicitly defined up front in the request then why can't the client do the "mail merge" and just send the verbatim text to the recipient? I'm not saying it's an invalid use case - just not seeing the value over (1).

The pattern we employ in BT is close to (3) - systems send a messaging request including the relevant business entity to the messaging system and leave it to the messaging system to select the particular message/template to use and what data to extract from the entity. e.g. we might request an order acknowledgement be sent - we ship a copy of the order to the messaging system and the messaging system is responsible for extracting as much or as little data from the order as needed for the message - and the message content will vary by medium (e.g. SMS vs Email). When the business changes the format or content of the message we need only change the messaging system, the client is not impacted.  This is the context for discussions of an order payload embedded in the TMF681 message. We leave is to the messaging system to decide on the exact message and to extract the required data from the order payload. As I say - this is not a client concern.

------------------------------
Alasdair MacLeod
BT Group plc


Original Message:
Sent: Feb 14, 2022 15:34
From: Jonathan Goldberg
Subject: TMF 681 - communication message - template parameters

Hi Rajkumar and Alasdair
After studying the user guide for TMF681, I am concerned that the semantics are incompletely specified.
There are hidden assumptions:

• The final communication message is a human-readable string (e.g. contents of an SMS)
• The message is constructed by the implementation of the API, using the content and the characteristics, with parameter substitution
• The responsibility is on the consumer to provide the raw content (with parameters) in the national language that makes sense for the receiver of the message

I don't think it makes sense to send a complex object as input to the API - what do we expect the implementation to do with (say) a product order?
I also don't understand how the message can become an app notification, without additional details - in order to send (e.g. to WhatsApp) there must be some way of specifying the target app and also any relevant metadata that the app might need in order to process the notification.

@Knut Johannessen what do you think?​

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.


Original Message:
Sent: Feb 14, 2022 13:57
From: Alasdair MacLeod
Subject: TMF 681 - communication message - template parameters

The alternative is to subclass the message type to include significant data as first-class fields of the payload.

I'm particularly interested in how far can you take characteristic values? I had always thought of them as essentially scalars - or at least simple non-hierarchical records.

What do others think?

------------------------------
Alasdair MacLeod
BT Group plc