# Trường động (Custom fields)

Trên nền tảng CareSoft, có 3 đối tượng dữ liệu chính gồm: `Phiếu ghi` (tickets), `Khách hàng` (contacts) và `Tổ chức` (organizations) 

Các đối tượng dữ liệu trên ngoài các trường thông tin cố định thì còn được cung cấp thêm 20 trường dữ liệu cho mỗi loại. CareSoft gọi nó là trường động, kèm với đối tượng dữ liệu đó, ví dụ: **Trường động khách hàng**, **trường động phiếu ghi**...

Các trường động có nhiều kiểu dữ liệu khác nhau, mục đích nhằm phân loại và khai thác dữ liệu sâu hơn. 

Để tạo ra các trường động, admin của từng domain sẽ sử dụng giao diện CareSoft và vào từng Đối tượng thông tin để thực hiện cấu hình.

*Ảnh minh họa danh sách và cấu hình trường động phiếu ghi trên giao diện CareSoft* 

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FCjhXuwH6xfibYOVSaLSQ%2FticketAditionField.png?alt=media&#x26;token=f6b55544-750f-48e8-8f00-c08cebe6cc72" alt=""><figcaption></figcaption></figure>

## Danh sách kiểu dữ liệu&#x20;

Bảng kê dưới đây mô tả kiểu dữ liệu, ứng dụng và đối tượng áp dụng của chúng&#x20;

<table><thead><tr><th width="69.33333333333331">STT</th><th width="186">Tên kiểu</th><th width="295">Đối tượng áp dụng<select multiple><option value="6d2ea5a5451848469a8f1a4a0b8ff498" label="Phiếu ghi" color="blue"></option><option value="5a39453cd0fe45169e8304b7ea5c5b3b" label="Khách hàng" color="blue"></option><option value="8fe5c0930fd24c8c9487ec82ddc0e40a" label="Tổ chức" color="blue"></option></select></th><th>Ý nghĩa</th></tr></thead><tbody><tr><td>1</td><td>TEXT</td><td><span data-option="6d2ea5a5451848469a8f1a4a0b8ff498">Phiếu ghi, </span><span data-option="5a39453cd0fe45169e8304b7ea5c5b3b">Khách hàng, </span><span data-option="8fe5c0930fd24c8c9487ec82ddc0e40a">Tổ chức</span></td><td>Ký tự</td></tr><tr><td>2</td><td>NUMERIC</td><td><span data-option="6d2ea5a5451848469a8f1a4a0b8ff498">Phiếu ghi, </span><span data-option="5a39453cd0fe45169e8304b7ea5c5b3b">Khách hàng, </span><span data-option="8fe5c0930fd24c8c9487ec82ddc0e40a">Tổ chức</span></td><td>Số </td></tr><tr><td>3</td><td>DATE</td><td><span data-option="6d2ea5a5451848469a8f1a4a0b8ff498">Phiếu ghi, </span><span data-option="5a39453cd0fe45169e8304b7ea5c5b3b">Khách hàng, </span><span data-option="8fe5c0930fd24c8c9487ec82ddc0e40a">Tổ chức</span></td><td>Ngày tháng<br>Định dạng (YYYY/MM/DD) </td></tr><tr><td>4</td><td>SINGLE DROP-DOWN LIST</td><td><span data-option="6d2ea5a5451848469a8f1a4a0b8ff498">Phiếu ghi, </span><span data-option="5a39453cd0fe45169e8304b7ea5c5b3b">Khách hàng, </span><span data-option="8fe5c0930fd24c8c9487ec82ddc0e40a">Tổ chức</span></td><td>Chọn 1 giá trị</td></tr><tr><td>5</td><td>MULTIPLE  DROP-DOWN LIST</td><td><span data-option="6d2ea5a5451848469a8f1a4a0b8ff498">Phiếu ghi, </span><span data-option="5a39453cd0fe45169e8304b7ea5c5b3b">Khách hàng, </span><span data-option="8fe5c0930fd24c8c9487ec82ddc0e40a">Tổ chức</span></td><td>Chọn nhiều giá trị</td></tr><tr><td>6</td><td>URL</td><td><span data-option="6d2ea5a5451848469a8f1a4a0b8ff498">Phiếu ghi</span></td><td>Liên kết</td></tr><tr><td>7</td><td>TEXTAREA</td><td><span data-option="6d2ea5a5451848469a8f1a4a0b8ff498">Phiếu ghi</span></td><td>Văn bản</td></tr><tr><td>8</td><td>STAGE</td><td><span data-option="6d2ea5a5451848469a8f1a4a0b8ff498">Phiếu ghi</span></td><td>Tiến trình (salefunnel) </td></tr></tbody></table>

