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 using no-code tools. Learn more: Web services (user documentation).

• Base web services.

  • Base web services that use cookie-based authentication.
  • Base 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 base web services use the WCF and are managed at the IIS level. .NET base 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 base 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 applications 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 base 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 base web services, custom web services let you solve unique integration problems.

The web service development procedure differs for each Creatio deployment framework. View the specifics of 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

Detailed example: Implement a custom web service that uses cookie-based authentication.

To 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.
   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).

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

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.

Detailed examples: Implement a custom web service that uses anonymous authentication, Implement a custom web service that uses anonymous authentication and non-standard text encoding.

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.

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

   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.

   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 schemas: 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

"Source code" type schema

Web services (user documentation)

Integrations tools

Implement a custom web service that uses cookie-based authentication

Implement a custom web service that uses anonymous authentication

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

---

Resources

Character encoding (Wikipedia)

Official Postman documentation