Service that runs business processes

1. Create a process that adds a contact 

1. Open the Configuration section and select a custom package to add the business process.
2. Open the Process Designer.

3. Fill out the business process properties.

   • Set Name to "Add New External Contact."
   • Set Code to "UsrAddNewExternalContact."

   Use default values for other properties.

   

4. Add business process parameters.

   The process uses parameters to pass the data of the new contact: name and phone number.

   View the process parameter values to fill out in the table below.

   Process parameter values

   Title	Code	Data type
   ContactName parameter
   "Contact Name"	"ContactName"	"Text (50 characters)"
   ContactPhone parameter
   "Contact Phone"	"ContactPhone"	"Text (50 characters)"

   

5. Add the ScriptTask element.

   1. Fill out the element properties.

      • Set Name to "Add contact."
      • Set Code to "ScriptTaskAddContact."

   2. Implement the mechanism that adds a new contact.

      To edit the script code, double-click a diagram element. This opens a window on the element setup area. Enter and edit the source code in the window.

      ScriptTaskAddContact

      /* Creates an instance of the [Contact] object schema. */ 
      var schema = UserConnection.EntitySchemaManager.GetInstanceByName("Contact"); 
      /* Creates an instance of the new object. */ 
      var entity = schema.CreateEntity(UserConnection); 
      /* Sets the default values for the object columns. */ 
      entity.SetDefColumnValues(); 
      string contactName = Get<string>("ContactName"); 
      string contactPhone = Get<string>("ContactPhone"); 
      /* Sets the [Name] column values from the process parameter. */ 
      entity.SetColumnValue("Name", contactName); 
      /* Sets the [Phone] column values from the process parameter. */ 
      entity.SetColumnValue("Phone", contactPhone); 
      /* Saves the new contact. */ 
      entity.Save(); 
      return true;
      

6. Click Save.

2. Create a process that reads all Creatio contacts 

The business process that creates the index of all Creatio contacts includes a single ScriptTask element as well.

To create a process that reads all Creatio contacts:

1. Open the Configuration section and select a custom package to add the business process.
2. Open the Process Designer.

3. Fill out the business process properties.

   • Set Name to "Get All Contacts."
   • Set Code to "UsrGetAllContacts."

   Use default values for other properties.

   

4. Add the business process parameter.

   Fill out the values of the business process parameter.

   • Set Title to "Contact List."
   • Set Code to "ContactList."
   • Set Data type to "Unlimited length text."
   

   The parameter returns the JSON index of all Creatio contacts.

5. Add the ScriptTask element.

   1. Fill out the element properties.

      • Set Name to "Get all contacts."
      • Set Code to "ScriptTaskGetAllContacts."

   2. Implement the mechanism that reads the Creatio contacts.

      To edit the script code, double-click the diagram. This opens a window on the element setup area. Enter and edit the source code in the window.

      ScriptTaskGetAllContacts

      /* Creates an EntitySchemaQuery instance. */ 
      EntitySchemaQuery query = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "Contact"); 
      /* Flag the [Id] primary column as required to select. */ 
      query.PrimaryQueryColumn.IsAlwaysSelect = true; 
      /* Adds columns to the query. */ 
      query.AddColumn("Name"); 
      query.AddColumn("Phone"); 
      /* Retrieve the resulting collection. */ 
      var entities = query.GetEntityCollection(UserConnection); 
      /* Creates the contact list to serialize in JSON. */ 
      List<object> contacts = new List<object>(); 
      foreach (var item in entities) { 
          var contact = new { 
              Id = item.GetTypedColumnValue<Guid>("Id"), 
              Name = item.GetTypedColumnValue<string>("Name"), 
              Phone = item.GetTypedColumnValue<string>("Phone") 
          }; 
          contacts.Add(contact); 
      } 
      /* Saves the contact collection that is serialized in JSON to the ContactList parameter. */ 
      string contactList = JsonConvert.SerializeObject(contacts); 
      Set<string>("ContactList", contactList); 
      return true;
      

6. Click Save.

Outcome of the example 

