# Custom Web Services

The *WireBootstrap Custom Data Connector* is included in the core WireBootstrap framework.  The *WireBootstrap Custom Data Connector* allows custom web services to be used with data sources.  These are services developed by in-house teams or third party vendors hosted on-premise or in the cloud.

## Provider Key

Use the `custom` provider key to use the service provider for this data connector with a data source.

```javascript
const service = new wire.data.DataSource("custom", {
    ...    
});
```

## Web Service Calls

URLs for making service calls are created using the standard template below.

```javascript
[root]/[method]?[filters]
```

| URL Element | Description                                                                                                                                                                                         |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| root        | The root to be used in web service calls.  This will be the [ServiceRoot](https://docs.wirebootstrap.com/wirebootstrap/reference/wire.data/wire.data.datasource#properties) set on the data source. |
| method      | The method to call on the web service.  This will be the entity set in a table query in the `from` clause.                                                                                          |
| filters     | Any filters passed to the method.  These are set up in the table query `where` clause.                                                                                                              |

Consider the following query.

```javascript
const service = new wire.data.DataSource("custom", {
    ServiceRoot: "https://service-reporting"
});

const query = wire.data.select().from("sales")
    .where()
        .eq("product", "PRD-001")
        .eq("territory", "East");
        
const result = service.exec(query);
```

When using this query with the custom web service provider, the following URL is constructed and used to call the web service.

```javascript
https://service-reporting/sales?product=PRD-001&territory=East
```

### GET vs POST

The previous query will result in a `GET` HTTP method being used for the web service call.  To use a `POST` with custom data, change the where clause in the filter to use the `custom` method to send up any custom data to the method in the body of the request.

In the example below, the same query will be posted to the service.

```javascript
...

const filter = { product: "PRD-001", territory: "East" }

const query = wire.data.select().from("sales")
    .where()
        .custom(filter)

...
```

For more on creating and executing queries, visit [Connecting to Data](https://docs.wirebootstrap.com/wirebootstrap/connecting-to-data/data-connectors) and [Creating Queries](https://docs.wirebootstrap.com/wirebootstrap/creating-queries/select-queries).

## Configuration

| Name       | Default | Description                                                                                                                         |
| ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| params     |         | Custom parameters to send with query requests.  See [details](broken://pages/-MLjnau1fAuKhsia05lJ#params) below.                    |
| testMethod |         | This method used to test the connection to the data service.  See [details](broken://pages/-MLjnau1fAuKhsia05lJ#test-method) below. |

### Params

Sometimes its helpful to be able to send custom parameters in the web service calls that are outside of any query filters.  Use the provider `params` configuration option to set these up.

```javascript
const service = new wire.data.DataSource("custom", {
    ServiceRoot: "https://service-reporting",
    Provider: {
        params: {
            option1: "value1",
            option2: "value2"
        }
    }
});
```

In the example above,  two extra parameters called `option1` and `option2` will be set up in the URL and sent to the data service.

```javascript
https://service-reporting/sales?product=PRD-001&territory=East&option1=value1&option2=value2
```

## Allow

Service providers are able to tell consumers about the functionality they support through an [`allow`](https://docs.wirebootstrap.com/wirebootstrap/connecting-to-data/data-connectors#allow) property.  Below is a list of the functionality that the custom service provider supports.

| Name               | Supports |
| ------------------ | -------- |
| delete             | true     |
| discover           | false    |
| storedProcedure    | false    |
| tableQuery         | true     |
| tableQuery.orderBy | false    |
| tableQuery.groupBy | false    |
| test               | true     |
| write              | true     |

### Test Method 

The custom service provider supports testing if the service is available. However, the method to be used for this needs to be specified in the `testMethod` configuration option.

```javascript
const service = new wire.data.DataSource("custom", {
    ServiceRoot: "https://service-reporting",
    Provider: {
        testMethod: "test"
    }
});

const available = service.test();
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.wirebootstrap.com/wirebootstrap/connecting-to-data/data-connectors/custom-web-services.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.