Falcon Space. Working with entities

Introduction to the entity

An entity is an object that must be able to change its status sequentially.

In this case, it is possible to implement the separation of powers to change the status between roles. As well as automating additional functionality when an entity changes its status (for example, sending notifications, creating certain other objects, adding comments, and so on).

The system automatically keeps a log of status changes for the entity.

Implementation of the Entity mechanism

We will consider an example. Let's say there is such an object in our system as a Project. We want to implement the Project as an Entity.

1. Creating a new entity, describing possible statuses

In the Components/Entities menu, add the entry about the new entityProject, specifying its project code. This adds a new entry to the as_en_entities system table in the DB.

Next, go to the page with the statuses of the new entity and add all the necessary statuses. Physically, entity statuses are stored in the as_en_statuses system table.

When adding a status, its code is specified, preferably unique in the system, so as not to confuse it with a status that has the same name for some other entity in the system.

Be sure to specify the number in order for the status, as well as the color.

Next, you must fill in the possible transitions from each status in the menu Available statuses.

For example, a project can only be moved from the Draft status to the Published status, or to the Canceled status. Moreover, only the customer role has the right to perform this transition. The buttons for selecting the next statuses will say Publish and Cancel respectively.

2. Instances of the

The Project entity itself is a single entry in the table as_en_entitieswith the project code.

Instances of an entity, such as Project #1, Project #2, Project #3, and so on, will be stored in the as_en_entityInstancestable.

In the first paragraph we have created the essence of the Project. Now we need to link this concept to our projects in the database. This is done as follows.

Let's say our projects and all the information about them is in the au_projects table. Now you need to add another field to this table - instanceID. This will be the foreign key to the as_en_entityinstances table. This creates a one-to-one relationship between au_projects and as_en_entityInstances.

A list of entity instances, in our case a list of specific projects, is output to the page using the usual table snippet

<div class='as-dashboard' data-code='forAdmin'></div>

Of course, you must first implement the projects table in the system.

3. Adding a new instance of an entity

Еhe easiest way to create a new instance of an entity is to implement FastCreate in a table with a list of instances of this entity.

For example, in the projects table, quick creation will create a new project by name. At the same time, you must specify in crud_projects_fastCreate the insertion of a new record not only in au_projects, but also beforeinserting a new record in as_en_entityInstances. And only then insert the new record in au_projects with the new instanceID.

4. Page of the entity instance

To create a page for working with a separate instance of an entity, you must first create the form of an object that acts as an entity. The shape of the object, as usual, will contain the fields of an object for viewing or editing.

In our case, we will create the entityProject form to manage the fields of the Project object.

After that, we will create a page for the entity instance where we will place the snippets:

• Regular form snippet:
  

  <div class="as-form" data-code="{formCode}" data-itemid="falcon-space--rabota-s-sushchnostyami"></div>

• Snippet for managing entity instance statuses:
  

  <div class="entity" data-code="{entityCode}" data-itemid="falcon-space--rabota-s-sushchnostyami" data-type="item"></div>

Example of page layout for an instance of the Project entity:

Thus, the current status pointer and buttons for available further transitions will be located in the right column of the project form:

5. Go from the page with the list of entities to the page with the selected instance

It is very important to correctly configure the transition to the page of the selected entity instance from the list table. Here is the next nuance.

When you link one of the table columns to an instance page, you should pass instanceID instead of the id from the project instance table as itemID.

For example, in the case of our projects:

6. Important note about logging status changes

The status changes is recorded in the as_en_statusesLog  log automatically only if the intence is automatically transferred to the next status - by corresponding button to transfer to the status.

If somewhere you programmatically prescribe the implementation of forced transition of an instance to the status, then do not forget  also insert the corresponding entry in as_en_statusesLog.

7. Data base schema for implementing the entity mechanism

Stored procedures for working with entities

Procedure BEFORE changing the status

Proceduresand en_{entityCode}_checkStatusis called to perform the necessary checks beforechanges the status of the entity instance.

Parameters: instanceID, fromStatusCode, toStatusCode, username

Select Result: msg, result, bit softMode, okButtonStyle, okButtonText, cancelButtonStyle, cancelButtonTextem>.

softModeparameter:

• If softMode = 1, it means that the restriction is not rigid and you can still change the status after confirmation.
• if softMode = 0, then if it is impossible to change the status, a message is sent about it, without the ability to forcibly change the status.

okButtonText,cancelButtonText-specify the button text for Canceling and Confirming the action.

okButtonStyle, cancelButtonStyle-set the button style. Values - danger, warning,success, secondary, primary, info, light

Procedure AFTER changing the status

The en_{entityCode}_afterChangeStatus procedure is called after the entity instance has successfully changed its status.

Parameters: instanceID, statusCode, username

Result

SELECT 1: msg, result

SELECT statement 2: the challenges of external actions (mail, SMS, notification, etc.). Cm. a call to an external action.

For example, in this procedure, it is convenient to insert a call to the procedure for generating notifications to the participants of an operation in the system, or to automate the formation of any documents.

Procedure for displaying an additional panel for the status

The procedure en_{entityCode}_getStatusAdditionalToolbar & nbsp; contains the output of additional markup under the buttons for switching to available statuses.

Parameters: instanceID, entityCode, statusCode, username, langID

Result Select: msg, result

In this case, the msg contains the markup stringof the additional panel.

For example, when the project is moved to the Completed status, you can add the "Add review" button to the additional panel. In this case, the msg should contain, for example, a call to the modal form to add a review to the project executor.

CREATE PROCEDURE [dbo].[project]
	@instanceID int,
	@entityCode nvarchar(32),
	@statusCode nvarchar(32),
	@username nvarchar(32),
	@langID int = 1
AS
BEGIN
	if @statusCode = 'done'
           SELECT 'Добавить отзыв' Msg,
                   1 Result
        else
           SELECT '' Msg, 0 Result
END

It will Look like this:

Stored procedure for displaying available statuses

By default, the standard procedure is used as_en_getAvailableStatusesForInstance.

If you need your own procedure, you set the Custom procedure mode Availablestatuses = YES and implement the procedure en_{entityCode}_getAvailableStatusesForInstance (SQL column of available statuses)