Context

After creating a Beevirtua, it is possible to enable "article mode". Articles can be created for a given document from the Beevirtua studio, or by using the AddDocumentArticle POST route. This route allows to upload a zip archive and create one or several articles at once for a given document. Articles should be provided in xml format.

The following section details how to use the public routes to upload an article. The second section provides specifications for the uploaded article file.

API usage

The process requires:

The media id of the Beevirtua.
The document id identifying the exact document.
- A Beevirtua can contain several documents (for example, for different languages).
- A GET request on the route /v1/medias/{mediaId}/documents (see the documentation) lists all of a media's documents.
An archive conform to the specification
A bearer token obtained using a valid username and password on the route /v1/auth/login (see the documentation)

Posting the archive

Two routes are available to add articles:

To add articles with an archive, use AddDocumentArticle POST route.
To remove all articles before add new articles with an archive, use overwritteDocumentArticle POST route.

Send the archive using the chosen route. The route has three parameters: mediaId and documentId must be filled in the route URL, and the archive must be submitted in the body with the key file. Use a bearer token in the header. This route will send back a response body with the following structure:

{
  "requestId": "d06ab83f-01f1-4ba5-8812-c729d7fbe545",
  "mediaId": "df3fcb2d-914d-4181-864b-49257d80d946",
  "documentId": "e2e23ec4-9a22-4670-9431-043d48aee75b",
  "$diagnoses": [
    {
      "$severity": "info",
      "$message": "Article file uploaded!",
      "$detail": "Article auto has been applied on beevirtua df3fcb2d-914d-4181-864b-49257d80d946"
    }
  ]
}

Checking the status

For convenience, the "location" field in the previous response header returns the exact status route to be used to check the status of the upload. Its parameters are the media Id and the returned request ID, and it has the form /v1/medias/{mediaId}/status/{requestId}. Use a bearer token in the header. When the archive is uploaded, the route send the response { "status": "completed" }.

Publishing the articles

The articles are now uploaded, but not published. To publish the articles and make them available, use the PUT publish route /v1/medias/{mediaId}/publish. Use a bearer token in the header.

The body of the response has the following structure:

{
  "requestId": "26d23d19-9119-407d-81fc-464f2e704102"
}

Again, the response header specify the exact location of the status route:

 location: /api/v1/medias/df3fcb2d-914d-4181-864b-49257d80d946/status/26d23d19-9119-407d-81fc-464f2e704102

When the status route answers { "status": "completed" }, the Beevirtua is published with the new articles.

Removing articles

To remove all the articles for a document, use the deleteAllDocumentArticles DELETE route. The route has two parameters: mediaId and documentId must be filled in the route URL. Use a bearer token in the header.

To remove a specific article for a document, use the deleteDocumentArticle DELETE route. The route has three parameters: mediaId, documentId and articleId must be filled in the route URL. Use a bearer token in the header.

Input Specification

The expected input is a .zip file with the below structure:

zip archive structure

Where:

The archive folder at the root of the zip archive is mandatory.
The index.xml file contains the document structure.
The articles folder contains all xml files describing the document's articles. Each file name is a unique identifier (user chosen) used as a reference in index.xml.
The images folder contains images for articles. Their file names are also unique identifiers (user chosen), referenced in the article xml files.

File index.xml

Each article is referenced in index.xml using article elements. Their id attribute is the name of the corresponding xml file (without the extension). Each article element contains:

A title element. Its contents is the title of the article.
A page element. Its contents is a comma separated list of pages as integers starting at 1. Example : 7, 8, 9, 10

The below example illustrates this structure:

<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
  <article id="20180503110439702">
      <title>Article 1 title</title>
      <page>1,3</page>
  </article>
  <article id="201805030987739702">
      <title>Article 2 title</title>
      <page>3</page>
  </article>
  <article id="20180516103304592">
      <title>Article 3 title</title>
      <page>6</page>
  </article>
  <article id="2018051345354345304592">
      <title>Article 4 title</title>
      <page>7,8</page>
  </article>
  <article id="20180346624592">
      <title>Article 5 title</title>
      <page>9</page>
  </article>
  <article id="2018039867423592">
      <title>Article 6 title</title>
      <page>10</page>
  </article>
</document>

File article.xml

Each article file contains a wrapping document element. Its id attribute is the name of the document id. Its children are page elements. Their attribute n contain the corresponding page number. page elements can have the following children:

Title elements from <h1> to <h6>.
Paragraph elements <p>.
Image elements <image>, with three children:
- <source> contains the name of the image (extension included) in the images/ directory,
- <descr> contains the image's alt text (displayed in text mode),
- <caption> contains a caption for the image.
Links elements <link>, with two children:
- <dest> contains an external URL,
- <text> contains the hyperlink text
List elements, <list> for bullet points and <numlist> for enumerations. Lists contain <item> elements.
Paragraph text, image captions and list items can contain the following formatting:
- bold (<bold>), italic (<italic>) and underline (<underline>) elements,
- Mathematical formulae typeset in the Mathml markup language. They should be contained in <math> elements, with the obligatory attribute xmlns=http://www.w3.org/1998/Math/MathML. They should follow the syntax described at https://www.w3.org/TR/MathML3/.

Note: Tables are not allowed. We recommend providing any table as images.

The below example shows the syntax for articles:

