Interfaces to Convertigo

HTTP protocol interface to Convertigo

Convertigo projects contain “requestable” objects, transactions and sequences, that can be invoked by HTTP protocol. This section describes possible URLs to access Convertigo projects and all reserved variables usable in these URLs.

• Convertigo URLs
• Convertigo reserved parameters

Convertigo URLs

General process

The following general process describes the HTTP protocol used from the client (web browser or application) to the Convertigo server.

1. The client issues an HTTP request to Convertigo to the following root URL :

• ConvertigoServer is the host name or IP address of your Convertigo server, with possibly a port number.
  • A local Convertigo Studio has as host name localhost and, in HTTP, 18080 as default port number, in HTTPS, 18081 as default port number.
  • A Convertigo Server installed locally on your computer shares the same host name: localhost. The Convertigo Server default port number is 28080 for HTTP and 28443 for HTTPS.
  • When installed in an existing application server, it has as IP address and ports the IP address and ports of the application server.
  • A Convertigo Cloud server is accessed through its server name, for example: me.convertigo.net (no port to provide in this case, either for HTTP or HTTPS).
• ConvertigoAppName defines the name of the Convertigo web application.
  • A local Convertigo Studio or a Convertigo Server installed locally has convertigo as Convertigo app name.
  • A Convertigo Cloud server has cems as Convertigo app name.
• ProjectName defines the name of the project you want to invoke in Convertigo. If the project doesn’t exist, the application server generates an error (HTTP 404 Not Found).
• ConvertigoRequester defines the requester to use on the Convertigo server. It can take several values that are described further (see “Convertigo requesters”).

For example, with a project named test_project in a local Convertigo Studio:

• ConvertigoServer = localhost:18080
• ConvertigoAppName = convertigo
• ProjectName = test_project

2. This HTTP request can use the following HTTP verbs: GET, POST, PUT, DELETE, HEAD. Convertigo would handle all these verbs the same way, by executing the called transaction / sequence. Only HEAD verb will have a different result, see point 4 of this procedure.

3. The root URL can be followed by a query string, possibly -containing reserved variables and variables to be passed to the invoked transaction / sequence. These variables may also be passed in POST data.

4. Convertigo handles the request, executing the requested transaction / sequence, and returns the response to the client.

• Depending on the invoked requester, the response can contain different documents and formats, see Convertigo requesters.
• Depending on the HTTP verb used in the request, the response may be different: HEAD verb will only return headers in response (following HTTP specifications).

5. The client (web browser or application) retrieves and manages the response, also depending on the invoked requester and the project’s parametrization.

Convertigo Requesters

Several requesters can be invoked in Convertigo to execute a transaction / sequence. This section explains in details the different values that can be passed in ConvertigoRequester part of the URL.

Weblib requester

This requester is invoked by calling the index.html file of the project, i.e. setting the ConvertigoRequester at the end of the URL to index.html.

For example, with a project named test_project in a local Convertigo studio, the URL to call a transaction / sequence is:

The weblib requester automatically includes a complete JavaScript AJAX library based on JQuery that allows:

• invoking Convertigo transactions / sequences / project resources,
• managing the Convertigo responses,
• performing XSL transformation (if necessary),
• encoding request parameters,
• sequencing several calls to Convertigo,
• including in a portal the widget generated from the transaction / sequence response,
• developing interactions between widgets,
• etc.

The client requests the project’s index, its request is handled by the JavaScript library, which performs an AJAX call to Convertigo engine and handles the response.

Some parametrization of this library framework can be performed by updating global variables values. Lots of these variables can be configured thanks to weblib reserved variables, that have to be passed in the request. For more information about weblib specific parameters, see Weblib reserved parameters.

The parametrization of the engine request, i.e. the definition of the transaction / sequence to call, etc. is done by using engine reserved variables. For more information about engine specific parameters, see Engine reserved parameters.

XML requesters

These requesters are invoked by setting the ConvertigoRequester at the end of the URL to the following expression:

< PoolName>.< Extension>.

• PoolName defines the name of the pool to invoke, in the case of pools use in the project. It is an optionnal parameter, it can be empty. Any value can be passed in this part of the URL: if a matching pool is found, it is used by Convertigo, if no pool is found, it is ignored and Convertigo returns to the default behavior. For more information about Pool object, see “Pool” documentation and examples.

• Extension, ending the URL, can take the following values:

  • xml,
  • cxml,
  • pxml,
  • cpdf.

