UC Davis Setup - ucdavis/StratoCore-API-Python-Example GitHub Wiki

This project is derived from https://pypi.org/project/pyppms/. That project however, only supports managing users. For UC Davis purposes we've added the ability to query order and invoices and to create new orders. I am not familiar enough with pytest to generate unit tests for these new features so any help you can provide would be appreciated.

This is a demonstration tool and proof of concept. If you would like to use this code in a working, production system you will need to modify and/or copy the code for your use case. Note: there is an entirely separate API called PPMS API2 that has a similar authentication mechanism with a different URL path and token. However API2 does not support creating orders.

Running the Examples:

  1. Ensure that you have Python installed and configured
  2. Clone this git repository locally
  3. Install pip. You can use pip install -e /path/to/repo to map a local package to your working Git repository. Alternatively, you can install "build" using pip install build then run python -m build from your repo to create package files that can be deployed to a server.
  4. Work with the campus resource to get access to the test Stratocore system. You will need: URL, PUMAPI API Token, and the PUMAPI documentation. The current (Sept 2022) campus contact is Stephani Leber.
  5. Find the puppmsconf.py file in repo/resources/examples and change the "SERVER_URL" in the PUMAPI_URL definition (line 4) to your URL. Example: "https://ppms.us/ucdavis-test/pumapi/"
  6. Create a new environmental variable named PUMAPI_KEY and set the value to your PUMAPI API Token.
  7. Locate the pyppms-example-session.py file and uncomment the examples that you would like to run. I haven't tested all of the examples from the original project, so you may want to focus on the orders and invoices.
  8. Run the pyppms-example-session.py file with py pyppms-example-session.py

Note: you may need to insert orders and/or invoices in the test Stratocore system before any results will appear.

How Commands are Sent to Stratocore

  • The communication uses simple POST requests (over HTTPS) to the PUMAPI_URL
  • All requests require a parameter "apikey" with a value of the PUMAPI API Token
  • All requests require a parameter "action" with a value of defined in the PUMAPI documentation. Example: 'getorders', 'createorder', 'getinvoicelist'
  • Each action may have one or more parameters as defined in the PUMAPI documentation. For example the 'getorderlines' action takes a parameter of 'orderref'
  • Responses can be in many formats (see PUMAPI documentation). Some return singular values, for example 'createorder' returns the 'orderref' value. Many queries return what the documentation refers to as "CSV" format.
  • CSV format includes comma-delineated values in one or more rows. Values may be surrounded by double quotes. Often, CSV results do not start until the third line of the results with the first line being a descriptor and the second line being the column headers. Read the README file for more details.

Working with Orders and Invoices

  • The API does not support creating or modifying invoices
  • The API allows the creation of single-line orders only -- you cannot create a multi-line order so if you have multiple products to add you will need to run the 'createorder' action once for each. This action requires: the serviceid (defined in StratoCore), the customer/user assigned to the order, and the quantity. There are other optional parameters described in the documentation.
  • Only accepted and completed orders can be added to an invoice. The StratoCore web interface provides a means to accept and complete orders. Apparently API2 can accept or complete an order, but that has not been tested. Through PUMAPI you cannot accept or complete an order _after _creation, although you can mark it at accepted and/or completed during creation.
  • Once an order is "accepted" and "completed" a StratoCore user (through the web interface) can add it to an invoice. All completed orders for a given customer are consolidated automatically when creating invoices so the user does not need to hunt for orders. This mitigates the problem of only allowing single-line orders through the API. The example code will automatically mark new orders as accepted and completed. Depending on the workflow requirements of the team, this may be expected behavior.

In this screenshot multiple single-line orders are consolidated into a single invoice automatically because they were all completed and belong to the same user/client. image