Afasgem
This very creatively named get wraps communication with AFAS get and updateconnectors
Installation
Add this line to your application's Gemfile:
gem 'afasgem'
And then execute:
$ bundle
Or install it yourself as:
$ gem install afasgem
Usage
General config
This gem can be configured using the well known ruby configure block
# Start the config block
Afasgem.configuration do |config|
# The WSDL url of the AFAS getconnector
# Probable format: https://<Environment number>.afasonlineconnector.nl/ProfitServices/AppConnectorGet.asmx?WSDL
config.getconnector_url = 'getconnectorurl'
# The WSDL url of the AFAS updateconnector
# Probable format: https://<Environment number>.afasonlineconnector.nl/ProfitServices/AppConnectorUpdate.asmx?WSDL
config.updateconnector_url = 'updateconnectorurl'
# The WSDL url of the AFAS updateconnector
# Probable format: ?
config.dataconnector_url = 'dataconnectorurl'
# The token to use
config.token = 'token'
# The number of rows to fetch when not specified
config.default_results = 150
# Whether to log all requests to the console
config.debug = true
end
To start communicating with AFAS you need to construct a connector using the
Afasgem.getconnector_factory and Afasgem.updateconnector_factory. Both take
the connectorId (the name of the connector, for example Profit_Debtor) as an
argument
This will return a configured get or updateconnector instance that is ready to communicate.
Getconnector
Create a getconnector using the factory after configuring afasgem
conn = Afasgem.getconnector_factory('Profit_Debtor')
Fetching data
The easiest way to get data out of a connector is to simply call get_data.
This will return an array of results, each in a hash. This hash will have the
AFAS field names as keys.
conn.get_data # [{result 1}, {result 2}]
The data xml is available using get_data_xml. This is the xml that contains
the data itself. Not the full SOAP request
get_result will return the full response as a hash. This also is not the full
SOAP request but just the interesting part of the response
When using get_result, get_data, or get_data_xml, the response
is cached and new requests will only be done when something was changed using
the pagination handlers below.
Calling execute issues a new request, even if nothing was changed
To get all data at once, the get_all_results method is available. This will
fetch all rows in a connector. Sadly there is no way to tell how many records
there are in total before fetching them all.
Handling pagination
conn.take(n) # Configures the connector to fetch n records at a time
conn.skip(n) # Configures the connector to skip the first n records
conn.page(n) # Provides a simple way to get the nth page of results, 1 indexed
conn.next # Gets the next page of results
conn.previous # Gets the previous page of results
All of the above methods provide fluent interfaced, meaning they can be chained.
# Will fetch result 15-25 since we are fetching 10 results a page,
# skipping the first 5 and then going to page 2
conn.take(10).skip(5).next.get_data
Filtering
This gem also wraps the filter functionality of the AFAS api. When adding a filter it is added with an and respective to the filters already in place. To filter using an OR you have to explicitly call add_or
# Filter where Field == 'val'
conn.add_filter('Field', FilterOperators::EQUAL, 'val')
# Filter where Field == 'val' && Field2 == 'val2'
conn.add_filter('Field', FilterOperators::EQUAL, 'val')
.add_filter('Field2', FilterOperators::EQUAL, 'val2')
# Filter where Field == 'val' || Field2 == 'val2'
conn.add_filter('Field', FilterOperators::EQUAL, 'val')
.add_or
.add_filter('Field2', FilterOperators::EQUAL, 'val2')
# Filter where (Field == 'val' && Field2 == 'val2') || (Field3 == 'val3')
conn.add_filter('Field', FilterOperators::EQUAL, 'val')
.add_filter('Field2', FilterOperators::EQUAL, 'val2')
.add_or
.add_filter('Field3', FilterOperators::EQUAL, 'val3')
To clear the filters in place use clear_filters
Available operators:
EQUAL # Value is exactly equal
LARGER_OR_EQUAL # Value is larger than or equal
SMALLER_OR_EQUAL # Value is smaller than or equal
LARGER_THAN # Value is larger than
SMALLER_THAN # Value is smaller than
LIKE # Text contains value
NOT_EQUAL # Value is not equal
EMPTY # Field is null
NOT_EMPTY # Field is not null
STARTS_WITH # Text starts with
NOT_LIKE # Text does not contain
NOT_STARTS_WITH # Text does not start with
ENDS_WITH # Text ends with
NOT_ENDS_WITH # Text does not end with
Updateconnector data
To view the fields an updateconnector accepts, there is bin/connector_format. This script takes a few params and then lists the fields the passed updateconnector would accept
Usage: connector_format [options]
-u, --username NAME AFAS username
-p, --password PASSWORD AFAS password
-c, --connector CONNECTOR Name of the UpdateConnector
-e, --environment ENVIRONMENT Name of the environment
-h, --help Show this message
Updateconnector
To Actually write data to the AFAS api you can use the updateconnector_factory. This factory will return an UpdateConnector object that has the following methods:
# Create a connector for the FbItemArticle updateconnector
connector = Afasgem.updateconnector_factory('FbItemArticle')
connector.insert(hash) # Insert data
connector.update(hash) # Update existing data
connector.delete(hash) # Delete existing data
The methods all take a hash that represents the object. Keys in this hash are expected to be fieldnames, while their values are treated like the field's values.
hash = { A: 'b', C: 5 } # => <A>b</A><C>5</C>
The wrapping xml is inferred using the updateconnector name and some constrant data.
Some objects accept nested objects as well as the usual fields. Those should be stored in the Objects key of the passed hash.
# <A>b</A><C>5</C>
# <Objects>
# <X>
# <Element>
# <Fields action='someaction'>
# <D>1</D>
# <E>2</E>
# </Fields>
# </Element>
# </X>
# <Y>
# <Element>
# <Fields action='someaction'>
# <F>3</F>
# <G>4</G>
# </Fields>
# </Element>
# </Y>
# </Objects>
# etc...
hash = { A: 'b', C: 5, Objects: { X: { D: 1, E: 2}, Y: { F: 3, G: 4} }
Development
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/Bonemind/Afasgem.
License
The gem is available as open source under the terms of the MIT License.