WebAPI

The ISYSwebApi allows developers to push content to Perceptive Enterprise Search to be indexed. Content can be push into both global index and user indexes.

Perceptive Enterprise Search supports several methods to index your data, including the traditional crawlers like the file system, website, database or document management systems; or you can create your own crawler via script.

The ISYSwebApi differentiates from crawlers in one key way. Crawlers use a "pull" methodology where they enumerate the entire datasource automatically detecting content that has changed, been added or removed. A crawled index can easily be rebuilt as it can simply re-enumerate all the content to re-add it to the index.

The ISYSwebApi uses a "push" methodology. A separate process must actively monitor the datasource looking for new, changed or deleted documents and issues a command to the ISYSwebApi to perform an action. To rebuild a "push" index, the pusher process must re-push add the data.

Both systems have their benefits, the push system works well for datasources that provide notifications when data is changed. Where pull systems are generally easier to manage.

Jump to:

• Configuring the ISYSwebApi
• Reference
• Examples

Configuring the ISYSwebApi

The ISYSwebApi is pre-configured out of the box to accept connection from the local web server. You will need to adjust the permissions if you intended to run your indexing service on a different machine.

Configuration

Enable Perceptive Enterprise Search data feeds

Enable indexing services to push content using the Perceptive Enterprise Search data feed. This option must be enabled if you wish to index Exchange or Lotus Notes email.

Enable GSA data feeds

Enable indexing services to push content using GSA XML data feeds.

Server Port

The ISYSwebApi is configured to listen on a single port, across all IP addresses on the web server, or bound to a virtual directory. The port either can be standalone or shared with an existing website. By default port the ISYSwebApi is bound to the "API" virtual directory on port 8700 which is shared with the Perceptive Enterprise Search Administration website.

Password

The password allows you to prevent unauthorized applications pushing content to Perceptive Enterprise Search. A password is randomly generated on installation, which must be specified by each pushing service. Passwords cannot contain semicolons (;).

Permissions

The permissions allow you to control which machines can push content to Perceptive Enterprise Search, this prevents unauthorized content being added to your indexes.

The Perceptive Enterprise Search supports two types of services, pushers and synchronizers. Most applications are pushers when they push individual documents. Synchronizer build an index on a remote server then synchronize it with the index on the server.

You can specify the allowed IP addresses using CIDR format for each type of indexer. The default, the push indexer is configured to only accept connections from it self.

Run As

The run as options allow you to specify the account that the service should run as. This may be required if you need access to secure content.

Reference

The ISYSwebApi accepts commands over HTTP using the port specified in the ISYSwebApi configuration.

You can create your indexing service application in any application that allows you to add custom HTTP headers to the request. For example .net or using WinHTTP on systems that support COM.

The first header that you must provide is the "action", this instructs the ISYSwebApi what to except. It may be one of the following: add, delete, touch, batchtouch, purge and starttouch. Each of these is documented in detail below.

Your service may also be required to provide a password as specified on the ISYSwebApi configuration page. This is done by specifying a "password" header.

Example

Set inet = Server.CreateObject("WinHttp.WinHttpRequest.5.1") 
inet.Open
"POST", "http://localhost:8700/api" inet.SetRequestHeader "action", "add"
inet.SetRequestHeader "password", "apipassword"

Add Action

The add action adds a single document to the specified index. The content of the document is posted to the server.

The document begin added is already in the index, old document is replaced with this one.

Request Headers

 Returned Headers

Delete Action

Removes the specified document from the index.

Request Headers

Returned Headers

Touch Action

Updates the last seen time for the document, this method is used in conjunction with the purge action to remove documents that have not been seen recently.

Request Headers

Returned Headers

BatchTouch Action

Updates the last seen time for a collection of documents in a single request. The document list must be posted in the body of the request, separated by a carriage return line feed.

Request Headers

Returned Headers

Purge Action

Removes documents that have not been seen since the given time. Used in conjunction with touch or batchtouch.

Request Headers

Returned Headers

StartTouch Action

The starttouch method returns the timestamp at the server, this can be used in conjunction with the purge action to remove documents that have to been seen in some time.

Request Headers

Returned Headers

Examples

Adding documents

The example below demonstrates adding documents to an index using VBScript.

Function SendFile(Filename)
	Set inet = Server.CreateObject("WinHttp.WinHttpRequest.5.1")
	inet.Open "POST", "http://localhost:8700/api"
	inet.SetRequestHeader "action", "add"
	inet.SetRequestHeader "password", "
		apipassword"
	inet.SetRequestHeader "filename", Filename
	inet.SetRequestHeader "index", "Demo"
	inet.Send ReadBinaryData(Filename)
End Function
Function ReadBinaryData(Filename)
	Set Stream = CreateObject("ADODB.Stream")
	Stream.Open Filename, 1
	Stream.Type = 1  ' adTypeBinary
	ReadBinaryData = Stream.Read
End Function
SendFile "c:\temp\test.doc"

Removing document with touch and purge

This example demonstrates touching document and then purging documents that not been touched in the period.

Function CreateCommand(Action)
	Set inet = Server.CreateObject("WinHttp.WinHttpRequest.5.1")
	inet.Open "POST", "http://localhost:8700/api"
	inet.SetRequestHeader "action", Action
	inet.SetRequestHeader "password", "
		apipassword"
	Set CreateCommand = inet
End Function
Set inet = CreateCommand("starttouch")
StartTime = inet.GetRequestHeader("Last-Modified")
' Enumerate all documents in your collection, this is for
' demonstration purposes only, you will need logic specific
' to your application here
For Each Document in DataSource
	' Create the touch command
	Set inet = CreateCommand("touch")
	inet.SetRequestHeader "filename", Document.Filename
	inet.Send
Next

' Purge the documents that were not touch in this pass
Set inet = CreateCommand("purge")
inet.Send