# Job Functions

The Job functions allow you to get information on the currently running job so that you can create tests that can work dynamically in relation to the current state of the simulation.

The various functions are listed below:

#### **`getRunSettings()`**

Use the `getRunSettings()` function to retrieve the run settings for the currently running job. The function returns an object with all the data pertaining to the run settings.

{% code title="Function:" %}

```javascript
getRunSettings()            //no arguments are required

console.log("The current run setting is "+getRunSettings().name)

//returns an object with the full run settings
```

{% endcode %}

{% code title="Response:" %}

```json
{
	id: '6246fbe5fdee1fd07c3bb331',
	name: 'Default',
	interval: 10000,
	iteration: 10,
	clients: 10,
	totalClients: 10,
	clientIdOffset: 0,
	clientGroupSize: 1000,
	maxParallelClients: 0,
	maxMessagesPerSecond: 0,
	captureLogs: true,
	captureState: true,
	capturePayload: false,
	interClientGap: 0,
	interGroupGap: 0,
	externalSync: true,
	strategy: 'Default',
	groupIndex: 0
}

The current run setting is Default
```

{% endcode %}

#### **`jobClients()`**

This function returns the total number of clients that are being simulated in the current job.

{% code title="Function:" %}

```javascript
jobClients()            //no arguments are required

console.log("Total clients for the job are "+jobClients())
//returns a number with the number of clients
```

{% endcode %}

{% code title="Response:" %}

```json
10

Total clients for the job are 10
```

{% endcode %}

#### **`jobId()`**

Returns the assigned name of the simulation job. This could be used to store the results in a database.

{% code title="Function:" %}

```javascript
jobId()                    //no arguments are required

console.log("The current running job is "+jobId())

//returns a string with the job name generated by the system
```

{% endcode %}

{% code title="Response:" %}

```json
ebaf0e09-7d8a-4b53-8182-55a2d3dc2230

The current running job is ebaf0e09-7d8a-4b53-8182-55a2d3dc2230
```

{% endcode %}

#### **`jobInterval()`**

Returns the time interval in seconds between each iteration.

{% code title="Function: " %}

```javascript
jobInterval()            //no arguments are required

console.log("There is a gap of "+jobInterval()+" seconds between iterations")

//returns a number with the time interval in seconds
```

{% endcode %}

{% code title="Response:" %}

```json
10000

There is a gap of 10000 seconds between iterations
```

{% endcode %}

#### **`jobRepeat()`**

Returns the total number of iterations specified in the job.

{% code title="Function:" %}

```javascript
jobRepeat()                //no arguments are required

console.log("The job will repeat "+jobRepeat()+" times")

//returns a number with the amount of times the simulation will repeat
```

{% endcode %}

{% code title="Response:" %}

```json
10

The job will repeat 10 times
```

{% endcode %}

#### `index() or iteration()`

For the simulations, you will specify the number of iterations that a test should run for. To get the value of the current iteration that the simulation is in, you can use the **index()** or **iteration()** functions

{% code title="Function:" %}

```javascript
index()                    //no arguments are required
iteration()                //no arguments are required

console.log("The job is currently in iteration number "+iteration())

//returns a number with the current iteration
```

{% endcode %}

{% code title="Response:" %}

```json
3
3

The job is currently in iteration number 3
```

{% endcode %}

#### `client()`

For the simulations, you may need to implement client-specific behaviours. The current client ID can be determined within the test by using the **client() function**.

{% code title="Function:" %}

```javascript
client()                    //no arguments are required

console.log("The current client ID is "+client())

//returns a number with the current client ID
```

{% endcode %}

{% code title="Response:" %}

```json
15

The current client ID is 15
```

{% endcode %}

#### `assert()`

Usually, an iteration for a client will be marked as failed, when the client is unable to publish a message to the server within the given timeout period. However, there may be cases where you would like to declare a test as failed when certain criteria are not met. 

When using IoTIFY for testing, you could force a test iteration to be failed even if message sending is successful using test assertion with the **`assert()`** function.

The function takes two parameters:

**condition**: A boolean condition that should be tested for truth (true)\
**message**: A string describing the cause of assertion failure which can be stored in test results.

For example, the following statement checks for an assertion failure in your template and marks the test result as failed, if `retval` does not equal to 123.

```
//Takes a boolean condition and a string message as arguments
assert(condition, message)

assert(retval == 123, "Return value doesn't equal "+123);

```


---

# 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.iotify.io/additional-helpers/iotify-helpers/job-functions.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.