# Operation JavaScript API

## Connector functions - Active Operation JS API guide

This API allows users to read and activate operations from a connector function.

## operation -- Main Object

The `operation` object is the main object. It allows making requests to the Operations API.

To do the request, the object `operation` use the [HTTP-Client API](/api/device_integration/connector_functions/protocol_apis/http/), you can use all attribute of this interface, for example, to add a certificate `http.client.certificate=XXX`

### operation -- Object Properties

| Property     | Type     | Description                                         |
|--------------|----------|-----------------------------------------------------|
| deviceId     | string   | Target device id of the operation pending           |
| apiKey       | string   | Api-Key to use in the request to the Operations-API |
| host         | string   | Host to use in the request to the Operations-API    |

*By default*, the attributes will be set with the value of the context.

### operation -- Functions

#### operation.getAllPending() 

**Read and return the selected device operations pending (with status WAITING_FOR_CONNECTION) of the user to execute the CFx**

This function does not require parameters.

**The operation.getAllPending function returns an object, described as follows:**

| Property   | Type           | Attributes          | Description                                                       |
|------------|----------------|---------------------|-------------------------------------------------------------------|
| error      | null or string | Message             | Description of the exception error caught, or error sent by the request. It will be `null` when the request contains no errors     |
| opResult   | Object         | statusCode, Object  | Contains **statusCode**, and the **result list** object of the request, when it's OK |


Example of use with default values:

```javascript
var opResult = operation.getAllPending();
```

#### operation.getNotFinished() 

**Read and return the selected device operations that are not finished**

This function does not require parameters.

**Function operation.getNotFinished return object, descript like:**

| Property   | Type           | Attributes          | Description                                                       |
|------------|----------------|---------------------|-------------------------------------------------------------------|
| error      | null or string | Message             | Description of the exception error caught, or error sent by the request. will be `null`, when the request no contains errors     |
| opResult   | Object         | statusCode, Object  | Contains **statusCode**, and the **result list** object of the request, when it's OK |

Example of use:
```javascript
var opResult = operation.getNotFinished();
```

#### operation.getByCustomCondition(customCondition)

**Read and return the selected device operations that match a custom filter condition**

| Param | Type | Description |
|-------|------|-------------|
| customCondition | Object | Filter condition to apply (e.g., `{ 'eq': { 'operationStatus': 'IN_PROGRESS' } }`) |

**Function operation.getNotFinished return object, descript like:**

| Property   | Type           | Attributes          | Description                                                       |
|------------|----------------|---------------------|-------------------------------------------------------------------|
| error      | null or string | Message             | Description of the exception error caught, or error sent by the request. will be `null`, when the request no contains errors     |
| opResult   | Object         | statusCode, Object  | Contains **statusCode**, and the **result list** object of the request, when it's OK |


Example of use:
```javascript
var opResult = operation.getByCustomCondition({ 'eq': { 'operationStatus': 'IN_PROGRESS' } });
```

##### opResult -- Object Functions

**opResult** is a JSON List Object returned by the operation.getAllPending function. You can use the following functions:

| Function     | Return         | Description                                                                              |
|--------------|----------------|------------------------------------------------------------------------------------------|
| activate     | null or string | Activates the target operation. Returns `null` when the activation is OK, otherwise returns the error cause message  |
| getRequest   | Object         | Builds and returns the request the device must send to respond to the operation          |

The object -**opResult**- contains all attributes and functions of the [response](/api/device_integration/connector_functions/core_javascript_api/operation_steps/) (operation) object.


###### activate() 

**Activate the target operation selected with parameters of the context**
(Update to IN_PROGRESS the operation)

This function does not require parameters.

Example of use with default values:
```javascript
var opResult = operation.getAllPending();
if (opResult.error) {
    return error;
}
opResult.forEach(op => op.activate());
```


###### getRequest() 

**Builds and returns the request the device must send to respond to the operation**

This function does not require parameters.


### reqRes -- Object return the getRequest function

**reqRes** is a JSON Object returned by the getRequest function, described as follows:

| Property     | Return         | Description                                                           |
|--------------|----------------|-----------------------------------------------------------------------|
| operation    | Object         | Main object to do the request                                         |

-- Attributes of `operation`

| Property     | Return         | Description                                                           |
|--------------|----------------|-----------------------------------------------------------------------|
| request      | Object         | Secondary main object to do the request                               |

-- Attributes of `request`

| Property     | Return         | Description                                   |
|--------------|----------------|-----------------------------------------------|
| name         | Object         | Operation name target of the request          |
| id           | Object         | Operation identifier target of the request    |
| parameters   | Object         | Parameters to use in the request              |
| timestamp    | Object         | Operation time on do the request              |

*By default*, the attributes will be set with the value of the target operation.

Example getRequest object return:

```javascript
{ 
    'operation': {
        'request': {
            'name': 'opName',
            'id': 'ce02792a-3a37-11f0-a48d-52540044ee01',
            'parameters': {},
            'timestamp': Date.now()
        }
    }
}
```                            

Example of use getRequest function:

```javascript
var opResult = operation.getAllPending();
if (opResult.error) {
    return error;
}
opResult.forEach(op => {
        op.activate();
        http.client.body = op.getRequest();
        var httpResp = http.client.post();
        if (httpResp.statusCode != 201) {
            throw Error('Unexpected response:', httpResp);
        }
    }
);
```