Cloud Software Group, Inc. EBX®
Documentation > Developer Guide > SOAP data services
Navigation mode Documentation > Developer Guide > SOAP data services

# WSDL generation

## Supported standard

TIBCO EBX® generates a WSDL that complies with the W3C Web Services Description Language 1.1 standard.

## Operation types

A WSDL can be generated for different types of operations:

Operation type | WSDL description
--- | ---
`custom` | WSDL for EBX® add-ons.
`dataset` | WSDL for dataset and replication operations.
`directory` | WSDL for default EBX® directory operations. It is also possible to filter data using the `tablePaths` or `operations` parameters.
`repository` | WSDL for dataspace or snapshot management operations.
`tables` | WSDL for operations on the tables of a specific dataset.
`userInterface` | Deprecated since version 5.8.1. This operation type has been replaced by `administration`. While the user interface management operations are still available for backward compatibility reasons, it is recommended to no longer use this type. WSDL for user interface management operations (these operations can only be accessed by administrators).
`administration` | WSDL for administration operations like: user interface management system information retrieval These operations can only be accessed by administrators.
`workflow` | WSDL for EBX® workflow management operations.

## WSDL download methods

EBX® supports the following methods:

- from the user interface

- from HTTP protocol

A WSDL can only be downloaded by authorized profiles:

Operation type | Access right permissions
--- | ---
`custom` | All profiles, if at least one web service is registered.
`dataset` | All profiles.
`directory` | All profiles, if the following conditions are valid: No specific directory implementation is used. (The built-in Administrator role is only subject to this condition). Global access permissions are defined for the administration. 'Directory' dataset permissions have writing access for the current profile.
`repository` | All profiles.
`tables` | All profiles.
`userInterface` | Deprecated since version 5.8.1. This operation type has been replaced by `administration`. While the user interface management operations are still available for backward compatibility reasons, it is recommended to no longer use this type. Built-in administrator role or delegated administrator profiles, if all conditions are valid: Global access permissions are defined for the administration. 'User interface' dataset permissions have writing access for the current profile.
`administration` | Built-in administrator role or delegated administrator profiles, if all conditions are valid: Global access permissions are defined for the administration. 'Administration' dataset permissions have write access for the current profile.
`workflow` | All profiles.

### WSDL download from the user interface

An authorized user can download an EBX® WSDL from the data services administration area.

##### Note

See Generating a WSDL for dataspace operations in the user guide for more information.

### WSDL download from HTTP protocol

An application can download an EBX® WSDL using `GET` or `POST` HTTP method. The application has to be authenticated using a profile with appropriate rights.

#### URL format

> `http[s]://<host>[:<port>]/<ebx-dataservices>/{type}[/{dataspace}[/{dataset}]]?{queryParameters}`

Where:

- `<ebx-dataservices>` corresponds to the 'ebx-dataservices.war' web application's path. The path is composed by multiple, or none, URI segments followed by the web application's name.

- `{type}` corresponds to the operation type.

- `{dataspace}` corresponds to the dataspace or snapshot identifier.

- `{dataset}` corresponds to the dataset name.

- `{queryParameters}` corresponds to common or dedicated operation parameters passed through the URL.

#### Parameters

A request parameter can be specified by one of the following methods:

- a `PathParam` which corresponds to a path segment from the URL (recommended)

- a `QueryParam` which corresponds to a standard HTTP parameter with value.

Parameter name | `PathParam` | `QueryParam` | Required | Description
--- | --- | --- | --- | ---
`WSDL` | no | yes | yes | Specifies the WSDL download operation. Empty value.
`login` | no | yes | no | Specifies the user identifier. Required when the standard authentication method is used. `String` type value.
`password` | no | yes | no | Specifies the user password. Required when the standard authentication method is used. `String` type value.
`type` | yes | no | yes | Specifies the operation type. Possible values are: `custom`, `dataset`, `directory`, `administration`, `userInterface`, `repository`, `tables` or `workflow`. `String` type value.
`branch` `version` | yes | yes | (*) | Specifies the dataspace or the snapshot identifier. (*) required for `tables` and `dataset` types, ignored otherwise. `String` type value.
`instance` | yes | yes | (*) | Specifies the dataset name. `String` type value.
`tablePaths` | no | yes | no | Specifies the list of table paths. Optional for `tables` or `directory` types, ignored otherwise. If not defined, all tables are selected. Each table path is separated by a comma character. `String` type value.
`operations` | no | yes | no | Allows generating a WSDL for an operations subset. Optional for `tables` or `directory` operation types, ignored otherwise. If not defined, all operations for the given type are generated. This parameter's value is a concatenation of one or more of the following characters: C = Count record(s) D = Delete record(s) E = Get credentials G = Get changes I = Insert record(s) U = Update record(s) R = Read operations (equivalent to CEGS) S = Select record(s) W = Write operations (equivalent to DIU) `String` type value.
`namespaceURI` | yes | yes | (**) | Specifies the unique name space URI of the custom web service. (**)Is required when `type` parameter is set to `custom`, ignored otherwise. `URI` type value.
`attachmentFilename` | no | yes | (***) | Specifies the attachment file name. (***) optional if `isContentInAttachment` parameter is defined and set to `true`, ignored otherwise. `String` type value.
`isContentInAttachment` | no | yes | no | Specifies if the WSDL is downloaded as an attachment. `Boolean` type value. Default value is `false`.
`targetNamespace` | no | yes | no | Overrides the target namespace URI of the WSDL. `URI` type value. Default value is `urn:ebx:ebx-dataservices`.

