Implement a custom web service

Level: intermediate

A web service is software reachable via a unique URL, which enables interaction between applications. The purpose of a web service is to integrate Creatio with external applications and systems.

Based on the custom business logic, Creatio generates and sends a request to the web service, receives the response, and extracts the needed data. Use this data to create or update records in the Creatio database as well as for custom business logic or automation.

Creatio supports the following web service types:

• External REST and SOAP services that you can integrate with no-code tools. Learn more: Web services (user documentation).

• System web services.

  • System web services that use cookie-based authentication.
  • System web services that use anonymous authentication.

• Custom web services.

  • Custom web services that use cookie-based authentication.
  • Custom web services that use anonymous authentication.

.NET Framework system web services use the WCF technology and are managed at the IIS level. .NET system web services use the ASP.NET Core Web API technology.

Learn more about the authentication types Creatio provides for web services: Authentication basics. We recommend using authentication based on the OAuth 2.0 open authorization protocol. Learn more about OAuth-based authentication: OAuth 2.0 (user documentation).

Creatio system web services that use cookie-based authentication include:

• odata that executes OData 4 external app requests to the Creatio database server. Learn more about using the OData 4 protocol in Creatio: OData 4 protocol.
• EntityDataService.svc that executes OData 3 external app requests to the Creatio database server. Learn more about using the OData 3 protocol in Creatio: OData 3 protocol.
• ProcessEngineService.svc that enables external apps to run Creatio business processes. Learn more about the web service: Service that runs business processes.

Creatio services that use anonymous authentication include AuthService.svc that executes Creatio authentication requests. Learn more about the web service: Authentication basics.

This article covers custom web services. Learn more about system web services: Integrations tools.

Implement a custom web service

A custom web service is a RESTful service that uses the WCF (for .NET Framework) or ASP .NET Core (for .NET) technology. Unlike system web services, custom web services let you solve unique integration problems.

The web service development procedure differs for each Creatio deployment framework. View the unique features of the custom web service development for the .NET Framework and .NET below.

You can use Postman to test querying a custom web service. Learn more about Postman: official vendor documentation (Postman). Learn more about querying Creatio using Postman: Test requests using Postman. Learn more about calling a web service via Postman: Call a custom web service from Postman.

Implement a custom web service that uses cookie-based authentication

1. Create the source code schema. Instructions: Implement the source code.

2. Create a service class.

   1. Add the Terrasoft.Configuration namespace or any of its nested namespaces in the Schema Designer. Name the namespace arbitrarily.
   2. Add the namespaces the data types of which to utilize in the class using the using directive.
   3. Use the Terrasoft.Web.Http.Abstractions namespace if you want the custom web service to support both .NET Framework and .NET. If you develop the web service using the System.Web namespace and have to run it on .NET, adapt the web service. Instructions: Migrate an existing custom web service to .NET Core or .NET 6.
   4. Add a class name that matches the schema name (the Code property).
   5. Specify the Terrasoft.Nui.ServiceModel.WebService.BaseService class as a parent class.
   6. Add the [ServiceContract] and [AspNetCompatibilityRequirement] class attributes that include the needed parameters. Learn more about the [ServiceContract] attribute: official vendor documentation (Microsoft). Learn more about the [AspNetCompatibilityRequirements] attribute: official vendor documentation (Microsoft).
   7. Add the SystemUserConnection system connection to enable anonymous access to the custom web service (optional).

3. Implement the class methods that correspond to the web service endpoints.

   Add the [OperationContract] and [WebInvoke] method attributes that include the needed parameters. Learn more about the [OperationContract] attribute: official vendor documentation (Microsoft). Learn more about the [WebInvoke] attribute: official vendor documentation (Microsoft).

4. Implement additional classes whose instances receive or return the web service methods (optional). Required to pass data of complex types. For example, object instances, collections, arrays, etc.

   Add the [DataContract] attribute to the class and the [DataMember] attribute to the class fields. Learn more about the [DataContract] attribute: official vendor documentation (Microsoft). Learn more about the [DataMember] attribute: official vendor documentation (Microsoft).

5. Publish the schema.

As a result, you will be able to call the custom web service that uses cookie-based authentication from the source code of configuration schemas as well as from external apps.

Implement a custom web service that uses anonymous authentication

A custom web service that uses anonymous authentication does not require the user to pre-authenticate, i. e., you can use the service anonymously.

Important

We do not recommend using anonymous authentication in custom web services. It is insecure and can hurt performance.

Implement a custom web service that uses anonymous authentication for .NET Framework

note

Custom web services that use anonymous authentication and non-standard text encoding can be implemented for Creatio deployed on .NET Framework only since version 8.0.2 and later.

To implement a custom web service that uses anonymous authentication for .NET Framework:

1. Repeat steps 1–5. Instructions: Implement a custom web service that uses cookie-based authentication.

   1. When creating a service class, add the SystemUserConnection system connection to enable anonymous access to the custom web service.

   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.

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

