Platform web service

Applies to Infiniti v8.0 or later

 
Overview
 
The Platform web service provides methods for retrieving projects and their answer files from Infiniti. It also handles user authentication and maintenance, allowing user synchronization with a third party system.
 
This service exposes a number of functions, or ‘methods’. These methods must be executed as an authenticated Infiniti user, and therefore the ‘Login’ method must always be called first. This creates a Session ID that is then used for subsequent calls to other methods.
 

Answer Files

 
Infiniti Answer Files are referred to often throughout this chapter. An Answer File is an XML data structure that contains the data captured by an Infiniti web form or document project. This data may include user responses to questions, data from external systems, and other content.
 
Infiniti uses Answer Files to save and pre-populate ‘In Progress’ web forms. Designers can control how specific responses are stored in the Answer File by setting Answer Labels in Designer. These labels become easy to read and write in an Answer File XML structure, as they are treated as simple ‘name/value’ pairs.
 
There are three types of Answer Files referred to:
  • Default Answer Files – these have no data or responses apart from default values.
  • Saved Answer Files – these are completed responses saved by the user in Producer after completing a web form.
  • In Progress Answer Files – these are partially completed responses, either saved programmatically to pre-populate a web form, or saved part way through a web form by the end user.
 

GetAnswerFile method

 
The GetAnswerFile method creates a default Answer File for any project, and returns it as XML data that can be manipulated and passed back to Infiniti to generate documents or pre-populate a web form. The default Answer File will contain default values where available for the project’s questions. Refer to Answer Files above for more information about each type of Answer File.
 
Using this method avoids the need to maintain ‘hard-coded’ answer files that become outdated when design changes are made to the project.
 
Often this method is used to ‘splice’ custom XML data into the Answer File before it is saved back to Infiniti, which is used to pre-populate a web form in Producer. This concept is described in the Pre-populating Web Forms section below.
 
The GetAnswerFile method requires a single parameter ‘templateGroupID’ which is an Integer value representing a project that has been published to a folder and can be accessed by authorised users.
 
Note the templateGroupID is different to the ID of the project itself, as each project may be published to multiple folders with different publish options. The templateGroupID is used to identify a specific published instance of a project.
 
Also note that this method requires the Integer templateGroupID value and not the equivalent GUID value as in other methods.
 
The templateGroupID value can be sourced programmatically using the GetPublishedProjects method, which is described below, or by running the following query on the Infiniti database directly:
 
SELECT tg.Template_Group_ID, tg.Template_Group_Guid, t.Name
FROM dbo.Template AS t INNER JOIN
dbo.Template_Group_Item AS tgi ON t.Template_ID = tgi.Template_ID INNER JOIN
dbo.Template_Group AS tg ON tgi.Template_Group_ID = tg.Template_Group_ID;

Samples

 
The code below uses the GetAnswerFile method to retrieve and begin to manipulate an Answer File.
 
Dim answerFile As String
'tempalteGroupID must be sourced from the getPublishedProjects Method or from the Infiniti Database.
Dim templateGroupID As Integer = 1234
'Call web service and return answer file answerFile = m_PlatformService.GetAnswerFile(templateGroupID)
'Example - Use XML Document to access the AnswerFileLabels Dim afXml As New Xml.XmlDocument afXml.LoadXml(answerFile)
If afXml.DocumentElement.SelectNodes("AnswerLabels/Label")
IsNot Nothing Then nbsp; For Each labelElement As Xml.XmlElement In _
nbsp; afXml.DocumentElement.SelectNodes("AnswerLabels/Label")
      Dim label As New AnswerLabel
      label.Name = labelElement.Attributes("name").InnerText
      '...
      '...
  Next
End If

GetAnswerFiles Method

While the GetAnswerFile method retrieves a default Answer File for a single project, the GetAnswerFiles method retrieves an array of all saved Answer Files, which may include a number of different projects.
 
The Answer Files retrieved by this method have been saved by the end user from the Finish Page, after completing a web form in Producer. Refer to Answer Files above for more information about each type of Answer File.
 
The GetAnswerFiles method returns an array of saved Answer Files for a particular user, based on the user specified in the Login method. This method is useful for creating a custom Infiniti interface or portal that enables users to retrieve saved Answer Files.
 

Samples

 
The code below uses the GetAnswerFiles method to retrieve an array of answer file objects.
 
Dim answerFiles As IxPlatformService.AnswerFile()
Dim myList As ListBox = Nothing
answerFiles = m_PlatformService.GetAnswerFiles()
myList = lstAnswerFiles
myList.Items.Clear()
myList.DisplayMember = "Description"
' Load list of answer files list box For Each answerFile As IxPlatformService.AnswerFile In answerFiles
    myList.Items.AddanswerFile)
Next
 
The GetAnswerFiles Method returns a list of available Answer Files but not the actual data, which is potentially quite large. To retrieve an Answer File’s actual data, a subsequent call to the getUserAnswerFile method is required, as described below.
 

