Create new related entity from detail using business action

Header

Level: Intermediate

Keywords: business action, create feature, related features, related-entity-list, key-value-form

The result: definition of action and input form needed to create new related feature instance from related-entity-list

How to create a new instance of related entity from detail of master entity?

This example describes the case when creating new instances of features related to currently opened master detail entity is not sufficient using the standard way. Creating of new entity activated by means of + icon from related-entity-list module is processed with using of action form and subsequently by business action.

Fig. 1. Icon + located in related-entity-list module within the detail form can open action form for adding new releted entities controlled by business action

Creating of action form

In this case the key-value-form module is used for arranging data items. Except for attributes that belong to the related feature type being created, also updated attribute of master entity and attachments can be added.

Action Form - configuration example

    {
        "addNewProtocol": {
            "title": "Insert new protocol",
            "sections": [
            {
                "module": {
                "type": "component:dynamic-app/modules/forms/key-value-form",
                "scope": "requestBody",
                "elements": [
                    {
                    "label": "Division",
                    "type": "codelist",
                    "property": "ft_protocol.at_protocol_cl_division",
                    "codelist": "cl_division",
                    "idProperty": "ca_division_id",
                    "titleProperty": "ca_division_description",
                    "disabled" : true,
                    "dynamic": true,
                    "validation": {
                        "required": true,
                        "validateOnChange": true
                    }
                    },
                    {
                    "label": "Execution date",
                    "type": "date",
                    "property": "ft_inspection.at_inspection_executionDate",
                    "hidden" : true,
                    "defaultValue" : "{today:}",
                    "validation": {
                        "type": "date",
                        "max": "{today:}",
                        "required": true,
                        "validateOnChange": true
                    }
                    },
                    {
                    "title": "Attachments to the protocol",
                    "property": "attachments",
                    "type": "entity-modules:entity-attachments",
                    "allowTemporary": true,
                    "detailMethod": "business",
                    "dateFormat": "DD. MM. YYYY"
                    }
                ]
                }
            }
        ]
        }
    }

Use action form instead of standard function

Using of action form i.e. buseness action instead of standard function for add new related element is defined by means of addRelatedByAction element inside the related-entity-list module in detail entity metadata.

Related-entity-list addRelatedByAction - configuration example

    {
        "default" : {
            "sections" : [
                {
                    "icon" : "cbu-icons:protocol",
                    "collapsible": true,
                    "collapsed": false,
                    "module" : {
                    "title": "Inspection protocols",
                    "type": "component:entity-modules/lists/related-entity-list",
                    "entity": "ft_protocol",
                    "relation": "as_protocol_inspection",
                    "role": "rt_protocol",
                    "displayType" : "list",
                    "readOnly": false,
                    "addRelatedByAction": {
                        "title" : "Add new protocol",
                        "actionId" : "addNewProtocol"
                    },
                    "permittedOperations" : {
                        "create" : true,
                        "edit"   : true,
                        "delete" : false
                    }
                    }
                }
            ]
        }
    }

### Registration of the relevant business action
Bussiness action must be defined in given entity (feature type) business metadata. The name of action must be the same as name of action form context.

```json title="addNewProtocol action reference - configuration example"
    {
        "actions": {
            "addNewProtocol": {
            "conditions": [
                {
                "type": "script",
                "source": "scripts/conditions/isNotExistsProtocol.js"
                }
            ],
            "steps": [
                {
                "type": "script",
                "source": "scripts/addNewProtocol.js"
                }
            ]
            }
        }
    }

Creating of business action script

Bussiness action script (JavaScript) is located and named based on parametr source from relevant action definition.

addNewProtocol action content - configuration example

    function action(context) {
        var jsonRequestReader =
            api.request()
                .prepareCreateJSONRequestReader(context)
                .create();

        var requestRootNode = jsonRequestReader.getRootNode();
        var protocol = requestRootNode.getNodeByPathThrowing("protocol").getObject();
        var attachments = requestRootNode.getNodeByPathThrowing("attachments").getObject();
        var inspection = context.entity;

        protocol.at_protocol_cl_typPisemnosti = { ca_typPisemnosti_id: 7 };
        protocol.at_protocol_aktSchvalujici = inspection.at_inspection_resitel;

        protocol.at_protocol_eSpisHodnotaId = getRandomHex8();

        var spis = api.features()
            .prepareGetFeature(context)
            .entityRef(inspection.at_inspection_rf_spis)
            .get();
        protocol.at_protocol_rf_DMSDocument = spis;

        var uzivatel = api.codelists().prepareGetCodelistItem(context)
            .entityType("cl_user")
            .entityId(api.security().users().prepareGetAuthenticatedUser().get().id)
            .get();

        if (inspection.at_inspection_creator != null) {
            protocol.at_protocol_owner = inspection.at_inspection_creator.ca_user_login;
        }

        protocol = api.features().prepareCreateRelatedFeature(context)
            .entityRef(inspection)
            .relatedType("ft_protocol")
            .relation("as_protocol_inspection")
            .role("rt_protocol")
            .createBody(protocol)
            .create();

        api.business()
            .prepareTriggerEntityAction(context)
            .entityRef(protocol)
            .action("addAddresse")
            .trigger();

        if (attachments && attachments.temporaryAttachments) {
            addAttachments(context, protocol, {attachments: attachments});
        }

        copyToDMS(context, protocol);
    }