For example, with a project named test_project not including pools, in a local Convertigo studio, the URL to call a transaction / sequence can be:

The XML requesters allow calling a transaction / sequence of a Convertigo project, possibly in the context of a pool. They allow retreiving the XML response and possibly performing an XSL transformation.

The difference between the four extensions is about the XSL transformation. It is described in the table above:

Table 4 - 1: XML requesters extensions

Using these requesters, the client interacts directly with Convertigo engine.

The parametrization of the engine request, i.e. the definition of the transaction / sequence to call and related parameters, is done by using engine reserved variables. For more information about engine specific parameters, see Engine reserved parameters.

JSON requesters

These requesters are invoked by setting the ConvertigoRequester at the end of the URL to the following expression: < PoolName>.< Extension>.

• PoolName defines the name of the pool to invoke, in the case of pools use in the project. It is an optional parameter, it can be empty. Any value can be passed in this part of the URL: if a matching pool is found, it is used by Convertigo, if no pool is found, it is ignored and Convertigo returns to the default behavior. For more information about Pool object, see “Pool” documentation and examples.

• Extension, ending the URL, can take the following values:

  • json,
  • jsonp.

For example, with a project named test_project not including pools, in a local Convertigo studio, the URL to call a transaction / sequence can be:

The JSON requesters allow calling a transaction / sequence of a Convertigo project, possibly in the context of a pool, and retrieving the JSON response.

The difference between the two extensions is about cross-domain issues. It is described in the following table:

Table 4 - 2: JSON requesters extensions

Using these requesters, the client interacts directly with Convertigo engine, dynamically transforming standard output XML data to JSON structure.

The parametrization of the engine request, i.e. the definition of the transaction / sequence to call and related parameters, is done by using engine reserved variables. For more information about engine specific parameters, see Engine reserved parameters.

Call-back function specific to JSONP requester is configured using a specific engine reserved variable. For more information about specific engine reserved parameters, see JSONP specific reserved parameters.

Binaries requester

This requester is invoked by setting the ConvertigoRequester at the end of the URL to the following expression: .bin.

For example, with a project named test_project, in a local Convertigo studio, the URL to call a transaction / sequence can be:

The binaries requester allows retrieving the last attachment file downloaded by a transaction / sequence of a Convertigo project. It can be called directly with the transaction extracting the attachment.

Using this requester, the client interacts directly with Convertigo engine.

The parametrization of the engine request, i.e. the definition of the transaction / sequence to call and related parameters, is done by using engine reserved parameters. For more information about engine specific parameters, see Engine reserved parameters.

Convertigo reserved parameters

All Convertigo specific parameters are prefixed with ‘__’ (double underscored). Depending on the invoked requester, some reserved parameters can be used by the weblib AJAX framework, some by Convertigo engine.

• Engine reserved parameters
• Weblib reserved parameters

Engine reserved parameters

Convertigo engine request parametrization, i.e. the definition of the transaction / sequence to call and related execution parameters, is done by using generic engine reserved parameters that have to be passed in the request.

Other specific engine reserved parameters exist and can be used to handle connector-related specific cases.

Generic engine reserved parameters

Here is the list of Convertigo engine-managed reserved parameters, valid and usable for all types of projects, and their description:

Table 4 - 3: Generic engine reserved parameters

http(s)://<ConvertigoServer>/<ConvertigoAppName>/projects/<ProjectName>/<ConvertigoRequester>?<<strong>Parameters</strong>>.

context.requireEndOfContext = true;

JSONP specific reserved parameters

The following is the engine reserved parameter specific to JSONP requester and its description:

Table 4 - 4: JSONP specific engine reserved parameters

Web connector-specific reserved parameters

The following list is the list of web connector-specific engine reserved parameters and their description:

Table 4 - 5: Web connector-specific engine reserved parameters

__header_test=myTestHeader

test=myTestHeader

__GET_login=johnsmith&__POST_password=mypassword

See also the __body and the __contentType reserved HTTP single-valued variable documentation in chapter 2 of this manual.

Legacy emulator-specific reserved parameters

The following list is the list of legacy emulator-specific engine reserved parameters and their description:

Table 4 - 6: Legacy emulator-specific engine reserved parameters

<devicename>,DIR|<mainframe_ip>:<mainframe_port>

__javelin_modified_fields={"name":["__field_c1_l9"]}

Carioca portal-specific reserved parameters

