# Getting started

> Overview of using OneFuse with the Python module

---

Site [llms.txt](/llms.txt)

---

Easily integrate CloudBolt OneFuse with Python to quickly automate and integrate into your business provisioning lifecycle.

The CloudBolt OneFuse integration platform offers integrations to services like Naming, IPAM, DNS, Microsoft Active Directory, Scripting, Ansible Tower and more.

[Upstream providers](/docs/onefuse/consume/what-is-upstream-provider/) like Ansible, Terraform, VMware vRealize Automation, CloudBolt CMP, ServiceNow and others are able to consume the same OneFuse integrations combined with organizational business logic for a standardized approach to automation across the enterprise.

## Prerequisites

<div class="alert alert-info" role="alert">


Identify a system to run the Python commands from. This could be your own desktop or a server in your environment. You will need to have Python 3 or greater installed on the system.
</div>


1. Verify **Python** is installed

   ```bash
   python --version
   ```

   <div class="alert alert-info" role="alert">


   [Python 2 has sunset.](https://www.python.org/doc/sunset-python-2/) If previously installed and on Python 2, upgrade to the latest Python.
   </div>


   - If **Python** is not installed (or upgrading), [download](https://www.python.org/downloads/) the latest Python

1. Verify **pip** is installed

   ```bash
   pip --version
   ```

   - [Install pip](https://pip.pypa.io/en/stable/installation/) if it does not exist

1. Review Python's [Installing Packages](https://packaging.python.org/tutorials/installing-packages/)

### OneFuse Python Module

**GitHub Repo**: [OneFuse Python Module](https://github.com/CloudBoltSoftware/onefuse-python-module)

---

## Install OneFuse Python Package

OneFuse Python Module is distributed as a Python Package. Install the OneFuse Python Package using `pip`.

<div class="alert alert-info" role="alert">


It is recommended to install the latest OneFuse Python Package that matches the OneFuse Appliance version.
</div>


<div class="alert alert-info" role="alert">


If the OneFuse Python Module is already installed, skip to [Upgrading the OneFuse Python Package](#upgrading-the-onefuse-python-package).
</div>


1. Open a **Command Prompt** or **Terminal** window
1. Install OneFuse Python Package using instructions below:

### Option 1. Installing the latest

```bash
pip install onefuse
```

---

### Option 2. Installing a specific version

#### Optional: list available OneFuse Python package versions

```bash
# Run the following in a Command Prompt/Terminal
pip install onefuse==versions

# An output error message similar to the below is returned, listing available versions:
# ~ERROR: Could not find a version that satisfies the requirement onefuse==versions (from versions: <!! versions are listed here !!>)
# ~ERROR: No matching distribution found for onefuse==versions
```

Then, install with a specific version.

```bash
# Replace <version> in the command below with a specific version number (e.g. 1.4.0)
# Run the following in a Command Prompt/Terminal
pip install onefuse==<version>

# An output message similar to the below is returned, where <version> is replaced with the version number installed:
# ~Successfully installed onefuse-<version>
```

### Upgrading the OneFuse Python Package

Upgrade to the latest OneFuse Python Package using `pip`.

1. Open a **Command Prompt** or **Terminal** window
1. Install OneFuse Python Package using the command below:

   ```bash
   pip install --upgrade onefuse
   ```

## Configure OneFuse Manager

Configure the connection to OneFuse with the OneFuse Manager from the OneFuse Python Package.

1. Open a **Command Prompt** or **Terminal** window

1. Enter the **Python Console** via command:

   ```bash
   # Run the following in a Command Prompt/Terminal to enter the Python Console
   python
   ```

1. **Import the OneFuse Manager** via command:

   ```python
   # Run the following in the Python Console
   from onefuse.admin import OneFuseManager
   ```

1. **Create a OneFuse Manager** via command:

   ```python
   # Replace <username> in the command below with the OneFuse username
   # Replace <password> in the command below with the password for the OneFuse user
   # Replace <host>     in the command below with the FQDN or IP Address of the OneFuse instance

   # Run the following in the Python Console
   ofm = OneFuseManager(<username>, <password>, <host>)

   # Example
   # ofm = OneFuseManager('admin', 'admin', 'onefuse.example.com')
   ```

   - Replace `<username>` with the OneFuse username that has at least the [Workspace Member role](/docs/onefuse/getting-started/roles-and-permissions/#workspace-roles).
   - Replace `<password>` with the password for the OneFuse user.
   - Replace `<host>` with the OneFuse Instance FQDN or IP Address.

   **Accepted optional kwargs:**

   | Key | Value |
   | --- | --- |
   | `protocol` | Defaults to `https`. Specify a protocol: `http` or a non-standard protocol. |
   | `port` | Defaults to `443`. Specify the port for the OneFuse Instance. |
   | `verify_certs` | Defaults to `false`. Specify whether or not to verify OneFuse Certificates (`true` or `false`). |
   | `logger` | Defaults to `onefuse.log` and to the console at the `LOG_LEVEL` set in `configuration.globals`. Pass in logger information. |
   | `source` | Defaults to `PYTHON`. Specify the source so that this class can be called by other Upstream Providers (Ansible, CloudBolt CMP, Terraform, ServiceNow, VMware vRealize Automation, etc). All OneFuse Jobs will show this value as the "Source" of the Job. |

   **Example using accepted optional kwargs:**

   ```python
   # Pass in accepted optional kwargs comma separated in format <key>='<value>'

   # Run the following in the Python Console
   ofm = OneFuseManager(<username>, <password>, <host>, verify_certs='true')
   ```

1. **Use the OneFuse Manager** to make API calls to OneFuse.

   <div class="alert alert-info" role="alert">


   From the example command above, the OneFuse Manager is instantiated in the Python variable `ofm`.
   </div>


   ```python
   # Run the following in the Python Console
   # Run commands and OneFuse API calls against the created OneFuse Manager
   # Example below outputs the OneFuse Instance version for the created OneFuse Manager
   ofm.onefuse_version
   ```

---

## Resources

- [Learn](https://www.w3schools.com/python/python_modules.asp) about Python Modules.
- Visit our **GitHub Repo**: [onefuse-examples](https://github.com/CloudBoltSoftware/onefuse-examples)

## Troubleshooting

**Update the OneFuse Manager's Log Level and re-try the request:**

```python
# Pass in accepted optional kwargs comma separated in format <key>='<value>'

# Run the following in the Python Console
ofm = OneFuseManager(<username>, <password>, <host>, log_level='DEBUG')
```

Refer to Python's [Logging facility for Python](https://docs.python.org/3/library/logging.html).

## Next steps

Start integrating with [OneFuse Modules](/docs/onefuse/consume/python-module/modules/).