1. Run business processes from the browser address bar.

   1. Run the process that adds a contact. To do this, enter the following URL in the browser address bar.

      URL that runs the process that adds a contact

      http[s]://[CreatioURL]/0/ServiceModel/ProcessEngineService.svc/UsrAddNewExternalContact/Execute?ContactName=John Johanson&ContactPhone=1 111 111 1111

      As a result, the process will add a contact to Creatio.

      

      Attention. A contact is added every time the service receives a request successfully. If you run multiple queries that contain the same parameters, the service adds multiple duplicate contacts.

   2. Run the process that reads all Creatio contacts. To do this, enter the following URL in the browser address bar.

      URL that runs the process that reads all Creatio contacts

      http[s]://[Creatio URL]/0/ServiceModel/ProcessEngineService.svc/UsrGetAllContacts/Execute?ResultParameterName=ContactList

      As a result, the browser window will display the JSON object that contains the contact collection.

      

2. Run business processes from the console app.

   View the complete source code of the custom console app that runs business processes via the ProcessEngineService.svc service on GitHub.

   1. Perform the authentication. To do this, use the AuthService.svc authentication service. Use the example available in a separate article: Implement authentication using C#.

   2. Add a string field that contains the base service URL to the source code of the Program class.

      URL that creates requests to the ProcessEngineService.svc service

      private const string processServiceUri = baseUri + @"/0/ServiceModel/ProcessEngineService.svc/";

   3. Add a GET method that runs the business process that creates a contact to the source code of the Program class.

      GET method that runs the business process

      public static void AddContact(string contactName, string contactPhone) { 
          /* Generates a request URL. */ 
          string requestString = string.Format(processServiceUri + "UsrAddNewExternalContact/Execute?ContactName={0}&ContactPhone={1}", contactName, contactPhone); 
          /* Creates an HTTP request. */ 
          HttpWebRequest request = HttpWebRequest.Create(requestString) as HttpWebRequest; 
          request.Method = "GET"; 
          request.CookieContainer = AuthCookie; 
          /* Executes the request and analyzes the HTTP response. */ 
          using (var response = request.GetResponse()) { 
              /* Displays the properties of the HTTP response if the service returns an empty string. */ 
              Console.WriteLine(response.ContentLength); 
              Console.WriteLine(response.Headers.Count); 
          } 
      }    
      

   4. Add GET method that runs the business process that reads all Creatio contacts to the Program class source code.

      GET method that runs the business process

      public static void GetAllContacts() { 
          /* Generates a request URL. */ 
          string requestString = processServiceUri + "UsrGetAllContacts/Execute?ResultParameterName=ContactList"; 
          HttpWebRequest request = HttpWebRequest.Create(requestString) as HttpWebRequest; 
          request.Method = "GET"; 
          request.CookieContainer = AuthCookie; 
          /* Creates an HTTP request. */ 
          using (var response = request.GetResponse()) { 
              /* Executes the request and displays the result. */ 
              using (var reader = new StreamReader(response.GetResponseStream())) { 
                  string responseText = reader.ReadToEnd(); 
                  Console.WriteLine(responseText); 
              } 
          } 
      }  
      

   5. Call the added methods in the main app method after a successful authentication.

      Call the methods

      static void Main(string[] args) { 
          if (!TryLogin("Supervisor", "Supervisor")) { 
              Console.WriteLine("Wrong login or password. Application will be terminated."); 
          } 
          else { 
              try { 
                  /* Calls methods that runs business processes. */ 
                  AddContact("John Johanson", "+1 111 111 1111"); 
                  GetAllContacts(); 
              } 
              catch (Exception) { 
                  /* Handle exceptions. */ 
                  throw; 
              } 
          }; 
          Console.WriteLine("Press ENTER to exit..."); 
          Console.ReadLine(); 
      }
      

   

1. Implement the Holding a meeting custom business process 

1. Create the Holding a meeting business process. To do this, implement the example from a separate article: Send emails via business processes.

2. Add the business process parameter.

   Fill out the values of the business process parameter.

   • Set Title to "Meeting contact."
   • Set Code to "ProcessSchemaContactParameter."
   • Set Data type to "Unique identifier."
   

3. Add the "[#Meeting contact#]" incoming parameter to the Contact property of the Call customer process action.

   

2. Implement the custom action on the account page 

1. Create a replacing view model schema of the account page To do this, follow the guide in a separate article: Add an action to the record page.

2. Add a localizable string that contains the menu item caption.

   1. Click the button in the context menu of the Localizable strings node.

   2. Fill out the localizable string properties.

      • Set Code to "CallProcessCaption."
      • Set Value to "Schedule a meeting."
   3. Click Add to add a localizable string.

