eDocBuilder has three SOAP web services APIs available.
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.
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.