## Cấu trúc thông tin trường động

Thực hiện lấy cấu hình các trường động. Tùy theo kiểu dữ liệu của trường động, các trường thông tin trong đó cũng sẽ thay đổi theo&#x20;

{% code title="Đối tượng trường động điển hình" %}

```json
[{
            "custom_field_id": 6740,
            "custom_field_lable": "Phân loại",
            "type": "Single drop-down list",
            "code":null, 
            "values": [
                {
                    "id": 109398,
                    "lable": "Đơn mua",
                    "code":"DONMUA",
                    "parent_value_id": -1
                },
                {
                    "id": 109399,
                    "code":"HOTRO",
                    "lable": "Hỗ trợ khách hàng",
                    "parent_value_id": -1
                }
            ]
        },       
       {   "custom_field_id": 6103,
           "code":"MADONHANG",
            "custom_field_lable": "Mã đơn hàng",
            "type": "Text"
        }]
```

{% endcode %}

Ý nghĩa các trường thông tin&#x20;

<table><thead><tr><th width="242.33333333333331">Tên trường</th><th>Ý nghĩa</th><th>Ghi chú</th></tr></thead><tbody><tr><td><code>custom_field_id</code><br>(int)</td><td>ID của trường dữ liệu</td><td></td></tr><tr><td><code>custom_field_lable</code><br>(string)</td><td>Tên trường </td><td></td></tr><tr><td><code>type</code><br>(string)</td><td>Kiểu dữ liệu </td><td>(trong danh sách kiểu) <a data-mention href="#danh-sach-kieu-du-lieu">#danh-sach-kieu-du-lieu</a></td></tr><tr><td><code>values</code><br>(array)</td><td>Giá trị lựa chọn. Đối với kiểu trường lựa chọn, chọn nhiều hay tiến trình. trường dữ liệu này chứa các giá trị định sẵn với ID riêng và nhãn cho từng  lựa chọn. </td><td><strong>Chỉ có với các kiểu dữ liệu:</strong><br>- <code>SINGLE DROP-DOWN LIST</code><br>- <code>MULTIPLE  DROP-DOWN LIST</code><br>- <code>STAGE</code></td></tr><tr><td>code</td><td>Mã trường động tự cấu hình (trong giao diện cấu hình)</td><td>Dùng để mapping các trường dữ liệu giữa các hệ thống</td></tr></tbody></table>

Chi tiết đối tượng Values của các trường dạng `SINGLE DROP-DOWN LIST, MULTIPLE  DROP-DOWN LIST, và STAGE`

<pre data-title="(click vào field để xem) "><code>"<a data-footnote-ref href="#user-content-fn-1">values</a>": [
                {
                    "<a data-footnote-ref href="#user-content-fn-2">id</a>": 109398,
                    "<a data-footnote-ref href="#user-content-fn-3">lable</a>": "Đơn mua",
                    "code":"DONMUA"
                    "<a data-footnote-ref href="#user-content-fn-4">parent_value_id</a>": -1
                },
<strong>                {
</strong>                    "id": 109399,
                    "lable": "Hỗ trợ khách hàng",
                    "code":"HOTRO",
                    "parent_value_id": -1
                }
            ]
</code></pre>

## Cách thức khai thác thông tin&#x20;

Để biết các đối tượng trên có những trường động nào. Lập trình viên sử dụng từng Api riêng lẻ dưới đây để thực hiện lấy về các thông tin đã cấu hình.

{% hint style="info" %}
LƯU Ý:  Trong quá trình vận hành Admin của domain có thể xóa, sửa tên, sửa kiểu dữ liệu hoặc thêm mới trường thông tin. Cần có cơ chế đồng bộ định kỳ hằng ngày để đảm bảo thông tin thông suốt&#x20;
{% endhint %}

### Trường động phiếu ghi