3. Implement the menu item behavior.

   1. Add the ProcessModuleUtilities module as a dependency.

   2. Implement the following methods in the methods property:

      • callCustomProcess(). Action handler method. Implements the executeProcess() method of the ProcessModuleUtilities module. Pass the name of the business process and object that contains the initialized incoming process parameters to the module as a parameter.
      • isAccountPrimaryContactSet(). Checks whether the primary contact of the account is filled out.
      • getActions(). An overloaded base method. Returns the action collection of the replacing page.

   View the source code of the replacing view model schema of the account page below.

   AccountPageV2

   define("AccountPageV2", ["ProcessModuleUtilities"], function(ProcessModuleUtilities) { 
       return { 
           /* The name of the record page object’s schema. */ 
           entitySchemaName: "Account", 
           /* The methods of the record page’s view model. */ 
           methods: { 
               /* Verifies the [Primary contact] field of the record page is filled in. */ 
               isAccountPrimaryContactSet: function() { 
                   return this.get("PrimaryContact") ? true : false; 
               }, 
               /* Overrides the base virtual method that returns the action collection of the record page. */ 
               getActions: function() { 
                   /* Calls the parent method implementation to retrieve the collection of the base page’s initialized actions. */ 
                   var actionMenuItems = this.callParent(arguments); 
                   /* Adds a separator line. */ 
                   actionMenuItems.addItem(this.getActionsMenuItem({ 
                       Type: "Terrasoft.MenuSeparator", 
                       Caption: "" 
                   })); 
                   /* Adds a menu item to the action list of the record page. */
                   actionMenuItems.addItem(this.getActionsMenuItem({ 
                       /* Binds the menu item caption to the localizable schema string. */ 
                       "Caption": { 
                           bindTo: "Resources.Strings.CallProcessCaption" 
                       }, 
                       /* Binds the action handler method. */ 
                       "Tag": "callCustomProcess", 
                       /* Binds the property of the menu item visibility to the value returned by the isAccountPrimaryContactSet() method. */ 
                       "Visible": { 
                           bindTo: "isAccountPrimaryContactSet" 
                       } 
                   })); 
                   return actionMenuItems; 
               }, 
               /* The action handler method. */ 
               callCustomProcess: function() { 
                   /* Receives the ID of the account primary contact. */ 
                   var contactParameter = this.get("PrimaryContact"); 
                   /* The object that transferred to the executeProcess() method as a parameter. */ 
                   var args = { 
                       /* The name of the process that needs to be run. */ 
                       sysProcessName: "UsrCustomProcess",
                       /* The object with the ContactParameter incoming parameter value for the CustomProcess process. */
                       parameters: { 
                           ProcessSchemaContactParameter: contactParameter.value 
                       } 
                   }; 
                   /* Runs the custom business process. */ 
                   ProcessModuleUtilities.executeProcess(args); 
               } 
           } 
       }; 
   });    
   

4. Click Save on the Module Designer’s toolbar.

3. Implement the custom action of the section page 

1. Create a replacing view model schema of the section. To do this, follow the guide in a separate article: Add an action to the record page.
2. Add a localizable string that contains the menu item caption. To do this, take step 2 of the procedure to implement a custom action of the account page.

3. Implement the menu item behavior. To do this, implement the isAccountPrimaryContactSet() method in the methods property. The method checks whether the primary contact of the account is filled out.

   View the source code of the replacing view model schema of the section page below.

   AccountSectionV2

   define("AccountSectionV2", [], function() { 
       return { 
           /* The name of the section page schema. */ 
           entitySchemaName: "Account", 
           /* The methods of the section page’s view model. */ 
           methods: { 
               /* Verifies the [Primary contact] field of the selected account is filled in. */ 
               isAccountPrimaryContactSet: function() { 
                   /* Defines the active record. */ 
                   var activeRowId = this.get("ActiveRow"); 
                   if (!activeRowId) { 
                       return false; 
                   } 
                   /* Retrieves the data collection of the section list’s list view. Retrieves the selected account model by the specified primary column value. */ 
                   var selectedAccount = this.get("GridData").get(activeRowId); 
                   if (selectedAccount) { 
                       /* Receives the model property – the primary contact. */ 
                       var selectedPrimaryContact = selectedAccount.get("PrimaryContact"); 
                       /* Returns true if the primary contact is filled in, return false otherwise. */ 
                       return selectedPrimaryContact ? true : false; 
                   } 
                   return false; 
               } 
           } 
       }; 
   });
   

