Created by potrace 1.16, written by Peter Selinger 2001-2019

Miva Developer Docs

Feed Builder feeds and Data Builder fields can be set up entirely from a provisioning file imported under Data Management > Import > XML Provisioning. The ready-made channel files are complete examples.

A feed’s or field’s settings live on an admin page created with it, so each takes two tags: Feed_Add (Feed Builder) or Field_Add (Data Builder) creates it and its page, and Page_Update fills in the settings on that page.

Install MivaLabs Feed Builder under Settings > Utilities before importing. An import doesn’t install it, and its tags fail until it’s installed.

Page_Update replaces every setting

Page_Update doesn’t merge with what’s there. A tag you leave out goes back to its default, and a missing <FieldMap> empties the field list. Always send the whole block.

Feed Builder#

Feed_Add#

<Feed_Add>
    <Code>my_feed</Code>
    <Name>My Feed</Name>
    <Module>mivalabsfeedbuilder</Module>
    <Settings>
        <Trigger>my_feed_trig</Trigger>
    </Settings>
    <File>
        <Enabled>Yes</Enabled>
        <Location>script</Location>
        <Name>/my-feed.csv</Name>
    </File>
</Feed_Add>

<Settings> must be present, even empty (<Settings />). Miva only calls the module when it is, and that call creates the builder page. <Trigger> is optional. <File> is Miva’s own feed delivery setting.

Page_Update#

The page code is FEEDBUILDER_ followed by the feed code. A code longer than 50 characters is cut to 50.

<Page_Update code="FEEDBUILDER_my_feed">
    <Item code="feedbuilder_page_builder">
        <SourceType>product</SourceType>
        <Format>csv</Format>
        <Delimiter>tab</Delimiter>
        <LineEnding>lf</LineEnding>
        <Load type="in_category">SHIRTS,PANTS</Load>
        <ExpandVariants>Yes</ExpandVariants>
        <Filter mode="all">
            <Rule field="price" operator="greater_than" value="0" />
        </Filter>
        <FieldMap>
            <Field source="code" output="id" />
            <Field source="descrip" output="description" transform="strip_html" />
            <Field source="__main_image__" image_type="main" output="image_link" />
            <Field source="__additional_images__" image_types="add1,add2,__untyped__" output="additional_image_link" />
            <Field source="__constant__" output="condition" constant="new" />
            <Field source="sale_price" output="sale_price">
                <Condition field="sale_price" operator="is_empty" output="" />
            </Field>
        </FieldMap>
        <HeaderText><![CDATA[id{{tab}}description{{tab}}image_link{{newline}}]]></HeaderText>
    </Item>
</Page_Update>
Tag Values Default when left out
<SourceType> product, category product
<Format> csv, json, xml csv
<Delimiter> comma, tab, pipe comma
<LineEnding> lf, crlf, cr lf
<Load type="..."> See below. The text is comma-separated category codes or group names. active
<ExpandVariants> Yes, No No
<Filter mode="..."> all, any, with <Rule> children No conditions
<FieldMap> <Field> children No fields
<HeaderText> Text, usually in CDATA Blank
<FooterText> Text, usually in CDATA Blank

To leave Header or Footer text blank, leave the tag out rather than sending it empty.

<Load> types: active, all, available, in_category, not_in_category, in_price_group, not_in_price_group, in_availability_group, not_in_availability_group. A category or group that doesn’t exist is logged as “Load: …” in the import log and matches nothing.

Data Builder#

Field_Add, Field_Update, Field_Delete#

Data Builder fields are added the same way as on the MivaLabs Data Builder tab:

<Module code="mivalabsfeedbuilder" feature="util">
    <Field_Add>
        <Code>my_feed_data</Code>
        <Name>My Feed Data</Name>
        <SourceType>Product</SourceType>
        <Trigger>my_feed_data_trig</Trigger>
    </Field_Add>
</Module>
Tag Required Meaning
<Code> Yes Letters, numbers, underscores and dashes, up to 36 characters. Adding a code that exists fails.
<Name> No The code when left out
<SourceType> No Product or Category. Product when left out. Can’t be changed later.
<Trigger> No The trigger name its Queued Records task uses

Change a field’s name or trigger, or delete it:

<Module code="mivalabsfeedbuilder" feature="util">
    <Field_Update code="my_feed_data">
        <Name>New Name</Name>
        <Trigger>new_trig</Trigger>
    </Field_Update>
    <Field_Delete code="old_field" />
</Module>

Deleting a field removes its page and stored values, not its scheduled tasks.

Page_Update#

The page code is FEEDDATAFIELD_ followed by the field code.

<Page_Update code="FEEDDATAFIELD_my_feed_data">
    <Item code="feeddatafield_settings">
        <Format>csv</Format>
        <Delimiter>comma</Delimiter>
        <ExpandVariants>Yes</ExpandVariants>
        <FieldMap>
            <Field source="code" output="id" />
            <Field level="master" source="descrip" output="description" transform="strip_html" />
            <Field source="price" output="price" />
        </FieldMap>
    </Item>
</Page_Update>
Tag Values Default when left out
<Format> csv, json, xml csv
<Delimiter> comma, tab, pipe comma
<ExpandVariants> Yes, No No
<FieldMap> <Field> children No fields
<HeaderText>, <FooterText> Accepted and saved, but not used Blank

The import updates the page. The field’s tasks pick up the new mapping on their next run. Run the All Products task to recompute stored values with it.

Scheduled tasks#

<ScheduledTask_Add>
    <Description><![CDATA[Update My Feed Data (Queued Products)]]></Description>
    <Enabled>Yes</Enabled>
    <Trigger>my_feed_data_trig</Trigger>
    <Module>mivalabsfeedbuilder</Module>
    <Operation>databuilder_recompute</Operation>
    <RunInterval units="manual" />
    <Settings>
        <FieldCode>my_feed_data</FieldCode>
        <Generation>queued</Generation>
    </Settings>
</ScheduledTask_Add>

<ScheduledTask_Add>
    <Description><![CDATA[Rebuild My Feed Data (All Products)]]></Description>
    <Enabled>No</Enabled>
    <Module>mivalabsfeedbuilder</Module>
    <Operation>databuilder_recompute</Operation>
    <RunInterval units="manual" />
    <Settings>
        <FieldCode>my_feed_data</FieldCode>
        <Generation>all</Generation>
    </Settings>
</ScheduledTask_Add>

<FieldCode> must name a field that already exists, so put the tasks after the field’s Field_Add. <Generation> is queued or all; anything else becomes queued.

The Field tag#

Feed Builder and Data Builder read <Field> the same way.

Attribute Required Meaning
source Yes A field source code, __constant__, __main_image__ or __additional_images__
output Yes The output name
transform No A transform code. Default none.
constant With __constant__ The constant text
image_type With __main_image__ An image type code
image_types With __additional_images__ Comma-separated image type codes, up to 10. __untyped__ means images with no type.
list No true to treat the value as a comma-separated list
max No With list, the most values to write
level No Data Builder only. master reads a variant’s master product value.

Child tags for conditional output:

<Field source="in_stock" output="availability">
    <Condition field="in_stock" operator="equals" value="in stock" output="in_stock" />
    <Condition field="inventory_count" operator="less_than" value="3" output="limited_availability" />
    <ConditionsDefault>out_of_stock</ConditionsDefault>
</Field>

<Condition> needs field and operator. value and output are optional; an empty output leaves the field out of the row. <ConditionsDefault> is the Otherwise output.

<Rule> (in Feed Builder’s <Filter>) takes field, operator and value.

Operator and transform codes aren’t checked on import. A misspelled operator never matches.