Skip to main content
Version: 8.1

Implement a custom web service that uses cookie-based authentication

Level: intermediate
Example

Create a custom web service that uses cookie-based authentication. The service must execute a Creatio request to return the contact information by the specified name. Creatio must return the following data:

  • If the contact is found, return the contact ID.
  • If several contacts are found, return the ID of the first contact only.
  • If no contacts are found, return an empty string.

1. Create a Source code schema

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

  2. Click AddSource code on the section list toolbar.

  3. Go to the Schema Designer and fill out the schema properties:

    • Set Code to "UsrCustomConfigurationService."
    • Set Title to "CustomConfigurationService."

    Click Apply to apply the properties.

2. Create a service class

  1. Go to the Schema Designer and add the namespace nested into Terrasoft.Configuration. You can use an arbitrary name. For example, UsrCustomConfigurationServiceNamespace.
  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.

3. Implement the class method

Go to the Schema Designer and add the public string GetContactIdByName(string Name) class method that implements the endpoint of the custom web service. The method executes database queries using EntitySchemaQuery. Depending on the value of the Name parameter in the query string, the response body will contain:

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

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

UsrCustomConfigurationService
namespace Terrasoft.Configuration.UsrCustomConfigurationServiceNamespace {
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 UsrCustomConfigurationService: 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 this option:
result = entities[0].GetTypedColumnValue<string>(colId.Name); */
}
// Return the results.
return result;
}
}

}

Click Save then Publish on the Designer's toolbar.

Outcome of the example

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

Access the GetContactIdByName endpoint of the web service from the browser and pass the contact name in the Name parameter.

Request string that contains the name of the existing contact
http://mycreatio.com/0/rest/UsrCustomConfigurationService/GetContactIdByName?Name=Andrew%20Baker

If you access the web service without preauthorization, an error will occur.

Log in to Creatio and execute the request once more. If Creatio finds the contact from the Name parameter in the database, the GetContactIdByNameResult property will return the contact ID value.

If Creatio finds no contacts from the Name parameter in the database, the GetContactIdByNameResult property will return an empty string.

Request string that contains the name of a non-existing contact
http://mycreatio.com/0/rest/UsrCustomConfigurationService/GetContactIdByName?Name=Andrew%20Bake

Resources

Package with case implementation