# 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](https://help.salesforce.com/s/articleView?id=sf.duplicate_rules_standard_contact_rule.htm\&type=5)
  - [Standard Contact Matching Rule and Standard Lead Matching Rule](https://help.salesforce.com/s/articleView?id=sf.matching_rules_standard_contact_rule.htm\&type=5)

These default mappings are supported for the TMF629 resources.

## Customer

| TMF Field<div style="width:120px"></div> | Description<div style="width:120px"></div>                                                                          | Is mandatory for POST as per TMF?<div style="width:120px"></div> | Supported methods<div style="width:120px"></div> | Is Supported in Post?<div style="width:120px"></div> | Is Mandatory for Post?<div style="width:120px"></div> | Supported<div style="width:120px"></div> | Salesforce Object<div style="width:120px"></div> | Salesforce Mapping<div style="width:120px"></div> | Field Type<div style="width:120px"></div>         |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------- | ------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------- |
| 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)](#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)](#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)](#contactmedium-contact) |
| engagedParty                             | An organization or an individual - that is engaged as a customer.                                                   | Yes                                                              | GET, POST, PATCH                                 | Yes                                                  | Yes                                                   | Yes                                      | Contact                                          | -                                                 | [EngagedParty (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<div style="width:120px"></div> | Description<div style="width:120px"></div>     | Is mandatory for POST as per TMF?<div style="width:120px"></div> | Supported Methods<div style="width:120px"></div> | Is supported in Post?<div style="width:120px"></div> | Is mandatory For Post?<div style="width:120px"></div> | Supported<div style="width:120px"></div> | Salesforce Object<div style="width:120px"></div> | Salesforce Mapping<div style="width:120px"></div> | Field Type<div style="width:120px"></div> |
| ---------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------- | ------------------------------------------------ | ------------------------------------------------- | ----------------------------------------- |
| 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<div style="width:120px"></div> | Description<div style="width:120px"></div>                                                               | Is mandatory for POST as per TMF?<div style="width:120px"></div> | Supported Methods<div style="width:120px"></div> | Is supported in Post?<div style="width:120px"></div> | Is mandatory in Post?<div style="width:120px"></div> | Supported<div style="width:120px"></div> | Salesforce Object<div style="width:120px"></div> | Salesforce Mapping<div style="width:120px"></div>   | Field Type<div style="width:120px"></div>     |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------- | ------------------------------------------------ | --------------------------------------------------- | --------------------------------------------- |
| characteristic                           | A medium characteristic (MediumCharacteristic). Any additional characteristic(s) of this contact medium. | Yes                                                              | GET, POST, PATCH                                 | Yes                                                  | Yes                                                  | Yes                                      | -                                                | -                                                   | [MediumCharacteristic](#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<br>Contact → Phone<br>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<div style="width:120px"></div> | Description<div style="width:120px"></div>                                                                                                       | Is mandatory for POST as per TMF?<div style="width:120px"></div> | Supported Methods<div style="width:120px"></div> | Is supported in Post?<div style="width:120px"></div> | Is mandatory in Post?<div style="width:120px"></div> | Supported<div style="width:120px"></div> | Salesforce Object | Salesforce Mapping<div style="width:120px"></div> | Field Type<div style="width:120px"></div> |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------- | ----------------- | ------------------------------------------------- | ----------------------------------------- |
| 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<div style="width:120px"></div> | Description<div style="width:120px"></div>                             | Is mandatory for POST as per TMF?<div style="width:120px"></div> | Supported methods<div style="width:120px"></div> | Is supported in Post?<div style="width:120px"></div> | Is mandatory in Post?<div style="width:120px"></div> | Supported<div style="width:120px"></div> | Salesforce Object<div style="width:120px"></div> | Salesforce Mapping<div style="width:120px"></div> | Field Type<div style="width:120px"></div> |
| ---------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------- | ------------------------------------------------ | ------------------------------------------------- | ----------------------------------------- |
| @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<div style="width:120px"></div> | Description<div style="width:120px"></div>                                                                                                                                | Is mandatory for POST as per TMF?<div style="width:120px"></div> | Supported methods<div style="width:120px"></div> | Is Supported in Post?<div style="width:120px"></div> | Supported<div style="width:120px"></div> | Salesforce Object<div style="width:120px"></div> | Salesforce Mapping<div style="width:120px"></div> | Field Type<div style="width:120px"></div> |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------- | ---------------------------------------- | ------------------------------------------------ | ------------------------------------------------- | ----------------------------------------- |
| 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.