The GetInProgressAnswerFiles Method

 
In Progress Answer Files are those saved by the end user during the web form via the Save button, as depicted below. Refer to Answer Files above for more information about each type of Answer File.
 
 
The GetInProgressAnswerFiles method returns an array of in progress Answer Files for a particular user, based on the user specified in the Login method. This method is useful for creating a custom Infiniti interface or portal which allows users to return to partially completed web forms.
 

Samples

 
The code below uses the GetAnswerFiles method to retrieve an array of answer file objects.
 
Dim inProgressAnswerFiles As IxPlatformService.AnswerFile()
Dim myList As ListBox = Nothing
inProgressAnswerFiles = m_PlatformService.GetInProgressAnswerFiles()
myList = lstAnswerFiles
myList.Items.Clear()
myList.DisplayMember = "Description"
' Load list of answer files list box
For Each answerFile As IxPlatformService.AnswerFile In inProgressAnswerFiles
    myList.Items.Add(answerFile)
Next
 
The GetInProgressAnswerFilesMethod returns a list of available answer files but not the actual ‘answerstring’ which is potentially quite large. This requires a subsequent getUserAnswerFile call described below.
 
 

GetPublishedProjects Method

 
The GetPublishedProjects method will return an array of projects that can be run by a particular user. The information can be used to create hyperlinks to projects, and is useful for creating a custom Infiniti interface or portal that allows users to launch Infiniti projects.
 
The method can be used to determine if a user has access to a particular project and return its ID or GUID for use with subsequent web service calls. The actual projects returned are those belonging to the user specified in the login call.
 

Samples

 
The sample below gets a user’s published projects and iterates through them in their published folders.
 
' clear old projects from drop-down list, and configure list to show
' Infiniti project names and remember the related GUIDs.
cboProjects.Items.Clear()
cboProjects.DisplayMember = "Name"
cboProjects.ValueMember = "TemplateGroupGuid"
' Call web service for list of published projects and then iterate through results.
Dim projList As IxPlatformService.PublishedProjectList
projList = platform.GetPublishedProjects()
If projList IsNot Nothing Then
    For Each folder As IxPlatformService.Folder In projList.Folders
      'discard folders for this sample, could be used to group the projects.
      For Each project As IxPlatformService.Project In folder.Projects
        cboProjects.Items.Add(project)
      Next
    Next
End If
 

The GetUserAnswer File method

 
The GetUserAnswerFile method will retrieve the properties for a particular AnswerFile saved by a user in a Producer web form. The answerFile requested must belong to the user specified in the login call.
 
The GetAnswerFile method requires a single input parameter, the answerFileId, which is an integer value representing a particular answerFile.
 
The ID value can be sourced programmatically using the getAnswerFiles and GetInProgressAnswerFiles methods described above or by running the following query on the Infiniti Database Directly.
 
SELECT   u.Username, af.AnswerFile_ID, af.Description
FROM     dbo.Answer_File AS af INNER JOIN         
dbo.Intelledox_User AS u ON af.User_ID = u.User_ID
WHERE   (u.Username = 'admin')
Samples
The code below uses the GetUserAnswerFile method to retrieve and begin to manipulate an answer file.
 
'AnswerrFileID must be sourced from the GetAnswerFiles/GetInprogress Method or from the Infiniti Database.
Dim AnswerFileID As Integer = 1234
' Call web service and return answer file answerFile = m_PlatformService.GetUserAnswerFile(AnswerFileID)
'Access the AnswerFileLabels Dim afXml As New Xml.XmlDocument afXml.LoadXml(answerFile.AnswerString)
'Access answerLabels
If afXml.DocumentElement.SelectNodes("AnswerLabels/Label") IsNot Nothing Then
    For Each labelElement As Xml.XmlElement In
     afXml.DocumentElement.SelectNodes("AnswerLabels/Label")
 
      Dim label As New AnswerLabel
      label.Name = labelElement.Attributes
("name").InnerText       '...
      '...
    Next
End If
 

The Login Method

The login method is to authenticate a user to the platform web service. No other method can be called without a successfully building a session header via this method.
The credentials passed to the method when using the login service, must match the authentication type used by the Infiniti method.
The GetAnswerFile method requires a username and password parameters, passed as strings.
 

Samples

 
The samples below create a platform web service session header for both forms and windows authentication.
 
Private Function LoginFormsAuth() As Boolean
' ------
' Uses Infiniti Platform web service to log in via Forms Authentication
' and return a valid Session GUID.
' ------
Dim m_PlatformService As New IxPlatformService.platform
' Call the Login web method, with the username and password.
Dim loginResult As IxPlatformService.LoginResult
Try
   loginResult = m_PlatformService.Login(userId, password)
Catch ex As Exception
   Throw New ApplicationException("Login failed for user '" & userId & "'.")
End Try
' Add Session GUID information into the web service header
Dim sessionHeader As New IxPlatformService.SessionHeader
sessionHeader.SessionId = loginResult.SessionID
m_PlatformService.SessionHeaderValue = sessionHeader
If sessionHeader.SessionId <> Guid.Empty Then
   Return True
Else
   Return False
End If
End Function
 
Private Function LoginWindowsAuth() As Boolean
' ------
' Uses Infiniti Platform web service to log in via Windows Authentication
' and return a%