eDocBuilder Web Services API

eDocBuilder has three SOAP web services APIs available.  

  • The primary builddoc service is used for standard forms based and session operations.
  • The RIA (rich internet application... also known as the Interactive Designer) API is also available for developing interactive eDocBuilder clients.
  • The templateMgr service is used for programs that need to automatically create templates, instead of a person using the Creator website to do so.  This service exists, but is not documented in this KB article.

Most web services calls do require credentials for authentication. These credentials provided at the time of provisioning. User accounts created in eDocBuilder will not work for web services calls.

If your account was setup with API access, then the API endpoints (URLs providing a WSDL definition, suitable for use in Visual Studio "add web service", or other IDEs) will have been included in your account welcome letter. Otherwise, please contact technical support for the SOAP endpoints, or if you have any questions.

Note: Some members of structures are there only for use by advanced interactive clients. Forms-based clients do not need to do anything with these members and they have been tagged “RIA Client Only”. Some structures have been left out altogether for this reason as well.

If you are not sure if you have eDocBuilder API access for your subscription, please check Can I use iFrame or SOAP API access with my eDocBuilder account?

METHODS

startDocSession 

Public Function startDocSession(ByVal docCode As String, ByVal docPwd As String, remote_tag as String) As sessionInfo
 
Summary:
Start a new eDoc session.

Parameters:
 docCode: GUID pointing to the eDoc template to be built.
 docPwd: Another GUID serving as password. Can be passed as empty string, and either whole web app or individual
 documents can be set to not require a password.
remote_tag: Any information you would like to provide, such as an order number, that should be associated with the eDocBuilder session.
 
Return Values:
 sessionInfo structure of the newly opened session.

 
Remarks:
 This is the first step of an eDocBuilder session. The sessionID returned as part of the sessionInfo structure is used in all
 subsequent calls.

 

getCurrentSession 

Public Function getCurrentSession(ByVal docSessionID As String) As docClientInfo
 
Summary:
Retrieve the info the client will need about the current session.
 
Parameters:
docSessionID:
 
Return Values:
docClientInfo structure with details about the session.
 
Remarks:
The structure returned has details about the fields the template requires, along with the presentation in the forms based client.
 

updateCurrentSession 

Public Function updateCurrentSession(ByVal docSessionID As String, 
  ByVal userValues() As userEntries) As Integer
 
Summary:
 Update the session info with new values submitted by the user.

Parameters:
 docSessionID: the current session ID
 userValues: array of user entries

 
Return Values:
 Zero for failure; nonzero for success.

 
Remarks:
 Send the changes the user has made to the server. This can include sending image files uploaded by the user. Only those values that have actually changed need to be sent.

 

getPreviews 

Public Function getPreviews(ByVal docSessionID As String, ByVal pageNumber() As Integer, 
  ByVal pixelSize As Integer, ByVal includeThumbs As Boolean) As docPreviewPage()
 
Summary:
 Get preview(s) for the document using current values.

Parameters:
 docSessionID: The current session ID
 pageNumber: List of page numbers to generate previews for
 pixelSize: Maximum preview height/width in pixels.  Providing 0 will cause the original page size to be used.
 includeThumbs: Whether to include thumbnail versions of the previews

 
Return Values:
 array of docPreviewPage structures pointing to the previews

 
Remarks:
 After updating the server with the user's changes, a new proof document is created on the server. This gets one or more page previews from that document.

 

updateVdpInfo 

Public Function updateVdpInfo(ByVal sessionID As String, ByVal dataFile() As Byte, 
  ByVal fileName As String, ByVal dataMap As dataMap, ByVal numVdpRecords As Integer) As Boolean
 
Summary:
 Update the VDP info in the session with the user provided data file and map.

Parameters:
 sessionID: The current session ID
 dataFile: Byte array containing the file data
 fileName: Filename used by the data (filename only, no path info)
 dataMap: The data map to be used
 numVdpRecords: Number of records from the variable data to be used in the preview.

 
Remarks:
 When a user is uploading a variable data file this call is made. It is also called again once the user has specified the mapping of field names in his file to field names used by the template.

 

