Integration with Intelledox Web Services
Overview
Intelledox provides two web services for integration, which can be used to provide document generation to third party or custom applications.
Generation Service is used to generate a completed Word document based on the information provided in the request.
The Generation Service is useful for when you want seamless integration with Intelledox. Users can be using a third party application, which calls on this service in the background to generate a document, and provide the document to the user without them needing to be aware that Intelledox is involved.
Platform Service is used to authenticate a user, and return a Session ID that can be used as part of a URL to launch the template QA wizard at the appropriate starting point in a browser.
This service is used in situations where the user will need to enter information into Intelledox prior to generating the document, perhaps because the client application doesn’t support the capture of all necessary information. This case is most commonly used in conjunction with an intermediate custom data service, which takes data from the client’s request and populates a data store on the server which can be used by Intelledox to generate the document.
Web Service Usage Scenarios
General Service Scenario
A client application must generate a Word document based on an Intelledox template. It knows all the data necessary for Intelledox to generate the document.
Before calling the Intelledox Generation Service, the client application must first build an XML Answer File. The answer file contains reference to all the questions that would otherwise be asked to the user if they were to manually launch that template from within the Intelledox Document Centre, and along with each question the answer file provides the appropriate answers. This can be built either using standard XML tools or simply by building a string, and need not be physically stored on disk as a file.
The client application will make a call to the Generation service, passing in as parameters valid Intelledox user credentials (username/password), the Template GUID to generate, and the answer file as a string parameter.
The return value of the service call is a byte array, which contains the binary definition of the generated Word document. The client can then save this to disk and open in Word, or perform any other appropriate action as required.
Platform Service Scenario
In this scenario the client application must call on Intelledox to generate a document, however requires that the user be directed through the template’s questions to provide information not being captured in the client application itself. The client is able to provide a large amount of data to begin with, however, and this must be passed through so the user isn’t required to rekey any information.
The client application firstly makes call to the custom data service, providing all relevant information that will be used in generating a document. The custom data service stores this data in a server-side database, and calls the Intelledox Platform Service to authenticate a valid Intelledox user.
The Platform Service returns a Session ID upon successful authentication, which the Data Service in turn passes back to the calling client application. So far no documents have been generated.
At this point the client application can launch a browser, pointing to the Intelledox Online Document Centre and passing in the Session ID via the URL. This will display the template at the appropriate question for the user to complete any necessary information. After the user finishes all questions, they must generate and then download the document as per standard Intelledox operation.
Integration Architecture
As shown in the diagram, you must have a web server running IIS and the .NET Framework v2. In addition a database server is required, such as SQL Server. This may be running on the same or different physical machine as the web server, as long as the Intelledox process has permission to access it.
Third party clients can access Intelledox via its Web Services. Data may be passed to the Intelledox generation engine in three ways:
► Directly by the user answering questions using the Online Document Centre via a browser.
► Programmatically using the Answer File passed to the Generation Service.
► By updating a data source used by the template being run. In this case there should be record identifiers placed in the Answer File when generating dynamically, or by the user when using the Online Document Centre. The external data source should be visible to both Intelledox and the client, so for distributed solutions it is advisable to create a custom web service as in the diagram.