4. Click Save on the Module Designer’s toolbar.

Outcome of the example 

To view the outcome of the example:

1. Clear the browser cache.
2. Refresh the Accounts section page.

As a result, Creatio will add the Schedule a meeting action to the account page. This action will be active if the primary contact of the account is filled out.

Select the action to run the Holding a meeting custom business process . The primary contact of the account will be passed to the business process as a parameter.

1. Implement the Result parameters custom business process 

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

2. Click Add → Business process on the section list toolbar.

   

3. Fill out the business process properties.

   • Set Title to "Result parameters."
   • Set Code to "UsrParametersProcess."

   Use default values for the other properties.

   

4. Add business process parameters.

   View the process parameters values to fil out in the table below.

   Process parameters values

   Title	Code	Data type	Direction
   "Primary contact"	"ProcessSchemaContactParameter"	"Unique identifier"	"Input"
   "Contact age"	"ProcessContactAge"	"Integer"	"Output"
   "Full job title"	"ProcessFullJob"	"Text (500 characters)"	"Output"

   

5. Implement data reading.

   1. Add the Read data element to the Process Designer workspace.

      

   2. Fill out the element properties.

      • Set Which data read mode to use? to "Read the first record in the selection."
      • Set Which object to read data from? to "Contact."
      • Set the filter by the Id column in the How to filter records? property. Set the value of the "Primary contact" incoming parameter as the column value.
      

6. Add the values of the outgoing parameters.

   1. Go to the Parameters tab.
   2. Enter "[#Read data.First item of resulting collection.Full job title#]" in the Value field for the Full job title parameter.
   3. Enter "[#Read data.First item of resulting collection.Age#]" in the Value field for the Contact age parameter.
   
7. Click Save on the Process Designer’s toolbar.

2. Create a replacing view model schema of the account page 

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

2. Click Add → Replacing view model on the section list toolbar.

   

3. Fill out the schema properties.

   • Set Code to "AccountPageV2."
   • Set Title to "Account edit page."
   • Set Parent object to "AccountPageV2."
   

4. Add a localizable string that contains the menu item caption.

   1. Click the button in the context menu of the Localizable strings) node.

   2. Fill out the localizable string properties.

      • Set Code to "CallProcessParametersCaption."
      • Set Value to "Recieve parameters."
      
   3. Click Add to add a localizable string.

