Forum OpenACS Development: Is there documentation for acs-service-contract?

Is there documentation available for acs-service-contract? I plan one creating an interface to an alternate credit-card gateway. Cybercash is no more and I plan on developing an interface to

This is going to be quite involved as Cybercash had a unique workflow and there are several severe bugs in the ecommerce module. Gilbert Wong did an excellent job of porting the ecommerce package but these bugs are inherited from ACS 3.x.

I hope that with the acs-service-contract documentation I'll be able to get a better understanding of how to separate the credit-card handling from the rest of the ecommerce module with a clean interface.

While I'm interested in an interface to others might be keen on different gateways. All input (and help) is welcome.

There is no documentation currently for acs-service-contract. But, let me give it a try:
  • A contract is comprised of abstract operations (e.g. search is an abstract operation of the FtsEngineDriver contract).
  • An implementation of a contract maps/alias the abstract operations to concrete functions (e.g. openfts_driver__search is the alias for the search operation of FtsEngineDriver)
  • You have to contact Gilbert Wong and together decide on a good set of abstract operations for credit card handling. These abstract operations comprise your credit-card-gateway contract (interface) and in order to separate credit-card handling from the rest of the ecommerce package, the ecommerce package should support this contract. I don't know to what extend Gilbert will be available to help with this one but I assume he will be more interested after the first OpenACS release.
  • You have to foresee all possible implementations (e.g. verisign,, e-clear, etc) while deciding the abstract operations.
Bart, if you volunteer to help, I can provide information on how to specify the object-display contract (for community-member.tcl). This will be good practice before you undertake the task of specifying a credit-card-gateway contract.
I know Gilbert's very interested in different payment gateways, too.  You should also give thought to whether or not you can provide a reasonable abstraction that can cover manual settlement (i.e. encrypted e-mail of order information followed by manual credit card verification).

It would be great to have payment services separated from e-commerce, since e-commerce is only one package that might make use of such a tool.

Another obvious client would be an events package, or components of a dotLRN solution where on-line registration
might be allowed, etc.  Or donation handling for non-profits.  The potential list is lengthy and payment services should be a central service of the toolkit.

Posted by Jun Yamog on
Yes I think this is the right direction.  On ACS 3.x we had to push for cybercash despite the uncertainty.  This will make OpenACS 4.0 more flexible.

This will also make other packages that needs credit card processing easier.  Like for example making ecommerce-lite etc.  Based from the my ACS 3.x stint with ecommerce I am sure that there will a lot of implementation that would not use the bagage of ecommerce.

Has anyone able to use other payment gateways in ACS 3.x?


I'm working on tying the ecommerce search function to openfts. Can you define what the impl_name and impl_owner_name are in the following sql code?

select acs_sc_impl__new(
           'FtsContentProvider',                -- impl_contract_name
           'note',                              -- impl_name
           'notes'                              -- impl_owner_name

My first guess is that the impl_name is an identifier and the impl_owner_name is the name of the package. Is that statement correct?

Eventually, I would like to get some information on how to write a service contract. Is there any code that I can look at to see how it should be written?


Can you define what the impl_name and impl_owner_name are in the following sql code?
The impl_owner_name is the package key of the package that provides the implementation (in our case ecommerce). The impl_name should be the object_type of the items that you want to index/search. So, for example ec_product, if you want to index/search ecommerce products. The sql code is:

select acs_sc_impl__new(
          'FtsContentProvider',                -- impl_contract_name
          'ec_product',                        -- impl_name
          'ecommerce'                          -- impl_owner_name
Note that for FtsContentProvider to work ok, you might need to write some triggers to update the search_observer_queue table. Unless, your content items are stored in the CR, you need to write the triggers. For examples look at notes-sc-create.sql and content-search.sql.
Eventually, I would like to get some information on how to write a service contract. Is there any code that I can look at to see how it should be written?
So far we have identified two kinds of contract:
  • impl_name is an object_type: We decide on which implementation to use by computing the type from an object_id using acs_object_util__get_object_type. FtsContentProvider is an example of this kind of contract.
  • impl_name is a package_key: We decide on which implementation to use by using the value of the parameter in the dependant package (the package that uses the contract). FtsEngineDriver is an example of this kind of contract.
If you want to write the PaymentGateway (pls, try to use this naming convention) contract, then the second case is probably what you'll need. Additionally, when writing a service contract you should try to foresee all possible implementations of the service contract. This involves two steps:
  • Decide what the operations are.
  • Decide on the message types (input/output). While message types are not being used extensively at this moment, they will soon be used to provide WSDL functionality.
  • It is very important to note that once a contract is stabilized/released there is no turning back. At least it will be difficult to update all available implementations -- and probably we won't know all the implementations because people might have independantly developed their own implementations of a contract. Maybe, we should keep track of all implementations of a contract at a repository when the new site is released so that we can inform people when something changes (I haven't thought of this very much, so if someone has a different POV please let us know).

Check search-sc-create.sql for the specification of FtsContentProvider and FtsEngineDriver. If you think your service contract doesn't fit in any of these categories please post more questions.

In case, you are writing a contract based on a package key, then the packages that make use of that contract should have a parameter named after the contract name and they will hold the value of the implementation to use. For an example check the search package. It has a parameter named "FtsEngineDriver" set to "openfts-driver".