getVdpDataFileFields 

 Public Function getVdpDataFileFields(ByVal sessionID As String) As String()
 
Summary:
 Return the field names from the data file in use.

Parameters:
 sessionID: The current session ID

Remarks:
 When the user has uploaded a variable data file (Excel or CSV format) this will inspect the file and return the field names from the top row.
 

getVdpDataFileInfo 

 Public Function getVdpDataFileInfo(ByVal sessionID As String) As vdpDataFileInfo
 
Summary:
 Return the number of records from, and a download link to the data file in use.

Parameters:
 sessionID: The current session ID

Remarks:
 The structure returned contains the total number of records in the data file, and a download link in case the file needs to be sent back to the client. Note: this is the only way to find the total number of records in the user's data file.
 

approveDocSession 

 Public Function approveDocSession(ByVal docSessionID As String) As approveDocSessionInfo
 
Summary:
 Marks the document as approved, so the production files can be generated

Parameters:
 docSessionID: the current session ID.

Return Values:
 Approval information structure.

Remarks:
 If the approval fails then null will be returned. 
 

reOpenSession 

 Public Function reOpenSession(ByVal docSessionID As String) As Boolean
 
Summary:
 Reopen a previously closed (i.e. approved) session.

Parameters:
 docSessionID: The session ID.

Remarks:
 

duplicateSession 

 Public Function duplicateSession(ByVal docSessionID As String) As String
Summary:
Duplicate a previous session.
 
Parameters:
docSessionID: Session ID to duplicate.
 
Return Values:
 The newly opened session ID

 
Remarks:
 You must already have the existing session ID. There is no function for retrieving a list of open sessions. 
 

getLibraryTemplates 

Public Function getLibraryTemplates(ByVal email As String, ByVal password As String) 
  As libraryTemplate()
 
Summary:
 Get the list of templates associated with a company.

 
Parameters:
 email: The company email.
 password: The company password.

 
Return Values:
 Array of libraryTemplate structures describing the templates associated with the company.
 Remarks:

 

getLibraryTemplates

Public Function getLibraryTemplates(ByVal email As String, ByVal password As String, 
  ByVal category As String) As libraryTemplate()
 
Summary:
 Get the list of templates associated with a company, filtered by category

 
Parameters:
 email: The company email.
 password: The company password.
 category: The category to filter by. Case sensitive.

 
Return Values:
 Array of libraryTemplate structures describing the templates associated with the company.

 
Remarks:
 

getLibraryTemplateInfo 

Public Function getLibraryTemplateInfo(ByVal docCode As String, ByVal docPassword 
  As String) As libraryTemplate
 
Summary:
 Get the template info for a single template identified by code and pwd

 
Parameters:
 docCode: GUID pointing to the eDoc template to be built.
 docPwd: Another GUID serving as password.

 
 

isSessionObsoleted 

 Public Function isSessionObsoleted(ByVal docSessionID As String) As Boolean
 
Summary:
Compare the session last modified date with the last modified date of the base template.
 
Parameters:
 docSessionID:

 
Return Values:
 True if the base template was modified more recently than the session.

 

getProofPDF 

Public Function getProofPDF(ByVal docSessionID As String, allVDP As Boolean) As String
 
Summary:
Retrieve URL to download proof PDF for the session.
 
Parameters:
docSessionID:
allVDP: If true then the proof PDF will contain all VDP records, If false, the proof PDF will contain only several first VDP records (usually 5)
 
Return Values:
On success, it returns the URL to download the proof PDF.
On error, it returns the error message prepended with "ERROR: " prefix.
 

getOrderFile 

Public Function getOrderFile(ByVal docSessionID As String, ByVal email As String,
  ByVal password As String) As String
 
Summary:
 Get the final product pdf for a document.

 
Parameters:
 docSessionID: the session ID
 email: associated company email
 password: associated company password. Can be passed as empty string if the template has been set to not require a password.

 
Return Values:
 A url for downloading the PDF

 
Remarks:
 For additional security, in addition to a valid sessionID, the correct company email and password must be included, unless
 the template specifies it is not required for this template.

 
 

