Home » discuss » Public forums » Developing for iMIS

SOA Documentation

Posted March 20th, 2012 by lbarclay
|

The documentation for SOA needs to be fixed up. For example:

http://docs.imis.com/SOA/index.htm?turl=commonoperations.htm

has a line saying "To Use Find - (TBD) - Include  a query". The query object should really be documented. This page also has "The details are removed:" everywhere.

On this page:

http://docs.imis.com/SOA/index.htm?turl=usingtheclientlibrar.htm

The code doesn't even compile.

On the class description page:

http://docs.imis.com/SOA/index.htm?turl=classdescriptions.htm

It has a basic list of the properties - but none of the useful information like what the properties actually mean or what data they should have. My particular favourite is the quote :

// Party is a complex item in its own right.
// It is beyond the scope of this documentation to cover it.

I mean, really.

The PHP toolkit examples page:

http://docs.imis.com/SOA/index.htm?turl=phptoolkitexamples.htm

I initially couldn't get the "Add a person" to work, the

"AddressPurpose = 'Work Address';"

line was causing problems, as in our DB it should have been set to "Business" - according to entries in the dbo.System_Params table - it would have been nice if this was mentioned in the doco, eg, "possible values for this field are A,B or C or come from table x".

 

‹ Populating SOURCE_CODE and CAMPAIGN_CODE for a ComboOrderDataWCM Multiple master pages ›
login or register to post comments | printer friendly version

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Agreed. The documentation

On March 20th, 2012 dharper says:

Agreed. The documentation is half finished and incorrect. Function parameters are also used in example code in the wrong order.

There's also example code where a variable named "row" appears out of nowhere and isn't defined. Looks like a copy and paste job gone seriously wrong.

login or register to post comments

Thanks for the feedback.

On March 21st, 2012 Courtney Weatherton says:

Thanks for the feedback. We've been hearing from several people that better Soa documentation is needed. As a developer myself, I 100% agree that documentation and examples are very important. We've already begun making updates and you should see better explanations and examples in the weeks and months to come. While we're focusing on the doc, is there something specific you'd like to see?

Courtney Robertson
Senior Software Developer
ASI

login or register to post comments

Absolutely: * Clear

On March 21st, 2012 lbarclay says:

Absolutely:

* Clear documentation for each method. How to use them, what each parameter's possible values are, possible errors thrown etc.

* Downloadable samples that work. One each for c#, php and java.

* Examples and a clear explanation on how to setup the web service.

* Examples for how to use the interface in c# without using the supplied Helper library. Supplying a helper library for a soap web service really defeats the whole point of having an interoperable web service.

On this page:

http://docs.imis.com/SOA/index.htm?turl=commonresources.htm

You recommend either using the provided access tool kits (fine, but personally I don't want to rely on them) or parsing the XML yourself, which I personally think is insane. To any other developers reading this, please don't do that, you are just making life incredibly difficult for yourself and re-inventing the wheel. The most sensible option is to generate the proxy yourself. 

Oh and BTW, this page doesn't have a code sample but it says it does:

http://docs.imis.com/SOA/index.htm?turl=entityservice.htm

login or register to post comments