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

Medium
PDF

The example is relevant to Creatio version 8.0.2 and later.

Example. Create a custom web service that uses anonymous authentication and gets an arbitrary text in the ISO-8859-1 encoding. The web service must return identical text that uses the same encoding.

1. Create a Source code schema 

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

  2. Click Add → Source code on the section list toolbar.

  3. Fill out the schema properties in the Source Code Designer:

    • Set Code to "UsrEncodingService."
    • Set Title to "Service with custom encoding."

    Click Apply to apply the properties.

2. Create a web service class 

  1. Go to the Schema Designer and add the namespace nested into Terrasoft.Configuration. For example, UsrEncodingServiceNamespace.
  2. Add the using directive to import the namespaces whose data types are utilized in the class.
  3. Add a class name to match 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.

3. Implement a method of the web service class 

  1. Implement the endpoint of the custom web service. To do this, add the public string Test(string Name) method to the class in the Source Code Designer. Depending on the Name parameter value specified in the ISO-8859-1 encoding and sent in the request string, the response body contains the same parameter value in the same encoding.

  2. 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.

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

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

UsrEncodingService
/* Custom namespace. */
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
    {
        /* Reference to the UserConnection instance required to call the database. */
        private SystemUserConnection _systemUserConnection;
        private SystemUserConnection SystemUserConnection {
            get {
                return _systemUserConnection ?? (_systemUserConnection = (SystemUserConnection)AppConnection.SystemUserConnection);
            }
        }
        
        /* 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 Test(string Name){
            /* The user on whose behalf to process the HTTP request. */
            SessionHelper.SpecifyWebOperationIdentity(HttpContextAccessor.GetInstance(), SystemUserConnection.CurrentUser);
            /* Return the result. */
            return Name;
        }
    }
}

Click Publish on the Source Code Designer’s toolbar to apply the changes on the database level.

4 Register the web service 

  1. Create a UsrEncodingService.svc file in the ..\Terrasoft.WebApp\ServiceModel directory.

  2. Add the following record to the UsrEncodingService.svc file.

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

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

  3. Save the file.

5. Register a non-standard text encoding 

  1. Add <customBinding> section to the ..\Terrasoft.WebApp\ServiceModel\http\bindings.config file.

  2. Add the following attributes to the <customBinding> file section:

    • 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>
  3. Save the file.
  4. Add an identical record to the ..\Terrasoft.WebApp\ServiceModel\https\bindings.config file.

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

  1. Add the following record to the ..\Terrasoft.WebApp\ServiceModel\http\services.config file.

    ..\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 contains the "<customBinding>" value that must match the name of the <customBinding> file section that registers the character encoding.

    The bindingConfiguration attribute contains the name of the registered character encoding. Must match the value of the <binding> element’s name attribute specified on the previous step.

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

7. Enable access to the web service for all users 

  1. Add the <location> element that defines the relative path and access permissions to the web service to the ..\Terrasoft.WebApp\Web.config file.

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

  2. Add the relative web service path to the value attribute of the <appSettings> element's AllowedLocations key in the ..\Terrasoft.WebApp\Web.config file.

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

8. Restart Creatio in IIS 

Restart Creatio in IIS to apply the changes.

Outcome of the example 

Use Postman request testing tool to view the outcome of the example. Learn more about working in Postman in the official Postman documentation. Learn more about using Postman to query Creatio in a separate article: Working with requests in Postman. Learn more about using Postman to call a web service in a separate article: Call a custom web service from Postman.

To view the outcome of the example, execute a request to the UsrEncodingService web service.

Configure the request in Postman as follows:

  • Specify the POST request method.

  • Specify the Test method in the request string to the UsrEncodingService custom web service.

    Request string to the UsrEncodingService custom web service
    http://mycreatio.com/0/ServiceModel/UsrEncodingService.svc/Test

  • Configure the request data format on the Body tab.

    1. Set the "raw" option.
    2. Select the "XML" type.
    3. Fill out the body of the POST request. Pass the characters in the ISO-8859-1 character encoding in the request body. Learn more about the characters the ISO-8859-1 character encoding uses in Wikipedia.

As a result, you will receive a response to the POST request. The response format is XML, the code is 200 OK. Postman will display the response body on the Body tab. The body will contain the value of the Name parameter in the ISO-8859-1 character encoding.

Resources
Package with example implementation
Collection of Postman queries that contain the outcome of the example