Version: 8.3

Implement a custom web service that uses anonymous authentication and non-standard text encoding

Level: intermediate

note

This functionality is available for Creatio deployed on .NET Framework only.

To implement the example:

Implement a custom web service. Read more >>>
Register the web service. Read more >>>
Register a non-standard text encoding. 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 UsrEncodingService custom web service that uses anonymous authentication and receives an arbitrary text in the ISO-8859-1 encoding. Creatio must return identical text that uses the same encoding.

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 sdkEncodingService package.
Change the current package. Instructions: Change the current package.

For this example, change the current package to sdkEncodingService 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
UsrEncodingService
Title
Service that has custom encoding
Apply the changes.
Create a service class.
1. Add the Terrasoft.Configuration namespace in the Schema Designer.
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. Add the SystemUserConnection system connection to enable anonymous access to the custom web service.
Implement a class method.

For this example, add the public string ReceiveEncodedText(string EncodedText) method that implements the endpoint of the custom web service. Depending on the EncodedText parameter value specified in the ISO-8859-1 encoding, the response body returns the same parameter value in the same encoding.

Property	Property value
Code	UsrEncodingService
Title	Service that has custom encoding

Specify the user on whose behalf to process the current 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.

/* 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 UsrEncodingService custom web service below.

UsrEncodingService
namespace Terrasoft.Configuration.UsrEncodingServiceNamespace {
    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 UsrEncodingService: BaseService {
        
        private SystemUserConnection _systemUserConnection;
        private SystemUserConnection SystemUserConnection {
            get {
                return _systemUserConnection ?? (_systemUserConnection = (SystemUserConnection) AppConnection.SystemUserConnection);
            }
        }

        /* The method that returns the value of the passed parameter in the specified encoding. */
        [OperationContract]
        [WebInvoke(Method = "POST", RequestFormat = WebMessageFormat.Xml, BodyStyle = WebMessageBodyStyle.Wrapped, ResponseFormat = WebMessageFormat.Xml)]
        public string ReceiveEncodedText(string EncodedText) {

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

            /* Return the result. */
            return EncodedText;
        }
    }
}

Publish the schema.

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

2. Register the web service

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

3. Register a non-standard text encoding

Register a non-standard text encoding for http.
1. Open the ..\Terrasoft.WebApp\ServiceModel\http\bindings.config file.
2. Go to the <bindings> section.
3. Add <customBinding> section to the root <bindings> section.
4. Add attributes to the <customBinding> file section.
  
  For this example, add and set the following attributes:
  - Set the name attribute of the <binding> element to "ISO88591Encoding."
  - Set the encoding attribute of the <customTextMessageEncoding> element to "ISO-8859-1."
  - Set the manualAddressing attribute of the <httpTransport> element to true.
  ..\Terrasoft.WebApp\ServiceModel\http\bindings.config file
```
<bindings>
    ...
    <customBinding>
        <binding name="ISO88591Encoding">
            <customTextMessageEncoding encoding="ISO-8859-1" />
            <httpTransport manualAddressing="true"/>
        </binding>
    </customBinding>
    ...
</bindings>
```
5. Save the changes.
Register a non-standard text encoding for https. To do this, repeat steps 2–5 of the previous step in the ..\Terrasoft.WebApp\ServiceModel\https\bindings.config file.

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

Enable HTTP support.
1. Open the ..\Terrasoft.WebApp\ServiceModel\http\services.config file.
2. Go to the <services> section.
3. Add the following record to the root <services> section.
  ..\Terrasoft.WebApp\ServiceModel\http\services.config file
```
<services>
    ...
   <service name="Terrasoft.Configuration.UsrEncodingServiceNamespace.UsrEncodingService">
        <endpoint name="UsrEncodingServiceEndPoint"
            address=""
            binding="customBinding"
            bindingConfiguration="ISO88591Encoding"
            behaviorConfiguration="RestServiceBehavior"
            bindingNamespace="http://Terrasoft.WebApp.ServiceModel"
            contract="Terrasoft.Configuration.UsrEncodingServiceNamespace.UsrEncodingService" />
    </service>
    ...
</services>
```
  The binding attribute includes the "customBinding" value that must match the name of the <customBinding> file section that registers the character encoding.
  
  The bindingConfiguration attribute includes the name of the registered character encoding. Must match the value of the <binding> element's name attribute specified on the previous step. For this example, bindingConfiguration="ISO88591Encoding".
4. 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.

5. 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/UsrEncodingService.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/UsrEncodingService.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/UsrEncodingService.svc"  />
      ...
    </appSettings>
  ...
</configuration>
```
Save the changes.
Apply the changes. To do this, restart Creatio in IIS.

View the result

Use Postman to view the outcome of the example. Learn more about working in Postman: official vendor documentation. Learn more about using Postman to query Creatio: Test requests using Postman. Learn more about using Postman to call a web service: Call a custom web service from Postman.

To view the outcome of the example:

Create a request.
1. Add a request string. To do this, access the /ServiceModel/UsrEncodingService.svc/ReceiveEncodedText endpoint.
  Request string
```
POST CreatioURL/0/ServiceModel/UsrEncodingService.svc/ReceiveEncodedText
```
2. Add a request body.
  1. Open the Body tab.
  2. Select raw=XML in the Body option parameter.
  3. Pass the request body. The EncodedText parameter includes the characters in the ISO-8859-1 character encoding. Learn more: ISO/IEC 8859-1 (Wikipedia).
  Request body
```
<?xml version="1.0" encoding = "iso-8859-1"?>
<ReceiveEncodedText xmlns="http://tempuri.org/">
    <EncodedText>ÀÁÂÃÄÅ</EncodedText>
</ReceiveEncodedText>
```
3. Save the changes.
Execute the request.

As a result, Postman will display:

200 OK status code.
The response body in XML format. The response body is displayed on the Body tab. The body includes the value of the EncodedText parameter in the ISO-8859-1 character encoding. View the result >>>

Source code

UsrEncodingService
namespace Terrasoft.Configuration.UsrEncodingServiceNamespace {
    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 UsrEncodingService: BaseService {
        
        private SystemUserConnection _systemUserConnection;
        private SystemUserConnection SystemUserConnection {
            get {
                return _systemUserConnection ?? (_systemUserConnection = (SystemUserConnection) AppConnection.SystemUserConnection);
            }
        }

        /* The method that returns the value of the passed parameter in the specified encoding. */
        [OperationContract]
        [WebInvoke(Method = "POST", RequestFormat = WebMessageFormat.Xml, BodyStyle = WebMessageBodyStyle.Wrapped, ResponseFormat = WebMessageFormat.Xml)]
        public string ReceiveEncodedText(string EncodedText) {

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

            /* Return the result. */
            return EncodedText;
        }
    }
}

Resources

Package with example implementation

Postman request that includes the outcome of the example

1. Implement a custom web service​

2. Register the web service​

3. Register a non-standard text encoding​

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

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

View the result​

Source code​

Resources​