STRUCTURES

sessionInfo 

Public Structure sessionInfo
Summary:
 Information about the current session.

 
Remarks:
 This is returned by the startDocSession or continueSession calls.

 
Members:
  • docName As String - Name of the eDoc document being worked on.
  • isUnBranded As Boolean - True if the session is unbranded
  • docSession As String - GUID of the document session.
  • numPages As Integer - Number of pages in the document.
  • pages() As pageInfo - Array of structures describing each page (RIA Clients Only)
  • dataMap As dataMap - Map of the variable data fields.
  • templateLockDown As TemplateLockDown - Frontend and change permissions for the template. (RIA Clients Only)
  • sessionImages() As background() - Array of structures describing each image that has been uploaded to the session
  • defaultPalette as PaletteInfo - Structure representing the default color palette for new text (RIA Clients Only)
  • fotoliaEnabled As Boolean
  • fotoliaAPIkey As String
  • fotoliaTabText As String
  • facebookEnabled As Boolean
  • facebookTabText As String
  • instagramEnabled As Boolean
  • instagramClientID As String
  • instagramTabText As String
  • defaultTextColor As String
  • fullScreenWindow As eDocLibrary.eRestriction
  • remote_tag As String
  • initialSize As String

dataMap

Public Class dataMap
Summary:
 Set of data field mappings from data file to eDoc template.

Remarks:
 The default datamap is returned by startDocSession, and when a user remaps fields it is returned in updateCurrentSession.

Members:
  • dataMapFields() As dataMapField - array of data field mappings

dataMapField

Public Structure dataMapField
Summary:
Mapping one data file field to eDoc field.
 
Remarks:
 
Members:
  • dataFileFieldName As String – what the field is called in the data file.
  • eDocFieldName As String - what the field is called in the template.
  • eDocFieldIsRequired As Boolean - whether this field is required for the template to be valid.

docClientInfo

Public Class docClientInfo
Summary:
 Information about an eDoc template.

Members:
  • palettes() As PaletteInfo - Array of structures describing every color palette used in the template.
  • inputForm() As formElement - Array of elements that make up the input form.
  • idFieldName As String - The name of the identifying field for this template
  • responseSetPrompt As String - The prompt that should be displayed near the select of response sets
  • responseSets() As responseSet - Array of response sets provided for this document
  • defaultPaletteID As Integer - Key for the palettes() map describing which palette is used for new text fields (and for the border color of new image fields). (RIA Clients Only)
  • defaultImageQualityRange() as Integer - Array of DPI levels representing the minimum DPI for Good, Acceptable, or Poor images (for new image fields). (RIA Clients Only)
  • defaultNewFieldLockdown As fieldLockDown - Structure representing the allowed operations for new text fields. (RIA Clients Only)
  • allowPDFProofDownload As Boolean - Whether the user should be offered a PDF proof of the document for downloading. (RIA Clients Only)
  • defaultFont as String - Which font to use for new text fields. (RIA Clients Only)
  • allowAutoPopulate As Boolean
  • fullScreenWindow As eRestriction
  • fotoliaEnabled As Boolean
  • fotoliaAPIkey As String
  • responseSetsFrom As System.Nullable(Of Integer)
  • defaultPalette As PaletteInfo
  • preventRasterQuantization As Boolean
  • fotoliaTabText As String
  • facebookEnabled As Boolean
  • facebookTabText As String
  • instagramEnabled As Boolean
  • instagramTabText As String
  • defaultTextColor As String

userEntries

Public Structure userEntries
Summary:
 Structure holding the field values submitted by the user.
 
Members:
  • elementName As String - Name of the field element.
  • elementReposition As String - Position of the element, overriding the template's default.
  • elementValue As String - Value entered/chosen by the user.
  • imageData() As Byte - Image data as a byte array.
  • textStyle As textElementOverride - Text style overriding the template's default. (RIA Clients Only)
  • lockdownField As fieldLockDown

docPreviewPage

Public Structure docPreviewPage
Summary:
 Structure that points to a generated preview image

