Transflo DMS Web Service API

This section describes the basic steps for programming with the TRANSFLO® Web Service Interface API.

1. Initialize the session.

2. Send authentication parameters.

3. Create a batch of document images.

4. Assign meta-data to the batch.

5. Submit batch.

6. Log Out and end session.

The following table lists the supported exposed methods and parameters of the TRANSFLO® Web Service Interface API.

Web Method	Parameters	Out Parameters	Properties/Description
Authenticate	string userName string password int applicationId string machineName DateTime clientCrc string sessionId		Overloaded web method for .NET
AuthenticateTF			Same as Authenticate for other technologies other than .NET
SendKeepAlive	string sessionId DateTime clientCrc	enum lockSignal	lockSignal will not be used
SaveBatch	string sessionId boolean releaseLock	string Confirmation Number	Used with zip DIME attachment. Note:releaseLock is always true for new batches
SaveBatch	string sessionId boolean releaseLock dataset BatchDataSet		Overloaded SaveBatch method. Primarily used for BatchDataSet updates where the images have already been saved.
GetNextBatchBy QueueAndAlias	string sessionId int queueId int aliasId bool getDocActivityFlag BatchFilterItem[] filter	dataset BatchDataSet	Used to retrieve the next batch in a specific queue that belongs to a specific alias.
GetNextBatchBy Queue	string sessionId int queueId bool getDocActivityFlag BatchFilterItem[] filter	dataset BatchDataSet	Used to retrieve the next batch in a specific queue.
GetBatchData List	string sessionId int queueId int aliased BatchFilterItem[] filter	dataset BatchListDataSet	Used to get a list of Batches and associated document data.
GetBatchBy QueueId	string sessionId long batchId int queueId bool getDocActivityFlag BatchFilterItem[] filter	dataset BatchDataSet	Used to retrieve a specific batch.
GetDocuments	string sessionId, long[] docIdArray, long batchId, int customerId, SoapContext responseSoapContext	Response with a list of DIME attachments per each item in the docIdArray.	Used to extract document images.

If using .Net, the web method name is Authenticate. If using another technology, it is AuthenticateTF. This is due to overloading on the server side. It is preferable to use the TRANSLFO® Client API, because it will absorb and hide all internals of our web services. This is critical especially as we advance and evolve our suite of services.

This method accepts the following parameters:

• userName string

• password string

• applicationId int, value = 15

• machineName string

• clientCrc datetime, by Ref

• sessionId string; the sessionId returned from the Authenticate web method. The client must persist this value and return it every time.

This method returns ConfigDataSet XML that contains all necessary information required for validation prior to submitting the batch to TRANSFLO® Server.

Examples

// Call Authenticate (TF) method to establish that the soap header authentication can be // done with issue and to download any new configurations from the server.

// ConfigDataSet data can be used to validate that the appropriate Fleet and field values // are being assigned before submission to the server to avoid batch failure on the // server.cds = tfws.Authenticate("jsmith", "mypassword", 15, "jsmithxp", ref cdt, out session);

//ConfigDataSet contains all Fleets and fields that this user has permissions to.

MessageBox.Show(string.Format("Fleets found = {0}. config dated {1}", cds.doc_class.Rows.Count, cdt));

//Compacting the DataSet to make it easier to read.

ChangeColumnMapping(cds);

//Saving DataSet as xml file for review.

cds.WriteXml(@"c:\temp\ConfigDataSet.xml", XmlWriteMode.WriteSchema);

The SendKeepAlive method is used to let the server know that this client is still alive and it also allows the server to deliver any new configuration back to the client. The client can update the local copy of the configuration with the new configuration. If no new configuration is available then this method will return NULL. The SendKeepAlive method is also used for early validation to avoid any server errors due to invalid data.

This method takes the following parameters:

• sessionId – string. This is the sessionId returned from the Authenticate web method. The client must persist this value and return it every time.

• clientCrc – DateTime. This parameter must pass the same datetime received earlier during the previous Authenticate method or the previous SendKeepAlive method call. This value is compared against the server config date time and if a new configuration is available it is automatically returned. If a new configuration is not available it will return NULL.

• lockSignal – out parameter – enum. This enum is included in the WSDL and is called DatabaseError. You pass the value DatabaseError.NoError.

The method returns a ConfigDataSet if the configuration has changed and NULL if not.

Examples

// lockSignal is not going to be used for this service. so just supply a return value

// and ignore it.

DatabaseError lockSignal = DatabaseError.NoError;

