Version: 8.3

Implement a custom web service that uses anonymous authentication

Level: intermediate

To implement the example:

Implement a custom web service. Read more >>>
Register the web service. Read more >>>
Enable both HTTP and HTTPS support for the web service. Read more >>>
Enable access to the web service for all users. Read more >>>

Example

Implement the UsrAnonymousConfigurationService custom web service that uses anonymous 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.

1. Implement a custom web service

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

For this example, create the sdkAnonymousService package.
Change the current package. Instructions: Change the current package.

For this example, change the current package to sdkAnonymousService user-made package.
Create the source code schema. To do this, click Add → Source code.
Fill out the schema properties.

For this example, use the following schema properties.

Property
Property value
Code
UsrAnonymousConfigurationService
Title
AnonymousConfigurationService
Apply the changes.
Create a service class.
1. Add the arbitrary namespace nested into Terrasoft.Configuration in the Schema Designer. For example, UsrAnonymousConfigurationServiceNamespace.
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.
6. Use SystemUserConnection to access the database in the custom anonymous web service. Out of the box, database operations in an anonymous web service are executed on behalf of a system-level user. If your integration requires a specific user context, implement a custom web service that uses cookie-based authentication instead. Learn more: Implement a custom web service that uses cookie-based authentication.
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 found contact (string type) if several contacts are found.
- The empty string if no contacts are found.

Property	Property value
Code	UsrAnonymousConfigurationService
Title	AnonymousConfigurationService

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 record (Entity) from the custom web service that uses anonymous authentication.

/* The user on whose behalf to process the HTTP request. */
Terrasoft.Web.Common.SessionHelper.SpecifyWebOperationIdentity(
    HttpContextAccessor.GetInstance(),
    SystemUserConnection.CurrentUser
);

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

UsrAnonymousConfigurationService
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)
        {
            /* 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 result. */
            return result;
        }
    }
}

Publish the schema.

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

2. Register the web service

Go to the "..\Terrasoft.WebApp\ServiceModel" directory.
Create and open the "UsrAnonymousConfigurationService.svc" file.
Register the web service. To do this, add the following record.
"UsrAnonymousConfigurationService.svc" file
```
<%@ ServiceHost
    Service="Terrasoft.Configuration.UsrAnonymousConfigurationServiceNamespace.UsrAnonymousConfigurationService"
    Debug="true"
    Language="C#"
%>
```
The Service attribute includes the full name of the web service class and specifies the namespace.
Save the changes.

3. Enable both HTTP and HTTPS support for the web service

Enable HTTP support.

Open the "..\Terrasoft.WebApp\ServiceModel\http\services.config" file.
Go to the <services> section.

Add the following record to the root <services> section.

"..\Terrasoft.WebApp\ServiceModel\http\services.config" file
<services>
    ...
    <service
        name="Terrasoft.Configuration.UsrAnonymousConfigurationServiceNamespace.UsrAnonymousConfigurationService">

        <endpoint
            name="UsrAnonymousConfigurationServiceEndPoint"
            address=""
            binding="webHttpBinding"
            behaviorConfiguration="RestServiceBehavior"
            bindingNamespace="http://Terrasoft.WebApp.ServiceModel"
            contract="Terrasoft.Configuration.UsrAnonymousConfigurationServiceNamespace.UsrAnonymousConfigurationService" />
    </service>
</services>

Save the changes.

Enable HTTPS support. To do this, repeat steps 1–4 of the previous step in the "..\Terrasoft.WebApp\ServiceModel\https\services.config" file.

4. Enable access to the web service for all users

Open the "..\Terrasoft.WebApp\Web.config" file.
Go to the <configuration> section.

Add the <location> element to the root <configuration> section after the <appSettings> element. The <location> element 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>

Check if the <appSettings> element includes the key attribute whose value is set to "AllowedLocations". If the <add key="AllowedLocations" value="" /> element is omitted, add it to the root <appSettings> section.
Add the relative web service path (ServiceModel/UsrAnonymousConfigurationService.svc) to the value attribute.

We do not recommend adding a separate value for an existing key attribute, since values are only read from the last key attribute whose name matches.
"..\Terrasoft.WebApp\Web.config" file
```
<configuration>
  ...
  <appSettings>
    ...
    <add
      key="AllowedLocations"
      value="[Previous values];ServiceModel/UsrAnonymousConfigurationService.svc" />
    ...
  </appSettings>
  ...
</configuration>
```
Save the changes.
Apply the changes. To do this, restart Creatio in IIS.

View the result

To view the outcome of the example that receives the contact ID:

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

Pass the contact name in the Name parameter. For example, "Andrew Baker."

Request string
[CreatioURL]/0/ServiceModel/UsrAnonymousConfigurationService.svc/GetContactIdByName?Name=Andrew%20Baker

As a result, the Creatio instance will return:

The contact ID if the contact is found. View the result >>>
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

UsrAnonymousConfigurationService
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)
        {
            /* 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 result. */
            return result;
        }
    }
}

Resources

Package with example implementation

1. Implement a custom web service​

2. Register the web service​

3. Enable both HTTP and HTTPS support for the web service​

4. Enable access to the web service for all users​

View the result​

Source code​

Resources​