Gram CRM solution example

Základný popis API rozhrania sa nachádza tu Gram CRM API. Tento dokument vyžaduje jeho znalosť.

Tu popísané API rozhranie sa môže kedykoľvek zmeniť bez upozornenia. Nepoužívajte v produkčnom systéme bez dôkladného otestovania, konzultácie.

UPOZORNENIE: Všetky vlastné Entity a Polia musia začínať prefixom „c“. Teda malé písmeno „c“. API umožní vytvoriť aj pole bez takéhoto prefixu, avšak v budúcnosti môže byť takéto pole/entita zmazaná aktualizáciou bez upozornenia.

Opis riešenia

Na tejto stránke si ukážeme modelový príklad vytvorenie úpravy systému pre „Bazénovú firmu“, teda organizáciu, ktorá predáva bazény a potrebuje pri obchodných prípadoch sledovať ich predaj a evidenciu. Riešenie vytvorí novú entitu Bazén, pridá prislúchajúci pohľad (Layout) s možnosťou editácie.

Entita Bazén bude obsahovať nasledovné polia:

Názov – textové jednoriadkové pole s dĺžkou 255 znakov
Dĺžka – číselná hodna, dĺžka bazénu v metroch
Stav – stav, v ktorom sa daný typ bazénu nachádza (V predaji, Novinka, Akcia). Pole typu rozbaľovací zoznam (option).
Potenciál Obchodných prípadov – hodnota aktuálne rozpracovaných obchodných prípadov pre daný typ bazénu. Počítané pole (calculated), kde je spočítaná hodnota všetkých aktívnych Obchodných prípadov
Predaných – celkový počet predaných bazénov. Počítané pole (calculated) typu mena, ako suma všetkých vyhratých Obchodných prípadov s daným bazénom
Celková dĺžka – celková dĺžka v metroch, ktoré sme doteraz predali. Pole typu formula, ktoré sa počíta ako súčin Dĺžky bazéna a Počtu predaných bazénov

Vytvoríme základný pohľad „Všetky bazény“, ktorý bude obsahovať polia:

Názov, Dĺžka, Stav, Predaných, Potenciál, Vytvoril, Upravil

Vytvoríme náhľad na entitu (Layout), ktorý v hlavičke zobrazí polia: Názov, Predaných, Celková dĺžka, Potenciál. V zozname polí bude potom: Dĺžka, Vytvoril.

V editácii entity potom budú k dispozícii tieto polia: Názov, Dĺžka, Stav

Vizualizácia riešenia

Karta Bazénu

Pohľad:

Riešenie

Riešenie pozostáva v postupnom zavolaní nasledovných API volaní. Všetky volania sú typu PUT. Volania možné realizovať len užívateľom, ktorý má Admin oprávnenie.

Vytvorenie Entity

https://api.gramcrm.com/demo/api/v1/core/Entity

{
    "Name": "cPool",
    "Label": "Bazén",
    "LabelPlural": "Bazény",
    "Icon": "f5c4",
    "Color": "692782",
    "GroupId": "sales_id",
    "GroupEntityOrder": 30,
    "HasActivity": 1,
    "HasAttachment": 1,
    "Main": 1    
}

Ikona je ľubovoľná ikona zo základných typov (solid, regular, light, thin) systému font awesome zapísaná vo forme unicode. Dostupné ikony ako aj prislúchajúce unicode sa nachádzajú na stránke: https://fontawesome.com/search. Parameter HasActivity určuje, či entita bude mať k dispozícii systémové aktivity (Telefonát, Email…). Parameter HasAttachment určuje, či bude možné prikladať prílohy k jednotlivým záznamom. GroupId definuje sekciu, do ktorej chceme zaradiť entitu (dostupné: accounts_id, sales_id, registry_id, preferences_id, fleet_id, support_id, services_id). GroupEntityOrder je následne poradie. Parameter Main určuje, či sa entita má zobraziť na hlavnom systémovom paneli.

Pridanie polí

Na pridanie, úpravu poľa (Field) slúži funkcia EntityField:

https://api.gramcrm.com/demo/api/v1/core/EntityField

Pole Názov (text)

Pridáme tzv. primárne pole „Názov“ typu jednoriadkový text s maximálnou dĺžkou 255 znakov. Vyplnenie poľa bude vždy povinné.

