Mspecs API


CUSTOM FIELDS

Custom fields enable the deals, contacts and estates to be extended
with organization specific attributes that are not provided in the
standard setup of the MSPECS service.


MANAGING CUSTOM FIELDS

The custom fields are added, modified and deleted using the Company
Settings panel in the top right avatar menu. In the panel, there is a
section for managing custom fields.

A custom filed has three mandatory attributes: name, type, and what
object it extends (deal, estate or contact). The field type can
allow further restrictions like the max length for a text field. The
field can also be assigned a default value, be hidden (for API use
only), be marked as mandatory, and be marked as locked (which prevents
editing the fields value).

Groups can be added to structure the the presentation of the fields in
the graphical user interface.


Example

We start by adding a field for nicknames to contacts. To achieve this
we open the custom fields part of the company settings and add a new
field named "Nick" of type "Text" to the "Contacts". We assign the new
field a max length of 80 characters and make no other alterations.

To add the field using the API but this is left as an exercise for
the interested reader; tables used for the data will be detailed
below.

The definition of the custom field is stored in the customFields table
in the database. If the custom filed belongs to a group, this is
indicated in the customFieldsGroupId field. The group is stored in the
customFieldsGroups table.

To use he custom field in the GUI we navigate to the page of a
contact, then choose the tab for custom fields, and edit the desired
value.

The value we set will be stored in the customFieldsValues table where
the foreignId points to the object that we added the data to. The
customFieldsValues table references to the definition of the custom
field in the customFieldId. The name of the extended table, though
stored in the customFields table, is for efficiency reasons also
stored in the customFieldsValues table.

Looking up the custom field we just set using the API can be done by adding
customFields=true to calls to the contact endpoint like this:

curl -k -u"user:passwd" "https://127.0.0.1:8080/contacts/MDAwMnwwMDAwMDAwMDAwNHw0Ng..?customFields=true"

{
  "id": "MDAwMnwwMDAwMDAwMDAwNHw0Ng..",..",
  ...
  "customFieldsValues": {
    "MDAwMnwwMDAwMDAwMDAwM3wxNDQ.": {
      "name": "Nick",
      "value": "Bob!"
    }
  }
}

The customFields param also works on the estate and deal endpoints.

An alternative way to look up customField data is to query the
customFieldValues endpoint. For example using the contact id from the
example above as the foreignKey:

curl -k -u"user:passwd" "https://127.0.0.1:8080/customFieldValues?q=foreignId='MDAwMnwwMDAwMDAwMDAwNHw0Ng..'"

which returns the data

[
  {
    "id": "MDAwMnwwMDAwMDAwMDAwMXwxNDU.",
    "customFieldId": "MDAwMnwwMDAwMDAwMDAwMXwxNDQ.",
    "value": "Nicker",
    "foreignId": "MDAwMnwwMDAwMDAwMDAwNHw0Ng..",
    "tableName": "contacts",
    "updatedDate": "2016-08-30T07:43:38.000Z"
  }
]

Just to show that we got the correct data, we can look at the
definition of the custom field

curl -k -u"user:passwd" "https://127.0.0.1:8080/customFields/MDAwMnwwMDAwMDAwMDAwMXwxNDQ.?strip=true"

which returns

{
  "id": "MDAwMnwwMDAwMDAwMDAwMXwxNDQ.",
  "customFieldsGroupId": "MDAwMnwwMDAwMDAwMDAwMXwyMTk.",
  "fieldType": "ENUM_CUSTOM_FIELDS_FIELD_TYPE_TEXT",
  "isMandatory": false,
  "maxLength": 80,
  "name": "Nick",
  "isReadOnly": false,
  "isNotDisplayed": false,
  "tableName": "contacts",
  "displayOrder": 1,
  "updatedDate": "2016-08-30T07:43:00.000Z"
}