Version: 8.2

Implement a custom web service that uses anonymous authentication

Level: intermediate

Example

Create a custom web service that uses anonymous 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

Go to the Configuration section and select a user-made package to add the schema.
Click Add → Source code on the section list toolbar.
Go to the Schema Designer and fill out the schema properties:
- Set Code to "UsrAnonymousConfigurationService."
- Set Title to "AnonymousConfigurationService."
Click Apply to apply the properties.

2. Create a service class

Go to the Schema Designer and add the namespace nested into Terrasoft.Configuration. You can use an arbitrary name. For example, UsrAnonymousConfigurationServiceNamespace.
Add the namespaces the data types of which to utilize in the class using the using directive.
Add the class name that matches the schema name (the Code property).
Specify the Terrasoft.Nui.ServiceModel.WebService.BaseService class as a parent class.
Add the [ServiceContract] and [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)] attributes to the class.
Add the SystemUserConnection system connection to enable anonymous access to the custom web service.

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 Creatio several contacts are found.
- The empty string if Creatio no contacts are found.

Specify the user on whose behalf to process the HTTP request. To do this, call the SessionHelper.SpecifyWebOperationIdentity method of the Terrasoft.Web.Common namespace after retrieving SystemUserConnection. This method enables business processes to manage the database entity (Entity) from the custom web service that uses anonymous authentication.

Terrasoft.Web.Common.SessionHelper.SpecifyWebOperationIdentity(
    HttpContextAccessor.GetInstance(),
    SystemUserConnection.CurrentUser
);

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

UsrAnonymousConfigurationService
/* The custom namespace. */
namespace Terrasoft.Configuration.UsrAnonymousConfigurationServiceNamespace {
    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 UsrAnonymousConfigurationService: BaseService {
        /* The link to the UserConnection instance required to access the database. */
        private SystemUserConnection _systemUserConnection;
        private SystemUserConnection SystemUserConnection {
            get {
                return _systemUserConnection ?? (_systemUserConnection = (SystemUserConnection) AppConnection.SystemUserConnection);
            }
        }

        /* 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) {
            /* Specify the user on whose behalf to process the HTTP request. */
            SessionHelper.SpecifyWebOperationIdentity(HttpContextAccessor.GetInstance(), SystemUserConnection.CurrentUser);
            /* 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(SystemUserConnection);
            /* 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;
        }
    }

}

Publish the schema.

4. Register the custom web service that uses anonymous authentication

Go to the ..\Terrasoft.WebApp\ServiceModel directory.

Create a UsrAnonymousConfigurationService.svc file and add the following record to it.

<% @ServiceHost
    Service = "Terrasoft.Configuration.UsrAnonymousConfigurationServiceNamespace.UsrAnonymousConfigurationService"
    Debug = "true"
    Language = "C#"
%>

The Service attribute contains the full name of the web service class and specifies the namespace.

5. Enable both HTTP and HTTPS support for the custom web service that uses anonymous authentication

Open the ..\Terrasoft.WebApp\ServiceModel\http\services.config file and add the following record to it.

..\Terrasoft.WebApp\ServiceModel\http\services.config file
<services>
    ...
    <service name="Terrasoft.Configuration.UsrAnonymousConfigurationServiceNamespace.UsrAnonymousConfigurationService">
        <endpoint name="[Service name]EndPoint"
            address=""
            binding="webHttpBinding"
            behaviorConfiguration="RestServiceBehavior"
            bindingNamespace="http://Terrasoft.WebApp.ServiceModel"
            contract="Terrasoft.Configuration.UsrAnonymousConfigurationServiceNamespace.UsrAnonymousConfigurationService" />
    </service>
</services>

Add an identical record to the ..\Terrasoft.WebApp\ServiceModel\https\services.config file.

6. Enable all users to access the custom web service that uses anonymous authentication

Open the ..\Terrasoft.WebApp\Web.config file.

Add the <location> element that defines the relative path and access permissions to the web service.

..\Terrasoft.WebApp\Web.config file
<configuration>
    ...
    <location path="ServiceModel/UsrAnonymousConfigurationService.svc">
        <system.web>
            <authorization>
                <allow users="*" />
            </authorization>
        </system.web>
    </location>
    ...
</configuration>

Add the relative web service path to the value attribute of the AllowedLocations key in the <appSettings> element.

..\Terrasoft.WebApp\Web.config file
<configuration>
    ...
    <appSettings>
        ...
        <add key="AllowedLocations" value="[Previous values];ServiceModel/UsrAnonymousConfigurationService.svc" />
        ...
    </appSettings>
    ...
</configuration>

7. Restart Creatio in IIS

Restart Creatio in IIS to apply the changes.

Outcome of the example

As a result, Creatio will add the custom UsrAnonymousConfigurationService REST web service that has the GetContactIdByName endpoint. You can access the web service from the browser, with or without pre-authentication.

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/ServiceModel/UsrAnonymousConfigurationService.svc/GetContactIdByName?Name=Andrew%20Baker

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/ServiceModel/UsrAnonymousConfigurationService.svc/GetContactIdByName?Name=Andrew%20Bake

Resources

Package with example implementation

1. Create a Source code schema​

2. Create a service class​

3. Implement the class method​

4. Register the custom web service that uses anonymous authentication​

5. Enable both HTTP and HTTPS support for the custom web service that uses anonymous authentication​

6. Enable all users to access the custom web service that uses anonymous authentication​

7. Restart Creatio in IIS​

Outcome of the example​

Resources​