Implement a custom web service that uses cookie-based authentication

Level: intermediate

To implement the example, set up a custom web service. Read more >>>

Example

Implement the UsrReceiveContactDataService custom web service that uses cookie-based authentication and receives the contact information by the specified name. Creatio must return the following data:

• The contact ID if the contact is found.

  

• The ID of the first contact only if multiple contacts are found.

  

• The empty string if no contacts are found.

  

Implement a custom web service

1. Open the Customer 360 app in the No-Code Designer.

2. Click in the top right → Application management → Application Hub → Customer 360 app → Advanced settings tab.

3. Create a user-made package to add the schema. To do this, click → Create new package → fill out the package properties → Save.

   For this example, create the sdkReceiveContactData user-made package.

4. Create the source code schema. To do this, click Add → Source code.

5. Fill out the schema properties.

   For this example, use the following schema properties.

   Property	Property value
   Code	UsrReceiveContactDataService
   Title	ReceiveContactDataService

6. Apply the changes.

7. Create a service class.

   1. Add the arbitrary namespace nested into Terrasoft.Configuration in the Schema Designer. For example, UsrReceiveContactDataServiceNamespace.
   2. Add the namespaces the data types of which to utilize in the class using the using directive.
   3. Add a class name that matches the schema name (the Code property).
   4. Specify the Terrasoft.Nui.ServiceModel.WebService.BaseService class as a parent class.
   5. Add the [ServiceContract] and [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)] attributes to the class.

8. Implement a class method.

   For this example, add the public string GetContactIdByName(string Name) method that implements the endpoint of the custom web service. The method executes database queries using the EntitySchemaQuery class. Depending on the Name parameter value specified in the query string, the response body returns the following:

   • The contact ID (string type) if the contact is found.
   • The ID of the first contact (string type) if several contacts are found.
   • The empty string if no contacts are found.

   View the source code of the UsrReceiveContactDataService custom web service below.

   UsrReceiveContactDataService

       namespace Terrasoft.Configuration.UsrReceiveContactDataServiceNamespace {
       using System;
       using System.ServiceModel;
       using System.ServiceModel.Web;
       using System.ServiceModel.Activation;
       using Terrasoft.Core;
       using Terrasoft.Web.Common;
       using Terrasoft.Core.Entities;
   
       [ServiceContract]
       [AspNetCompatibilityRequirements(
           RequirementsMode = AspNetCompatibilityRequirementsMode.Required)]
       public class UsrReceiveContactDataService: BaseService {
   
           /* The method that returns the contact ID by the contact name. */
           [OperationContract]
           [WebInvoke(
               Method = "GET",
               RequestFormat = WebMessageFormat.Json,
               BodyStyle = WebMessageBodyStyle.Wrapped,
               ResponseFormat = WebMessageFormat.Json)]
           public string GetContactIdByName(string Name) {
               /* The default result. */
               var result = "";
               /* The EntitySchemaQuery instance that accesses the "Contact"
               database table. */
               var esq = new EntitySchemaQuery(
                   UserConnection.EntitySchemaManager,
                   "Contact");
               /* Add columns to the query. */
               var colId = esq.AddColumn("Id");
               var colName = esq.AddColumn("Name");
               /* Filter the query data. */
               var esqFilter = esq.CreateFilterWithParameters(
                   FilterComparisonType.Equal,
                   "Name",
                   Name);
               esq.Filters.Add(esqFilter);
               /* Retrieve the query results. */
               var entities = esq.GetEntityCollection(UserConnection);
               /* If the service receives data. */
               if (entities.Count > 0) {
                   /* Return the "Id" column value of the first query result record. */
                   result = entities[0].GetColumnValue(colId.Name).ToString();
                   /* You can also use the following option.
                   result = entities[0].GetTypedColumnValue<string>(colId.Name); */
               }
               /* Return the results. */
               return result;
           }
       }
   }

9. Publish the schema.

As a result, Creatio will add the custom UsrReceiveContactDataService REST web service that has the GetContactIdByName endpoint.

View the result

To view the outcome of the example without preauthorization:

1. Access the GetContactIdByName endpoint of the UsrReceiveContactDataService web service from the browser address bar.

2. Pass the contact name in the Name parameter. For example, "Mary King."

   Request string

   [CreatioURL]/0/rest/UsrReceiveContactDataService/GetContactIdByName?Name=Mary%20King

As a result, the Creatio instance will return the 401 Unauthorized error.

To view the outcome of the example that receives the name of a single contact:

1. Log in to Creatio.

2. Access the GetContactIdByName endpoint of the UsrReceiveContactDataService web service from the browser address bar.

3. Pass the contact name in the Name parameter. For example, "Mary King."

   Request string

   CreatioURL/0/rest/UsrReceiveContactDataService/GetContactIdByName?Name=Mary%20King

As a result, the Creatio instance will return:

• The contact ID if the contact is found. View the result >>>
• The empty string if no contact is found. View the result >>>

To view the outcome of the example that receives the names of multiple contacts:

1. Log in to Creatio.

2. Access the GetContactIdByName endpoint of the UsrReceiveContactDataService web service from the browser address bar.

3. Pass the contact names in the Name parameter. For example, "Mary King" and "Andrew Wayne."

   Request string

   CreatioURL/0/rest/UsrReceiveContactDataService/GetContactIdByName?Name=Mary%20King&Andrew%20Wayne

As a result, the Creatio instance will return:

• The ID of the first contact only if several contacts are found. View the result >>>
• The empty string if no contacts are found. View the result >>>

Source code

UsrReceiveContactDataService

namespace Terrasoft.Configuration.UsrReceiveContactDataServiceNamespace
{
    using System;
    using System.ServiceModel;
    using System.ServiceModel.Web;
    using System.ServiceModel.Activation;
    using Terrasoft.Core;
    using Terrasoft.Web.Common;
    using Terrasoft.Core.Entities;

    [ServiceContract]
    [AspNetCompatibilityRequirements(
        RequirementsMode = AspNetCompatibilityRequirementsMode.Required)]
    public class UsrReceiveContactDataService: BaseService
    {

        /* The method that returns the contact ID by the contact name. */
        [OperationContract]
        [WebInvoke(
            Method = "GET",
            RequestFormat = WebMessageFormat.Json,
            BodyStyle = WebMessageBodyStyle.Wrapped,
            ResponseFormat = WebMessageFormat.Json)]
        public string GetContactIdByName(string Name)
        {
            /* The default result. */
            var result = "";
            /* The "EntitySchemaQuery" instance that accesses the "Contact"
            database table. */
            var esq = new EntitySchemaQuery(
                SystemUserConnection.EntitySchemaManager,
                "Contact");
            /* Add columns to the query. */
            var colId = esq.AddColumn("Id");
            var colName = esq.AddColumn("Name");
            /* Filter the query data. */
            var esqFilter = esq.CreateFilterWithParameters(
                FilterComparisonType.Equal,
                "Name",
                Name);
            esq.Filters.Add(esqFilter);
            /* Retrieve the query results. */
            var entities = esq.GetEntityCollection(UserConnection);
            /* If the service receives data. */
            if (entities.Count > 0)
            {
                /* Return the "Id" column value of the first query result
                record. */
                result = entities[0].GetColumnValue(colId.Name).ToString();
                /* You can also use the following option.
                result = entities[0].GetTypedColumnValue<string>(colId.Name); */
            }
            /* Return the results. */
            return result;
        }
    }
}

---

Resources

Package with example implementation