// https://api.gramcrm.com/demo/api/v1/core/EntityField
{
    "Entity": "cPool",
    "Name": "cName",    
    "Label": "Názov",
    "Type": "edit",
    "DataType": "varchar(255)",
    "Primary": 1,
    "Required": 1
}

Pole Dĺžka (číslo)

Pridáme tzv. primárne pole „Dĺžka“ typu číslo.

// https://api.gramcrm.com/demo/api/v1/core/EntityField
{
    "Entity": "cPool",
    "Name": "cLength",    
    "Label": "Dĺžka",
    "Type": "edit",
    "DataType": "number(11)"   
}

Pole Stav (zoznam)

Pridáme pole „Stav“ typu zoznam. Zároveň aj nastavíme, jednotlivé hodnoty, farbu, „stage“ a poradie.

// https://api.gramcrm.com/demo/api/v1/core/EntityField
{
    "Entity": "cPool",
    "Name": "cStatus",
    "Label": "Stav",
    "Type": "edit",
    "DataType": "option(cPool_cStatus)",
    "DefaultValue": 3,
    "Required": 1,
    "Option": {
        "Name": "cPool_cStatus",
        "Items": [
            {
                "Label": "V predaji",
                "Value": 3,
                "Color": "#8bc34a",
                "Stage": 0,
                "Order": 1000
            },
            {
                "Label": "Novinka",
                "Value": 1,
                "Color": "#f28e2b",
                "Stage": 0,
                "Order": 1001
            },
            {
                "Label": "Akcia",
                "Value": 2,
                "Color": "#ff3547",
                "Stage": 0,
                "Order": 1002
            }
        ]
    }
}

Pole Predaných (calculated)

Pridáme pole „Počet Predaných„. Jedná sa o pole typu „calculated“, teda jeho hodnota bude vypočítaná na základe prepojenia v parametre „RelatedTo“, ktorý určuje vzťah medzi jednotlivými entitami. V tomto prípade prepojíme Obchodný prípad(Deal) a jeho pole cPool s našou entitou cPool (zhodou okolností majú rovnaký názov). V tomto momente ešte nie je pole cPool v entite Deal vytvorené, čo nevadí. V rámci parametru AdvInfo môžeme určiť pomocou Where podmienku, pre ktoré Deal-y sa bude vzťahovať výpočet. V tomto prípade zoberieme do úvahy len tie Obchodné prípady, ktoré sú v stave „Won“. Ak by sme nepoužili parameter Where, tak spočítame všetky obchodné prípady, v ktorých je prepojenie na náš bazén.

// https://api.gramcrm.com/demo/api/v1/core/EntityField
{
    "Entity": "cPool",
    "Name": "cDealCount",
    "Label": "Počet Predaných",
    "Type": "calculated",
    "RelatedTo": "Deal:cPool",
    "DataType": "number(11)",
    "AdvInfo": {
        "Operator": "COUNT",
        "Field": "Id",
        "Where": [
            {
                "Field": "Status",
                "Operator": "e",
                "Value": "Won"
            }
        ]
    },
    "DefaultValue": 0
}

Pole Potenciál (calculated)

Pridáme aj pole „Potenciál„, čo je hodnota všetkých otvorených (Aktívnych) Obchodných prípadov.

// https://api.gramcrm.com/demo/api/v1/core/EntityField
{
    "Entity": "cPool",
    "Name": "cDealPrice",
    "Label": "Potenciál",
    "Type": "calculated",
    "RelatedTo": "Deal:cPool", // relation between deal and cPool
    "DataType": "currency(10,2)",
    "AdvInfo": {
        "Operator": "SUM",
        "Field": "Price",
        "Where": [
            {
                "Field": "Status",
                "Operator": "e",
                "Value": "Active"
            }
        ]
    },
    "DefaultValue": 0
}

Pole Celková dĺžka (formula)

Pridáme aj pole „Celková dĺžka„, ktorá je typu „formula“ a teda vypočítame hodnoty podľa vzorca uvedeného v parametri AdvInfo.

// https://api.gramcrm.com/demo/api/v1/core/EntityField
{
    "Entity": "cPool",
    "Name": "cTotalLength",
    "Label": "Celková Dĺžka",
    "Type": "formula",
    "DataType": "number(11)",
    "AdvInfo": "={cDealCount} * {cLength}",
    "DefaultValue": 0
}

