# Provision JavaScript API

## Connector functions - Provision JS API guide

This API allows users to manage entity provisioning (creation and retrieval) from a connector function.

## provision -- Main Object

The `provision` global object provides properties and methods to interact with the Provisioning API.

### provision -- Object Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `apiKey` | `string` | If available, current connection's apikey | API Key for the request. |
| `host` | `string` | Frontend's default endpoint | Host for the Provisioning API. |
| `identifier` | `string` | `null` | Identifier of the entity to act upon. |
| `organization` | `string` | Device`s organization | Organization to which the entity belongs. |
| `serviceGroup` | `string` | `"emptyServiceGroup"` | Service Group for the entity. |
| `defaultChannel` | `string` | `"defaultChannel"` | Channel to which the entity belongs.  |
| `plan` | `string` | `null` | Provisioning plan to apply. |
| `extraDatastreams` | `Array` | `[]` | Extra data as an array of objects like `{datastreamId:value}` pairs. |

---

### provision -- Functions

#### provision.get(id)

Retrieves an existing entity from the database with specified identifier.

**Kind**: global function  
**Returns**: `Object` - If entity is found, entity data will be returned in `result`. If it is not found, `result` field will be null. If some error happened, it will be returned in `error` field.

| Param | Type | Default | Description |
|-------|------|------|-------------|
| `id` | `string` | `this.identifier` | (Optional) Entity identifier. If not defined `identifier` field will be used. |


Example with `provision.identifier`:
```javascript
provision.identifier = "device_123";
const resp = provision.get();
if (!resp.error && resp.result) {
    logger.info("Entity identifier:", resp.result._value("provision.administration.identifier"));
}
```


Example with parameter:
```javascript
const resp = provision.get("device_123");
if (!resp.error && resp.result) {
    logger.info("Entity identifier:", resp.result._value("provision.administration.identifier"));
}
```


Example with unexepected error:
```javascript
const resp = provision.get("device_123");
if (resp.error) {
    logger.error("Some error:", resp.error);
}
```

The object `resp.result` contains then same functions than [entity object](/api/device_integration/connector_functions/core_javascript_api/entity/).


#### provision.create(fullBody)

Creates a new entity in the platform.

**Kind**: global function  

| Param | Type | Description |
|-------|------|-------------|
| `fullBody` | `Object` | (Optional) Complete JSON body for the creation request. If not provided, it is generated from the object properties. |

**Returns**: `Object` - An object containing either `result` (201 status) or `error`.

Example using properties:
```javascript
provision.identifier = "new_device_001";
provision.plan = "TEST_PLAN";
provision.extraDatastreams = [{ "provision.device.name": "cellName" }, { "provision.device.administrativeState": "ACTIVE" }, { "provision.device.specificType": "COMHUB" }, { "provision.tec": "NBIoT Cell" }];
const resp = provision.create();
if(!resp.error && resp.result == 201) {
    logger.info('Created');
} else {
    logger.error('Error creating entity:', resp.error);
}
```

Previous example will create with following body:
```javascript
{
    "provision.administration.channel": {
        "_value": {
            "_current": {
                "value": "defaultChannel"
            }
        }
    },
    "provision.administration.identifier": {
        "_value": {
            "_current": {
                "value": "new_device_001"
            }
        }
    },
    "provision.administration.organization": {
        "_value": {
            "_current": {
                "value": "deviceOrg"
            }
        }
    },
    "provision.administration.serviceGroup": {
        "_value": {
            "_current": {
                "value": "emptyServiceGroup"
            }
        }
    },
    "provision.administration.plan": {
        "_value": {
            "_current": {
                "value": "TEST_PLAN"
            }
        }
    },
    "provision.device.name": {
        "_value": {
            "_current": {
                "value": "cellName"
            }
        }
    },
    "provision.device.administrativeState": {
        "_value": {
            "_current": {
                "value": "ACTIVE"
            }
        }
    },
    "provision.device.specificType": {
        "_value": {
            "_current": {
                "value": "COMHUB"
            }
        }
    },
    "provision.tec": {
        "_value": {
            "_current": {
                "value": "NBIoT Cell"
            }
        }
    }
}
```

If `fullBody` is provided, it will be used as the request body instead of building it from the object properties.

Example:
```javascript
const body = {
    "provision.administration.channel": {
        "_value": {
            "_current": {
                "value": "defaultChannel"
            }
        }
    },
    "provision.administration.identifier": {
        "_value": {
            "_current": {
                "value": "new_device_001"
            }
        }
    },
    "provision.administration.organization": {
        "_value": {
            "_current": {
                "value": "deviceOrg"
            }
        }
    },
    "provision.administration.serviceGroup": {
        "_value": {
            "_current": {
                "value": "emptyServiceGroup"
            }
        }
    }
};
const resp = provision.create(body);
if(!resp.error && resp.result == 201) {
    logger.info('Created');
} else {
    logger.error('Error creating entity:', resp.error);
}
```