Schema for XML/JSON used in Mail Merge API of Aspose.Words Cloud

Please provide a schema (for example a RelaxNG file) and/or other documentation of permitted values for the XML and/or JSON which may be used in an executeMailMerge and executeTemplate Cloud API Call.


(Even better would be a web page with a validator. . .)

The current documentation (at least what I can find) is insufficient to determine why a particular piece of otherwise valid XML and/or JSON is not accepted by the API. Thus, it is difficult without extensive trial-and-error to construct XML that satisfies the API.

As an example, the templates features page suggests checking the examples in the Mail Merge examples, but none of the examples indicate why the below provided XML sample fails. It appears perfectly valid and similar to other examples provided in the forms and in the documentation.

However, sending it in an API call to executeMailMerge and/or executeTemplate fails with the following message: “The same table ‘contact’ cannot be the child table in two nested relations.” It would be helpful to understand what the problem is with this particular XML. However the root problem is that, without a schema, there is no visibility into what would be valid XML; without constructing it and sending it to the API.

<?xml version="1.0" encoding="utf-8"?>

Peter Piggy

Frank Fox


Hi,

There are two solutions to this issue:

1. Remove one dot from the name of your fields i.e. change them to sender.name and recipient.name and update your XML accordingly e.g.

Sender Name

Recipient Name

  1. If you want to keep two dots in your field names, then change middle part of the name i.e. change sender.contact.name to sender.sendercontact.name and recipient.contact.name to recipient.recipientcontact.name, and update the XML accordingly e.g.

    <letter_data>

    <letter_data>

    Sender Name

    Recipient Name

    </letter_data>

    </letter_data>

    Best Regards,

Thanks for your suggestion, I’ll try it and hopefully it will enable this example.





But, what I need to know is, how to successfully create the XML (or JSON) form my source data so that I know it won’t be rejected. There is no way for me to know what types of XML structures are allowed or not allowed because there is no documentation or schema on what is permitted. I can change the fields in the template document to be whatever I want them to be.





We have a big pre-existing relational database of information that we need to be able to turn into bits of XML and provide to the API, and it is not going to work to write a customized parser for each individual record on a case by case basis.





Relational databases have lots of nested relationships. It is generally very straightforward to turn relational database data into XML; however, there appear to be some constraints in what XML is accepted by the API; which is what is making this a problem.

Hi,

Mail merge APIs accept data in simple XML format. There are only two requirements:

  1. XML should be enclosed by a tag. Root tag can have any name.
  2. All XML tags other than root tag should match mail merge field names.

Please check the following topics for more details.

http://www.aspose.com/docs/display/wordsnet/Prepare+a+Document

http://www.aspose.com/docs/display/wordsnet/Simple+Mail+Merge+Explained

http://www.aspose.com/docs/display/wordsnet/Mail+Merge+with+Regions+Explained

You can also share a sample XML schema if you want Aspose APIs to support a certain type of schema. We will check the viability and implement it if feasible.

Best Regards,

Gentlemen, thanks again for your continued attention to this issue. I think that either I'm confused about what works or does not work, or you're confused about what I'm asking about. I'm happy to volunteer to be the one that is confused!

But if I'm not confused, then either your statements and documentation is correct and there is a bug in your implementation of XML parsing / templating, or the statements and documentation is wrong and your APIs only accept a very limited subset of XML with substantial constraints on element names. If the former is true, fixing the bug would really help me out, so I'm trying to give you as much information as I can.

Both your messages and the documentation say that Mail Merge APIs accept simple XML data that is enclosed by a tag, and where the XML tags match merge field names.

For example, when I try to upload the the following simple XML data to the execute template API, it is rejected with an HTTP 400 status code and the message: The same table \'signatories\' cannot be the child table in two nested relations.

<?xml version="1.0" encoding="utf-8"?>
Heisenberg Productions
Walter White
Jesse Pinkman
Los Pollos Hermanos
Gustavo Fring
Mike Ehrmantraut