Prepojenie medzi Entitami

Pole Bazén (lookup)

Pridáme aj pole „Bazén„, do entity Deal. Tým vytvoríme prepojenie medzi našou novou entitou Bazén(cPool) a existujúcim Obchodným prípadom(Deal).

// https://api.gramcrm.com/demo/api/v1/core/EntityField
{
    "Entity": "Deal",
    "Name": "cPool",    
    "Label": "Bazén",
    "Type": "edit",
    "DataType": "lookup(cPool)"
}

Vytvorenie pohľadu

Vytvoríme pohľad „Všetky Bazén„ aby sme mohli zobraziť obsah záznamov.

https://api.gramcrm.com/demo/api/v1/core/View/77b5c9e5-3d7a-4235-8de2-de2963a5f094

{
    "Entity": "cPool",
    "Label": "Všetky Bazény",    
    "Columns": [
        {"Field": "cName", "Width": 150},
        {"Field": "cLength", "Width": 75},
        {"Field": "cStatus", "Width": 75},
        {"Field": "cDealCount", "Width": 75},
        {"Field": "cDealPrice", "Width": 75},
        {"Field": "CreatedUser", "Width": 75},
        {"Field": "ModifiedUser", "Width": 75}
    ]
}

Vytvorenie layoutu

Vytvoríme layout pre Entitu „Bazén„ pomocou funkcie Layout. Každá entita môže mať viacero layoutov. PreviewPage určuje vzhľad po otvorení v aplikácii tzv. „DetailView“, kde „TopFields“ sú prvé 4 polia a „Fields“ sú bežné polia zobrazené v aplikácii. „DetailPage“ je editačná stránka entity. Teda polia, ktoré sa zobrazia pri pridávaní, resp. editácii záznamu. Parameter „Related“ obsahuje pohľady na prepojené záznamy.

https://api.gramcrm.com/demo/api/v1/core/Layout

{
    "Id": "d50555fc-9208-4a8b-84ae-747995eb59be",
    "Entity": "cPool",
    "Label": "Default",
    "PreviewPage": {
        "TopFields": [
            {
                "Field": "cName"
            },
            {
                "Field": "cDealCount"
            },
            {
                "Field": "cTotalLength"
            },
            {
                "Field": "cDealPrice"
            }
        ],
        "Fields": [
            {
                "Field": "cLength"
            },
            {
                "Field": "CreatedUser"
            }
        ]
    },
    "DetailPage": {
        "Sections": [
            {
                "Label": "Popis",
                "Columns": 1,
                "Fields": [
                    {
                        "Field": "cName",
                        "Column": 1,
                        "Hidden": 0
                    },
                    {
                        "Field": "cLength",
                        "Column": 1,
                        "Hidden": 0
                    },
                    {
                        "Field": "cStatus",
                        "Column": 1,
                        "Hidden": 0
                    }
                ]
            }
        ]
    },
    "Related": {
        "Views": [
            {
                "Field": "Deal:cPool",
                "Label": "Obchodné prípady",
                "Columns": [
                    {
                        "Field": "Number",
                        "Width": "75"
                    },
                    {
                        "Field": "OpenedDate",
                        "Width": "75"
                    },
                    {
                        "Field": "Name",
                        "Width": "75"
                    },
                    {
                        "Field": "Status",
                        "Width": "75"
                    },
                    {
                        "Field": "Account",
                        "Width": "75"
                    },
                    {
                        "Field": "Price",
                        "Width": "75"
                    }
                ],
                "Section": {
                    "Field": "Status",
                    "Order": "Asc"
                },
                "Total": [
                    {
                        "Field": "Price"
                    }
                ],
                "OrderBy": [
                    {
                        "Field": "Row",
                        "Order": "asc"
                    }
                ],
                "Id": "665f9da4-d532-384a-0183-9e34c956cbf6"
            }
        ]
    }
}

Publikovanie riešenia

Po ukončení práce je potrebné zavolať funkciu „Publish“, ktorá všetky zmeny zverejní okamžite. V opačnom prípade je možné, že niektoré, z tu uvedených zmien sa aplikujú až po určitom čase (desiatky minút až hodiny).

https://api.gramcrm.com/demo/api/v1/core/Publish

Dátum poslednej aktualizácie 8. novembra 2024

Obsah