API Reference

KeyFieldDefinition

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

  • 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 details about the API, including syntax and additional information, please follow this link:
https://developer.maximizer.com/reference/octopus-api-getting-started

HowTo's

Create - Full layout (group titles, separators, columns)

// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
    // Full layout: two columns + a group + a separator.
    "KeyFieldDefinition": {
        "Data": {
            "Key": null,
            "ParentKey": "S2V5RmllbGRMaXN0CTEzNjU2MjQ0NTY=", // mandatory - the KeyFieldList this definition belongs to
            // Target = parameter used to group Key Field Definitions (optional).
            // Omit this value if this key field definition is intended to be displayed in the UI. Omitted on purpouse in this example
            "EntityType": 2, // 2 = Opportunity
            "Name": "Opportunity key fields (full layout)",
            "Layout": [
                {
                    "Name": null, // Optional, if assigned fields will be in a group with this name
                    "ColumnNo": 0, // 0 = LEFT column in the UI
                    "Element": [
                        {
                            "ID": "/Opportunity/Status"
                        },
                        // Separator (divider line in the UI): Element.ID = null.
                        // Only written/echoed when Options.IncludeSeparator = true (See Options).
                        {
                            "ID": null
                        },
                        {
                            "ID": "/Opportunity/Cost"
                        }
                    ]
                },
                {
                    "Name": null, // Optional, if assigned fields will be in a group with this name
                    "ColumnNo": 1, // 1 = RIGHT column in the UI
                    "Element": [
                        {
                            "ID": "/Opportunity/Leader"
                        },
                        {
                            "ID": "/Opportunity/SalesTeam"
                        }
                    ]
                },
                {
                    "Name": "Grouped Fields", // Group name for below fields
                    "ColumnNo": 1, // 1 = RIGHT column in the UI
                    "Element": [
                        {
                            "ID": "/Opportunity/Rating"
                        },
                        {
                            "ID": "/Opportunity/Revenue"
                        }
                    ]
                }
            ],
            "RequestedBy": "$CURRENTUSER()"
        },
        "Options": {
            // Required so separators (ID = null) are persisted and echoed back. 
            "IncludeSeparator": true
        }
    },
    "Compatibility": {
        "KeyFieldDefinitionObject": "1.1"
    }
}

Create - AbEntry key fields

// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
    // AbEntry has SIX variants - {Company, Individual, Contact} x {Starred, non-starred} - and each is a SEPARATE definition.
    // The "Rule" picks which variant this layout applies to (maps to the "Show key fields for" selector in the UI). 
    // Combination of ParentKey + EntityType + Target + Rule must be unique.
    "KeyFieldDefinition": {
        "Data": {
            "Key": null,
            "ParentKey": "S2V5RmllbGRMaXN0CTEzNjU2MjQ0NTY=", // mandatory
            "EntityType": 1, // 1 = AbEntry
            // Target = parameter used to group Key Field Definitions (optional).
            // Omit this value if this key field definition is intended to be displayed in the UI. Omitted on purpouse in this example
            "Name": "Company key fields",
            // Rule = the variant selector (mandatory for AbEntry). Type is Company | Individual | Contact;
            // Lead (Starred) is true/false.
            "Rule": {
                "$AND": [
                    {
                        "Type": {
                            "$EQ": "Company"
                        }
                    },
                    {
                        "Lead": {
                            "$EQ": false
                        }
                    }
                ]
            },
            "Layout": [
                {
                    "Name": null,
                    "ColumnNo": 0,
                    "Element": [
                        {
                            "ID": "/AbEntry/AccountManager"
                        },
                        {
                            "ID": "/AbEntry/Category"
                        },
                        {
                            "ID": null
                        } // separator
                    ]
                },
                {
                    "Name": "Territory", // Group title
                    "ColumnNo": 1,
                    "Element": [
                        {
                            "ID": "/AbEntry/Territory"
                        },
                        {
                            "ID": "/AbEntry/TerritoryStatus"
                        }
                    ]
                }
            ],
            "RequestedBy": "$CURRENTUSER()"
        },
        "Options": {
            "IncludeSeparator": true
        }
    },
    "Compatibility": {
        "KeyFieldDefinitionObject": "1.1"
    }
}

Create - UDF field with a custom description

// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
    "KeyFieldDefinition": {
        "Data": {
            "Key": null,
            "ParentKey": "S2V5RmllbGRMaXN0CTEzNjU2MjQ0NTY=", // mandatory
            "EntityType": 2, // 2 = Opportunity
            "Name": "Opportunity key fields (UDF description)",
            "Layout": [
                {
                    "ColumnNo": 0,
                    "Element": [
                        {
                            "ID": "/Opportunity/Cost"
                        },
                        {
                            // Element.Description overrides the text shown under this UDF in the UI.
                            // NOTE: it is GLOBAL to the UDF - it changes everywhere the UDF appears, not just in this layout (same as the classic Key Fields admin UI).
                            // Send "" / null to clear it. The UDF must already exist in the database.
                            "ID": "/Opportunity/Udf/$TYPEID(2)",
                            "Description": "Primary advisor for this deal"
                        }
                    ]
                }
            ],
            "RequestedBy": "$CURRENTUSER()"
        }
    },
    "Compatibility": {
        "KeyFieldDefinitionObject": "1.1"
    }
}

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)
            // Note: separators and group titles cannot be added via Append - author them with Replace or Create.
            "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
            // Note: separators and group titles cannot be targeted via Remove - re-author the layout with Replace or Create.
            "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

Create - KeyFieldDefinition

// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
    // Combination of ParentKey + EntityType + Target must be unique.
    // (For AbEntry the Rule is also part of that key - see the "Create - AbEntry key fields" HowTo.)
    "KeyFieldDefinition": {
        "Data": {
            "Key": null,
            "ParentKey": "S2V5RmllbGRMaXN0CTI2NDk0MDA0MQ==", // mandatory
            // Supported EntityTypes:
            // - 1  = AbEntry (Address Book)  -- requires a "Rule" to pick the variant
            // - 2  = Opportunity
            // - 5  = Customer Service (Case)
            // - 19 = Lead
            "EntityType": 2, // mandatory
            // Target = parameter used to group Key Field Definitions (optional).
            // Omit this value if this key field definition is intended to be displayed in the UI.
            "Target": "my_target",
            "Name": "Test KeyFieldDefinition from Postman",
            // Layout supports the full Key Fields structure. See the "HowTo's" folder for examples of:
            //   - Multiple columns (Group.ColumnNo: 0 = left, 1 = right)
            //   - Group titles (Group.Name)
            //   - Separators (Element.ID = null, with Options.IncludeSeparator = true)
            //   - Custom UDF descriptions (Element.Description)
            "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"
            }
        }
    }
}

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
                "Name": 1, 
                "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
                            }
                        ]
                    }
                ],
                "DisplayValue": 1
            }
        },
        "Criteria": {
            "SearchQuery": {}
        }
    },
    "Compatibility": {
        "KeyFieldDefinitionObject": "1.0"
    }
}

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 supports the full Key Fields structure (multiple columns, group titles,
            // separators, custom UDF descriptions). See the "HowTo's" folder for examples.
            // 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
        }
    }
}

Updated 20 days ago

Did this page help you?

Updated 20 days ago

Did this page help you?