TMF629 Resource Mappings

Before using the TMF629 resource mappings, refer the following.

  • The CommsCloud license must be enabled to invoke the TMF629 API.
  • 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.
  • 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 prevoius 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 the following.

These default mappings are supported for the TMF629 resources.

TMF FieldDescription
property
Is Mandatory for POST as per TMFSupported methodsIsSupported In PostIs Mandatory for PostSupportedSalesforce ObjectSalesforce MappingField Type
idUnique identifier for customers.NoGETNoNoYesAccountAccount → IdString
nameTerm by which the customer is known and distinguished from other customers.YesGET, POST, PATCHYesYesYesAccountAccount → NameString
statusUsed to track the lifecycle status of the customer.No-NoNoNo---
statusReasonA string providing an explanation on the value of the status lifecycle.No-NoNoNo---
validForThe time period that the Customer is valid for.No-NoNoNo---
@typeThe @type attribute provides a way to represent the actual class type of an entity.NoGETNoNoYes-AccountString
hrefURL used to reference the customer.NoGETNoNoYes-BaseUrl + ID-
agreementA list of agreement references (AgreementRef [*]),such as a service level agreement or a customer price agreement.NoGETNoNoNoContract-AggrementRef (Contract)
characteristicA list of characteristics (Characteristic [*]). Describes the characteristic of a customer.No-NoNoNo---
accountA account may be a party account or a financial account.NoGET, POST, PATCHYesNoNoAccount-AccountRef (Account)
contactMediumA list of contact mediums (ContactMedium [*]). Indicates the contact medium that could be used to contact the partyNoGET, POST, PATCHYesNoYesContact-ContactMedium (Contact)
engagedPartyAn organization or an individual - that is engaged as a customer.YesGET, POST, PATCHYesYesYesContact-EngagedParty (Contact)
relatedPartyA related party defines party or party role linked to a specific entity.No-NoNo---
creditProfileCredit profile for the party.No-NoNoNo---
paymentMethodA list of payment method references (PaymentMethodRef [*]). A payment method defines a specific mean of payment.No-NoNoNo---
TMF FieldDescription
property
Is Mandatory for POST as per TMFSupported methodsIs Supported in postIs Mandatory For PostSupportedSalesforce ObjectSalesforce MappingField Type
idA string. Reference of the account.NoGET, POST, PATCHYesYesYesAccountAccount→IdString
descriptionA string. Detailed description of the account.NoGETNoNoYesAccountAccount→ Description-
hrefA string. Reference of the account.NoGETNoNoYesAccountBase Url + IdString
nameA string. Name of the account.NoGET, POST, PATCHYesYesYesAccountAccount → NameString
referredTypeA string. Type of the account.NoGETNoNoYesAccountAccount → RecordTypeId → NameString
TMF FieldDescription
property
Is Mandatory for POST as per TMFSupported methodsIs Supported In PostIs Mandatory In PostSupportedSalesforce ObjectSalesforce MappingField Type
characteristicA medium characteristic (MediumCharacteristic). Any additional characteristic(s) of this contact medium.YesGET, POST, PATCHYesYesYes--MediumCharacteristic
mediumTypeA string. Type of the contact medium, such as: email address, telephone number, postal address.YesGET, POST, PATCHYesYesYesContactContact → Email
Contact → Phone
Contact → Fax
String
preferredA boolean. If true, indicates that is the preferred contact medium.No-NoNoNo---
validForA time period. The time period that the contact medium is valid for.No-NoNoNo---
TMF FieldDescription
property
Is Mandatory for POST as per TMFSupported methodsIs Supported In PostIs Mandatory in PostSupportedSalesforce ObjectSalesforce MappingField Type
cityA string. The city.No-NoNoNo---
contactTypeA string. The type of contact. For example, phone number such as mobile, fixed home, fixed office. Postal address such as shipping installation.NoGET, POST, PATCHNoNoYes--String
countryA string. The country.No-NoNoNo---
emailAddressA string. Full email address in standard format.NoGET, POST, PATCHYesNoYesContactContact → EmailString
faxNumberA string. The fax number of the contact.NoGET, POST, PATCHYesNoYesContactContact → FaxString
phoneNumberA string. The primary phone number of the contact.NoGET, POST, PATCHYesNoYesContactContact → PhoneString
postCodeA string. Postcode.No-NoNoNo---
socialNetworkIdA string. Identifier as a member of a social network.No-NoNoNo---
stateOrProvinceA string. State or province.No-NoNoNo---
street1A string. Describes the street.No-NoNoNo---
street2A string. Complementary street description.No-NoNoNo---
TMF FieldDescription
property
Is Mandatory for POST as per TMFSupported methodsIs Supported In PostIs Mandatory In PostSupportedSalesforce ObjectSalesforce MappingField Type
@referredTypeThe actual type of the target instance when needed for disambiguation.No-NoNoNo---
hrefA string. Reference of the related entity.NoGETNoNoYes--String
idA string. Unique identifier of a related entity.NoGET, POST, PATCHYesNoYesContactContact → IdString
nameA string. Name of the agreement.NoGET, POST, PATCHYesYesYesContactContact → LastNameString
roleA string. Role played by the related party.NoGETNoNoYesAccountContactRelationAccountContactRelation → RoleString
TMF FieldDescription
property
Is Mandatory for POST as per TMFSupported methodsIs Supported In PostSupportedSalesforce ObjectSalesforce MappingField Type
idA string. Unique identifier of a related entity.YesGETNoYesContractContractNumberString
hrefA string. Reference of the related entity.NoGETNoYes--String
@referredTypeA string. The actual type of the target instance when needed for disambiguation.No-NoNo---
nameA string. Name of the agreement.NoGETNoYesContractDescriptionString
@baseTypeThe @baseType attribute gives a way to provide explicitly the base of class of a given resource that has been extended.No-NoNo---
@schemaLocationThe @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-NoNo---
@typeThe @type attribute provides a way to represent the actual class type of an entity.No-NoNo---

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 Is should 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 thepayload.

  • If multiple entries for same mediumType are present in the request then only one of the entry for the mediumType is considered.