In other words, the Mail Merge APIs do not accept all XML data in the simple XML format that matches your two requirements. There is an additional requirement in the current implementation, which my experimentation thus far indicates is something like:
  1. If your XML contains an element named A, and
  2. A contains multiple elements named B, then
  3. No element named B may be repeated more than once in any other element in the entire XML stream other than within additional A's which are the sibling of the first A.
For a simpler example, this XML works:
<?xml version="1.0" encoding="utf-8"?>
Value
Value
Value
Value

And this XML works:
<?xml version="1.0" encoding="utf-8"?>
Value
Value
Value

But this XML, which satisfies the rules you provided earlier, does not work:
<?xml version="1.0" encoding="utf-8"?>
Value
Value
Value
Value


Another couple of most-likely-related bugs in XML processing.


First: "Cannot add a nested relation or an element column to a table containing a SimpleContent column."

Second: "The table (item) cannot be the child table to itself in nested relations."

Examples:

This XML works:
<?xml version="1.0" encoding="UTF-8"?>
content

And, this XML works:
<?xml version="1.0" encoding="UTF-8"?>
content
content2

This XML (and variations on it) does not work:
<?xml version="1.0" encoding="UTF-8"?>
content
content2







Based on my understanding thus far and from piecing together various bits and pieces of other forum messages, the underlying problem here seems to be that:
  • On the back end, the XML is being translated into some other data structure (which based on the error messages seems to be table based),
  • This translation step is broken, most likely because it does not properly respect the "scope" of the elements, in other words, their parent elements.
Specifically, the bug may be that the xml->table translation function looks for repeated elements inside of an element, for example the two elements in this XML (which works):
<?xml version="1.0" encoding="UTF-8"?>
1
2

When the xml->table translator finds repeated sibling elements it makes a "table" of some sort which is linked to the name of the element (in this case, 'b'). Non-repeated elements do not get this table treatment, which means that this XML also works, because the element inside of the element is not repeated:
<?xml version="1.0" encoding="UTF-8"?>
1
2
3

However, this XML does not work because of the xml->tables translation bug:

<?xml version="1.0" encoding="UTF-8"?>
1
2
3
4

It causes the error message: The same table 'item' cannot be the child table in two nested relations. Why? It would be perfectly natural to loop over these in a template like so:

Items in bin A:{{#foreach a}}{{item}} {{/foreach a}}
Items in bin B:{{#foreach b}}{{item}} {{/foreach b}}

It happens because the translator bit fails to take into account that and are completely different scopes. The 's inside of have nothing to do with the 's inside of . Because of this bug, all sorts of structures which are perfectly natural to express in XML and/or JSON break the API.

Hi,

Your understanding is correct and the XML issues you mentioned are related. The solution I shared to use different names was just a workaround. Original XML issues you mentioned are logged into our issue tracking system as SAASWORDS-172 and SAASWORDS-173.

Our codebase accepts these XML formats and templates so there is no such issue with the codebase and the issues with live service will be resolved soon. We will keep you updated on these issues in this thread.

Best Regards,

Great, thanks!!


We’re building an application around this feature right now so I’d be very pleased to provide any information I can to help, including:
  • Sample Documents and
  • Sample XML (that we think should work with the documents).
-e

Hi,

Thanks for your cooperation. The information you already shared looks sufficient to resolve this issue however we will let you know if anything else from your side is required.

Best Regards,

Hello-


Any update on this bug(s)?

thanks,
Erik

Hi Erik,

ETA request has been forwarded to our development team and we will share the ETA as soon as the issue is analyzed. Sorry for the inconvenience.

Best Regards,

Hi Erik,

Development team members working on this issue are on vacation and this issue has been planned for second week of December. We will update you as soon as it is resolved.

Sorry for the inconvenience.

Best Regards,

The issues you have found earlier (filed as SAASWORDS-173;SAASWORDS-172) have been fixed in this update.


This message was posted using Notification2Forum from Downloads module by Aspose Notifier.