Members:
  • largeURL As String – URL to the full sized image
  • pageNumber As Integer - Page number within the document
  • thumbURL As String - URL to the thumbnail sized image

vdpDataFileInfo

Public Structure vdpDataFileInfo
Summary:
 Structure that describes the variable data file that was uploaded

Members:
  • fileURL As String – URL for re-downloading the file
  • numRecords As Integer – number of records found in the file

formElement

Public Structure formElement
Summary:
 Information about a form element.

Remarks:
 Some of these fields are only used in RIA clients, not forms based clients.

Members:
  • elementAllowPositionOverride As Boolean - True if the element's position may be overridden.
  • elementEntryBlockInstructions As String - Instructions for the entry block (Appears before the first element in a new block.)
  • elementEntryBlockName As String - Name of the entry block the element belongs to.
  • elementEntryBlockNewLine As Boolean - Whether the element gets a newline within its entry block.
  • elementIsOptional As Boolean - True if the element is optional.
  • elementLockDown As fieldLockDown - Describes the types of changes that are allowed to this element. (not used by forms-based clients)
  • elementMaxLength As Integer - Maximum length of the element (if applicable)
  • elementName As String - Name of the element.
  • elementPageNumber As Integer - Page number on which the element appears.
  • elementPrompt As String - Text prompt for the element.
  • elementProtected As Boolean - Whether the element is protected (protected elements are hidden on ordinary clients, and only administrators using “privileged” clients are allowed to see them)
  • elementRect As String - Rectangle in which the element is bounded (four doubles separated by spaces, e.g. “100 100 250 350”, representing the left, bottom, right, and top sides of the rectangle)
  • elementReformatText As enumTextReformat - What sort of text reformatting the element may undergo (if any). The reformatting is handled by the server, so clients need not worry about it
  • elementReformatTextEveryTime As Boolean - Whether the element should be reformatted every time.
  • elementSortOrder As Integer - Specifies the order of elements on the UI form.
  • elementTextStyleOverride As textElementOverride - Text style override for the element (RIA Clients Only)
  • elementToolTip As String - Popup description for the element.
  • elementType As String - Type of UI control that should be used to represent the element to the user. Can be any of Textbox, TextArea, ddListSimple, standardImageUpload, advancedImageUpload, imagePicker, or HTMLBOX.
  • elementValue As String - Current value of the element. A string, URL, or filename.
  • formElementOption() As formElementOption - Array of options for a multiple choice element.
  • profileType As profileMap - How the client can prefill user profile information into the field. For example, if profileType = “fullname”, then the client should prefill this element with the end user's full name.
  • elementForceFit As Boolean
  • elementForceFitMaxLines As Integer
  • elementDefault As String
  • elementQualityRanges() As Integer
  • elementOpacity As Double
  • imageFitType As imageFitMethod
  • allowUploadFromAssets As Boolean
  • initialAssetCategory As String
  • palette As PaletteInfo
  • parent As docClientInfo
  • paletteID As Integer

formElementOption

Public Structure formElementOption
Summary:
 Information about a multiple choice option.

Members:
  • optionName As String
  • optionValue As String

approveDocSessionInfo

Public Structure approveDocSessionInfo
Summary:
 Approval information structure.

Members:
  • approvalStatus As Boolean – True if the document approval succeeded.
  • sessionIdentifier As String – session ID that was approved

libraryTemplate

Public Structure libraryTemplate
Summary:
 Library template information.

Members:
  • clientType As Byte - Which client to use. 0 = forms client, 1 = RIA client.
  • docBleed As Decimal - bleed of the document in inches
  • docCategory As String - Category for document
  • docDescription As String - Description of the document.
  • docHeight As Decimal - height of the document in inches
  • docID As System.Guid - ID of the document.
  • docName As String - Name of the document.
  • docPageCount As Integer - number of pages in the document
  • docPassword As System.Guid - Password for accessing the document.
  • docWidth As Decimal - width of the document in inches
  • userID As Integer
  • fullScreenWindow As eRestriction
  • isActive as boolean - Indicates if the template is marked as deleted or not
Related Topic: