Customize delivery process

Install scripts let you execute CRUD operations with data using Entity and EntitySchemaQuery classes. Learn more about the Entity class in the .NET class library. Learn more about the EntitySchemaQuery class in the .NET class library.

Retrieve data 

Retrieve a contact that has specified data 

public static Entity GetContact(UserConnection userConnection, string name) {
    EntitySchemaManager entitySchemaManager = userConnection.EntitySchemaManager;
    Entity contact = entitySchemaManager.GetEntityByName("Contact", userConnection);
    var contactConditions = new Dictionary<string, object> {
        { "SomeContactName", name }
    };
    return !contact.FetchFromDB(contactConditions) ? null : contact;
}

Retrieve data using pagination 

namespace Terrasoft.Configuration
{
    using System;
    using System.Collections.Generic;
    using Terrasoft.Core;
    using Terrasoft.Core.Entities;

    public class FillDeliveryType : IInstallScriptExecutor {
    
        public void Execute(UserConnection userConnection)
        {
            /* Create an ESQ that contains the [Id] column of the product and [Name] column from the [OrderProduct] database table. */
            EntitySchemaQuery esqResult = new EntitySchemaQuery(userConnection.EntitySchemaManager, "OrderProduct");
            EntitySchemaQueryColumn orderIdColumn = esqResult.AddColumn("Order.Id");
            EntitySchemaQueryColumn productCategoryColumn = esqResult.AddColumn("Product.Category.Name");
            /* Implement pagination. */
            var options = new EntitySchemaQueryOptions {
                PageableDirection = Core.DB.PageableSelectDirection.First,
                RowsOffset = 0,
                PageableRowCount = userConnection.AppConnection.MaxEntityRowCount,
                PageableConditionValues = new Dictionary<string, object>()
            };
            /* Retrieve the collection of the orders. */
            EntityCollection productsInOrder = esqResult.GetEntityCollection(userConnection, options);
            EntitySchemaManager entitySchemaManager = userConnection.EntitySchemaManager;
            Entity orderEntity = entitySchemaManager.GetEntityByName("Order", userConnection);
            /* The first page. */
            EditOrders(productsInOrder, orderIdColumn, productCategoryColumn, orderEntity);
            int rowsRead = productsInOrder.Count;
            /* Use the pagination. */
            while (productsInOrder.Count > 0) {
                options.RowsOffset = rowsRead;
                /* Scroll forward. */
                options.PageableDirection = Core.DB.PageableSelectDirection.Next;
                /* Retrieve next page. */
                esqResult.ResetSelectQuery();
                productsInOrder = esqResult.GetEntityCollection(userConnection, options);
                rowsRead += productsInOrder.Count;
                EditOrders(productsInOrder, orderIdColumn, productCategoryColumn, orderEntity);
            }
        }

        private void EditOrders(EntityCollection productsInOrder, EntitySchemaQueryColumn orderIdColumn,
                EntitySchemaQueryColumn productCategoryColumn, Entity orderEntity) {
                    /* Implement the modifying logic. */
        }
    }
}

To work with big data, follow the recommendations listed in a separate article: Customize delivery process.

Add data 

Add a contact that has specified data 

public static void CreateContact(UserConnection userConnection, string contactName, string accountName) {
    if (GetContact(userConnection, contactName) != null){
        return;
    }
    EntitySchemaManager entitySchemaManager = userConnection.EntitySchemaManager;
    Entity contact = entitySchemaManager.GetEntityByName("Contact", userConnection);
    contact.SetDefColumnValues();
    contact.SetColumnValue("Id", Guid.NewGuid());
    /* The AccountHelper class is a helper class. */
    contact.SetColumnValue("AccountId", AccountHelper.GetAccountId(userConnection, accountName));
    contact.SetColumnValue("Name", contactName);
    contact.Save();
}

Add a new job title that supports different cultures 

namespace Terrasoft.Configuration {
    using System;
    using System.Globalization;
    using Terrasoft.Common;
    using Terrasoft.Core;
    using Terrasoft.Core.Entities;

    public class CreateJobTitle : IInstallScriptExecutor {

        public void Execute(UserConnection userConnection) {
            EntitySchemaManager entitySchemaManager = userConnection.EntitySchemaManager;
            Entity job = entitySchemaManager.GetEntityByName("Job", userConnection);
            job.SetDefColumnValues();
            job.SetColumnValue("Id", Guid.NewGuid());
            var jobName = new LocalizableString();
            var esCulture = new CultureInfo("es-ES");
            var enCulture = new CultureInfo("en-US");
            jobName.SetCultureValue(esCulture, "Mentor");
            jobName.SetCultureValue(enCulture, "Master");
            job.SetColumnValue("Name", jobName);
            job.Save();
        }
    }
}

Modify data 

public static void SetContactField(UserConnection userConnection, string contactName, string columnValue) {
    /* The ContactHelper class is a helper class. */
    var entity = ContactHelper.GetContact(userConnection, contactName);
    /* The LanguageHelper class is a helper class. */
    entity.SetColumnValue("ProgrammingLanguageId", LanguageHelper.GetLanguageId(userConnection, columnValue));
    entity.Save();
}

Delete data 

public static void DeleteContact(UserConnection userConnection, string contactName) {
    /* The ContactHelper class is a helper class. */
    var contact = ContactHelper.GetContact(userConnection, contactName);
    contact.Delete();
}

1. Implement an install script 

1. Open the Configuration section and select a custom package to add the schema.

2. Click Add → Source code on the section list toolbar.

   

3. Fill out the schema properties in the Source Code Designer:

   • Set Code to "UsrPopulateDeliveryType."
   • Set Title to "Populate the delivery type."
   

   Click Apply.

4. Implement the business logic of the delivery type filling.

   UsrFillDeliveryType

   namespace Terrasoft.Configuration
   {
       using System;
       using System.Collections.Generic;
       using Terrasoft.Core;
       using Terrasoft.Core.Entities;
   
       public class UsrPopulateDeliveryType : IInstallScriptExecutor {
   
           private static object GetDeliveryIdByName(string deliveryName) {
               /* The unique ID of the delivery type. Delivery types are stored in the [DeliveryType] configuration element of the [Data] type in the [Order] package. */
               switch (deliveryName) {
                   case "Courier":
                       return new Guid("50df77d0-7b1f-4dbc-a02d-7b6ebb95dfd0"); 
                   case "Customer pickup":
                       return new Guid("ab31305f-7c6d-4158-bd0a-760ac7897755"); 
                   default:
                       return Guid.Empty;
               }
           }
           
           private static object GetDeliveryTypeByProductCategory(string category) {
               /* The category of the product. Product categories are stored in the [ProductCategory] configuration element of the [Data] type in the [ProductCatalogue] package. */
               switch (category) {
                   case "Software":
                       return GetDeliveryIdByName("Courier");
                   case "Hardware":
                       return GetDeliveryIdByName("Customer pickup");
                   case "Services":
                       return GetDeliveryIdByName("Customer pickup");
                   default:
                       return GetDeliveryIdByName("");
               }
           }
           
           public void Execute(UserConnection userConnection) {
               /* Create an ESQ that contains the [Id] column of the product and [Name] column from the [OrderProduct] database table. The [Name] column is the name of the product category. */
               EntitySchemaQuery esqResult = new EntitySchemaQuery(userConnection.EntitySchemaManager, "OrderProduct");
               EntitySchemaQueryColumn orderIdColumn = esqResult.AddColumn("Order.Id");
               EntitySchemaQueryColumn productCategoryColumn = esqResult.AddColumn("Product.Category.Name");
               /* Retrieve the collection of products in the order. */
               EntityCollection productsInOrder = esqResult.GetEntityCollection(userConnection);
               EntitySchemaManager entitySchemaManager = userConnection.EntitySchemaManager;
               Entity orderEntity = entitySchemaManager.GetEntityByName("Order", userConnection);
               foreach (Entity entity in productsInOrder) {
                   /* Retrieve the order object using the ID. */
                   Guid id = entity.GetTypedColumnValue<Guid>(orderIdColumn.Name);
                   string category = entity.GetTypedColumnValue<string>(productCategoryColumn.Name);
                   var conditions = new Dictionary<string, object> {
                       { "Id", id }
                   };
                   orderEntity.FetchFromDB(conditions);
                   /* Populate the delivery type based on the product category. */
                   orderEntity.SetColumnValue("DeliveryTypeId", GetDeliveryTypeByProductCategory(category));
                   /* Save the order. */
                   orderEntity.Save();
               }
           }
       }
   }
   

5. Click Publish on the Source Code Designer’s toolbar to apply the changes to the database level.

2. Add the install script to the installation steps 

1. Open the Configuration section and select a custom package.
2. Select Properties in the package menu.
3. Go to the Installation steps tab to set up the execution order of steps when installing the package.

4. Add the UsrFillDeliveryType install script to the After package installation start event.

   1. Click + Add in the After package installation block. This opens a window.
   2. Select the UsrPopulateDeliveryType schema.
   3. Click Select.
5. Click Apply.

Outcome of the example 

To view the outcome of the example for the current Creatio instance:

1. Click Actions → Run as install script on the Source Code Designer’s toolbar to execute the Source code schema as install script.
2. Open the Sales Enterprise app page and click Run app.
3. Open the Orders section.
4. Open the order page → Products tab to check the category of the product.
5. Go to the Delivery tab.

As a result, Creatio will set the "Courier" delivery type for products that have the "Software" category.

Creatio will set the "Customer pickup" delivery type for products that have "Hardware" category.

Creatio will set the "Customer pickup" delivery type for products that have "Services" category.

Creatio will leave the Delivery type field empty for products that have other categories.

To view the outcome of the example for other Creatio instances:

1. Select Export in the package menu.
2. Install the package to the needed Creatio instance. To do this, follow the guide in a separate article: Install apps from the Marketplace.
3. Repeat steps 2-5 of the procedure to view the outcome of the example for the current Creatio instance.