Is there an API available (published or unpublished) to introspect documents defined in the Integration Server?
Using a document type name I need to determine the structure of the document including field names and types.
Thanks,
Fred
Fred,
You can “walk” an IData structure recursively using a java service. There’s an example of doing this in the WmSamples package.
A pub.flow:tracePipeline call does this on the pipeline “document” when it dumps the pipeline structure and datatypes to the console.
What do you need to do with the structure?
Mark
Sometime back I too was looking for such a utility but couldn’t find any.
Mark - what you have suggested (walk an IData) is meant for an IS Document that is in the pipeline - populated with data. What I wanted to do and perhaps fhouse too is looking to do (apologies if my understanding is incorrect) is to get the structure of the document type, by specifying the fully qualified name. Something like what a ‘tree’ command does in DOS.
I needed this because I was documenting the mapping of IS Documents to the flatfile schemas defined by our Mainframe applications. I managed to write a java service that takes an IS document from the pipeline and creates a “tree” like structure in an excel, but couldn’t find anything that would do the same thing for document types rather than the documents.
Thoughts welcome…
Rohit
Ahhhh.
Well, the node.ndf file that describes a document type is just an XML file after all. I don’t know of any published documentation on its structure, but you should be able to build a document type that contains all of the available IS variable types and get back to what you need to “introspect” the document structure.
If you are doing this just for documentation, you might take a look at the WmDoc sample on Advantage in the Best Practices->Samples and Utilities section.
Mark
Mark
Yes, Rohit is correct. I too am looking for a way to introspect a document type definition rather than an instance of a document in the pipeline. I’m convinced that such an API exists as it’s the type of thing that would probably be used by Developer and Broker Admin when a user requests the structure of a document type.
Interesting idea to access the node.ndf file. I’ll look into that.
As far as what I’m trying to do… well, it’s a long story! Basically I’d like to identify all of the fields in a document type that are list types for use with the xmlNodeToDocument service. Your first suggestion is probablly going to be that I use the “documentTypeName” parameter instead of the “arrays” parameter but unfortunately my document structure will not exactly match my xml. Specifically, my XML will have a root node and the document will not have a parent document field that represents the root node.
Thanks,
Fred
I too think that there should be some API to read the structure of a document type - cuz I believe that’s what is used when you open a document type in the developer editor, but I couldn’t find it. Yes node.ndf is an xml and I did try to make use of it in the past, to get the structure… but the document types that I am dealing with have a fairly complicated and hierarchical structure… at times, the dept of a variable goes upto level 10. Trying to write some kind of service to deal with xml of such documents is a task in itself… I was hoping to leverage the existing code that the developer uses. Wonder if I should decompile a few classes… try to dig through it :rolleyes:
Anyway… if you guys come across anything built-in, please share. Thanks,
Rohit
Good news, wM Support comes through in the clutch!! One of their support team members pointed me towards the following sample that contains a package called WmDoc:
[U][FONT=Tms Rmn][COLOR=#0000ff][URL=“http://advantage.webmethods.com/article/?id=1612707169”]http://advantage.webmethods.com/article/?id=1612707169[/URL][/color][/font][/u]
By using the services contained in the package I was able to develop a series of java and flow services that do the following:
- Service takes package name and interface name as input.
- Use WmDoc\pub.doc.ui:getPackageViewChildren to get a list of all the package children and determine which package children are documents (this was the easy part!).
- Recursively use WmDoc\pub.doc.ui:getNSViewChildren to introspect each document and identify those fields that are defined as list types (string list, document list, object list).
- Build a TreeMap that contains every document in the package. The TreeMap key is the document name and the TreeMap value is a StringList of the document fields that are list type.
For my purposes, I use the information in conjunction with the pub.xml:xmlNodeToDocument service to properly convert arrays (I can’t use the documentTypeName parameter… don’t ask). The services listed above can be used to introspect any package node, not just documents.
Two additional points:
- I couldn’t get the WmDoc package to work in 6.1. The package is intended to provide an HTML view of all nodes defined in the IS Basically, an HTML version of what you see in the left-most pane of Developer. “Out-of-the-box” the package doesn’t work in my 6.1 environment, however, the individual services work fine. This isn’t too surprising as it’s listed as compatible with 6.5 on the website.
- Be careful, wM Support was very clear to point out that the software is not supported or guaranteed to work in future versions of the product!
TWH,
Fred
Thanks for sharing this Fred. Good news - it exists… not so good news - I’m using IS 6.1… but its a good find.
Rohit
Rohit-
Just to clarify, I’m on 6.1 too. The service within the sample package work fine, it’s just the package homepage that has issues in 6.1.
Fred
Fred,
If you are using the WmDoc built-in services to identify document type array elements, what do you do when the same definition might be used in both ways, sometimes as an array and sometimes as a single?
Your pub.xml:validate would still detect a dimension mismatch error.
Mark
Mark-
While designing my custom soap processor/web service framework I considered the following two approaches for converting incoming XML requests into documents (note: I always call pub.schema:validate prior to performing the conversion):
- Create document types that match my incoming XML requests identically, allowing me to use the pub.xml:mlNodeToDocument the “documentType” parameter.
- Advantage: Easy to define new document types by simply importing them from the corresponding schema.
- Disadvantage: Document types have an additional parent node with the same name as the document type. For example, a document used to invoke a web service to update customer data might be called “updateCustomerData”. The document will contain a field called “updateCustomerData” that represents the root node of the XML. In my opinion this is cumbersome when developing the corresponding target flow services.
- “Flatten” my imported document types to remove the document field that represents the root node. Determine the array fields using the process defined in this thread and provide the field names to the pub.xml:mlNodeToDocument “arrays” parameter.
- Advantage: Each document type has a corresponding flow service (the target web service invoked by the custom soap processor) that defines a document type reference as input. In my opinion, the “flattened” document structure makes the target flow service easier to develop and read. For example, referencing a pipeline variable called “updateCustomerData/customerName” is more intuitive that a variable called “updateCustomerData/updateCustomerData/customerName” or even “input/updateCustomerData/customerName”.
- Disadvantage: Additional understanding is required of the developer importing a document from the schema to flatten the document structure. As you noted, if the schema defines two fields with the same name and one is an array while the other is not, the processor will convert them both to arrays.
Ultimately, I decided that improving flow service development outwayed the disadvantage of using the pub.xml:mlNodeToDocument “arrays” parameter and the corresponding restriction it places on defining service inputs/outputs. Furthermore, I’m hosting and defining the web services so I have complete control over the naming of them and don’t need to worry about duplicate field names of different types.
Any feedback would be appreciated!
Thanks,
Fred
Thanks Fred, I will try it out then.
Rohit
Fred,
I guess the alternative is to create a service meta-data repository that specifies the input and output document types for each operation.
I usually create my document types from the schema XSD files and then manually remove the extra layer. That is a painful bit of busy work, but generally only needs to be done once unless the schema changes.
The developer of the Flow service just references that document type and the name of the document type is “registered” in the meta-data repository, so that the custom soap processor knows what to map the content of the body to and also what document type to use for the pub.xml:validate statement if the meta-data indicates that XML validation is required for that operation on either the request or reponse side.
BTW, I think the design for the next version of IS web services will allow you to associate doc types with web services operations a bit more naturally to avoid these extra steps. Too bad we probably won’t see that version until a year from now or more. 
Mark
Mark-
I use a naming convention to alleviate the need for a repository. If the service name is “updateCustomer” then the web service is called “updateCustomer”, the input document is called “updateCustomerRequest” and the output document is called “updateCustomerResponse”.
I also use the schema to import my documents and then name them as described above. As you mention, I also manually remove the extraneous root node when importing, an annoying but tolerable task.
My biggest challenge became mapping the incoming XML request (which in this example contains a root node of “updateCustomerRequest”) to the imported document type. Because I removed the root node my incoming XML does not match the document type definition. This thread provides my solution which is to introspect the document “updateCustomerRequest” and determine the array fields. It imposes the document field naming restriction also discussed in this thread, but provides the benefit of easing flow service development. I suppose I could have also removed the root node from the XML request before calling the pub.xml:mlNodeToDocument service (XQL query maybe?).
Anyway, hope this helps someone!
Fred
One more comment… I made a mistake, the WmDoc package discussed in this thread actually works fine in 6.1!
Fred