5. Implement the menu item logic.

   Implement the following methods in the methods property:

   • isAccountPrimaryContactSet(). Checks whether the primary contact of the account is filled out and defines the visibility of the menu item.
   • callCustomProcess(). Action handler method. Runs the business process and displays the values of the resulting parameters in the dialog.
   • getActions(). An overloaded base method. Returns the action collection of the replacing page.

   View the source code of the replacing view model schema of the account page below.

   AccountPageV2

   define("AccountPageV2", [], function() { 
       return { 
           /* The name of the record page object’s schema. */  
           entitySchemaName: "Account", 
           /* The methods of the record page’s view model. */ 
           methods: { 
               /* Check the [Primary contact] field of the account is filled out to define the visibility of the menu item. */ 
               isAccountPrimaryContactSet: function() { 
                   /* Return true if the primary contact is filled out, return false otherwise. */
                   return this.get("PrimaryContact") ? true : false;
               }, 
               /* Overload the base virtual method that returns the collection of record page actions. */ 
               getActions: function() { 
                   /* Call the parent method implementation to retrieve the collection of base page’s initialized actions. */ 
                   var actionMenuItems = this.callParent(arguments); 
                   /* Add a separator line. */ 
                   actionMenuItems.addItem(this.getActionsMenuItem({ 
                       Type: "Terrasoft.MenuSeparator",
                       Caption: "" 
                   })); 
                   /* Add a menu item to the action list of the record page. */
                   actionMenuItems.addItem(this.getActionsMenuItem({ 
                       /* Bind the menu item caption to the localizable schema string. */
                       "Caption": { 
                           bindTo: "Resources.Strings.CallProcessParametersCaption" 
                       }, 
                       /* Bind the action handler method. */
                       "Tag": "callCustomProcess", 
                       /* Bind the property of the menu item visibility to the value returned by the isAccountPrimaryContactSet() method. */ 
                       "Visible": { 
                           bindTo: "isAccountPrimaryContactSet" 
                       } 
                   })); 
                   return actionMenuItems; 
               }, 
               /* The action handler method. Run the business process and display the values of the resulting parameters in the dialog. */
               callCustomProcess: function() { 
                   /* Receive the ID of the account’s primary contact. */ 
                   var contactParameter = this.get("PrimaryContact"); 
                   /* Create an object of the Terrasoft.RunProcessRequest class. */
                   const runProcessRequest = Ext.create("Terrasoft.RunProcessRequest", { 
                       /* The process schema code. */
                       "schemaName": "UsrParametersProcess", 
                       /* The ID of the process diagram. */
                       "schemaUId": "9ff60fa7-314e-4b9e-b9fc-57f91b8b2e21", 
                       /* Incoming process parameters. */
                       "parameterValues": { 
                           "ProcessSchemaContactParameter": contactParameter.value 
                       }, 
                       /* Outgoing process parameters. */
                       "resultParameterNames": [ 
                           "ProcessContactAge", 
                           "ProcessFullJob" 
                       ] 
                   }); 
                   /* Run the custom business process. */
                   runProcessRequest.execute(function(response) { 
                       /* If the process is executed successfully, display the values of the resulting parameters in the dialog. */ 
                       if (response.isSuccess()) { 
                           var job = response.resultParameterValues["ProcessFullJob"]; 
                           var age = response.resultParameterValues["ProcessContactAge"]; 
                           Terrasoft.showInformation("Full job title: " + job + " Age: " + age); 
                       } 
                   }, this); 
               } 
           } 
       }; 
   });        
   

6. Click Save on the Module Designer’s toolbar.

Creatio does not display the custom account page action in combined mode.

3. Create a replacing view model schema of the section page 

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

2. Click Add → Replacing view model on the section list toolbar.

   

3. Fill out the schema properties.

   • Set Code to "AccountSectionV2."
   • Set Title to "Accounts section."
   • Set Parent object to "AccountSectionV2."
   
4. Add a localizable string that contains the menu item caption. To do this, take step 4 of the procedure to create a replacing view model schema of the account page.

5. Implement the menu item behavior. To do this, implement the isAccountPrimaryContactSet() method in the methods property. The method checks whether the primary contact of the account is filled out and defines the visibility of the menu item.

   View the source code of the replacing view model schema of the section page below.

   AccountSectionV2

   define("AccountSectionV2", [], function() { 
       return { 
           /* The name of the section page schema. */ 
           entitySchemaName: "Account", 
           /* The methods of the section page’s view model. */
           methods: { 
               /* Check whether the [Primary contact] field of the account is filled out. */
               isAccountPrimaryContactSet: function() { 
                   /* Define the active record. */
                   var activeRowId = this.get("ActiveRow"); 
                   if (!activeRowId) { 
                       return false; 
                   } 
                   /* Retrieve the data collection of the section list’s list view. Retrieve the model of the account by the specified primary column value. */
                   var selectedAccount = this.get("GridData").get(activeRowId); 
                   if (selectedAccount) { 
                       /* Receive the [Primary contact] model property. */
                       var selectedPrimaryContact = selectedAccount.get("PrimaryContact"); 
                       /* Return true if the primary contact is filled out, return false otherwise. */ 
                       return selectedPrimaryContact ? true : false; 
                   } 
                   return false; 
               } 
           } 
       }; 
   });    
   

6. Click Save on the Module Designer’s toolbar.

Outcome of the example 

To view the outcome of the example: 

1. Refresh the Accounts section page.
2. Open an account page, for example, Vertigo Systems.

As a result, Creatio will add the Receive parameters action to the account page.

Click the Receive parameters action to run the Result parameters business process. The primary contact of the account will be passed to the business process as a parameter. The job title and age of the account’s primary contact will be displayed as the resulting parameters of the business process.

The action will be active if the account has a primary contact, i. e., the Primary contact field of the account page is filled out. For example, the action is inactive for the Wilson & Young account.

The Receive parameters custom action will be displayed on the Accounts section page and active for the selected account that has a primary contact.