The following list is the list of specific engine reserved parameters used when Convertigo is accessed through Carioca portal and their description:

Table 4 - 7: Engine reserved parameters for access through Carioca

Weblib reserved parameters

Weblib framework parametrization can be performed by updating global variables values. Lots of these variables can be set thanks to weblib reserved parameters that have to be passed:

• In the request, using a query string that sends all parameters to the network, or
• By a hash query (using a ‘#’) that only sends needed parameters in POST data.

Here is the list of Convertigo weblib-managed reserved parameters and their description:

Table 4 - 8: Weblib reserved parameters

Web service interface to Convertigo

Convertigo projects can be accessed using web services. This section describes possible URLs to access Convertigo projects through the two types of web services that are supported, then it describes the problem of context state conservation.

SOAP web services

SOAP WSDL of a Convertigo project can be accessed by using the following URL:

Where:

1. ConvertigoServer is the host name or IP address of your Convertigo server, with possibly a port number.

• A local Convertigo Studio has as host name localhost and as default port number 18080 for HTTP.
• A Convertigo Server installed locally on your computer shares the same host name: localhost. The Convertigo Server default port number is 28080 for HTTP.
• A Convertigo Cloud server is accessed through its server name, for example: me.convertigo.net (no port to provide in this case).

2 . ConvertigoAppName defines the name of the Convertigo web application.

• A local Convertigo Studio or a Convertigo Server installed locally has convertigo as Convertigo app name.
• A Convertigo Cloud server has cems as Convertigo app name.

3. ProjectName defines the name of the project you want to invoke in Convertigo. If the project doesn’t exist, the application server generates an error (HTTP 404 Not Found).

4. WsType defines the type of encoding you want for SOAP web service. It corresponds to SOAP web service requesters that can be invoked on Convertigo. For more information about the other available requesters, see Convertigo URLs.

This WsType part of the URL can take several values that are detailed in following table:

Table 4 - 9: SOAP encoding types

For example, with a project named test_project in a local Convertigo Server, the URL to retrieve the SOAP WSDL can be:

For the same project in a Convertigo Cloud Server, the URL to retrieve the SOAP WSDL is:

REST web services

Any Convertigo project can be invoked as a REST web service, using the following URL:

Where:

1. ConvertigoServer is the host name or IP address of your Convertigo server, with possibly a port number.

• A local Convertigo Studio will have as host name localhost and as default port number 18080.
• A Convertigo Server installed locally on your computer will share the same host name: localhost. When installed in an existing application server, it will have as IP address the IP address of the application server. The Convertigo Server default port number is 28080.
• A Convertigo Cloud server is accessed through its server name, for example: me.convertigo.net (no port to provide in this case).

2. ConvertigoAppName defines the name of the Convertigo web application.

• A local Convertigo Studio or a Convertigo Server installed locally has convertigo as Convertigo app name.
• A Convertigo Cloud server has cems as Convertigo app name.

3. ProjectName defines the name of the project you want to invoke in Convertigo. If the project doesn’t exist, the application server generates an error (HTTP 404 Not Found).

You can notice that this URL uses an XML requester; for more information about the other available requesters, see Convertigo URLs.

For more information about HTTP protocol to call transactions or sequences and the variables to pass to this request, see HTTP protocol interface to Convertigo.

To expose a project as a REST web service with customized URLs, you may use an URL Mapper object.

It allows you to define Path Mappings objects to the outside world: /api/v1/accounts/{id}

It generates a Swagger compliant definition of your service into a YAML or JSON format, which may be consumed by the Swagger console or any other REST client to test the generated API.

For more information, see URL Mapper

Context state conservation

When using web services, you can have:

• Stateless web services: when the response of a web service method does not depend on a previous state left by a preceding web service call. This is also called “atomic” web services.

• Stateful web services: when the response of a web service method does depend on a previous state left by a preceding call. Convertigo projects mostly generate stateful web services. For example, you cannot get information from a legacy application or a web application if you don’t call a “login” transaction before.

Consuming stateful web services, the programmer must maintain the HTTP session from its calling application to Convertigo between two methods calls. See the corresponding web service client documentation to do so.

A few examples for SOAP clients

If you are using Java AXIS web service client, simply use the following line of code:

If you are using Microsoft .NET web service client, use this code construction (C# Syntax):

Case of REST calls

For REST web service calls, be sure that the HTTP client will maintain session cookies with Convertigo.