## Danh sách trường động phiếu ghi

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/tickets/custom_fields`

#### Headers

| Name   | Type   | Description                                                          |
| ------ | ------ | -------------------------------------------------------------------- |
| \*\*\* | String | [Thông tin xác thực chung](https://docs.caresoft.vn/thong-tin-chung) |

{% tabs %}
{% tab title="200: OK " %}
{% code title="Kết quả điển hình" %}

```json
{
    "code": "ok",
    "custom_fields": [
        {
            "custom_field_id": 5164,
            "code":"PHANLOAI",
            "custom_field_lable": "Phân loại phiếu ghi( Không được đổi của Liên)",
            "type": "Single drop-down list",
            "values": [
                {
                    "id": 89496,
                    "code":"TIENTRINHDEAL",
                    "lable": "Tiến trình Leads",
                    "parent_value_id": -1
                },
                {
                    "id": 89497,
                    "lable": "Tiến trình Deals",
                    "code":"null",
                    "parent_value_id": -1
                },
                {
                    "id": 98211,
                    "code":"KHIEUNAI",
                    "lable": "Case Khiếu nại",
                    "parent_value_id": -1
                }
            ]
        },
        {
            "custom_field_id": 6068,
            "custom_field_lable": "Phân loại tương tác",
            "code":"TUONGTAC",
            "type": "Single drop-down list",
            "values": [
                {
                    "id": 106902,
                    "lable": "Spam",
                    "code":"null",
                    "parent_value_id": -1
                },
                {
                    "id": 106903,
                     "code":"null",
                    "lable": "Nội dung",
                    "parent_value_id": -1
                }
            ]
        },

```

{% endcode %}

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}
{% endtabs %}

### Trường động khách hàng

## Danh sách trường động khách hàng

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/contacts/custom_fields`

#### Headers

| Name                                     | Type   | Description                                                          |
| ---------------------------------------- | ------ | -------------------------------------------------------------------- |
| \*\*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung](https://docs.caresoft.vn/thong-tin-chung) |

{% tabs %}
{% tab title="200: OK Tương tự trường động phiếu ghi" %}

{% endtab %}
{% endtabs %}

### Trường động tổ chức

## Danh sách trường động tổ chức

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/organizations/custom_fields`

#### Headers

| Name                                   | Type   | Description                                                          |
| -------------------------------------- | ------ | -------------------------------------------------------------------- |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung](https://docs.caresoft.vn/thong-tin-chung) |

{% tabs %}
{% tab title="200: OK Tương tự trường động phiếu ghi" %}

{% endtab %}
{% endtabs %}

Khi lấy về thông tin trường động, cách tốt để tích hợp là làm 1 bảng dữ liệu mapping trường dữ liệu tương ứng từ CRM sang CareSoft<br>

*Ví dụ:* 1 Bảng dữ liệu mapping với trường  trạng thái đơn hàng từ CRM sang CareSoft tương ứng

<table><thead><tr><th>crmField</th><th width="155.33333333333331">crmValue</th><th>caresoftField</th><th>caresoftValue</th></tr></thead><tbody><tr><td>orderStatus</td><td>New</td><td><a data-footnote-ref href="#user-content-fn-5">6740</a></td><td><a data-footnote-ref href="#user-content-fn-6">109398</a></td></tr><tr><td>orderStatus</td><td>Delivery</td><td>6740</td><td>109399</td></tr><tr><td>orderStatus</td><td>Payment</td><td>6740</td><td>109400</td></tr></tbody></table>

Khi tạo mới thông tin sang CareSoft, Object custom\_fields sẽ được trình bày bằng cấu trúc sau

{% code overflow="wrap" %}

```json
{
  "username" : "...", 
  "custom_fields" : [
    {
     "id": "{{custom_field_id: ID của trường động}}",
     "value": "{{Giá trị muốn truyền vào nếu trường động kiểu Date/Text/Number/Url/Textarea hoặc ID values của lựa chọn nếu là kiểu Single Select, State hoặc Multiple Select}}" 
     },
         .....
    ]
   }
```

{% endcode %}

{% hint style="info" %}
**DEMO:** \
Ứng dụng, tạo mới phiếu ghi kèm thông tin trường động [xem tại đây](https://docs.caresoft.vn/danh-muc/restful-api-cua-caresoft/tao-phieu-ghi-lead-deal-kem-thong-tin-truong-dong). Các đối tượng dữ liệu khác thực hiện tương tự&#x20;
{% endhint %}

[^1]: Mảng giá trị trường động dạng lựa chọn&#x20;

[^2]: Id lựa chọn

[^3]: Tên lựa chọn

[^4]: Id trường cha của lựa chọn&#x20;

[^5]: ID trường động dạng chọn 1&#x20;

[^6]: ID Giá trị lựa chọn tương ứng với  trạng thái New trên CRM&#x20;