// calling this method will evaluate the datetime returned earlier by the initial.

// authenticate then if a new config exists on server it will be downloaded.

ConfigDataSet newCds = tfws.SendKeepAlive(session, ref cdt, out lockSignal);

// if new config is present update local set

if (newCds != null)

cds = newCds;

The diagram in Fig 3.2 ConfigDataSet contains the most important pieces of the ConfigDataSet.xml that is returned by SendKeepAlive and is used to validate.

Data Table	Description
customer	The customer table contains a list of all customers that the authenticated credentials are allowed to scan for.
doc_class	The doc_class table contains a list of all Fleets that the authenticated credentials are allowed to scan for.
alias	The alias table is the same as the doc_class table in this context. These 2 tables contain the same ids for the same names. In some cases the alias_id will be used instead of the doc_class_id. (The reason for these two tables is that other TRANSFLO® services require multiple aliases for each doc_class.)
field_def	The field_def table contains any field configurations for each doc_class (fleet).
queue	The queue table is used for routing by other TRANSFLO® services but is not used in this context. Routing occurs on PTC server.
doc_type	The doc_type table is used to provide a list of configured document types for the driver to assign to each document. This is an optional feature.

Table 3.2 ConfigDataSet Description

The SaveBatch method is used to upload and trigger the upload and save of the batch. The TRANSFLO® Web Service uses Microsoft Web Services Enhancements WSE version 2.0 to upload binary batches to the TRANSFLO® Server using DIME Direct Internet Message Encapsulation (DIME) is the binary message format used by the TRANSFLO® Web Service Interface to transmit document batches and associated metadata. technology.

• You must have Microsoft.web.services2.dll in your references to use DIME attachments.

• The reference.cs file must use the Microsoft.Web.Services2.WebServicesClientProtocol class instead of the System class.

• The batch must be submitted as a compressed ZIP file containing the batch dataset xml file and all the corresponding TIFF image files. The xml for the batch contains the schema as well.

• The schema has a standard section that is the same for all fleet configurations. There is also a variable portion that changes depending on the fields defined for the fleet.

Examples

The following example demonstrates the steps used to upload a Batch ZIP file to the TRANSFLO® Server:

// Prepare the DIME attachment.

AttachmentCollection attachments = new AttachmentCollection();

TypeFormat typeFormat = TypeFormat.MediaType;

string zipFileName = @"c:\temp\Batch.zip";

DimeAttachment batchDime = new DimeAttachment("zip", typeFormat, zipFileName);

// Guid is assigned to every batch from the client side, this is the unique identifier of

// a batch. Guid is referenced here and in the XML file inside the zip. this Guid is

// evaluated on the server to avoid duplicate batches.

// If the same guid has been already received and saved on the server, the server will

// not save again and will simply return the previously saved confirmation number.

batchDime.Id = "118ee23bc5b347bab98fc3e00a10462b";

attachments.Add(batchDime);

// Add DIME attachement to Soap Context.

SoapContext soapContext = tfws.RequestSoapContext;

soapContext.Attachments.AddRange(attachments);

// Save Batch method called to trigger the save of the uploaded batch attachment.

string confNumber = tfws.SaveBatch(session, true);

The Confirmation number returned from the server represents a successful batch transmission and can then be returned to the driver for a receipt or for the driver’s records.

This number can be used to look up the driver’s batch online via the TFX Services Confirmation Viewer.

The diagram in Fig. 3.3 Batch Dataset for Save WebMethods shows the contents of the BatchDataSet schema.

The BatchDataSet schema contains a static portion and a dynamic portion.

The static Data Tables are batch, Doc and DocActivity.

The dynamic Data Tables are DocDataPerm and DocDataTemp.

DocDataTemp can be ignored since it will not be used here.

DocDataPerm is dynamic due to the different field configurations that each fleet has.

This table needs to be created using the following pattern:

Table Name: DocDataPermD22 – the number after the letter is based on the value identifier for that fleet.

In the ConfigDataSet all Fleets are referred to as “doc_class”.

Therefore the number after the DocDataPermD### refers to one of the IDs in the doc_class table in the ConfigDataSet.xml.

This ID value must be the one corresponding to the fleet that this batch belongs to.

The following table describes the details of the BatchDataSet object. Data Columns in the static Data Tables that are not listed in the previous section (ConfigDataSet) can be ignored or set to the default value in the schema if the Data Column is defined as “Not NULL”.