2. Register the web service.

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

   2. Create and open the file whose name matches the web service name.

   3. Register the web service. To do this, add the following record.

      Template that registers the custom web service that uses anonymous authentication

      <% @ServiceHost
          Service = "Service, ServiceNamespace"
          Factory = "Factory, FactoryNamespace"
          Debug = "Debug"
          Language = "Language"
          CodeBehind = "CodeBehind"
      %>

      Example that registers the custom web service that uses anonymous authentication

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

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

      Learn more about the @ServiceHost WCF directive: official vendor documentation (Microsoft).

   4. Save the file.

3. Register a non-standard text encoding (optional).

   note

   This functionality is available for Creatio deployed on .NET Framework only since version 8.0.2 and later.

   Creatio lets you use arbitrary character encodings in .NET Framework web services that use anonymous authentication. For example, you can use such encodings as ISO-8859, ISO-2022, etc. Learn more about encodings: Character encoding (Wikipedia).

   To register an arbitrary character encoding:

   1. 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 the following attributes to the <customBinding> file section.

         • Set the name attribute of the <binding> element to custom name of the encoding.
         • Set the encoding attribute of the <customTextMessageEncoding> element to the code of the encoding. For example, "ISO-8859-1."
         • Set the manualAddressing attribute of the <httpTransport> element to true.
         ..\Terrasoft.WebApp\ServiceModel\http\bindings.config file

         <bindings>
             ...
             <customBinding>
                 <binding name="CustomEncodingName">
                     <customTextMessageEncoding encoding="ISO-8859-1" />
                     <httpTransport manualAddressing="true"/>
                 </binding>
             </customBinding>
             ...
         </bindings>

         Register each encoding, i. e., add <binding> file section, for each encoding individually.

      5. Save the changes.

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

   1. 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.SomeCustomNamespace.SomeServiceName">
                 <endpoint name="SomeServiceNameEndPoint"
                 address=""
                 binding="SomeBinding"
                 bindingConfiguration="SomeCustomEncoding"
                 behaviorConfiguration="RestServiceBehavior"
                 bindingNamespace="http://Terrasoft.WebApp.ServiceModel"
                 contract="Terrasoft.Configuration.SomeCustomNamespace.SomeServiceName" />
             </service>
             ...
         </services>

         The <services> element includes the list of Creatio web service configurations (the <service> nested elements).

         The name attribute includes the name of the type (class or interface) that implements the web service contract.

         The <endpoint> nested element includes the address, binding, and interface that defines the contract of the web service specified in the name attribute of the <service> element.

         The binding attribute includes the value of the character encoding. Must match the name of the file section where the encoding that the web service uses is registered. Set the attribute to "webHttpBinding" to use the UTF-8 encoding. Set the attribute to "customBinding" to use a custom encoding.

         The bindingConfiguration attribute must be presented if the binding attribute is set to "customBinding." Must match the value of the <binding> element's name attribute specified on the previous step.

         Learn more about the web service configuration elements: official vendor documentation (Microsoft).

      4. Save the changes.

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

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

   2. Go to the <configuration> section.

   3. Add the <location> element to the root <configuration> section. The <location> element defines the relative path and access permissions to the web service.

      ..\Terrasoft.WebApp\Web.config file

      <configuration>
        ...
          <location path="ServiceModel/SomeServiceName.svc">
            <system.web>
              <authorization>
                <allow users="*" />
              </authorization>
            </system.web>
          </location>
        ...
      </configuration>

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

   5. 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="[Some previous values];ServiceModel/SomeServiceName.svc" />
          ...
        </appSettings>
        ...
      </configuration>

   6. Save the changes.

   7. Apply the changes. To do this, restart Creatio in IIS.

As a result, you will be able to call the custom web service that uses anonymous authentication from the source code of configuration schemas as well as from external applications. You can access the web service both with and without pre-authentication.

Implement a custom web service that uses anonymous authentication for .NET

1. Repeat steps 1–5. Instructions: Implement a custom web service that uses cookie-based authentication.

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

   1. Open the ..\Terrasoft.WebHost\appsettings.json file.
   2. Go to the AnonymousRoutes block.
   3. Add the web service data to the root AnonymousRoutes block.
   ..\Terrasoft.WebHost\appsettings.json file

   "Terrasoft.Configuration.SomeServiceName": [
       "/ServiceModel/SomeServiceName.svc"
   ]

3. Restart Creatio.

As a result, you will be able to call the custom web service that uses anonymous authentication from the source code of configuration schemas as well as from external applications. You can access the web service both with and without pre-authentication.

Important

Reconfigure the web service after updating Creatio. The existing configuration files are overwritten as part of the update.

---

See also

Authentication basics

OData basics

Service that runs business processes

Configuration elements of the Source code type

Web services (user documentation)

Integrations tools

---

Resources

Character encoding (Wikipedia)

Official Postman documentation