# PortaBilling (PortaOne)

## Overview

The Workfront connector currently allows you to retrieve specified data about any type of object within Workfront.

## Authentication

To authenticate with the PortaBilling connector you will need your login/username used to access the PortaBilling UI. You will also need an API token/key (not your password).
To connector to your PortaBilling instance, the domain of where your PortaBilling server is hosted is required, along with the port number. The interface is available for administrators on port 443, the interface for customers is available on port 8444, the interface for resellers is available on port 8442 and the interface for accounts is available on port 8445.
If you're not sure which port is required and you have an admin account on your PortaBilling instance, use the default of 443.

## Notes on operation usage

The API documentation for PortaBilling can be [found here](https://www.portaone.com/docs/pb/mr75/PortaBilling_API_MR75.html#AboutPB_API).
The operations for the PortaBilling connector allows users to specify which high level service and associated record type they would like to create or retrieve. For example, the `Account` service type encompasses a number of record types, such as `Account`, `Alias` and `Auto payment`. If all that was required is to create an account, then the service type would be `Account` and the record type would also be `Account`. The same goes for customer and service.
The PortaBilling connector allows users to enter properties in `Attributes` for the record type they are creating or listing. For create operations, the attributes represent values that will populate the new record. In the list operation, the values are used to filter the results e.g. only return customers with a name of "Tray demo".
The `Attributes` object needs to be structured in the same way as the PortaBilling API documentation specifies. For example when creating a customer, in the API document it specifies the properties you need (see below).
![Create customer properties](https://tray.ai/documentation/images/connectors/service/portabilling/349d67fa-1f9fe7ed_customer_properties.png)
The `AddCustomerRequest` table shows two high level properties that are required to create an account, `customer_info` and `generate_web_password`. We can see that there is a nested structure underneath `customer_info`. This is another object which contains properties for the account. Clicking on the link in the type column, it takes us to another table of properties.
The structure of `customer_info > CustomerInfo properties` needs to be replicated under the attributes object. Please see below for a basic example.

## Example 1 - Creating an account

In this example, we'll go ahead and create an account.

### Step 1 - Navigate to API documentation

The first step is to navigate to the PortaBilling API documentation to find out the name of the service and record type that is required. To add a new account, we could search for add\_account. We could also navigate in the documentation to `PortaBilling API methods > Account information > Account management > add_account`.
![API Navigation Menu](https://tray.ai/documentation/images/connectors/service/portabilling/349d67fa-afb05541_api_doc_menu.png)
A sure way to find out the service name is to look at the URL of the API docs page as you click on the links e.g. clicking on the `add_account` link makes the end of the URL change to `Accountadd_account`. This means the service is `Account`, the operation is `add` (create), and the record type is `account`.
![Service and record type in URL](https://tray.ai/documentation/images/connectors/service/portabilling/349d67fa-79f3ecc0_api_doc_url.png)

### Step 2 - Configure input

In the Tray workflow, drag a PortaBilling step to the workflow. Select the `Create record` operation. Select `Account` as the `Service type` and `account` as the `Record type`.
We can now start building up our request. In the API documentation, we can see the the request should contain two high level properties.
![Create account request](https://tray.ai/documentation/images/connectors/service/portabilling/349d67fa-dbe9f72c_account_properties.png)
The `AddAccountRequest` table shows two high level properties that are required to create an account, `account_info` and `generate_web_password`. We can see that there is a nested structure underneath `account_info`. This is a nested object which contains properties for the account. Clicking on the link in the type column, it takes us to another table of properties.
So we add two properties to our attributes object (see below) - the account\_info (which is iteself an object) and generate\_web\_password (a boolean which takes a boolean or a 1 or 0).
![Adding account properties](https://tray.ai/documentation/images/connectors/service/portabilling/349d67fa-811a8d23_add_account_properties.png)
In the screenshot above we are also changing the data type of the properties we are adding i.e. account\_info is an object, generate\_web\_password is a boolean. It should look like the below.
![Example account properties](https://tray.ai/documentation/images/connectors/service/portabilling/349d67fa-3ea82752_example_account_properties.png)

### Step 3 - Adding account properties

Now we can start adding account properties to the `account_info` object. To do this we refer to the table of account properties in the API documentation (see below).
![Account properties](https://tray.ai/documentation/images/connectors/service/portabilling/349d67fa-b3ed493b_account_info.png)
To add a property, click on `Add Property To account_info`. Enter the name of the property exactly as it appears in the API document.
The mandatory fields for creating an account are `bill_status`, `billing_model`, `i_product`, `id` and `i_customer`.
Remember to change the data type so that it matched the API documentation. The exception here is where the property is a 1 or 0 indicating true or false respectively. The data type for these properties can be a boolean and the connector will automatically convert.
Once all the desired account properties have been added, you should have an account\_info object that looks like the below.
![Completed account properties](https://tray.ai/documentation/images/connectors/service/portabilling/349d67fa-cce1c767_completed_account_input.png)

### Step 4 - Run workflow

Once the input properties have been entered. It's time to run the workflow and create the account. If there is anything wrong or missing with the account property names the PortaBilling API will send an error similar to the below.
![API Error](https://tray.ai/documentation/images/connectors/service/portabilling/349d67fa-feed47a5_api_error.png)
This tells us that we did not include the required field `billing_model` on the `account_info` object.

## Example 2 - Listing customers

In this example, we'll list customers in the PortaBilling instance.

### Step 1 - Discover filter attributes

To list records, we can filter on the properties for that record type. The list of properties to filter on can be found in the API documentatoin for PortaBilling.
In the API document, navigate to `PortaBilling API methods > Customer information > get_customer_list` in left menu.
![Navigate to list customer request](https://tray.ai/documentation/images/connectors/service/portabilling/349d67fa-5a3014c5_list_customer_api.png)
Once at the right point in the document, you should be able to see a table of customer filters (see below).
![Customer filters](https://tray.ai/documentation/images/connectors/service/portabilling/349d67fa-b570b6a8_customer_filters.png)
The limit and offset properties used for pagination are added for you, so there is no need to add these to the attributes object.

### Step 2 - Filter by bill status

To retrieve a list of customers filtered by bill\_status, we need to add that property to the attributes object in the input property panel.
We can see from the API documentation that bill\_status has four possible values, O (open), S (suspended), C (closed) and E (exported). Here we will search for customers with bill status of open. So we add new property called `bill_status` and a value of `O`.
![Filter by bill status](https://tray.ai/documentation/images/connectors/service/portabilling/349d67fa-602e22f7_filter_by_bill_status.png)