Creating anonymous web service
Glossary Item Box
Introduction
Bpm’online service model implements the base set of web services, which you can use for integration of bpm’online with external applications and systems. Examples of system services are: the EntityDataService.svc, which enables exchanging data with bpm'online via the OData protocol and the ProcessEngineService.svc, which provides the launch of bpm’online business process from external applications. These services are implemented based on the WCF technology and are managed at IIS level.
There also exist configuration web services in bpm’online that can be called from the custom part of the application. You can implement specific integration tasks via configuration web services. More information about creation of a custom configuration web service can be found in the “How to create custom configuration service” article.
Most of WCF-services require preliminary user authentication. However, there exist services that permit anonymous usage. An example of such a service is AuthService.svc.
ATTENTION
Since configuration services are managed directly by the application and not by IIS, you cannot make them anonymous.
To create a WCF-service that would be accessible without user authentication:
- Create a configuration web service (if needed).
- Register the WCF-service.
- Configure WCF-service for the http and https protocols.
- Set up access to WCF-service for all users.
ATTENTION
You need to change the application configuration files to set up anonymous web-service. When updating the application, all the configuration files are changed by the new ones. Thus, you need to set up the web service again after the application update.
Case description
Create custom configuration service that returns the Id of a contact by the provided name. If there are several contacts found, it is only necessary to return the Id of the first contact. If the contact is not found, the service should return an empty string.
NOTE
You can use the service created based on the example covered in the “How to create custom configuration service” article as the configuration web service.
Case implementation algorithm
1. Creating configuration service
How to create the configuration service is covered in the “How to create custom configuration service” article.
ATTENTION
Because you are creating an anonymous configuration service, system user connection must be used instead of user connection.
The source code of configuration service, which uses system user connection:
namespace Terrasoft.Configuration.UsrCustomConfigurationService { 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 UsrCustomConfigurationService { // Link to the UserConnection instance required to access the database. private SystemUserConnection _systemUserConnection; private SystemUserConnection SystemUserConnection { get { return _systemUserConnection ?? (_systemUserConnection = (SystemUserConnection)AppConnection.SystemUserConnection); } } // A method that returns the contact's ID by its name. [OperationContract] [WebInvoke(Method = "GET", RequestFormat = WebMessageFormat.Json, BodyStyle = WebMessageBodyStyle.Wrapped, ResponseFormat = WebMessageFormat.Json)] public string GetContactIdByName(string Name){ // The default result. var result = ""; // An EntitySchemaQuery instance that accesses the Contact table of the database. var esq = new EntitySchemaQuery(SystemUserConnection.EntitySchemaManager, "Contact"); // Adding 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); // Get the result of the query. var entities = esq.GetEntityCollection(SystemUserConnection); // If the data is received. if (entities.Count > 0) { // Return the value of the "Id" column of the first record of the query result. 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; } } }
2. Registering the WCF-service.
Create the UsrCustomConfigurationService.svc file in the ..\Terasoft.WebApp\ServiceModel catalog and add the following record into it:
<%@ ServiceHost Language="C#" Debug="true" Service="Terrasoft.Configuration.UsrCustomConfigurationService.UsrCustomConfigurationService" %>
In the Service attribute specify the full name of the configuration service class. Read more about the @ServiceHost WCF-directive in Microsoft documentation.
3. Configuring WCF-service for the http and https protocols.
Add the following record to the services.config files located at ..\Terasoft.WebApp\ServiceModel\http and ..\Terasoft.WebApp\ServiceModel\https catalogs:
<services> ... <service name="Terrasoft.Configuration.UsrCustomConfigurationService.UsrCustomConfigurationService"> <endpoint name="UsrCustomConfigurationServiceEndPoint" address="" binding="webHttpBinding" behaviorConfiguration="RestServiceBehavior" bindingNamespace="http://Terrasoft.WebApp.ServiceModel" contract="Terrasoft.Configuration.UsrCustomConfigurationService.UsrCustomConfigurationService" /> </service> </services>
Configure the service here. The <services> element contains a list of configurations of all application services (the <service> nested elements). The name attribute contains the name of type (class or interface) implementing the service contract. The <endpoint> nested element requires address, binding and interface that define the service contract specified in the name attribute of the <service> element.
You can find detailed description of the service configuration elements in the documentation.
4. Setting up access to WCF-service for all users.
Perform the following changes in the ..\Terasoft.WebApp\Web.config file:
- Add the <location> element defining the relative path and access rights to the service.
- In the <appSettings> element change the value value for the “AllowedLocations” key by adding the relative path to the service into it.
An example of changes in the ..\Terasoft.WebApp\Web.config file:
<?xml version="1.0" encoding="utf-8"?> <configuration> ... <location path="ServiceModel/UsrCustomConfigurationService.svc"> <system.web> <authorization> <allow users="*" /> </authorization> </system.web> </location> ... <appSettings> ... <add key="AllowedLocations" value="[Previous values];ServiceModel/UsrCustomConfigurationService.svc" /> ... </appSettings> ... </configuration>
After reloading the application pool in IIS, the service will become available at:
[Application Address]/0/ServiceModel/[Custom Service Name].svc/[Custom Service Endpoint]?[Optional parameters]
For example:
http://mysite.bpmonline.com/0/ServiceModel/UsrCustomConfigurationService.svc/GetContactIdByName?Name=Supervisor
You can address the service, e.g., from a browser (fig.1) either with preliminary login or without it.
Fig. 1. Example of access to the anonymous service from browser.
