Run the business process from the browser address bar using the business process service

Level: advanced

To implement the example:

1. Implement a business process that adds a contact. Read more >>>
2. Implement a business process that retrieves the list of contacts. Read more >>>

Example

Run the following custom business processes from the browser address bar using the ProcessEngineService.svc business process service:

• "Add external contact" that adds a contact to the Contacts section. The Contact and Mobile phone field of the added contact must be populated.

  

• "Retrieve the list of contacts" that retrieves the list of contacts from the Contacts section.

  

1. Implement a business process that adds a contact

1. Create a business process

1. Open the Configuration section. Instructions: Open the Configuration section.

2. Create a package. Instructions: Create a user-made package using Configuration section.

   For this example, create the sdkWorkWithBusinessProcessService package.

3. Change the current package. Instructions: Change the current package.

   For this example, change the current package to sdkWorkWithBusinessProcessService user-made package.

4. Create the business process schema. To do this, click Add → Business process.

5. Open the Settings tab.

6. Fill out the schema properties.

   For this example, use the schema properties as follows.

   Property	Property value
   Title	Add external contact
   Code	UsrAddExternalContactProcess

7. Save the changes.

As a result:

• The "Add external contact" business process will be created.
• Creatio will add the "Add external contact" business process to the Process library section.

2. Set up the business process parameters

1. Open the properties of the business process schema. To do this, click an arbitrary place in the working area of the Process Designer.

2. Open the Parameters tab.

3. Add the business process parameters.

   For this example, add the following parameters:

   • parameter that contains the contact name
   • parameter that contains the mobile phone of the contact

   To do this:

   1. Click Add parameter and select a parameter of the needed type.

   2. Fill out the parameter properties.

      Element	Element type	Property	Property value
      Parameter that contains the contact name	Text	Title	Contact name
      		Code	ContactName
      		Data type	Text (50 characters)
      Parameter that contains the mobile phone of the contact	Text	Title	Mobile phone
      		Code	MobilePhone
      		Data type	Text (50 characters)

As a result, the Parameters tab of the "Add external contact" business process will be as follows.

3. Implement adding a contact

1. Add a Script task element. To do this, click → place the Script task element between the Simple page element and Terminate page element in the working area of the Process Designer.

2. Fill out the element properties.

   Property	Property value
   Title	Add contact

3. Implement the logic of working with process parameters. To do this, go to the element setup area and add the source code.

   Add contact script task

   // IMPORTANT: When implementing
   // long-running operations,
   // it is crucial to enable timely and
   // responsive cancellation. To achieve
   // this, ensure that your code
   // is designed to respond appropriately
   // to cancellation requests using
   // the context.CancellationToken
   // mechanism. For more detailed
   // information and examples,
   // please, refer to our documentation.
   
   /* Create an instance of the "Contact" object. */
   var schema = UserConnection.EntitySchemaManager.GetInstanceByName("Contact");
   
   /* Create an instance of new object. */
   var entity = schema.CreateEntity(UserConnection);
   
   /* Set object columns to default values. */
   entity.SetDefColumnValues();
   
   /* Contact name. */
   string contactName = Get<string>("ContactName");
   
   /* Mobile phone of the contact. */
   string contactPhone = Get<string>("MobilePhone");
   
   /* Set "Name" column to process parameter value. */
   entity.SetColumnValue("Name", contactName);
   
   /* Set "MobilePhone" column to process parameter value. */
   entity.SetColumnValue("MobilePhone", contactPhone);
   
   /* Save added contact. */
   entity.Save();
   
   return true;

4. Save the changes.

5. Publish the changes.

As a result, the diagram of the "Add external contact" business process will be as follows.

2. Implement a business process that retrieves the list of contacts

1. Create a business process

1. Select a user-made package to add the schema.

   For this example, select the sdkWorkWithBusinessProcessService user-made package.

2. Create the business process schema. To do this, click Add → Business process.

3. Open the Settings tab.

4. Fill out the schema properties.

   For this example, use the schema properties as follows.

   Property	Property value
   Title	Retrieve the list of contacts
   Code	UsrRetrieveContactListProcess

5. Save the changes.

As a result:

• The "Retrieve the list of contacts" business process will be created.
• Creatio will add the "Retrieve the list of contacts" business process to the Process library section.

2. Set up the business process parameters

1. Open the properties of the business process schema. To do this, click an arbitrary place in the working area of the Process Designer.

2. Open the Parameters tab.

3. Add the business process parameters.

   For this example, add the parameter that contains the list of contacts. To do this:

   1. Click Add parameter and select a parameter of the needed type.

   2. Fill out the parameter properties.

      Element	Element type	Property	Property value
      Parameter that contains the list of contacts	Text	Title	List of contacts
      		Code	ContactList
      		Data type	Unlimited length text

As a result, the Parameters tab of the "Retrieve the list of contacts" business process will be as follows.

3. Implement retrieving the list of contacts

1. Add a Script task element. To do this, click → place the Script task element between the Simple page element and Terminate page element in the working area of the Process Designer.

2. Fill out the element properties.

   Property	Property value
   Title	Retrieve contacts

3. Implement the logic of working with process parameters. To do this, go to the element setup area and add the source code.

   Retrieve contacts script task

   // IMPORTANT: When implementing
   // long-running operations,
   // it is crucial to enable timely and
   // responsive cancellation. To achieve
   // this, ensure that your code
   // is designed to respond appropriately
   // to cancellation requests using
   // the context.CancellationToken
   // mechanism. For more detailed
   // information and examples,
   // please, refer to our documentation.
   
   /* Create an "EntitySchemaQuery" instance. */
   EntitySchemaQuery query = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "Contact");
   
   /* Flag the "Id" primary column as required to select. */
   query.PrimaryQueryColumn.IsAlwaysSelect = true;
   
   /* Add columns to the query. */
   query.AddColumn("Name");
   query.AddColumn("MobilePhone");
   
   /* Retrieve an entity collection. */
   var entities = query.GetEntityCollection(UserConnection);
   
   /* Create the list of contacts 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"),
           MobilePhone = item.GetTypedColumnValue<string>("MobilePhone")
       };
       contacts.Add(contact);
   }
   
   /* Save the contact collection that is serialized in JSON to the "ContactList" parameter. */
   string contactList = JsonConvert.SerializeObject(contacts);
   Set<string>("ContactList", contactList);
   
   return true;

4. Set up the business process methods

1. Open the properties of the business process. To do this, click an arbitrary place in the working area of the Process Designer.

2. Open the Methods tab.

3. Add the business process methods.

   1. Click and fill out the method properties.

      Property	Property value
      Namespace	Newtonsoft.Json

   2. Click Save.

4. Save the changes.

5. Publish the changes.

As a result:

• The Methods tab of the "Retrieve the list of contacts" business process will be as follows.

  

• The diagram of the "Retrieve the list of contacts" business process will be as follows.

  

View the result

To view the outcome of the example that adds a contact:

1. Access the UsrAddExternalContactProcess endpoint of the ProcessEngineService.svc service from the browser address bar.

2. Pass the contact name in the ContactName parameter. For example, "James Bennett."

3. Pass the mobile phone of the contact in the MobilePhone parameter. For example, "1 111 111 1111."

   Request string

   CreatioURL/0/ServiceModel/ProcessEngineService.svc/UsrAddExternalContactProcess/Execute?ContactName=James%20Bennett&MobilePhone=1%20111%20111%201111

4. Click Enter.

As a result:

• ProcessEngineService.svc service will run an "Add external contact" business process.

  

• The "Add external contact" business process will add the contact whose fields are populated using the specified values to the Contacts section. View the result >>>

To view the outcome of the example that retrieves the list of contacts:

1. Access the UsrRetrieveContactListProcess endpoint of the ProcessEngineService.svc service from the browser address bar.

2. Pass the ContactList parameter as a value of the ResultParameterName parameter.

   Request string

   CreatioURL/0/ServiceModel/ProcessEngineService.svc/UsrRetrieveContactListProcess/Execute?ResultParameterName=ContactList

3. Click Enter.

As a result:

• ProcessEngineService.svc service will run a "Retrieve the list of contacts" business process.

  

• The "Retrieve the list of contacts" business process will retrieve the list of contacts from the Contacts section. View the result >>>

Source code

Add contact

// IMPORTANT: When implementing
// long-running operations,
// it is crucial to enable timely and
// responsive cancellation. To achieve
// this, ensure that your code
// is designed to respond appropriately
// to cancellation requests using
// the context.CancellationToken
// mechanism. For more detailed
// information and examples,
// please, refer to our documentation.

/* Create an instance of the "Contact" object. */
var schema = UserConnection.EntitySchemaManager.GetInstanceByName("Contact");

/* Create an instance of new object. */
var entity = schema.CreateEntity(UserConnection);

/* Set object columns to default values. */
entity.SetDefColumnValues();

/* Contact name. */
string contactName = Get<string>("ContactName");

/* Mobile phone of the contact. */
string contactPhone = Get<string>("MobilePhone");

/* Set "Name" column to process parameter value. */
entity.SetColumnValue("Name", contactName);

/* Set "MobilePhone" column to process parameter value. */
entity.SetColumnValue("MobilePhone", contactPhone);

/* Save added contact. */
entity.Save();

return true;

Retrieve contacts

// IMPORTANT: When implementing
// long-running operations,
// it is crucial to enable timely and
// responsive cancellation. To achieve
// this, ensure that your code
// is designed to respond appropriately
// to cancellation requests using
// the context.CancellationToken
// mechanism. For more detailed
// information and examples,
// please, refer to our documentation.

/* Create an "EntitySchemaQuery" instance. */
EntitySchemaQuery query = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "Contact");

/* Flag the "Id" primary column as required to select. */
query.PrimaryQueryColumn.IsAlwaysSelect = true;

/* Add columns to the query. */
query.AddColumn("Name");
query.AddColumn("MobilePhone");

/* Retrieve an entity collection. */
var entities = query.GetEntityCollection(UserConnection);

/* Create the list of contacts 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"),
        MobilePhone = item.GetTypedColumnValue<string>("MobilePhone")
    };
    contacts.Add(contact);
}

/* Save the contact collection that is serialized in JSON to the "ContactList" parameter. */
string contactList = JsonConvert.SerializeObject(contacts);
Set<string>("ContactList", contactList);

return true;

---

Resources

Package with example implementation