Additional information for xml imports

xIn this article you will find additional information about the XML. We will tell what all fields/tags are called and what their purpose is.

  • Fields mapping
  • Entering costs in XML

    • Field mappings:

    Below you will find an overview of all the fields in the product.xsd with more elaborate explanation and examples. These fields are written down here to make it easier to read and understand. In Automatic updating your products via XML our product.xsd can be found. All technical explanation, structure wise but also all possible data types/values are listed.

    Our xml example gives an overview how this data should be shaped.

    Field name/elements Description     Requirements
    * Products / Product <Products> is the root element of this XML. Below elements are the structure for each product. And each new product starts with the <Product> element
    ID Use the ID element om provide an unique value to the product. We use this ID to update/create/delete the products since the importer works CRUD. 
    This means that when the ID does not exist in the Springest Database, a new product is created. When an ID is in our database but not in the XML all data for that product will be deleted.
    If the ID is in the xml and in our database we update all training information.

    When you change ID's please always contact datasupport. Since we want to save the conversions, google ranking and reviews attached to this unique identifier.
    • Mandatory field
    • Unique per product
    Name Use the name element to give the product a title. This has to be unique. 
    When you offer a training in different languages please create another product and mention the language in the title.
    • Mandatory
    • Unique per product
    Description Us the description element to provide as much information about the training as possible. Use a CDATA to give it HTML markup. Punctiationmarks that are allowed within CDATA: ' " < > &.

    These HTML tags are allowed:  p, b, strong, h2, em, i, ul, ol, li, br. Other HTML tags will be ignored. 

    Read more about CDATA in XML.
    • Mandatory
    • Minimum of 150 words.
    *Images Images is a root element for pictures. It can have one or more ImageUrl elements.
    • Optional
    Images/ImageUrl Url of the image
    • Optional
    • URL
    • .png, .gif, any other image format
    VideoEmbed Provide youtube or vimeo url of your trainingvideo.
    • Optional
    • URL 
    • mp4, Youtube
    Language The language code for this training. So in what language is the course-material and what language is spoken for classical trainings.
    Only one language per training.
    • Mandatory
    • Alpha 2 code of ISO ISO_639-1.
    Price Use the Price elements to provide us the price without Vat.
    • Always without VAT. VAT has to be provided seperately. See below.
    • Free products? use 0.
    • If not free, this tag should also contain the 'tuition fee' costs. Additional costs can be enter under <AdditionalCosts> or can be added on the Price tag.
    • Exception: For in-company/custom products where the price is negotiable you can leave it empty. 
    • In the bottom of this page more information about costs.
    • Mandatory
    • Decimal
    VatIncluded    Use VatIncluded to say if the product is exempted of VAT or it should include VAT. 
    Possible options:
    • 'exempt', Price of product is exempted of VAT. If you are allowed to do this, please inform datasupport@springest.com so we can set this up.
    • 'no', Price of product is not exempted of VAT. In that case we always expect the presence of VatAmount and a valid amount of VAT.
    • Mandatory
    • Values: 'exempt' or 'no'
    VatAmount Use the VatAmount element to provide the number of Vat. If you have VAT exempted products, you can leave it empty for these products. 
    • Mandatory
    • Decimal
    PriceExemptAmount   Use the PriceExemptAmount element to provide an alternative price, excluded of VAT.
    This gives you the option to provide a price exempted as well als price with VAT.
     The VAT exempted price will be shown to users (usually employees of our GO's/business platforms) that are allowed to buy exempt free.

    • Optional
    • Decimal
    PricePeriod Use PricePeriod to inform about the duration of the price. 
     Possible values.  
    • 'monthly', price per month
    • 'yearly', price per year
    • 'all', for the total duration of the training.
    • Mandatory
    • Values: 'monthly' 'yearly', 'all'
    PriceAgreement Only for Incompany/custom made products. For all other products we ignore this value. 
    PriceAgreement gives the option to negotiate about pricing. When yes, we wont show any prices on Springest
    Values:
    • true
    • false
    • Optional
    • Boolean
    * AdditionalCosts Use <AdditionalCosts> as a root element to specify costs. Per costs the VAT amount can differ. Also it provides the option to make a costs optional or mandatory.


    • Optional
    AdditionalCost Use the AdditionalCost element to provide costs
    • Optional
    AdditionalCost/Type   Type of cost.  
    • Optional
    • Values: 
      • "examination"
      • "excursions"
      • "lunch"
      • "dinner"
      • "registration fee"
      • "study material
      • "visa/permit"
      • "coaching"
      • "accommodation"
      • "arrangement"
      • "second accomodation"
    AdditionalCost/Price Price of the additional cost.
    • Optional
    • Decimal
    AdditionalCost/VatIncluded Use VatIncluded to say if the product is exempted of VAT or it should include VAT.  
    Possible options: 
      'exempt', Price of product is exempted of VAT. If you are allowed to do this, please inform datasupport@springest.com so we can set this up.
      'no', Price of product is not exempted of VAT. In that case we always expect the presence of VatAmount and a valid amount of VAT.
    • Mandatory
    • Values: 'exempt' or 'no'
    AdditionalCost/VatAmount
    Use the VatAmount element to provide the number of Vat. If you have VAT exempted products, you can leave it empty for these products.


    • Mandatory
    • Decimal
    AdditionalCost/PriceExemptAmount 





    Use the PriceExemptAmount element to provide an alternative price, excluded of VAT.

    • Optional
    • Decimal
    AdditionalCost/VATExemptAmount Use the VATExemptAmount element to provide the VAT amount exempted of VAT. In some cases low VAT amounts still have to be added to the total vatexempted price. 
     
    • Optional
    • Decimal
    AdditionalCost/Mandatory Provides thethe option to make a costs optional or mandatory.

    • Optional
    • boolean 
      • true
      • false
    PriceComplete The PriceComplete element tells us if all costs are mentioned. No hidden costs. We always expect that all prices are mentioned, wether optional or mandatory.  Not pricecomplete costs can be deleted.
    • Mandatory
    • boolean
      • true
      • false
    PriceInfo Extra information about prices. 
    • Optional
    CourseType What type of course is it. In most cases 'course' will.
    • Mandatory
    • Possible values:
      • 'course', 'cursus'
      • 'educational program',
      • 'opleiding'
      • 'seminar',
      • 'training'
      • 'workshop'
      • 'video'
      • 'evenement'
      • 'book'
    Duration Use the Duration element to declare the total duration of the training. 
    • Mandatory
    • Double
    DurationUnit The Unit used for duration.
    • Mandatory
    • Possible values:
      • 'minutes'
      • 'hours'
      • 'days'
      • 'weeks'
      • 'months'
      • 'years'
    DurationAgreement Only applicable for In-company/custom made products.  It provided information wether the duration of the course can be decided in consultation.


    • Optional
    • Boolean.
    Runtime Use the Runtime element to provide extra information on the lead time of the training. 
    Example: " The training takes place on 4 scheduled evenings spread over 2 months time"
    • Optioneel
    • Free text field
    Completion  Provide information about the completion of the product.
    Example: "Diploma", "Certificat"
    • Optional
    • Free text field
    MaxParticipants Use MaxParticipants to inform about the maximum number of participant for this training. A training can never take place with more participants than this number. Value 0 will be ignored.
    • Mandatory for open bookings only
    MaxNumberOfSeats Use MaxNumberOfSeats to tell us how many seats are (maximum) available for that specific startdate. 

    Example: you have entered the value 3 here. When 3 people have signed up for this course within Springest for this specific startdate, we will close this startdate, preventing it from getting any additional bookings.
    The value 0 is acceptable. We will close the startdate but still show it. Another more simpler option: when there are no spots left just remove the StartingDatePlace completely from the xml. We will remove it too.
    • Optional
    • Per startdate
    MinNumberOfSeats MinNumberOfSeats is relevant when you, by default, put StartGuarenteed to true. We won't show startguarenteed is true untill the condition by MinNumberOfSeats has been met.

    For example when you enter value 2, we need 2 Springest bookings before we show Startguarenteed is true. 
    • Optional
    • Per startdate
    • Integer
    AvailableSeats With AvailableSeats u can state the amount of places that are still bookable for that startmoment. When this tag has a value of 0 we close the startdate. It is still visible but not anymore bookable.    
    • Optioneel: 
    • Per startdatum
    WebAddress With the WebAddress element you can link the product to your own site, where the product is also displayed. We wont show any of the urls to end-users.
    • Mandatory
    • AnyURI
    PdfBrochure To provide a PdfBrochure.
    • Optional
    • pdf URL
    ProductType  What kind of product is this training.
    • 'open', Open booking
    • 'home', Home studies
    • 'in-company', incompany/custom made
    • elearning
    • 'book'
    • 'evenement' (rarely used)
    • 'learning-bite'  (rarely used)
    • 'group', specific booking used for group booking at existing customers. For this producttype a domain has to be chosen for the field AllowedSites
    • Mandatory
    • Possible values:
      • 'open'
      • 'home'
      • 'in-company'
      • elearning
      • 'book'
      • 'evenement'
      • 'learning-bite' 
      • exam
    * Regions Use <Regions> as a root element to specify Regions.
    Region
    Region/name     		Use the Region element to provide one or more Regions.
    Region is only relevant if you don't provide start dates. When start dates are present we deduct from <place> wat the correct region is for that startdate event. 

    • Optional
    Level Use Level element for the level of education. 
    • Optional
    * PriceDiscounts/
     Discount     		Only for products that are linked to our Go/business platforms. Contact datasupport@springest.com if you want to use this. 

    Go Use the go element to declare on which Go/business platforms discount should happen.

    • Optional

    Possible values

    • ing
    • vivat
    • ns
    • Over 200 options (contact support)
    *StartingDatePlaces/StartingdatePlace Use <StartingDatePlaces> as a root element to specify unlimited amount of <StartingDatePlace> elements.
    • Look at product_example.xml for the required structure
    • When an event should not be bookable anymore(for example the maximum amount of people have booked), we advise you to remove that complete StartingDatePlace from the xml. We will remove the option to book on that day.
    StartingDatePlace/ID Use the ID element om provide an unique value to the product. When you re-use this ID we update the old startdates with the new information.
    • Free text field
    StartingDatePlace/Startdate Startdate of that event.
    • yyyy-mm-dd
    StartingDatePlace/Enddate Enddate of that event.

    • yyyy-mm-dd
    StartingDatePlace/Place



    StartingDatePlace/Online     		Use Place element to provide the location/city of this event. 
    We use this element to decide in what region the event takes place and place them in the correct filters.

    If distance learning is possible for this startdate.
    • Free text field
    • Boolean
    StartingDatePlace/StartdateIsMonthOnly
    		When it is not clear what exact day a startdate will happen but the month is clear, you can provide this information.
    • boolean
    StartingDatePlace/EnddateIsMonthOnly
    		When it is not clear what exact day a enddate will happen but the month is clear, you can provide this information.
    • boolean
    StartingDatePlace/StartGuaranteed
    		Use StartGuaranteed element to inform users that no matter what but the provided startdate event will start.
    Use MaxNumberOfSeats if you want to restrict the possible maximum of bookings for that startdate.
    • boolean
    * Schedule / Courseday You can provide a schedule per startdate with courseday moments. This way the user knows exactly if all moments fit his 
    Courseday/ID Use the ID element to provide an unique value to the courseday.
    • Free text field
    Courseday/Date Use Date to tell on which date a courseday takes place.
    • yyyy-mm-dd
    Courseday/Place Location/city.
    • Free text field
    Courseday/Name Name that day.
    For example: Courseday 1 , introduction 1.
    • Free text field
    Courseday/Starttime Starttime element of the courseday
    • hh:mm
    Courseday/Endtime



    Additionele opties:
    		 Endtime element of the courseday
    • hh:mm
    *Moments  Only relevant if you don't provide Courseday/schedule data 
    Purpose Only for vitality products
    Purpose of the product.
    • Optional
    * CostPlacements Only for vitality products.
    Costcenter. This can differ per site depending on the contract.

    • Optional
    *AllowedSites Only used for group booking at existing customers. For this producttype a domain has to be chosen for the field AllowedSites.



    • Optional

    Cost types, taxes and calculations in the XML:

    It is possible to state the costs per cost type. This can be useful for example when you have different vat percentages per cost type. 
    If this is the case you can fill in the cost for the 'tuition fee' in <price> and for stating different cost types and matching VAT percentages you can use the node  <AdditionalCosts> stating each cost type and all values per <AdditionalCost>.

    Our example: 
    Let assume you have these values in the xml:

    <Price>100</Price> 

    <AdditionalCost>

    <Type>registration fee </Type> * see our xsd for possible values. Note that tuition fee is not included because we expect it to be(included) in the <price> tag, it is 100 in our example.
    <Price> 20</Price> 
    <VatIncluded> no</VatIncluded>
    <VatAmount> 5</VatAmount>
    <Mandatory>no</Mandatory>

    </AdditionalCost>

    <AdditionalCost>

    <Type> lunch </Type>
    <Price> 40</Price> 
    <VatIncluded> no</VatIncluded>
    <VatAmount> 3</VatAmount>
    <Mandatory> no</Mandatory>

    </AdditionalCost>

    Calculating course price.

    Below a tabel with different price options:

      Price VatIncluded VatAmount
    		Price on Springest
    Option1 100 no 21 121
    Option2 100 exempt - 100

    Adding different cost types from Additional Costs:

    The calculation follows the same method as for <price>. 

     Type Price VatIncluded VatAmount Mandatory Additional costs
    Registration fee 20 no 5 yes + 25
    Lunch 40 exempt - yes + 40
    TOTAL + 75
    ------------------------------------------------------------------------------------------------------------------
    Calculation of the TOTAL price:

    We will sum all mandatory costs and add to the total of the course price.

      Price VatIncluded VatAmount Additional costs Total price on Springest
    Option2 100 no 21 75 196
    Option3 100 exempt - 75 175

    Additional information:

    • Courses free of charge should have <price>0</price>
    • For <producttype> in-company</producttype> there should not be a price. To make sure we don't show a price you can use the <PriceAgreement> true</PriceAgreement in the XML. We won't show any prices in that case.
    • The <VATamount> for for In-company trainings is not relevant. Please leave empty.
    • Optional costs are not shown until the actual booking is happening. On this booking screen we will give users the option to book any optional costs.
  • Have any questions or feedback for us? Please reach out to support@springest.nl and we will get back to you as soon as possible.