Data Table	Data Column	Data Type	Description
Batch	Typically contains one row for the batch being uploaded.
	id	long	The number assigned to a batch. Must be a negative number for new batches.
	name	string	This value can be the same as batch_guid.
	batch_guid	string	Must be a newly generated guid.
	alias_id	int	The alias_id that represents the fleet this can be looked up from the config dataset.
	origin_datetime	dateTime	The datetime when the batch was scanned in client local time.
	queue_id	int	Assign value = 1.
	origin_user_name	string	The user name performing scan of documents, ignore if not available.
	origin_module_id	int	Assign value = 27.
	origin_machine_name	string	The actual machine/device name where the scanning was done.
Doc	Must be one row for each document In Transflo DMS, a document is an image file of a scanned page usually stored as a black and white TIFF image. being sent in the batch.
	Id	long	The number assigned to document. Must be negative number for new documents.
	batch_id	long	The number assigned for the batch (negative) batch.id.
	doc_file_name	string	The actual file name in the zip file typically this is 1.tif, 2.tif, etc…
	doc_type_id	int	The id of the doc_type assigned can be looked up from the ConfigDataSet doc_type table value for id column.
	page_count	int	The number of page in each document. In this case it will always be 1.
	order_in_batch	int	Scan order of document in the batch. This must be correct and preferably matching to the file name order 1 matches 1.tif.
	revision	int	Assign value = 0. Revision number of document. In this case it will always be 0.
	command	string	1 in this case we are always inserting.
DocActivity	Must be one or more rows for each document describing what happened to each document.
	Id	long	Number assigned to each activity. Must be negative number.
	doc_id	long	Doc.id value assigned for the document above.
	activity_type_id	int	Value of the type of activity.
	doc_class_id	int	Represents the fleet id should be same as alias id in this case and can get it from ConfigDataSet Doc_Class table.
	doc_type_id	int	The id of the doc_type assigned can be looked up from the ConfigDataSet doc_type table value for id column.
	complete_datetime	dateTime	Scan complete local datetime for this document, if not able to get scan complete datetime for each document, then use the same value for all documents.
	duration_ms	int	Milliseconds taken to scan each document per document, if can’t get duration of each document, then get the total time and divide by number of documents.
DocDataPermD##	Must be one row for each document. This is the dynamic table that contains any custom index fields for this batch as defined by the field_def table in ConfigDataSet.
	doc_id	long	Doc.id value assigned for the document above.
	All data columns that are configured in field_def in ConfigDataSet that have been populated by the user. If no data was populated for a field, then do not reference that field. (See BatchDataSet Schema for DocDataPerm Data Tables below.)

BatchDataSet Schema for DocDataPerm Data Tables

The BatchDataSet Schema for DocDataPerm Data Tables must also be added to the batch.xml.

This schema is as follows:

<xs:element name="DocDataPermD2">

<xs:complexType>

<xs:attribute name="doc_id" form="unqualified" type="xs:long" use="required" />

<xs:attribute name="fieldb" form="unqualified" msdata:Caption="FieldB" msprop:DocClassId="2">

<xs:simpleType>

<xs:restriction base="xs:string">

<xs:maxLength value="10" />

</xs:restriction>

</xs:simpleType>

</xs:attribute>

<xs:attribute name="fieldc" form="unqualified" msdata:Caption="FieldC" msprop:DocClassId="2">

<xs:simpleType>

<xs:restriction base="xs:string">

<xs:maxLength value="10" />

</xs:restriction>

</xs:simpleType>

</xs:attribute>

</xs:complexType>

</xs:element>

</xs:complexType>

<xs:unique name="DocDataPermD2_BatchDataSetKey4" msdata:ConstraintName="BatchDataSetKey4" msdata:PrimaryKey="true">

<xs:selector xpath=".//mstns:DocDataPermD2" />

<xs:field xpath="@doc_id" />

</xs:unique>

<xs:unique name="DocDataTempD2_BatchDataSetKey3" msdata:ConstraintName="BatchDataSetKey3" msdata:PrimaryKey="true">

<xs:selector xpath=".//mstns:DocDataTempD2" />

<xs:field xpath="@doc_id" />

</xs:unique>

<xs:keyref name="DocDataTempD2_fkDocDocDataTemp" refer="pkey_tf_doc" msdata:ConstraintOnly="true">

<xs:selector xpath=".//mstns:DocDataTempD2" />

<xs:field xpath="@doc_id" />

</xs:keyref>