#### Message body

No message body is required.

#### HTTP codes

An HTTP code is always returned. Errors are indicated by a code above 400.

Status code | Information
--- | ---
`200` (OK) | The WSDL content was successfully generated and is returned by the request (optionally in an attachment).
`400` (Bad request) | The request is incorrect. This occurs when: A request element is incorrect. The unicity check on table names contains at least one error. ##### Note See WSDL and table operations for more information.
`401` (Unauthorized) | Request requires an authenticated user.
`403` (Forbidden) | Request is not allowed for the authenticated user.
`405` (Method not allowed) | Request is not allowed in this configuration.
`500` (Internal error) | Request generates an error (a stack trace and a detailed error message are returned).

#### Response body

The response body depends on the returned status code and on the requested WSDL content.

- `200` (OK): the HTTP header `Content-Type` is set to `text/xml;charset=UTF-8`.

  If the content is in attachment, the HTTP header `Content-Disposition` is set to `attachment; filename*=UTF-8''<filename.wsdl>`.

- `4xx`: A detailed message is returned in the body. The HTTP header `Content-Type` is set to `text/html;charset=utf-8`.

## HTTP examples

Some of the following examples are displayed in two methods: `PathParam` and `QueryParam`.

- The WSDL will contain all repository operations, using standard authentication method.

  `http[s]://<host>[:<port>]/<ebx-dataservices>/repository?WSDL&login=<login>&password=<password>`

- The WSDL will contain all workflow operations.

  `http[s]://<host>[:<port>]/<ebx-dataservices>/workflow?WSDL`

- The WSDL will contain all tables operations for the `'dataset1'` dataset in `'dataspace1'` dataspace.

  `PathParam`

  `http[s]://<host>[:<port>]/<ebx-dataservices>/tables/dataspace1/dataset1?WSDL`

  `QueryParam`

  `http[s]://<host>[:<port>]/<ebx-dataservices>/tables?WSDL&branch=<dataspace1>&instance=<dataset1>`

- The WSDL will contain all tables with only read operations for the `'dataset1'` dataset in `'dataspace1'` dataspace.

  `PathParam`

  `http[s]://<host>[:<port>]/<ebx-dataservices>/tables/dataspace1/dataset1?WSDL&operations=R`

  `QueryParam`

  `http[s]://<host>[:<port>]/<ebx-dataservices>/tables?WSDL&branch=dataspace1&instance=dataset1&operations=R`

- The WSDL will contain the two selected tables operations for the `'dataset1'` dataset in `'dataspace1'` dataspace.

  `PathParam`

  `http[s]://<host>[:<port>]/<ebx-dataservices>/tables/dataspace1/dataset1?WSDL&tablePaths=/root/table1,/root/table2`

  `QueryParam`

  `http[s]://<host>[:<port>]/<ebx-dataservices>/tables?WSDL&branch=dataspace1&instance=dataset1&tablePaths=/root/table1,/root/table2`

- The WSDL will contain custom web service operations for the dedicated URI.

  `PathParam`

  `http[s]://<host>[:<port>]/<ebx-dataservices>/custom/urn:ebx-test:com.orchestranetworks.dataservices.WSDemo?WSDL`

  `QueryParam`

  `http[s]://<host>[:<port>]/<ebx-dataservices>/custom?WSDL&namespaceURI=urn:ebx-test:com.orchestranetworks.dataservices.WSDemo`

Documentation > Developer Guide > SOAP data services