Sagekit

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

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')

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:

Open IIS Manager
In Application Pools, select Sage300 Pool.
In the Actions pane, click Advanced Settings.
In the Process Model section, change the Idle Time-out Action from Terminate to Suspend.
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.

Sagekit todo list.

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

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
bin		bin
docs		docs
lib		lib
spec		spec
.gitignore		.gitignore
.rspec		.rspec
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
Gemfile		Gemfile
LICENSE.txt		LICENSE.txt
README.org		README.org
Rakefile		Rakefile
sagekit.gemspec		sagekit.gemspec

License

lepepe/sagekit

Folders and files

Latest commit

History

Repository files navigation

Sagekit

Installation

Usage

Resources

Query options

Account Receivable (AR)

Customers

Customer Groups

Customer Terms

Sales Persons

Account Sets

Account Payable (AP)

Invoices Batches

Vendors

Vendor Groups

Vendor Terms

Invenotry Control (IC)

Items

Categories

Locations

Order Entry (OE)

Sales Orders

Invoices

Sales History

Credit Notes

Purchase Orders (PO)

Purchase Orders

Receipts

Vendor Contract Costs

Performance tips

Increase page size for requets

Change IIS idle time

Contributing

License

Sagekit todo list.

About

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases 4

Packages 0

Languages

Packages