Key Field Definition is used to define the layout of a specific Entity Type. Each definition is stored under a Key Field List (referred by ParentKey) and contains:
-
Name: to easily identify the layout\
-
Entity Type: which entity the layout is related to
-
For Read: currently supports AbEntry (1)*, Opportunity (2) and Customer Service/Case (5)\
-
For Create/Update/Delete: currently supports Opportunity (2) and Customer Service/Case (5)\
-
-
List of fields that compose the layout. Those fields can be:
-
Basic Fields\
-
Udfs\
-
-
Security: each Key Field Definition will follow the exact same security defined in the parent Key Field List. When the parent Key Field List security changes, it will be applied to all child Key Fiend Definition records.\
-
When creating, the combination of ParentKey + EntityType + Target must be unique.\
-
When updating, there is no way to change ParentKey or EntityType or Target. If, for some reason, those fields need to be changed, the entire Key Field Definition must be deleted and a new one must be created.\
*For reading Entity Type = 1 (AbEntry), the non-assignable "Rule" field is populated based on what that layout is related to: Contact, Company or Individual. In addition, it has a flag (Lead = true|false) that indicates if that Contact, Company or Individual is related to a Lead. For all other Entity Types, the "Rule" field does not apply (null).
For details about the API, including syntax and additional information, please follow this link:
https://developer.maximizer.com/reference/octopus-api-getting-started
HowTo's
Read - Only entries current user has access to
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"KeyFieldDefinition": {
"Scope": {
"Fields": {
"Key": 1
}
},
"Criteria": {
// This is a special filter that ensures only entries which the current user has access to are returned. Note that this is OUTSIDE the SearchCriteria
"SecAccess": {
"$ALLOWS": "$CURRENTUSER()"
},
"SearchCriteria": {},
"Top": 3
}
},
"Compatibility": {
"KeyFieldDefinitionObject": "1.0"
}
}Read - Specific target
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"KeyFieldDefinition": {
"Scope": {
"Fields": {
"Key": 1,
"Target": 1
}
},
"Criteria": {
"SearchQuery": {
"Target": {
"$EQ": "my_target"
}
},
"Top": 3
}
},
"Compatibility": {
"KeyFieldDefinitionObject": "1.0"
}
}Read - Key fields for AbEntry (EntityType = 1)
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"KeyFieldDefinition": {
"Scope": {
"Fields": {
"Key": 1,
"EntityType": 1
}
},
"Criteria": {
"SearchQuery": {
"EntityType": {
"$EQ": 1
}
},
"Top": 3
}
},
"Compatibility": {
"KeyFieldDefinitionObject": "1.0"
}
}Read - Key fields for Opportunity (EntityType = 2)
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"KeyFieldDefinition": {
"Scope": {
"Fields": {
"Key": 1,
"EntityType": 1
}
},
"Criteria": {
"SearchQuery": {
"EntityType": {
"$EQ": 2
}
},
"Top": 3
}
},
"Compatibility": {
"KeyFieldDefinitionObject": "1.0"
}
}Read - Key fields for Cusomer Service (EntityType = 5)
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"KeyFieldDefinition": {
"Scope": {
"Fields": {
"Key": 1,
"EntityType": 1
}
},
"Criteria": {
"SearchQuery": {
"EntityType": {
"$EQ": 5
}
},
"Top": 3
}
},
"Compatibility": {
"KeyFieldDefinitionObject": "1.0"
}
}Read - Key fields for Lead (EntityType = 19)
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"KeyFieldDefinition": {
"Scope": {
"Fields": {
"Key": 1,
"EntityType": 1
}
},
"Criteria": {
"SearchQuery": {
"EntityType": {
"$EQ": 19
}
},
"Top": 3
}
},
"Compatibility": {
"KeyFieldDefinitionObject": "1.0"
}
}Read - Layout with separators
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"KeyFieldDefinition": {
"Scope": {
"Fields": {
"Key": 1,
"EntityType": 1,
"Layout": [
{
"Element": [
{
// For separators (if any):
// ID will always be null
// Description will always show "Separator"
"ID": 1,
"Description": 1
}
]
}
]
}
},
"Criteria": {
"SearchQuery": {},
"Top": 3
},
"Options": {
"IncludeSeparator": true
}
},
"Compatibility": {
"KeyFieldDefinitionObject": "1.0"
}
}Update - Replace layout (default)
// POST https://api.maximizer.com/octopus/Update
// Authorization: Bearer <token>
{
"KeyFieldDefinition": {
"Data": {
"Key": "S2V5RmllbGREZWZpbml0aW9uCTMxMTg4OTA5OQ==", // mandatory
"Layout": [
{
"Element": [
{
"ID": "/Opportunity/Cost"
},
{
"ID": "/Opportunity/Category"
},
{
"ID": "/Opportunity/Udf/$TYPEID(3)"
}
]
}
]
},
"Options": {
// This instructs the API to replace existing layout elements with the three items above (delete existing, add new ones). This is the default behavior if no option is specified.
"Replace": true
}
}
}Update - Append to layout
// POST https://api.maximizer.com/octopus/Update
// Authorization: Bearer <token>
{
"KeyFieldDefinition": {
"Data": {
"Key": "S2V5RmllbGREZWZpbml0aW9uCTMxMTg4OTA5OQ==", // mandatory
"Layout": [
{
"Element": [
{
"ID": "/Opportunity/Cost"
},
{
"ID": "/Opportunity/Category"
},
{
"ID": "/Opportunity/Udf/$TYPEID(3)"
}
]
}
]
},
"Options": {
// This instructs the API to append the three element items above to the existing layout elements (keep existing, add new ones)
"Append": true
}
}
}Update - Remove from layout
// POST https://api.maximizer.com/octopus/Update
// Authorization: Bearer <token>
{
"KeyFieldDefinition": {
"Data": {
"Key": "S2V5RmllbGREZWZpbml0aW9uCTMxMTg4OTA5OQ==", // mandatory
"Layout": [
{
"Element": [
{
"ID": "/Opportunity/Cost"
},
{
"ID": "/Opportunity/Category"
},
{
"ID": "/Opportunity/Udf/$TYPEID(3)"
}
]
}
]
},
"Options": {
// This instructs the API to remove the three element items above from the existing layout elements
"Remove": true
}
}
}Update - Clear layout
// POST https://api.maximizer.com/octopus/Update
// Authorization: Bearer <token>
{
"KeyFieldDefinition": {
"Data": {
"Key": "S2V5RmllbGREZWZpbml0aW9uCTMxMTg4OTA5OQ==" // mandatory
},
"Options": {
// This instructs the API to clear all fields from existing layout. If any field is included in the payload, they will be ignored, as all current items will be removed (layout will be empty after this request runs)
"Clear": true
}
}
}MetaData
Read KeyFieldDefination metadata (simple)
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"Schema": {
"Scope": {
"Fields": 1
},
"Criteria": {
"SearchQuery": {
"Key": {
"$TREE": "/KeyFieldDefinition"
}
}
}
},
"Compatibility": {
"SchemaObject": "1.0",
"KeyFieldDefinitionObject": "1.0"
}
}Read KeyFieldDefination metadata (more)
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"Schema": {
"Scope": {
"Fields": {
"Key": 1,
"Alias": 1,
"Type": 1,
"Name": 1,
"AppliesTo": 1,
"Sortable": 1,
"Nullable": 1,
"Assignable": 1,
"Queryable": 1,
"Mandatory": 1,
"Attributes": 1,
"HasOption": 1,
"DisplayValue": 1
}
},
"Criteria": {
"SearchQuery": {
"Key": {
"$TREE": "/KeyFieldDefinition"
}
}
}
},
"Compatibility": {
"SchemaObject": "1.0",
"KeyFieldDefinitionObject": "1.0"
}
}KeyFieldDefinition CRUD
Read - KeyFieldDefinition
// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
"KeyFieldDefinition": {
"Scope": {
"Fields": {
"Key": 1,
"ParentKey": 1,
"EntityType": 1,
"Target": 1, // available only in KeyFieldDefinitionObject version 1.x
"Rule": 1, // populated only for EntityType = 1 (AbEntry). Null for any other EntityType
"Layout": [
{
"ColumnNo": 1,
"Element": [
{
"ID": 1,
"Field": {
// This has the same metadata fields available as when reading schema. Added a few just for illustration
"Key": 1,
"Type": 1,
"Attributes": 1
},
"Description": 1
}
]
}
],
// This is readonly (not assignable) field. It will reflect the security defined by the parent Key Field List
"SecAccess": 1,
"DisplayValue": 1
}
},
"Criteria": {
"SearchQuery": {},
"Top": 3
}
},
"Compatibility": {
"KeyFieldDefinitionObject": "1.0"
}
}Create - KeyFieldDefinition
// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
// Combination of ParentKey + EntityType + Target must be unique
"KeyFieldDefinition": {
"Data": {
"Key": null,
"ParentKey": "S2V5RmllbGRMaXN0CTI2NDk0MDA0MQ==", // mandatory
// Currently supported EntityTypes:
// - 2 = Opportunity
// - 5 = Customer Service (Case)
// - 19 = Lead
"EntityType": 2, // mandatory
"Target": "my_target", // mandatory
"Name": "Test KeyFieldDefinition from Postman",
// Layout currently supports only specifying Element.ID (field codes).
// - Currently no support for:
// - Multiple columns (column will always be 0)
// - Groups
// - Separators
// - Setting Description of Udf fields
"Layout": [
{
"Element": [
{
// Example of a basic field
"ID": "/Opportunity/Cost"
},
{
// Example of a System Udf (which is also considered basic field)
"ID": "/Opportunity/RevenueType"
},
{
// Example of a Udf (must exist in the database)
"ID": "/Opportunity/Udf/$TYPEID(2)"
}
]
}
],
"RequestedBy": {
"Uid": "USER"
}
}
}
}Update - KeyFieldDefinition
// POST https://api.maximizer.com/octopus/Update
// Authorization: Bearer <token>
{
// ParentKey, EntityType and Target fields CANNOT be updated
"KeyFieldDefinition": {
"Data": {
"Key": "S2V5RmllbGREZWZpbml0aW9uCTMxMTk4MDEwMg==", // mandatory
"Name": "Updated KeyFieldDefinition from Postman",
// Layout currently supports only specifying Element.ID (field codes).
// - Currently no support for:
// - Multiple columns (column will always be 0)
// - Groups
// - Separators
// - Setting Description of Udf fields
// Default behavior: API will replace ALL current layout elements with the ones sent in the payload. For more options on how to change this behavior, please refer to "HowTo's"
"Layout": [
{
"Element": [
{
// Example of a basic field
"ID": "/Opportunity/Cost"
},
{
// Example of a System Udf (which is also considered basic field)
"ID": "/Opportunity/Category"
},
{
// Example of a Udf (must exist in the database)
"ID": "/Opportunity/Udf/$TYPEID(3)"
}
]
}
]
}
}
}Delete - KeyFieldDefinition
// POST https://api.maximizer.com/octopus/Delete
// Authorization: Bearer <token>
{
"KeyFieldDefinition": {
"Data": {
"Key": "S2V5RmllbGREZWZpbml0aW9uCTMxMTkwMjEwMA==" // mandatory
}
}
}