# LBM Public API User Guide

The Pipeline LBM Public API gives programmatic access to job information, allows adding quantities to jobs, and allows retrieval of generated job BOMs.

This user guide will document the details of using the API and provide a step-by-step guide to using the LBM Public API.

## Endpoints Overview

The available endpoints, their request properties, and returned data types are available on the Swagger page for the API:

https://293-app-prod-pipeline-public-api.azurewebsites.net/swagger/index.html

- A Jobs endpoint allow searching for job information by various properties of each job. This endpoint is paginated by default and returns the first 20 results by default
- A second Jobs endpoint allows retrieving a single job by its ID (not Job Number). An ID will always be an integer, while a Job Number can be any text that Pipeline LBM allows.
- The Jobs Export endpoint allows the retrieval of the last generated BOM for a job. This endpoint does not generate BOMs by itself, and that must be done through Pipeline LBM.
- The Job Quantities endpoint allows adding Products and Key Measures to a Job’s quantities.
- Finally, a Health check endpoint allows the user to check if their JWT token and other request parameters are valid and working, as well as checking that the API is available.


## Authentication and Authorization

The Public API uses an OAuth2 Endpoint located at: https://sso.strongtietech.com/common/oauth2/v1.0/token
Authentication requires a `client_id`, `client_secret`, and the Pipeline LBM tenant name. The tenant name is in the Pipeline LBM URL, for example, within https://lb.pipelinebt.app/lbmsales
, `lbmsales` is the tenant name.
The tenant name is used to request a scoped JWT token to the LBM tenant and is in the format of: `LBMPublicAPI.Customer.<tenant name>`

Here is an example POST request using curl (with the `client_id` and `client_secret` omitted) to obtain a scoped token to the `lbmsales` tenant:


```bash
 curl --location 'https://sso.strongtietech.com/common/oauth2/v1.0/token' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data-urlencode 'grant_type=client_credentials' \
 --data-urlencode 'scope=LBMPublicAPI.Customer.lbmsales' \
 --data-urlencode 'aud=pipeline_lbm_public_api' \
 --data-urlencode 'client_id=...' \
 --data-urlencode 'client_secret=...'
```

Here is an example Postman request to the same endpoint, and with the same information:

![User Guide PipelineLBM -01](/assets/userguide-pipelinelbm-01.7d58464eabc78cd4f751dcfa45114ea24df107dc79d08aa5455dad3eaed08dc0.db900501.png)

The resulting `access_token` is a JWT token used in the Authorization header for requests
to the LBM Public API.

## Required Values

Each request to the LBM Public API requires an `X-Customer` header value set to the same tenant name as above. For example, `X-Customer: lbmsales` would be sent with each request if your tenant name is `lbmsales`

The API Version is also required in the LBM Public API URL path for each request. Currently, the only version is “1”, so a request to the jobs endpoint would have it set as `v1`: https://293-app-prod-pipeline-public-api.azurewebsites.net/api/v1/jobs

## Step-by-Step Guide

As a basic walk-through, we will:

1. Request a JWT token for a Pipeline LBM tenant
2. Create a test job in Pipeline LBM
3. Retrieve the job details by calling the Jobs endpoint
4. Add quantities to the job by calling the Job Quantities endpoint
5. Generate a Job BOM and call the Job Export endpoint


1. Make a request to the https://sso.strongtietech.com/common/oauth2/v1.0/token endpoint to get a valid JWT token for use with the LBM Public API:
![User Guide PipelineLBM -02](/assets/userguide-pipelinelbm-02.9211edc2a38d5b33bbc332d10a168f131d501894f0a47edc9a6d2bd112f995f2.db900501.png)
  - You will need your Pipeline LBM tenant name. Your tenant name will be different than these examples and can be found in the URL you use to access Pipeline LBM.
  - For this example, if we are using this URL to access Pipeline LBM, https://lb.pipelinebt.app/lbmsales, the tenant name would be: `lbmsales`
  - The tenant name `lbmsales` is also used in the scope value for this request: `lbmsales` → `LBMPublicAPI.Customer.lbmsales`
  - Fill in the `client_id` and `client_secret` values given to you
  - Use the returned `access_token` value in the Authorization header for subsequent LBM Public API requests, like any other JWT token: `Authorization: Bearer <access_token>`
  - This tenant name should also be used as the value for the `X-Customer` header for all LBM Public API requests: `X-Customer: lbmsales`
2. Create a Test job with any job number - here I have created the `Test API Job` job:
![User Guide PipelineLBM -03](/assets/userguide-pipelinelbm-03.ecc465ca83246bbbfcbeb0ac49f958878f44ea7e5e904218bdb4500bb87b9e44.db900501.png)
3. We can view the Job’s details by calling the Jobs endpoint and filtering by `jobNumber`:
![User Guide PipelineLBM -04](/assets/userguide-pipelinelbm-04.1ed60948210a71c35cad30d1b95e23fa85a6e2d41b8b9666ceca96be94878be6.db900501.png)
4. Next, we will add some quantities to this job:
![User Guide PipelineLBM -05](/assets/userguide-pipelinelbm-05.41c00d757c2cb9e37d8d854253f3ce5b1fde8ae1d6c2bdc65711b22bfcd542ef.db900501.png)
  - The HTTP Response code is `201 Created` when quantities are successfully added.
  - You will also receive the quantities added to the job in the response. `useName` , `length` , and `sourceName` are all null because we did not submit those values originally.
  - `productName` can be a Product or a Key Measure name.
  - If a `sourceName` is not specified, it will be “Pipeline” by default. Source names can be added via the Job Quantity Source grid on the General Settings page and then specified with the `sourceName` property for each quantity.
  - We can also verify that the products or key measures were added to the Job on the Quantities page:
![User Guide PipelineLBM -06](/assets/userguide-pipelinelbm-06.4b1fa1d20b7d8e3db2118023d8c78da7967f4cb874c452d4f2e04c123ce890d3.db900501.png)
5. Next, generate a BOM within Pipeline LBM.
  - This BOM has many more products shown than its Quantities page because we added Key Measures to the job in step 4.
![User Guide PipelineLBM -07](/assets/userguide-pipelinelbm-07.c4c83008082067ee8a5c5a6448414b405bb3bde2851c4013cd31f416254bc42a.db900501.png)
  - Then, call the Job Export endpoint to get the generated BOM, represented as JSON:
![User Guide PipelineLBM -08](/assets/userguide-pipelinelbm-08.0b37d9e27eef7c8af805201c4340a8749f13d7b600170f3ca102d766e364865f.db900501.png)