# headlessclient

(plugins.headlessclient)

## Overview

The `headlessclient` plugin provides functionality to create and manage headless clients, which operate without a user interface and execute code in an isolated server-side environment. These clients are particularly useful for running automated processes or backend operations independently of any user session. They can be created, retrieved, and reused across multiple sessions or applications.

The `createClient` function initializes a new headless client and opens a specified solution using credentials and optional arguments for the solution's open method. In developer mode, limitations exist for debugging unless a "nodebug" argument is used. The `getClient` function allows retrieval of an existing headless client using its unique client ID, enabling further operations such as queuing remote methods. The `getOrCreateClient` function combines these capabilities by either fetching an existing client or creating a new one if it does not already exist, ensuring seamless session management across different application contexts.

## **Returned Types**

[JSClient](/reference/servoyextensions/server-plugins/headlessclient/jsclient.md),

## Methods Summarized

| Type                                                                              | Name                                                                                                                                                                       | Summary                                                                                                                                                                                                                        |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [JSClient](/reference/servoyextensions/server-plugins/headlessclient/jsclient.md) | [createClient(solutionName, username, password, solutionOpenMethodArgs)](#createclient-solutionname-username-password-solutionopenmethodargs)                              | Creates a headless client on the server that will open the given solution.                                                                                                                                                     |
| [JSClient](/reference/servoyextensions/server-plugins/headlessclient/jsclient.md) | [getClient(clientID)](#getclient-clientid)                                                                                                                                 | Gets an existing headless client for the given client uuid.                                                                                                                                                                    |
| [JSClient](/reference/servoyextensions/server-plugins/headlessclient/jsclient.md) | [getOrCreateClient(clientId, solutionname, username, password, solutionOpenMethodArgs)](#getorcreateclient-clientid-solutionname-username-password-solutionopenmethodargs) | This will try to get a existing client by the given id if that client is already created for that specific solution; it will create a headless client on the server that will open the given solution if it didn't exists yet. |

## Methods Detailed

### createClient(solutionName, username, password, solutionOpenMethodArgs)

Creates a headless client on the server that will open the given solution.\
The clientId of this client can be stored in the database to be shared between clients so that that specific client can be used over multiple clients later on, or picked up later on by this client. (Even after restart of this client)

NOTE: in the developer this will only load one solution in debug mode when it is the current active solution or a module of the active solution. So calling createClient with the same or another solution/module will replace the existing debug client. You can load any solution (and have multiple JSClient instances) from the workspace when you pass "nodebug" as last argument in the arguments list (it should still use the same resources project). But then you won't be able to debug it, breakpoints won't hit.

**Parameters**

* [String](/reference/servoycore/dev-api/js-lib/string.md) **solutionName** ;
* [String](/reference/servoycore/dev-api/js-lib/string.md) **username** ;
* [String](/reference/servoycore/dev-api/js-lib/string.md) **password** ;
* [Array](/reference/servoycore/dev-api/js-lib/array.md) **solutionOpenMethodArgs** ;

**Returns:** [JSClient](/reference/servoyextensions/server-plugins/headlessclient/jsclient.md) A new JSClient instance for the specified solution, or null if the client could not be created.

**Sample**

```js
// Creates a headless client that will open the given solution.
var headlessClient = plugins.headlessclient.createClient("someSolution", "user", "pass", null);
if (headlessClient != null && headlessClient.isValid()) {
	var x = new Object();
	x.name = 'remote1';
	x.number = 10;
	headlessClient.queueMethod(null, "remoteMethod", [x], callback);
}
```

### getClient(clientID)

Gets an existing headless client for the given client uuid.

**Parameters**

* [String](/reference/servoycore/dev-api/js-lib/string.md) **clientID** ;

**Returns:** [JSClient](/reference/servoyextensions/server-plugins/headlessclient/jsclient.md) The JSClient corresponding to the given client ID if it exists and is valid, or null otherwise.

**Sample**

```js
// Gets an existing headless client for the given client uuid.
var headlessClient = plugins.headlessclient.getClient("clientID");
if (headlessClient != null && headlessClient.isValid()) {
	 headlessClient.queueMethod(null, "someRemoteMethod", null, callback);
}
```

### getOrCreateClient(clientId, solutionname, username, password, solutionOpenMethodArgs)

This will try to get a existing client by the given id if that client is already created for that specific solution;\
it will create a headless client on the server that will open the given solution if it didn't exists yet.

If the client does exist but it is not loaded with that solution an exception will be thrown.

NOTE: in the developer this will only load the solution in debug mode when it is the current active solution or a module of the active solution;\
you can load any solution from the workspace when you pass "nodebug" as last argument in the arguments list (it should still use the same resources project).\
But then you won't be able to debug it, breakpoints won't hit.

**Parameters**

* [String](/reference/servoycore/dev-api/js-lib/string.md) **clientId** The client to lookup by id, if not found a new headless client is created with this id.
* [String](/reference/servoycore/dev-api/js-lib/string.md) **solutionname** The solution to load
* [String](/reference/servoycore/dev-api/js-lib/string.md) **username** The user name that is used to login to the solution
* [String](/reference/servoycore/dev-api/js-lib/string.md) **password** The password for the user
* [Array](/reference/servoycore/dev-api/js-lib/array.md) **solutionOpenMethodArgs** The arguments that will be passed to the solution open method.

**Returns:** [JSClient](/reference/servoyextensions/server-plugins/headlessclient/jsclient.md) An existing JSClient or the JSClient that is created.

**Sample**

```js
// Creates a headless client that will open the given solution.
var storedSolutionSpecificID = "aaaabbbbccccc1111";
var headlessClient = plugins.headlessclient.getOrCreateClient(storedSolutionSpecificID, "someSolution", "user", "pass", null);
if (headlessClient != null && headlessClient.isValid()) {
	var x = new Object();
	x.name = 'remote1';
	x.number = 10;
	headlessClient.queueMethod(null, "remoteMethod", [x], callback);
}
```

***


---

# 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.servoy.com/reference/servoyextensions/server-plugins/headlessclient.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.