HTML transaction | Convertigo Documentation

Defines an HTML transaction.

As regards web applications, Convertigo’s basic principle is to:

• connect to websites,
• detect defined screen classes and navigate through web pages,
• extract web page data using screen class-specific extraction rules,
• treat extracted data in order to generate an XML document structured as required.

This process defines the notion of HTML transaction.
HTML transactions are based on input variables, as other transactions. They execute actions that are programmed using event handlers and statements, they are designed to handle web pages navigation. HTML Transactions return data in an XML structure resulting from automated navigation on the target website and extraction rules execution on these pages or, in the case of Web Clipper extraction rule, clip required HTML parts of the web pages.
A Convertigo project can contain several HTML transactions, each of them being exposed as standard REST or SOAP web service method.

Property	Type	Category	Description
Accessibility	Accessibility	standard	Defines the transaction/sequence accessibility. This property can take the following values: • Public: The transaction/sequence is runnable from everyone and everywhere, visible in the Test Platform and is also exposed in the SOAP WSDL as a web service method. • Hidden: The transaction/sequence is runnable but only from people who know the execution URL, not visible in the Test Platform nor exposed in the SOAP WSDL. • Private: The transaction/sequence is only runnable from within the Convertigo engine (Call Transaction/(Call Sequence steps), is not visible in the Test Platform and cannot be requested as SOAP web service method. This value is used for tests, unfinished transactions/sequences or functionalities not to be exposed. Private transactions/sequences remain runnable in the Studio, for the developer to be able to test its developments. Note: In the Test Platform: • The administrator user (authenticated in Administration Console or Test Platform) can see and run all transactions / sequences, no matter what their accessibility is. • The test user (authenticated in the Test Platform or in case of anonymous access) can see and run public transactions/sequences and run hidden ones if he knows their execution URL.
Comment	String	standard	Describes the object comment to include in the documentation report. This property generally contains an explanation about the object.
HTTP response in CDATA	boolean	standard	Defines if the string result must be in a CDATA under the root Element or in a simple TextNode. If ‘true’, CDATA is used and the string content isn’t modified. If ‘false’, TextNode is used and the string content is automatically XML encoded.
HTTP string charset	String	standard	Defines the charset use to decode the data string received through the HTTP connector. Works only for ‘HTTP data encoding’ in ‘string’ mode. If blank, the charset is retrieve from the response header if any else ‘ascii’ is used.
HTTP verb	HttpMethodType	standard	Defines the HTTP verb to use for this HTTP request: GET, POST, PUT, DELETE, HEAD, TRACE, OPTIONS or CONNECT. For more information about HTTP verbs, you can visit the following RFC page: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html.
Response timeout	long	standard	Defines the response maximum waiting time (in seconds). Maximum time (in seconds) for a transaction/sequence to run. When specified time is reached, the transaction/sequence ends and returns a timeout error. If requested through the SOAP interface, the error is returned as a SOAP exception.
Sub path	String	standard	Defines the end of the path to use for connecting to the target web page. HTML transaction can connect automatically to a target web page without using a specific statement (see the Maintain connector state property). The Sub path property allows to define the sub path, relative to the connector root path, to connect to the target web page URI. For example, if the target is: http://server/MyApp/targetpage.jsp, the connector server would be: server, the connector root path: /MyApp and the transaction sub path: /targetpage.jsp.
Add statistics to response	boolean	expert	Defines whether some statistics of execution of the transaction/sequence should be added as data in the transaction/sequence’s response. If this property is set to true, the transaction/sequence response will be enhanced with the statistics data of its execution (total time for the request, time spent waiting for the mainframe, etc.). Note: This property has nothing to do with the general property of the Convertigo engine Insert statistics in the generated document that can be edited in the Configuration page of the Administration Console.
Allow Download Attachment	boolean	expert	Defines if files of multipart response must be written. If the property is true, the attachments are written on temporary files. In SOAP, create an <attachment> tag for each attachment directly under the corresponding <xop:Include> element.
Authenticated context required	boolean	expert	Defines whether an authenticated context is required to execute the transaction/sequence. If this property is set to true, the context of execution of the transaction/sequence must have been authenticated. Otherwise, the transaction/sequence is not executed. Default value is false for a standard access to transactions/sequences. Notes: • When a context is authenticated, all the contexts in the same HTTP session are also authenticated. For more information about context and HTTP session, see Context general presentation paragraph in JavaScript Objects APIs chapter. • When executing a transaction/sequence from stub (__stub variable passed to true in entry), this property is ignored. Indeed, executing from stub is for testing purposes and should not require any authentication: the context would never be authenticated as the transaction/sequence setting the context as authenticated could also be executed from stub.
Authenticated user as cache key	boolean	expert	Defines whether the authenticated user should be used as cache key. When the cache is enabled (Response lifetime setting filled with a time-to-live), the Authenticated user as cache key property allows to specify to use the authenticated user ID from context/session as an additional key to the cache. It would have as effect that two different identified users cannot retrieve the cached response of the other for the same request. Default value is false: the authenticated user is not used as cache key.
Call the biller	boolean	expert	Defines whether the billing management module should be called for each generated XML document. If this property is set to true, the applicable billing management module, defined thanks to the connector’s billing class name property, is invoqued. This parameter should never be changed (Convertigo private use only).
Character set	String	expert	Defines the character set used for operations on the generated XML document (default: UTF-8).
Custom HTTP verb	String	expert	Defines a custom HTTP verb that override the HTTP verb selected. This property allows to override the verb of HTTP verb but inherit its behavior. Does nothing if empty.
Follow Redirect	boolean	expert	Defines if the transaction automatically follow the redirect. If the property is true, a new request is done to the new URL defined by the Location header. If the property is false and a redirect occurs, the result will be empty so we recommend to enable the HttpInfo property.
HTTP Pool	HttpPool	expert	Defines the HTTP pool policy for connection reuse. Possible values: • no: create a new connection for each request • context: pool connection for the current convertigo context • session: pool connection for the current http session • global: pool connection for the whole server Default value is global.
HTTP headers	XMLVector	expert	Defines HTTP headers to be sent. HTML transaction can connect automatically to a target web page without using a specific statement (see the Maintain connector state property). The HTTP headers property allows to define the request Header Fields to be sent with the request to connect to the target web page. For each header, two colums have to be parametered: • Variable: HTTP header name (ex: Content-Type). • Value: HTTP header value (ex: application/x-www-from-urlencoded).
Handles cookies	boolean	expert	Defines whether cookies must be handled. If set to true (default value), the transaction maintains cookies in Convertigo’s context. Default value should not be changed unless you specifically want the transaction to ignore cookies while browsing.
Include certificate group	boolean	expert	Includes the certificate group into the cache key. If set to true, the certificate group is added to the cache key which is used to determine whether the transaction’s response should be pulled from the cache or not. A transaction’s cached response is pulled from the cache when all cache key values are corresponding to a stored cache entry.
Maintains connector state	boolean	expert	Defines whether the connector state must be maintained between transactions. If set to false (default value), each time the transaction is executed, it connects the connector browser to the target web page specified in the Sub path property using the HTTP headers property for headers, and the Synchronization property to synchronize on the accessed page. If set to true, the transaction maintains the connector state, i.e. uses the browser in the state in which it has been left when the preceding transaction ended.
Request template	String	expert	Defines the request body template file path. HTTP request sent by the transaction can contain data in its body. This data is based on a user-defined template file, which can be: • an XML file describing the content of the HTTP request body, possibly including transaction input variables in the data structure, • an XSL file used to transform the variable-based transaction input XML to generate the content of the HTTP request body. This property allows to define the path of the template file, it is either: • a local file, by default relative to the project’s directory, or to the project’s current subfolder, • a local file relative to the Convertigo webapp common templates directory, • an absolute path. If the template file is an XML file, it can contain transaction variables identified with a specific syntax in the XML and dynamically replaced at runtime with received variable values. The syntax to use in the XML template file to refer to a transaction variable is the following: • $(<variableHttpName>): this simple notation starts with a $ character and then includes between brackets the HTTP name of the variable. Beware that the HTTP name of the variable can be different from the variable name (see Variable objects documentation). • $(<variableHttpName>)concat: this notation is very similar to the preceding, excepted that the last bracket is followed by the concat keyword. It starts by a $ character and includes between brackets the HTTP name of the variable, that should be in this case a Multi-valued variable. The concat keyword implies that all values received in the Multi-valued variable must be concatenated before replacing this notation by this computed value in the template XML. • $(<variableHttpName>): this notation is identical to the first notation, but the behavior is different for a Multi-valued variable. The tag surrounding this notation in the template XML is duplicated for each value in the Multi-valued variable.
Response client cache	boolean	expert	Defines whether the transaction/sequence response should be cached by the client. If set to false, the response XML is sent to the client along with HTTP headers forcing the client browser not to store it in its local cache. This is the default value, since dynamic responses are usually preferred. If set to true, the XML response is sent normally.
Response lifetime	String	expert	Defines the response time-to-live (in seconds) in cache, i.e. the time during which the cached response remains valid or time interval for its renewal. This property enables the cache when filled, disables the cache when left empty. The Response lifetime property allows to specify the cache settings for the transaction/sequence’s response. It can be set to the following values: • <empty>: Disables the cache for the transaction/sequence. The response will not be cached and each request will execute the complete transaction. It is the default value. • absolute,<time in secs>: Enables the cache for the transaction/sequence. The response will be cached for the time specified in seconds. If an other request with the same parameters occurs within this time, the response will be returned from the cache. • daily,hh:mm:ss: Enables the cache for the transaction/sequence. The response will be cached until hh:mm:ss of the current day is reached. If an other request with the same parameters occurs before this time, the response will be returned from the cache. A new day starts at 00:00:00. • weekly,hh:mm:ss,w: Enables the cache for the transaction/sequence. The response will be cached until hh:mm:ss of the wth day of week is reached. For Sunday w = 1, for Monday w = 2 … and for Saturday w = 7. If an other request with the same parameters occurs before this time, the response will be returned from the cache. A new day starts at 00:00:00. • monthly,hh:mm:ss,d: Enables the cache for the transaction/sequence. The response will be cached until hh:mm:ss of the dth day of month is reached. If an other request with the same parameters occurs before this time, the response will be returned from the cache. A new day starts at 00:00:00. Notes: • The Response lifetime property editor proposes a Generator tool that can help you configure the Response lifetime setting. • The Variable objects contain the Cache key property that allows to specify to use this variable as a key to the cache or not. See Variable objects documentation for more information.
Secure connection required	boolean	expert	Defines whether the transaction/sequence should be called through a secured connection (e.g. HTTPS). Depending on the requester, if this property is set to true, the transaction/sequence must be accessed through a secure connection (e.g. HTTPS in case of HTTP access). Default value is false for a standard access to transactions/sequences.
Style sheet	int	expert	Defines how the XML returned by the transaction has to be processed by XSLT. This property can take the following values: • None: Do not process with XSLT. Usual setting for web services (SOAP or REST) where plain XML data is to be returned. • From transaction: Use the XSL style sheet attached to the transaction. When used, make sure a style sheet object is added to the transaction. • From last detected screen class: Use XSL style sheet attached to the last detected screen class (in case of a transaction with screen classes). Transactions using sheets from last detected screen class are mainly used in Web Clipping or Legacy Publishing projects.
Synchronization	TriggerXMLizer	expert	Defines how to synchronize the transaction. HTML transactions can connect automatically (without using any specific statement) to a target web page (see the Maintain connector state property). This property allows to specify which type of synchronizer is used in the connection process. A synchronizer states how and when accessed pages are considered fully loaded. Only then are data extracted and new pages re-detected. There are several types of synchronizers, that are described hereafter: • Document completed: The synchronizer waits for a number of documents to be completed. Specify here how many “document completed” events Convertigo has to wait for before assuming that the page is complete. In many cases, when the target application uses HTTP META redirects or JavaScript redirects, the document is loaded several times. You can monitor ==== start parse ====== and ==== Parse end ==(XXXms )==================== traces in the Engine console (debug mode) to count the number of “document completed” events needed for the synchronizer. The Document completed synchronizer can be configured to also stop on alert messages that could pop up. Alert messages do not trigger a “document completed” event and are not detected by this synchronizer. To activate this option, check the Stop on alert checkbox. • XPath: The synchronizer waits until a specified XPath is found. Convertigo tries to evaluate the specified XPath while receiving a web page or executing JavaScript in it. Once the XPath matches at least one node of the page, the synchronizer returns. • Wait time: The synchronizer waits until a specified time is reached (in ms, set via the Timeout property). • Screen Class: The synchronizer waits for one of the selected screen classes to be detected. Several screen classes can be selected to be waited for. The synchronizer returns when one of them is reached. • Download started: The synchronizer waits for a download request. This is the perfect synchronizer to use before a Get attachment statement. • No wait: The synchronizer doesn’t wait and execution proceeds directly. For all synchronizer types, the maximum waiting time is set using the Timeout property.
URL charset encoding	String	expert	Defines the charset encoding to use for the variable values sent as parameters in HTTP request. This property allows to define the charset encoding used to URL-encode the parameter values: • GET parameters for the query string, • POST parameters in case of application/x-www-form-urlencoded content-type. Default value is blank. If blank, the parent connector’s Default URL charset encoding property value is used.