iKnow Web Services

The %iKnow package provides web service classes that execute iKnow queries. This chapter provides an overview of these classes and describes how to use them. It discusses the following topics:

Available Web Services

iKnow provides the following web service classes:

%iKnow.Queries.CcWSAPI — provides web methods that you can use to get information about concept-concept (CC) pairs. These web methods are equivalent to the methods in the %iKnow.Queries.CcAPI class.
%iKnow.Queries.CrcWSAPI — provides web methods that you can use to get information about Concept-Relation-Concept (CRC) triples. These web methods are equivalent to the methods in the %iKnow.Queries.CrcAPI class.
%iKnow.Queries.EntityWSAPI — provides web methods that you can use to get information about entities. These web methods are equivalent to the methods in the %iKnow.Queries.EntityAPI class.
%iKnow.Queries.EquivWSAPI — provides web methods that you can use to manage equivalences. These web methods are equivalent to the methods in the %iKnow.Queries.EquivAPI class.
%iKnow.Queries.MetadataWSAPI — provides web methods that you can use to manage and get information about source metadata. These web methods are equivalent to the methods in the %iKnow.Queries.MetadataAPI class.
%iKnow.Queries.PathWSAPI — provides web methods that you can use to get information about paths. These web methods are equivalent to the methods in the %iKnow.Queries.PathAPI class.
%iKnow.Queries.SentenceWSAPI — provides web methods that you can use to get information about sentences. These web methods are equivalent to the methods in the %iKnow.Queries.SentenceAPI class.
%iKnow.Queries.SourceWSAPI — provides web methods that you can use to get information about sources. These web methods are equivalent to the methods in the %iKnow.Queries.SourceAPI class.

The %iKnow.Queries package also contains classes that the compiler generated when these classes were compiled. For example, when the compiler compiled the class %iKnow.Queries.CcWSAPI, it generated the classes in the %iKnow.Queries.CcWSAPI package. These generated classes are not intended for direct use.

Using an iKnow Web Service

To use a web service, you create and use a web client that communicates with it. To do so for an iKnow web service, you use the same procedure as with any other web service:

Create a web client that can communicate with the web service. Typically, to do so, you generate the web client using a tool provided by the client technology and you provide the WSDL of the web service as input. This process generates a set of client classes.

For example, in Caché, use the Studio SOAP wizard. For a Caché web service, Caché conveniently publishes the WSDL at the following URL:
```
http://hostname:port/csp/namespace/web_service_class.cls?WSDL
```
Where:
- hostname is the server on which Caché is running.
- port is the port on which the web server is running.
- namespace is the namespace name.
- web_service_class is the full package and class name of the web service with .cls at the end.
  
  For example, for the class %iKnow.Queries.EntityWSAPI, use %25iKnow.Queries.EntityWSAPI.cls
  
  Important:
  
  Be sure to replace the leading percent sign of the package with the URL escape sequence %25 as shown here.
For example:
```
http://localhost:57772/csp/samples/%25iKnow.Queries.EntityWSAPI.cls?WSDL
```
Rather than editing the generated client classes, create an additional class or routine that uses them. The details depend on the technology.

In Caché, to use a web client, you create an instance of the web client class and then invoke its instance methods. See the following example.

Example

For demonstration purposes, let us generate and use a Caché web client to work with an iKnow web service on the same machine. To do this in the SAMPLES namespace:

In Studio, click Tools > Add-ins > SOAP Wizard.
On the first screen, click URL.
Type the following URL:
```
http://localhost:57772/csp/samples/%25iKnow.Queries.EntityWSAPI.CLS?WSDL
```
If needed, replace 57772 with the port that your web server uses for this installation of Caché.
Click Next.
For Proxy Class Package, type a package name such as MyClient
Click Next twice.

The wizard generates and compiles the classes and displays a list of these classes.

This process generates the class MyClient.iKnow.Queries.EntityWSAPISoap. This class defines a set of methods, one for each web method defined in the web service on which this client is based. Each of these methods looks like this (with illegal line breaks added here):
```
Method GetByFilter(domainid As %Integer, filter As %String, filtermode As %Integer, enttype As %Integer, 
blackListIds As %ListOfDataTypes(ELEMENTTYPE="%String",XMLITEMNAME="blackListIdsItem",XMLNAME="blackListIds")) 
As %XML.DataSet [ Final, ProcedureBlock = 1, SoapBindingStyle = document, SoapBodyUse = literal, WebMethod ]
{
 Quit ..WebMethod("GetByFilter").
  Invoke($this,"http://www.intersystems.com/iKnow/Queries/EntityWSAPI/%iKnow.Queries.EntityWSAPI.GetByFilter",
         .domainid,.filter,.filtermode,.enttype,.blackListIds)
}
```
The signature of this method is the same as for the corresponding method in the web service.

This process also generates a set of classes in the MyClient.iKnow.Queries.EntityWSAPISoap, which are not for direct use.
Click Finish.
To use the generated client, enter the following in the Terminal in the SAMPLES namespace:
```
set client=##class(MyClient.iKnow.Queries.EntityWSAPISoap).%New()
```
This creates an instance of the client class, which can then communicate with the web service.
Execute methods of this class. For example:
```
write client.GetCountByDomain(2)
```

Comparison of iKnow Web Services with Primary iKnow APIs

The primary iKnow APIs use arguments that cannot be easily represented in SOAP messages, so the methods in iKnow web services have different signatures than do the methods in the primary iKnow APIs. In particular, note the following differences:

Instead of %Library.List, the web services (and their clients) use %Library.ListOfDataTypes. This means that to build a list for a web service, you create an instance of %Library.ListOfDataTypes and then use its SetAt() method to add items. You cannot use list functions such as $LISTBUILD with this instance.
Instead of an instance of %iKnow.Filters.Filter, the web services (and their clients) use a string of the form returned by the ToString() method of that class.
For APIs that return complex results, rather than returning results by reference as a multidimensional array, the web services (and their clients) return an instance of %XML.DataSet.

Important:

This structure is supported only in .NET and in Caché. Other web technologies do not recognize this format.

iKnow Web Services

Available Web ServicesCopy link to this section

Using an iKnow Web ServiceCopy link to this section

ExampleCopy link to this section

Comparison of iKnow Web Services with Primary iKnow APIsCopy link to this section

See AlsoCopy link to this section

Available Web Services

Using an iKnow Web Service

Example

Comparison of iKnow Web Services with Primary iKnow APIs

See Also