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.