Metadata-Version: 2.4
Name: orpythonsdk
Version: 1.4.0
Summary: Python SDK for the OnRamp public API.
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0

<!-- GENERATED FILE. Do not edit README.md directly. Edit README_PUBLIC.md and examples/main.py, then run PushSDKToGit.ps1. -->

# OnRamp Python SDK

Python client for the OnRamp public API.

## Install

```powershell
python -m pip install --extra-index-url https://git.onramp-solutions.com/api/packages/OnRampSDK/pypi/simple orpythonsdk
```

## Basic Usage

```python
from orpythonsdk import OnRampAPI

api = OnRampAPI("https://onramp.customer.com/ProductionCopy/")
api.APILogin("api_user", "api_password")

print(api.SessionID)

api.KeepSessionAlive()
api.LogOut()
```

`APILogin` stores the session ID on the `OnRampAPI` instance. Most methods use that stored session, so callers do not need to pass `sess` into every API call.

To attach to an existing session:

```python
api = OnRampAPI("https://onramp.customer.com/ProductionCopy/")
```

## API Queries

Use `RunAPIQuery` for registered API queries.

Use a dictionary when the query parameters are named in OnRamp.

```python
rows = api.RunAPIQuery("QL-10000008", {"param_name": "param_value"})

for row in rows:
    print(row)
```

Use a list as args when the query expects indexed or positional parameters.

```python
customers = api.RunAPIQuery("Q-10010176", ["1/1/1900"])

for customer in customers:
    print(customer["cusm_id"], customer["cusm_name"])
```

If a registered query performs an action and returns `Executed`, `RunAPIQuery` returns that response. If the response is neither an array nor `Executed`, the SDK raises an exception.

## Screen Calls

```python
from orpythonsdk import ORApiScreenMode, ORApiScreenOKCancel

screen = api.ScreenLoad("S2431")

api.ScreenEnterFrame(screen, "01")
api.ScreenEnterMode(screen, ORApiScreenMode.Add)
api.ScreenSetControlValue(screen, "01-01-01", "TaskID ID")
api.ScreenSetControlValue(screen, "01-01-02", "TaskID Desc")
api.ScreenOKCancel(screen, ORApiScreenOKCancel.OK)

errors = api.ScreenGetCurrentErrors(screen)
api.CloseScreen(screen)
```

## Message Boxes And Files

Some screen actions can trigger modal message boxes. Use `SetAutoMsgBoxAnswer` to choose the automatic answer for future prompts in the current session.

```python
from orpythonsdk import ORApiAutoAnswerMsgBoxOption

api.SetAutoMsgBoxAnswer(ORApiAutoAnswerMsgBoxOption.Yes)

# Do work that may trigger a modal prompt.

api.SetAutoMsgBoxAnswer(ORApiAutoAnswerMsgBoxOption.NoneOption)
```

The setting is sticky for the session. Reset it to `NoneOption` when finished.

## File Download

```python
screen = api.ScreenLoad("S2431")
file_name = api.ScreenGetControlValue(screen, "01-01-03")
api.ScreenGetControlFile(screen, "01-01-03", f"C:\\Temp\\{file_name}")
api.CloseScreen(screen)
```

## Full Example

The full example code is included below.

```python
import sys
from pathlib import Path

# Local repo debug import:
#sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from OnRampAPI import OnRampAPI
from OnRampAPI import ORApiAutoAnswerMsgBoxOption, ORApiScreenMode, ORApiScreenOKCancel


DOWNLOAD_FOLDER = r"C:\Temp"


def print_api_error(error):
    if len(error.args) == 4:
        status_code, message, error_type, stack_trace = error.args
        print("StatusCode =", status_code)
        print("Message =", message)
        print("Type =", error_type)
        print("StackTrace =", stack_trace)
        return

    print("Error type:", type(error).__name__)
    print("Error:", error)


def test_web_api():
    # Create an instance of OnRampAPI.
    api = OnRampAPI()

    # ProductionCopy endpoint.
    api.Url = "https://onramp.customer.com/ProductionCopy/"

    # Production endpoint.
    # api.Url = "https://onramp.customer.com/Production/"

    try:
        # The web requests themselves are handled in the OnRampAPI package.
        # Exceptions can be raised on any request. OnRamp server exceptions include
        # status code, message, type, and stack trace details.
        api.APILogin("api_user", "api_password")

        # Sessions expire after a configured timeout. If your thread is alive for a
        # long period of time, KeepSessionAlive can push the active session forward.
        api.KeepSessionAlive()

        # Execute query QL-10000008 with named parameter part_type for purchased parts.
        api.RunAPIQuery("QL-10000008", {"part_type": "P"})

        # Get data from OnRamp with a specified query number and iterate over results.
        # Parameters are denoted in the query and passed as an array to RunAPIQuery.
        customer_data = api.RunAPIQuery("Q-10010176", ["1/1/1900"])
        for customer in customer_data:
            customer_id = customer["cusm_id"]
            customer_name = customer["cusm_name"]
            print(customer_id + "-" + customer_name)

            customer_contacts = api.RunAPIQuery("Q-10010177", [customer_id])
            for contact in customer_contacts:
                contact_name = contact["peop_full_name"]
                contact_email = contact["peop_email"]
                print("  Contact:", contact_name, contact_email)

            customer_open_invoices = api.RunAPIQuery("Q-10010178", [customer_id])
            for invoice in customer_open_invoices:
                inv_number = invoice["ivcm_inv_num"]
                inv_open_bal = invoice["ivcm_open_bal"]
                print("  Invoice:", inv_number, inv_open_bal)

        # Example of using the API to open screen S2431.
        screen = api.ScreenLoad("S2431")

        # Get file name from control value and create a save file path.
        file_name = api.ScreenGetControlValue(screen, "01-01-03")
        file_path = f"{DOWNLOAD_FOLDER}\\{file_name}"

        # Download file from that screen control.
        api.ScreenGetControlFile(screen, "01-01-03", file_path)

        # All API screen functions require the screen instance GUID as the first argument.
        api.ScreenEnterFrame(screen, "01")

        # Mimic a user activating a frame mode.
        api.ScreenEnterMode(screen, ORApiScreenMode.Add)

        # Mimic a user entering data into fields. Use F1 in OnRamp text boxes to get IDs.
        api.ScreenSetControlValue(screen, "01-01-01", "TaskID ID")
        api.ScreenSetControlValue(screen, "01-01-02", "TaskID Desc")

        # Commit data to the databound frame.
        api.ScreenOKCancel(screen, ORApiScreenOKCancel.OK)

        # Retrieve a specific value on the screen.
        current_value = api.ScreenGetControlValue(screen, "01-01-01")
        print("Current value:", current_value)

        # Retrieve current screen errors.
        errors = api.ScreenGetCurrentErrors(screen)
        print("Screen errors:", errors)

        # Jump to a specific grid record by key value.
        api.ScreenGridFind(screen, "01-01-01", "asdf")

        # Close screen and garbage collect on server.
        api.CloseScreen(screen)

        # Reset sticky modal dialog behavior for this session.
        api.SetAutoMsgBoxAnswer(ORApiAutoAnswerMsgBoxOption.NoneOption)
        api.LogOut()
        print("TestWebAPI completed successfully.")

    except Exception as error:
        print_api_error(error)


if __name__ == "__main__":
    test_web_api()
```

