Sagekit

Table of Contents

Sagekit is a ruby gem client library to talk with Sage300 API.

sagekit.svg

The gem maps as closely as possible to the Sage300 API so you can easily convert API examples to gem code. Responses are created as objects like. They’re built using OpenStruct so you can easily access data in a Ruby-ish way.

The Sage 300 Web API makes it easier to create services that integrate with Sage 300 data and business logic. The Web API improves on existing tools for third-party integrations without requiring in-depth understanding of the Sage 300 View protocol and components.

Installation

Add this line to your application’s Gemfile: 

gem 'sagekit'

And then execute: 

$ bundle install

Or install it yourself as: 

$ gem install sagekit

Usage

Make sure you have Sage300 web services up and runing. Web service is an easy way to communicate with 3rd party application without hampering the existing system & this is the reason we will always suggest to go for web service integration, whenever any customer requires integration.

Initialize client to make requets: 

require 'sagekit'
client = Sagekit::Client.new(URL, AUTH)
client.sales_orders.list(COMPANY, '$top':10)

Make sure to change:

  • URL with the web serive url Example: http://localhost/Sage300WebApi/v1.0/-/SAMLTD/AR/ARCustomers

    Component Description Example
    {protocol} The application protocol enabled in IIS setup http, https
    {host} The path to the Web API localhost/Sage300WebApi
    {version} The API version v1.0
    {company} The org ID of the company being requested SAMLTD
    {module} SAge300 application module AR, AP, GL, IC
    {resource} The resource entity being requested APVendors, ARCustomers

    {company} needs to be pass by the request, module and resource the gem will take car of.

  • AUTH with the Basic authentication key, Example:
Authorization: Basic QURNSU46QURNSU4=
(constructed for user "ADMIN" and password "ADMIN")
  • COMPANY with teh company id

Resources

The simplest way to retrieve records of a particular resource is to call a GET (list object). 

client.sales_orders.list('COMPANY')

Currently the maximum number of records that can be returned for a single GET request is 100. In order to retrieve records beyond the first 100 or find records based on a given set of criteria, the use of query options is required.

To reduce the number of requests necessary for transferring large datasets, the maximum page size can be adjusted from the default value of 100 records per request.

Query options

Component Example
{query-options} $skip:100
  $filer:“CustomerNumber eq ‘LEPEPE’”
  $select
  $top:5
  $count:true

  • $skip

    The $skip query option must be a positive integer N that specifies the records beyond which the response feed should start with, effectively skipping N records. This is typically used to retrieve records beyond the top 100, the default maximum limit of a single response page. 

        client.sales_orders.list('COMPANY', '$skip':5)

  • $top

    The $top query option must a positive integer N that specifies the maximum number of records the response feed could contain, effectively selecting the first N records. 

        client.sales_orders.list('COMPANY', '$top':2)

  • $count

    The $count query option specifies whether a count of all records will be returned as part of the response feed, regardless of how many records are actually returned in the response.

  • $select

    The $select query option get records with a subset of properties to include in the response 

        client.sales_orders.list('COMPANY', '$select':'OrderNumber,CustomerNumber')

  • $filter

    The $filter query option specifies a set of criteria that records must satisfy before being returned, effectively allowing the caller to retrieve a subset of the resource collection based on a specified filter. Expressions can reference properties as well as literals. Literal values can be strings enclosed in single quotes, dates, numbers, and boolean values. The following is a list of the operators that are supported in the Sage 300 Web API:

    Operator Description Example
    eq equal ’$filter’:“City eq ‘Miami’”
    ne not equal ’$filter’:“City ne ‘Miami’”
    gt greater than ’$filter’:“NumberOfDaysToPay” gt 30“
    lt less than ’$filter’:“AccountPastDue” lt 90“
    le less than or equal to ’$filter’:“DateLastMaintained le datetime’2015-12-31T12:00’”
    and and ’$filter’:“GroupCode eq ‘EXPORT’ and OnHold eq ‘No’”
    or or ’$filter’:“City eq ‘Los Angeles’ or City eq ‘Miami’”

Combining query options 

client.customers.list('COMPANY', '$filter':"CustomerNumber eq '112321' and OrderType eq 'Active'", '$skip':5, '$top':2)

Account Receivable (AR)

Customers

client.customers.list('COMPANY')
client.customers.retreive('COMPANY', 'IDCUST')
client.customers.create('COMPANY', {})
client.customers.update('COMPANY', 'IDCUST', {})
client.customers.delete('COMPANY', 'IDCUST')

Customer Groups

client.customer_groups.list('COMPANY')
client.customer_groups.retreive('COMPANY', 'GROUPCODE')
client.customer_groups.create('COMPANY', {})
client.customer_groups.update('COMPANY', 'GROUPCODE', {})
client.customer_groups.delete('COMPANY', 'GROUPCODE')

Customer Terms

client.customer_terms.list('COMPANY')
client.customer_terms.retreive('COMPANY', 'TERMSCODE')
client.customer_terms.create('COMPANY', {})
client.customer_terms.update('COMPANY', 'TERMSCODE', {})
client.customer_terms.delete('COMPANY', 'TERMSCODE')

Sales Persons

client.sales_persons.list('COMPANY')
client.sales_persons.retreive('COMPANY', 'KEY')
client.sales_persons.create('COMPANY', {})
client.sales_persons.update('COMPANY', 'KEY', {})
client.sales_persons.delete('COMPANY', 'KEY')
client.sales_persons.statistics('COMPANY')
client.sales_persons.filter_stats('COMPANY', 'SALESPERSON', 'YEAR', 'PERIDO')

Account Sets

