TMF629 v4 Resource Mappings

Before using the TMF629 resource mappings, refer to the following.

Constraints and Limitations

The id, href, and agreement, are not patchable attributes.
Each element inside contactMedium can be patched like phoneNumber, emailAddress and faxNumber. And only these fields are patchable inside characteristic field.
All the validations for contactmedium of POST method are also applicable for PATCH method as well.
- mediumType and characteristic are mandatory.
Removing of any of the contactmedium entry is supported.
When updating the contactMedium for non-existing engagedParty no change is observed.
Ensure that accounts that are patched must be existing accounts in the system.
Ensure that there is no cyclic dependency for an account.
It is advised and not mandated to have unique email in every request in the contactMedium.
The DELETE operation deletes the associated contacts and resets the relation with associated account. If the contact is not deletable, then the corresponding message from database is displayed.
If multiple entries for same mediumType are present in the request, then only one of the entry for the mediumType is considered.
When updating engagedParty with an existing or new contact, contactMedium is also updated as per the new contact information. For example, if a customer wants to update engagedParty it is advised to send contactMedium information as well that is updated for a new contact.

Assumptions

The customer (Accounts Object) created using the API operates in the same fashion as Account records created from Salesforce UI. These can be utilized in all other flows and business processes.
The Characteristics sub-resource, provided by the customer is a free text. This is not supported in Salesforce out-of-the-box implementation.
The TMF629 API POST message expects ID for entity references, such as AccountRef, PaymentMethodRef and AgreementRef. The ID should exist in the Salesforce ORG. If not, the API call fails, and an appropriate error message is generated.
The CreditProfile node is not supported.
The name and id fields are mandatory for the AccountRef sub-resource.
The engagedParty association is supported. The relatedParty entity contains the customer details associated with the given account.
The AccountRef node contains the details of all the accounts that are related to the given customer, that includes service account, Billing account, and so on.
- In GET API, Account node contains the list of all the accounts that are referred to a customer.
- In POST API, request is expected to have the id and name of the account. The account with the given id and name should pre-exist in the Salesforce ORG. If not, the API call fails and an appropriate error message is generated.
The PaymentMethod is not be supported out-of-the-box, as the Object is a custom object and available in the package. However, a customer who wishes to use to the payment method can do so by exposing an Apex end point and internally use the core end point.
Account Sub-resource:
- The id and name fields are mandatory for an account. Use existing account’s name and id in the payload.
- If the account has any previous ParentId field, it is updated with the new account that is created.
EngagedParty Sub-resource:
- A new contact can be created or an existing contact be used.
- Id can be passed in engagedParty along with the name and name is updated for the contact Id sent in the request.
ContactMedium Sub-resource:
- Maximum only 3 elements can be added in this sub-resource: email, phone, and fax
- Same information is populated in all the contacts that are created from the engagedParty.
Agreement Sub-resource :
- Not supported in the POST request.
Version in any request greater than or equal to v60.0.
For uniqueness of the Contact, enable duplicate contact check and add standard contact matching rule and standard lead matching rule. For more information, refer to the following.
- Standard Contact Duplicate Rule
- Standard Contact Matching Rule and Standard Lead Matching Rule

These default mappings are supported for the TMF629 resources.

Customer

TMF Field	Description	Is mandatory for POST as per TMF?	Supported methods	Is Supported in Post?	Is Mandatory for Post?	Supported	Salesforce Object	Salesforce Mapping	Field Type
id	Unique identifier for customers.	No	GET	No	No	Yes	Account	Account → Id	String
name	Term by which the customer is known and distinguished from other customers.	Yes	GET, POST, PATCH	Yes	Yes	Yes	Account	Account → Name	String
status	Used to track the lifecycle status of the customer.	No	-	No	No	No	-	-	-
statusReason	A string providing an explanation on the value of the status lifecycle.	No	-	No	No	No	-	-	-
validFor	The time period that the Customer is valid for.	No	-	No	No	No	-	-	-
@type	The @type attribute provides a way to represent the actual class type of an entity.	No	GET	No	No	Yes	-	Account	String
href	URL used to reference the customer.	No	GET	No	No	Yes	-	BaseUrl + ID	-
agreement	A list of agreement references (AgreementRef [*]),such as a service level agreement or a customer price agreement.	No	GET	No	No	No	Contract	-	AggrementRef (Contract)
characteristic	A list of characteristics (Characteristic [*]). Describes the characteristic of a customer.	No	-	No	No	No	-	-	-
account	A account may be a party account or a financial account.	No	GET, POST, PATCH	Yes	No	No	Account	-	AccountRef (Account)
contactMedium	A list of contact mediums (ContactMedium [*]). Indicates the contact medium that could be used to contact the party	No	GET, POST, PATCH	Yes	No	Yes	Contact	-	ContactMedium (Contact)
engagedParty	An organization or an individual - that is engaged as a customer.	Yes	GET, POST, PATCH	Yes	Yes	Yes	Contact	-	EngagedParty (Contact)
relatedParty	A related party defines party or party role linked to a specific entity.	No	-	No	No		-	-	-
creditProfile	Credit profile for the party.	No	-	No	No	No	-	-	-
paymentMethod	A list of payment method references (PaymentMethodRef [*]). A payment method defines a specific mean of payment.	No	-	No	No	No	-	-	-

Sub-resources

AccountRef (Account)