<xs:keyref name="DocDataPermD2_fkDocDocDataPerm" refer="pkey_tf_doc" msdata:ConstraintOnly="true">

<xs:selector xpath=".//mstns:DocDataPermD2" />

<xs:field xpath="@doc_id" />

</xs:keyref>

This method retrieves the next batch in the system from a specific queue that belongs to a specific alias. It can only return the next batch that is not locked by another session or user.

This method accepts the following parameters:

• string sessionId. This is the sessionId returned from the Authenticate web method. The client must persist this value and return it every time.

• int queueId

• int aliasId

• bool getDocActivityFlag

• BatchFilterItem[] filter

This method returns BatchDataSet XML.

Example

The example below shows the structure of the BatchFilterItem[] parameter. This same structure is used by GetNextBatchByQueue, GetBatchDataList, and GetBatchByQueueId.

struct BatchFilterItem

{

BatchFilterType FilterType {get; set;}

string FilterValue {get; set;}

string FilterFieldName {get; set;}

Operator FilterOperator {get; set;}

}

enum BatchFilterType

{

None = 0,

// LastActivityIsNot is not going to be used for this service. so just supply a //return value and ignore it.

LastActivityIsNot = 1,

//The BatchFilterType of DocDataField is used to filter by a Batch Data field.

DocDataField = 2,

//The BatchFilterType of DocType is used to filter by Document Type.

DocType = 3

}

enum Operator

{

None = 0,

Equal = 1,

LessThan,

LessThanOrEqual,

GreaterThan,

GreaterThanOrEqual,

Contains,

StartsWith,

EndsWith

}

BatchDataSet Returned by GetNextBatchByQueueAndAlias

The BatchDataSet that is returned by GetNextBatchByQueueAndAlias is shown below. The data set is also returned by GetNextBatchByQueue, GetBatchDataList, and GetBatchByQueueId WebMethods.

The following table provides details about the BatchDataSet returned by GetNextBatchByQueueAndAlias, GetNextBatchByQueue, GetBatchDataList, and GetBatchByQueueId WebMethods.

Data Table	Data Column	Data Type	Description
Batch	Typically contains one row for the returned batch.
	id	long	The number assigned to a batch.
	name	string	This value can be the same as batch_guid.
	batch_guid	string	The batch guid.
	local_insert_datetime	dateTime	The date the batch was saved in the TRANSFLO® database.
	page_count	int	The total number of pages in the batch.
	not_indexed_page_ count	int	The total number of pages that have not yet been indexed.
	alias_id	long	Alias that the batch belongs to.
Doc	Must be one row for each document being sent in the batch.
	tf_batch_Id	long	The id assigned to the batch in the Batch DataTable. Must be negative number for new documents.
	last_activity_comment	string	Comment attached to the document

The GetNextBatchByQueue WebMethod allows for the retrieval of the next batch on the from the TRANSFLO® Server from a specific queue.

It can only return the next batch that is not locked by another session or user.

This method accepts the following parameters:

• string sessionId. This is the sessionId returned from the Authenticate web method. The client must persist this value and return it every time.

• int queueId

• bool getDocActivityFlag

• BatchFilterItem[] filter

This method returns the BatchDataSet XML.

The GetBatchDataList WebMethod is used to get a list of batches and associated document data from the TRANSFLO® Server.

This method accepts the following parameters:

• string sessionId. This is the sessionId returned from the Authenticate web method. The client must persist this value and return it every time.

• int queueId

• int aliased

• BatchFilterItem[] filter

This method returns XML for the BatchListDataSet.

The GetBatchByQueueId WebMethod is used to retrieve a specific batch from the TRANSFLO® Server.

This method accepts the following parameters:

• string sessionId. This is the sessionId returned from the Authenticate web method. The client must persist this value and return it every time.

• long batchId

• int queueId

• bool getDocActivityFlag

• BatchFilterItem[] filter

This method returns a BatchDataSet XML files that contains all information for the batch that is being retrieved from the TRANSFLO® Server.

This method accepts the following parameters:

• string sessionId. This is the sessionId returned from the Authenticate web method. The client must persist this value and return it every time.

• long[] docIdArray

• long batchId

• int customerId

• SoapContext responseSoapContext

The response to this WebMethod call contains a set of DIME Direct Internet Message Encapsulation (DIME) is the binary message format used by the TRANSFLO® Web Service Interface to transmit document batches and associated metadata. attachments per each item in the docIdArray. These DIME attachments are a set of images returned by the WebMethod.