client.account_sets.list('COMPANY')
client.account_sets.retreive('COMPANY', 'KEY')
client.account_sets.create('COMPANY', {})
client.account_sets.update('COMPANY', 'KEY', {})
client.account_sets.delete('COMPANY', 'KEY')

Account Payable (AP)

Invoices Batches

client.invoice_batches.list('COMPANY')
client.invoice_batches.retreive('COMPANY', 'NUMBER')
client.invoice_batches.create('COMPANY', {})
client.invoice_batches.update('COMPANY', 'NUMBER', {})

Vendors

client.vendors.list('COMPANY')
client.vendors.retreive('COMPANY', 'VENDCODE')
client.vendors.create('COMPANY', {})
client.vendors.update('COMPANY', 'VENDCODE', {})
client.vendors.delete('COMPANY', 'VENDCODE')
client.vendors.statistics('COMPANY', 'VENDCODE')

Vendor Groups

client.vendor_groups.list('COMPANY')
client.vendor_groups.retreive('COMPANY', 'GROUPCODE')
client.vendor_groups.create('COMPANY', {})
client.vendor_groups.update('COMPANY', 'GROUPCODE', {})
client.vendor_groups.delete('COMPANY', 'GROUPCODE')

Vendor Terms

client.vendor_terms.list('COMPANY')
client.vendor_terms.retreive('COMPANY', 'TERMSCODE')
client.vendor_terms.create('COMPANY', {})
client.vendor_terms.update('COMPANY', 'TERMSCODE', {})
client.vendor_terms.delete('COMPANY', 'TERMSCODE')

Invenotry Control (IC)

Items

client.items.list('COMPANY')
client.items.retreive('COMPANY', 'ITEMNO')
client.items.create('COMPANY', {})
client.items.update('COMPANY', 'ITEMNO', {})
client.items.delete('COMPANY', 'ITEMNO')

Categories

client.categories.list('COMPANY')
client.categories.retreive('COMPANY', 'CATEGORY')
client.categories.create('COMPANY', {})
client.categories.update('COMPANY', 'CATEGORY', {})
client.categories.delete('COMPANY', 'CATEGORY')

Locations

client.locations.list('COMPANY')
client.locations.retreive('COMPANY', 'LOCATION')
client.locations.create('COMPANY', {})
client.locations.update('COMPANY', 'LOCATION', {})
client.locations.delete('COMPANY', 'LOCATION')

Order Entry (OE)

Sales Orders

client.sales_orders.list('COMPANY')
client.sales_orders.retreive('COMPANY', 'ORDERID')
client.sales_orders.create('COMPANY', {})

Create sales order passing json payload instead of ruby atributes. 

client.sales_orders.create_json('COMPANY', {})

Invoices

client.invoices.list('COMPANY')
client.invoices.retreive('COMPANY', 'INVUNIQ')

Sales History

client.sales_history.list('COMPANY', {})
client.sales_history.details('COMPANY', {})
client.sales_history.stats('COMPANY', {})

Credit Notes

client.credit_notes.list('COMPANY', {})
client.credit_notes.retreive('COMPANY', 'CNUNIQ')
client.credit_notes.create('COMPANY', {})

Purchase Orders (PO)

Purchase Orders

client.purchase_orders.list('COMPANY')
client.purchase_orders.retreive('COMPANY', 'SECUENCEID')
client.purchase_orders.create('COMPANY', {})

Receipts

client.receipts.list('COMPANY')
client.receipts.retreive('COMPANY', 'SECUENCEID')
client.receipts.create('COMPANY', {})

Vendor Contract Costs

client.vendor_contract_costs.list('COMPANY')
client.vendor_contract_costs.retreive('COMPANY', 'ITEMNO', 'VENDCODE')
client.vendor_contract_costs.create('COMPANY', {})
client.vendor_contract_costs.update('COMPANY', 'ITEMNO', 'VENDCODE', {})
client.vendor_contract_costs.delete('COMPANY', 'ITEMNO', 'VENDCODE')

Performance tips

It is possible to adjust the performance of Sage 300 Web API if improvements are required for integration purposes.

Increase page size for requets

When large amounts of records need to be retrieved through Sage 300 Web API, the page size setting can be increased to reduce the number of GET requests and thus reduce the overall time for the entire process.

In order to increase the page size setting, you can use a text editor to open the Web.config file located in the Online\WebApi folder under your Sage 300 installation folder. Search for the line in this file that contains the following text: 

<add key="PageSize" value="100" />

Increase the value to the required page size. The recommended setting for large numbers of records is 1000.

Change IIS idle time

By default, IIS terminates a web application after 20 minutes of inactivity. This means that if Sage 300 Web API requests are not made within 20 minutes of one another, a request will take longer than usual to process. To curb this behavior, the IIS application pool Idle Time-out setting can be adjusted.

To increase the Time-out time and Time-out Action:

  1. Open IIS Manager
  2. In Application Pools, select Sage300 Pool.
  3. In the Actions pane, click Advanced Settings.
  4. In the Process Model section, change the Idle Time-out Action from Terminate to Suspend.
  5. The Idle Time-out time should be increased to a more reasonable amount. 1447 minutes is the recommended value, as it is greater than a single day.

Contributing

Everyone is encouraged to help improve this project. Bug reports and pull requests are welcome at https://github.com/lepepe/sagekit/pulls. Feel free to open an issue to get feedback on your idea before spending too much time on it.

License

The gem is available as open source under the terms of the MIT License.

TODO Sagekit todo list.

  • [ ] Testing API requests
  • [ ] Add endpoints for:
    • [ ] Common Services
    • [ ] General Ledger
    • [ ] Complete other module’s endpoints

Author: Jose Perez

Created: 2021-12-22 Wed 22:39