TMF Field	Description	Is mandatory for POST as per TMF?	Supported Methods	Is supported in Post?	Is mandatory For Post?	Supported	Salesforce Object	Salesforce Mapping	Field Type
id	A string. Reference of the account.	No	GET, POST, PATCH	Yes	Yes	Yes	Account	Account→Id	String
description	A string. Detailed description of the account.	No	GET	No	No	Yes	Account	Account→ Description	-
href	A string. Reference of the account.	No	GET	No	No	Yes	Account	Base Url + Id	String
name	A string. Name of the account.	No	GET, POST, PATCH	Yes	Yes	Yes	Account	Account → Name	String
referredType	A string. Type of the account.	No	GET	No	No	Yes	Account	Account → RecordTypeId → Name	String

ContactMedium (Contact)

TMF Field	Description	Is mandatory for POST as per TMF?	Supported Methods	Is supported in Post?	Is mandatory in Post?	Supported	Salesforce Object	Salesforce Mapping	Field Type
characteristic	A medium characteristic (MediumCharacteristic). Any additional characteristic(s) of this contact medium.	Yes	GET, POST, PATCH	Yes	Yes	Yes	-	-	MediumCharacteristic
mediumType	A string. Type of the contact medium, such as: email address, telephone number, postal address.	Yes	GET, POST, PATCH	Yes	Yes	Yes	Contact	Contact → Email Contact → Phone Contact → Fax	String
preferred	A boolean. If true, indicates that is the preferred contact medium.	No	-	No	No	No	-	-	-
validFor	A time period. The time period that the contact medium is valid for.	No	-	No	No	No	-	-	-

MediumCharacteristic

TMF Field	Description	Is mandatory for POST as per TMF?	Supported Methods	Is supported in Post?	Is mandatory in Post?	Supported	Salesforce Object	Salesforce Mapping	Field Type
city	A string. The city.	No	-	No	No	No	-	-	-
contactType	A string. The type of contact. For example, phone number such as mobile, fixed home, fixed office. Postal address such as shipping installation.	No	GET, POST, PATCH	No	No	Yes	-	-	String
country	A string. The country.	No	-	No	No	No	-	-	-
emailAddress	A string. Full email address in standard format.	No	GET, POST, PATCH	Yes	No	Yes	Contact	Contact → Email	String
faxNumber	A string. The fax number of the contact.	No	GET, POST, PATCH	Yes	No	Yes	Contact	Contact → Fax	String
phoneNumber	A string. The primary phone number of the contact.	No	GET, POST, PATCH	Yes	No	Yes	Contact	Contact → Phone	String
postCode	A string. Postcode.	No	-	No	No	No	-	-	-
socialNetworkId	A string. Identifier as a member of a social network.	No	-	No	No	No	-	-	-
stateOrProvince	A string. State or province.	No	-	No	No	No	-	-	-
street1	A string. Describes the street.	No	-	No	No	No	-	-	-
street2	A string. Complementary street description.	No	-	No	No	No	-	-	-

EngagedParty (Contact)

TMF Field	Description	Is mandatory for POST as per TMF?	Supported methods	Is supported in Post?	Is mandatory in Post?	Supported	Salesforce Object	Salesforce Mapping	Field Type
@referredType	The actual type of the target instance when needed for disambiguation.	No	-	No	No	No	-	-	-
href	A string. Reference of the related entity.	No	GET	No	No	Yes	-	-	String
id	A string. Unique identifier of a related entity.	No	GET, POST, PATCH	Yes	No	Yes	Contact	Contact → Id	String
name	A string. Name of the agreement.	No	GET, POST, PATCH	Yes	Yes	Yes	Contact	Contact → LastName	String
role	A string. Role played by the related party.	No	GET	No	No	Yes	AccountContactRelation	AccountContactRelation → Role	String

AggrementRef (Contract)

TMF Field	Description	Is mandatory for POST as per TMF?	Supported methods	Is Supported in Post?	Supported	Salesforce Object	Salesforce Mapping	Field Type
id	A string. Unique identifier of a related entity.	Yes	GET	No	Yes	Contract	ContractNumber	String
href	A string. Reference of the related entity.	No	GET	No	Yes	-	-	String
@referredType	A string. The actual type of the target instance when needed for disambiguation.	No	-	No	No	-	-	-
name	A string. Name of the agreement.	No	GET	No	Yes	Contract	Description	String
@baseType	The @baseType attribute gives a way to provide explicitly the base of class of a given resource that has been extended.	No	-	No	No	-	-	-
@schemaLocation	The @schemaLocation property can be used in resources to allow specifying user-defined properties of an Entity or to specify the expected characteristics of an entity.	No	-	No	No	-	-	-
@type	The @type attribute provides a way to represent the actual class type of an entity.	No	-	No	No	-	-	-

Validations and Conditions for POST

Following validations and conditions are considered for the POST operation. Account Sub-resource :

The id and name fields are mandatory for an account, and an existing account’s name and ID must be used in payload.
If the account has any previous ParentId field, it is updated with the new account that is created.

EngagedParty Sub-resource :

A new contact resource is created with the name sent in the request.
The id field is not passed in the engagedParty.

ContactMedium Sub-resource :

At maximum only 3 elements can be added in this sub-resource : email, phone, fax. And the same information is populated in all the contacts that are created from engagedParty.
It is advised and not mandated to have unique email in every request in contactMedium.
To reuse the email in multiple POST requests, user must deactivate the duplicate rule by performing the following steps.
1. Go to Setup.
2. Search for duplicate rule in quick find.
3. Select Standard Contact Duplicate Rule.
4. Select deactivate.
Agreement Sub-resource: Not Supported in POST request, as agreement cannot exist without an account, and to create an agreement there is not enough data from the payload.
If multiple entries for same mediumType are present in the request then only one of the entry for the mediumType is considered.