<?xml version="1.0" encoding="UTF-8"?>
<document id="someid">
   <page n="1">
      <h1>Level 1 title</h1>
      <p>Paragraph</p>
      <image>
         <source>someimage.jpg</source>
         <caption>
            <bold>Figure 1:</bold>
            This is an image
         </caption>
         <descr>alternative description for the image</descr>
      </image>
      <p>
         Paragraph text
         <link>
            <dest>http://some.link</dest>
            <text>click here to go somewhere</text>
         </link>
        This paragraph contains maths:
         <math xmlns="http://www.w3.org/1998/Math/MathML">
            <mfenced>
               <mrow>
                  <mi>x</mi>
                  <mo>+</mo>
                  <mn>2</mn>
               </mrow>
            </mfenced>
            <mfenced>
               <mrow>
                  <mi>x</mi>
                  <mo>-</mo>
                  <mn>5</mn>
               </mrow>
            </mfenced>
            <mo>=</mo>
            <msup>
               <mi>x</mi>
               <mn>2</mn>
            </msup>
            <mo>-</mo>
            <mn>2</mn>
            <mi>x</mi>
            <mo>-</mo>
            <mn>15</mn>
         </math>
      </p>
      <list>
         <item>Lists are outside of paragraphs</item>
         <item>They can have any number of items</item>
         <item>This list will have bullet points</item>
         <item>
            <bold>Text formatting is allowed in lists</bold>
         </item>
      </list>
      <p>Other paragraph</p>
   </page>
   <page n="2">
      <h2>Level 2 title</h2>
      <numlist>
         <item>This item is in a numbered list</item>
         <item>it is also outside of a paragraph</item>
         <item>
            <underline>and can have formatting</underline>
         </item>
      </numlist>
      <p>A last paragraph</p>
   </page>
   <page n="3">
      <image>
         <source>https://some.other.image</source>
         <descr>alt text</descr>
      </image>
          <h3>Third level title</h3>
      <p>
         More text, 
         <underline>some of it underlined</underline>,
         <bold>and some bold</bold>
         .
      </p>
   </page>
</document>

XSD Schema validation

Articles and index should follow the provided syntax strictly. Their syntax will be validated using the following XSD schemas. If validation fails, the articles will not be created.

XSD schema for the index:

<xs:schema elementFormDefault="qualified" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="document">
        <xs:annotation>
            <xs:documentation>
                Wrapper containing the index. 
                Can contain any number of articles.
            </xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:sequence>
                <xs:element name="article" minOccurs="0" maxOccurs="unbounded">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element name="title" type="xs:string"/>
                            <xs:element name="page" type="xs:string"/>
                        </xs:sequence>
                        <xs:attribute name="id" type="xs:string" use="required"/>
                    </xs:complexType>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>

XSD schema for articles:

<xs:schema elementFormDefault="qualified" 
           xmlns:xs="http://www.w3.org/2001/XMLSchema" 
           xmlns:mml="http://www.w3.org/1998/Math/MathML">

    <xs:import schemaLocation="mathml2/mathml2.xsd" 
        namespace="http://www.w3.org/1998/Math/MathML" />

    <xs:element name="document">
        <xs:annotation>
            <xs:documentation>
                Wrapper containing the entire article.
            </xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:choice>
                <xs:element ref="page" maxOccurs="unbounded" minOccurs="1"/>
            </xs:choice>
            <xs:attribute type="xs:string" name="id"/>
        </xs:complexType>
    </xs:element>

    <xs:element name="page">
        <xs:annotation>
            <xs:documentation>Each pdf page</xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:choice maxOccurs="unbounded" minOccurs="0">
                <xs:element ref="p" />
                <xs:element name="h1" type="xs:string"/>
                <xs:element name="h2" type="xs:string"/>
                <xs:element name="h3" type="xs:string"/>
                <xs:element name="h4" type="xs:string"/>
                <xs:element name="h5" type="xs:string"/>
                <xs:element name="h6" type="xs:string"/>
                <xs:element ref="image"/>
                <xs:element ref="list"/>
                <xs:element ref="numlist"/>
            </xs:choice>
            <xs:attribute type="xs:string" name="n"/>
        </xs:complexType>
    </xs:element>

    <xs:element name="image">
        <xs:complexType>
            <xs:all>
                <xs:element name="source" type="xs:string"/>
                <xs:element name="caption" type="markupText" minOccurs="0"/>
                <xs:element name="descr" type="xs:string"/>
            </xs:all>
        </xs:complexType>
    </xs:element>

    <xs:element name="link">
        <xs:complexType>
            <xs:all>
                <xs:element name="dest" type="xs:string"/>
                <xs:element name="text" type="xs:string"/>
            </xs:all>
        </xs:complexType>
    </xs:element>

    <xs:element name="list" type="enum"/>
    <xs:element name="numlist" type="enum"/>
    <xs:element name="p" type="markupText"/>
    <xs:element name="item" type="markupText"/>


    <xs:complexType name="enum"  mixed="true">
        <xs:choice maxOccurs="unbounded" minOccurs="1">
            <xs:element ref="item" />
        </xs:choice>
    </xs:complexType> 

    <xs:complexType name="markupText"  mixed="true">
        <xs:choice maxOccurs="unbounded" minOccurs="0">
            <xs:element name="bold" type="markupText"/>
            <xs:element name="underline" type="markupText"/>
            <xs:element name="italic" type="markupText"/>
            <xs:element ref="link"/>
            <xs:element ref="mml:math"/>
        </xs:choice>
    </xs:complexType> 

</xs:schema>