Merge branch 'add' into 'master'

*.idea

 No newline at end of file

## Getting Access

Currently, access to the Billing Service is handled through JWT tokens. If you are looking to access the Billing Service and use its functionality please email us (doit-billing-service-support@office365.wisc.edu).

Please include the following information in the email:

* Your name

* Your email address

* The name of the service

* The name of the department in-charge of the service

Once your request is reviewed and approved, we will notify you and provide you a JWT token for access.

 No newline at end of file

## Reporting Database

The Billing Service has a separate SQL based persistence layer for Reporting.

We synchronize the Reporting Database every hour.

- [Tables](#Tables)

    * [Charge](#Charge)

    * [Service](#Service)

    * [Funding Source](#Funding-Source)

- [Connect to Reporting Database through Google Data Studio](#Connect-to-Reporting-Database-through-Google-Data-Studio)

    * [Requesting Access](#Requesting-Access)

## Tables

Information about the tables and its contents are described below

### Charge

The `charges` table contains a copy of all charges in the Billing Service. 

| Column name | Description |

|---|---|

|`id`|Unique identifier for this charge.|

|`amount`|Amount of dollars due|

|`funding_source_id`|The ID of the funding source to be used for this charge.|

|`service_id`|The ID of the service this charge is tied to.|

|`created_date`|Date this charge resource was created in the Billing Service.|

|`service_date`|Date that service was provided.|

|`submitted_date`|Date when this charge was submitted to the external financial system.|

|`processed_date`|Date when this charge was processed in the external financial system.|

|`billable`|Whether this charge is eligible for submission to external financial system.|

|`read_only`|Read only state will be true if the charge has been processed in the external financial system.|

|`cbs_id`|ID for the charge in CBS (external financial system).|

|`line_number`|Line number for a charge of a CBS invoice.|

### Service

The `services` table contains a copy of all services in the Billing Service.

| Column name | Description |

|---|---|

|`id`|Unique identifier for this service.|

|`name`|Descriptive name of the service|

|`cbs_name`|Name used in CBS (external financial system) tables|

|`inventory_number`|Identifier used by financial services for funding location.|

|`inventory_description`|Description of service the inventory number is tied to.|

|`created_date`|Date this service service was created in the Billing Service.|

|`billable`|Whether charges for this service are eligible for submission to external financial system|

|`unit`|Denomination for which the service is quantified|

### Funding Source

The `funding_sources` table contains a copy of all funding Sources in the Billing Service.

| Column name | Description |

|---|---|

|`id`|Unique identifier for this funding source.|

|`dnumber`|DoIT Number - a type of funding string which is always tied to a UDDS.|

|`udds`|Unit, Division, Department, Subdepartment.|

|`project`|Project - a type of funding string.|

|`task`|Task - a type of funding string which is always tied to a Project.|

|`parent_id`|The parent dnumber/udds funding source ID that a project/task funding source will charge to.|

|`valid`|Whether the record is valid for purposes of showback or chargeback reporting.|

|`validation_message`|Information about validation problems.|

|`name`|Descriptive name of this funding source.|

|`created_date`|Date this funding source resource was created in the Billing Service.|

### Charge Error

The `charge_errors` table contains Errors for Charges in the Billing Service.

| Column name | Description |

|---|---|

|`charge_id`|`id` of the charge with this error.|

|`code`|Billing Service internal error code.|

|`message`|Information about this error.|

|`related_resource`|Link to the resource this error is related to.|

## Connect to Reporting Database through Google Data Studio

You can use the PostgreSQL connector in Google Data Studio to connect to the Reporting Database.

(_Please see:_ https://support.google.com/datastudio/answer/7288010?hl=en&ref_topic=7332343)

### Requesting Access

If you are looking to access the Billing Service Reporting Database please email us (doit-billing-service-support@office365.wisc.edu).

Please include the following information in the email:

* Your name

* Your email address

* The name of your department

* The reason for requesting access

Once your request is reviewed and approved, we will notify you and provide you the required credentials.

 No newline at end of file

## Support And Feedback

Please contact us (doit-billing-service-support@office365.wisc.edu) if you need additional help or if you were not able to use the documentation to answer your question.

If you have feedback for us please send us an email.

 No newline at end of file

# Billing Service

## Overview

Billing Service is a REST API which provides an interface for DoIT's Financial System, CBS.

This service allows DoIT Service Providers to send bills for their users to CBS.

The goal of this service is to consolidate billing processes that interact with CBS.

This will allow us to easily switch to a different financial application if CBS were to be replaced, without affecting the billing processes.

Our initial clients are SEO Service Providers for infrastructure services including Physical Server Hosting, Virtual Server Hosting, Bucky Backup and Enterprise Storage, with the intention to expand to other SEO services like Cloud, Azure, etc.

We also intend the Billing Service to be used for reporting purposes and customer inquiries.

Please see [Reporting Database](./docs/reporting-database.md) for more information.

### OpenAPI Specification

Here is a link to our OpenAPI Specification: https://api.test.billing.doit.wisc.edu/api-docs/

The OpenAPI Specification includes descriptions of Billing Service resources and their properties, the available endpoints and supported methods, and examples of requests and responses.

This is the primary location for our API Documentation. Any changes to our API will first be reflected in the OpenAPI Specification.

The Swagger document above allows you to try out the API functionality as well.

You can select the environment you want to interact with and send requests.

You will need the appropriate access token to do so (Please read [Getting Access](./docs/getting-access.md)).

### Responsibilities of Billing Service

The Billing Service API has three resources, `Charge`, `FundingSource`, and `Service`.

#### Charge

The `Charge` resource represents a bill for a customer.

The Billing Service is responsible for submitting valid charges to CBS.

`Charge` resource submission to CBS happens asynchronously from when a user creates the `Charge` resource in the Billing Service.

This allows users of the Billing Service to create `Charge` resources without depending on the availability of CBS.

The Billing Service considers a charge valid if it meets the following criteria:

* The charge is billable (`billable` property is true)

* The charge is billed to a valid `FundingSource` (contains `fundingSourceId` property of a valid `FundingSource`).

* The charge is for a valid `Service` (contains `serviceId` property of a valid `Service`)

__Example__

```

{

  "amount": 450,

  "units": 2,

  "serviceId": "1234abcd-12ab-34cd-56ef-5678efgh90ij",

  "billable": true,

  "fundingSourceId": "5678efgh-12ab-34cd-56ef-1234abcd90ij",

  "serviceDate": "2020-01-01T00:00:00.000Z"

}

```

The Billing Service will append errors to the `errors` property of the `Charge` resource if there are issues with charge submission.

The errors will need to be resolved for the `Charge` resource to be submitted.

__Example__

```

{

  "id": "faeba731-9706-4080-83f7-d5f1c540b41a",

  "amount": 450,

  "units": 2,

  "serviceId": "1234abcd-12ab-34cd-56ef-5678efgh90ij",

  "billable": true,

  "fundingSourceId": "5678efgh-12ab-34cd-56ef-1234abcd90ij",

  "serviceDate": "2020-01-01T00:00:00.000Z",

  "createdDate": "2020-01-04T00:00:00.000Z",

  "errors": [

    {

      "code": 201,

      "message": "Funding Source is not valid."

      "relatedResource": "http://api.test.billing.doit.wisc.edu/fundingSource/5678efgh-12ab-34cd-56ef-1234abcd90ij"

    }

  ]

}

```

The Billing Service checks if a submitted charge has been processed in CBS on an hourly basis.

If it has been processed, the `processedDate` property of the `Charge` resource will be added.

The resource itself will also be set to `readOnly` so that no further changes can be made to the resource.

__Example__

```

{

  "id": "faeba731-9706-4080-83f7-d5f1c540b41a",

  "amount": 450,

  "units": 2,

  "serviceId": "1234abcd-12ab-34cd-56ef-5678efgh90ij",

  "billable": true,

  "fundingSourceId": "5678efgh-12ab-34cd-56ef-1234abcd90ij",

  "serviceDate": "2020-01-01T00:00:00.000Z",

  "createdDate": "2020-01-04T00:00:00.000Z",

  "submittedDate": "2020-01-04T00:00:00.000Z",

  "processedDate": "2020-01-08T00:00:00.000Z",

  "readOnly": true

}

```

The Billing Service is not responsible for submitting credits for customers.

Please contact Financial Services for more information (projectbilling@doit.wisc.edu) regarding Customer Credits.

#### FundingSource

The `FundingSource` resource represents the funding string a bill is charged to.

A `FundingSource` can be one of two types, Dnumber/UDDS type or Project/Task type.

__Example__

A `FundingSource` resource with a Dnumber and UDDS.

```

{

  "id": "5678efgh-12ab-34cd-56ef-1234abcd90ij",

  "name": "Division of Information technology:Enterprise Integrations",

  "billable": true,

  "dnumber": "D000101",

  "udds": "A001001",

  "valid": true,

  "validationMessage": "Funding Source has been validated.",

  "createdDate": "2020-01-01T00:00:00.000Z"

}

```

__Example__

A `FundingSource` resource with a Project and Task.

```

{

  "id": "5678efgh-12ab-34cd-56ef-1234abcd90ij",

  "name": "CBS - Support",

  "billable": true,

  "project": "1001018",

  "task": "200",

  "valid": true,

  "validationMessage": "Funding Source has been validated.",

  "createdDate": "2020-01-01T00:00:00.000Z"

}

```

The Billing Service contains an initial set of `FundingSource` resources with funding strings available in CBS.

The user submitting a charge is responsible for getting the correct funding string information from their customers.

If a `FundingSource` resource with the funding string exists in the Billing Service, its `id` property can be used in a `Charge` resource.

The Billing Service validates `FundingSource` resources against CBS.

If a `FundingSource` resource is not valid, `Charge` resources using it will fail the submission process.

#### Service

The `Service` resource represents the service a bill is charged for.

The Billing Service contains an initial set of services registered in CBS.

The Billing Service validates `Service` resources against CBS and populates the `inventoryNumber` and `inventoryDescription` properties.

The `inventoryNumber` property is required for a `Service` resource to be valid.

This provides CBS information regarding where the revenue should go. 

Service owners are responsible for registering a service with CBS.

Please contact Financial Services for more information (projectbilling@doit.wisc.edu) regarding registering a Service.

### Resources

To further familiarize yourself with REST APIs please use the resources below:

* [REST API](https://www.restapitutorial.com/)

* [Using REST API](https://www.smashingmagazine.com/2018/01/understanding-using-rest-api/)

* [OpenAPI Specification](https://swagger.io/specification/#:~:text=Introduction,or%20through%20network%20traffic%20inspection.)

### Example

DoIT Bucky Backup service needs to send charges to CBS

## Related Documentation

* [Getting Access](./docs/getting-access.md)

* [Reporting Database](./docs/reporting-database.md)

* [Support and Feedback](./docs/support-and-feedback.md)

 No newline at end of file