Defines a Download file HTTP transaction.

A Download HTTP transaction is a Convertigo transaction based on HTTP requests. It allows to perform an HTTP request and get the response store in a file.
It is used to retrieve any data in HTTP protocol (non XML-based REST web service, image or file getting, etc.).
By default, files are downloaded in the current project _data/download/[random] directory, cleared at project initialization.
Note: HTTP connector supports OAuth authentication. To enable OAuth, you simply need to provide four variables to any kind of HTTP transaction: __header_oAuthKey, __header_oAuthSecret, __header_oAuthToken and __header_oAuthTokenSecret. For more information about OAuth in HTTP connector, refer to the following article in our Technical Blog: http://www.convertigo.com/en/how-to/technical-blog/entry/using-oauth-with-convertigo-http-connector.html
Dynamic parameter exists:
• __header_[name]: dynamically add a header name,
• __GET_[name]: dynamically add a GET parameter name,
• __POST_[name]: dynamically add a POST parameter name,
• __download_folder: dynamically set the file destination folder,
• __download_filename[name]: dynamically set the file destination filename,

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.
Auto remove file policy AutoRemoveFilePolicy standard Defines the policy for the file life cycle.
Policy that determine if the downloaded file should be removed and when:

• Don't remove: no automatic remove (but project initialization clear the _data/download folder),
• Context ending: auto remove the file when the current Context is destroyed,
• Session ending: auto remove the file when the current Session is destroyed.
Comment String standard Describes the object comment to include in the documentation report.
This property generally contains an explanation about the object.
File exists policy FileExistPolicy standard Defines the policy used if a file already exists.
Policy in case of file alredy exists can one of the following:

• Don't download: let the existing file and skip the download,
• Override: download over the existing file with no condition,
• Override if different size: download over the existing file if the size from the Content-Length header is different from the existing file,
• Override if newer: download over the existing file if the date from the Date header is different from the existing file,
• Increment filename download beside the existing file using a incremented filename.
Filename String standard Define the filename of the downloaded file.
Empty will use the tail of the current request.
Folder String standard Define the destination folder of the downloaded file.
Empty will download the file in the _data/download/[random] folder.
This path is either absolute or relative to Convertigo environment. Relative paths starting with:

• ./ are relative to Convertigo workspace,
• .// are relative to current project folder.
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 for the HTTP connection.
This property allows to define the sub path, relative to the connector root path, to the target web service 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.
The transaction sub path can be parameterized with the transaction’s variables, to be dynamically configured at runtime with variable values. To use transaction variables in the sub path, use following syntaxe:
• the simple-brace notation - variable name surrounded by curly braces : /subdir/{variable_name}.jsp.
Use Content-Disposition boolean standard Define if the filename is extracted from the Content-Disposition header.
If true, the filename comes from the Content-Disposition header. If false or there is no header, the filename comes from the Filename property.
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.
This property allows to define the request Header Fields to be sent with the request to the target web service method.
For each header, two columns have to be set:

• Variable: HTTP header name (ex: Content-Type).
• Value: HTTP header value (ex: application/x-www-from-urlencoded).

The “Content-Type” header of this property can be overridden with a __contentType variable.
Note: A new HTTP header can be added to the list using the blue keyboard icon. The HTTP headers defined in the list can be ordered using the arrow up and arrow down buttons, or deleted using the red cross icon.
HTTP info boolean expert Defines whether to include HTTP information in output XML.
HTTP information can be added to the transaction’s output XML, such as the request URL, HTTP status code and the HTTP request and response headers. You can also have the raw HTTP data in case of error.
The HTTP info property allows to define whether these information have to be inserted in the transaction’s output XML (value set to true) or not (value set to false).
Default value is false.
HTTP info tagname String expert Defines the tagname of the element containing the HTTP info in output XML.
When the HTTP info property defines to insert the HTTP information in the transaction’s output XML, the HTTP info tagname property allows the programmer to define the tagname of the element containing these information.
Default value is HttpInfo.
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.
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.
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.