10/19/2016 - 12:35 AM

Miva - Dynamic Order Export

miva-dynamic-order-export.md

Rendered
Source

Dynamic Order Export

Outline

Outline
About
Installation
Configuration
Modification Keys
Page Items
- Using DOE Page Items
- Entity Specifics
Exporting Template Based Batch Reports
Request Parameters
Other Dynamic Order Export Capabilities
Sample Integrations
- POST Customer Data to 3rd-Party
- Create an API Endpoint for Order Data

About

Latest Module Version: 2.0002 (as of 10/17/2016)

Dynamic Order Export is a module that keeps track of new and modified: orders, customers, categories, & products.

The knowledge of modified items is then able to be exported through order Template Based Batch Reports or used on other Miva page templates.

Throughout this document we'll refer to "Dynamic Order Export" as "DOE", and "orders, customers, categories, & products" as "entities".

Installation

It is very likely, that the installation process will be handled for you by a Miva merchant developer, but here are the steps:

Reach out to your point of contact Miva to get a copy of the latest Dynamic Order Export module. You can also email design@miva.com to get this process going.
Got to Menu > Modules, and click the plus-sign (+) button
Click the Upload button
Browse your computer for the dynamicorderexport.mvc module file, upload it, and click the "+ Add" button.

Configuration

After the module has been installed, it's settings can be configured in the Miva Admin under: Menu > Utilities > Dynamic Order Export.

On that page it will: allow you to Add Modification Keys, list all of the store's existing Modification Keys, and allow you to perform the following actions: Mark Batch Report Orders, Mark Orders, Mark Products, Mark Categories, Mark Customers.

Modification Keys

A modification key is a key that will be used to track which orders, products, categories, and customers have been modified. Each key can be assigned to track either one, or up to all four of those items. The Modification Key Param is kind of like a name/code that is used to put product, categories, customers, and orders into different "buckets" so to speak.

For example, if you need to export orders to a CRM software, and you also need to export orders to a Shipment Fulfillment software, then you could create two Keys to keep track of which orders have been sent to each location. Other examples could be for integrations with 3rd-Party Analytics/Services like Power Reviews, Listrak, or SearchSpring.

When you add a Modification Key, you will be asked which entities you would like to track. Be sure to track all of them that apply to a given system/topic.

The "Manually Reset Modified Items" option is present if you would like to keep entities on the "Modified" queue indefinitely. Entities will only be marked "Unmodified" when they are manually set to be "Unmodified". This setting is helpful for initial development testing & debugging. It can also be helpful where you would like the 3rd-party system to respond & verify that changes with items have been received.

Modification Events

An entity (product, category, order, or customer) is considered modified when the entity has been created. The entity is also considered modified when it is edited in the Miva admin from an edit page or from a Batch List page.

Additionally, customers can also be considered modified through actions that happen on the StoreFront. See Entity Specifics > Customers > Modified Events for a breakdown.

Set Modified

There is a "Set Modified" field visible in the Miva Admin and in data exports/imports that can be used to mark an entity as modified/unmodified. You can set that field to "Yes", "1", or "True" to mark an entity as Modified. You can set an entity to Unmodified be setting the Set Modified field to either "No", "0", or "False".

Getting Started

Once a store has been configured with Modification Keys it will keep track of all of the entities (products, categories, customers, and orders) as they are created or edited. Initially, all entities are considered un-modified so there will not be a queue of entities to start testing with.

You can use the Menu > Utilities > Dynamic Order Export page to "Mark" entities as "Modified" or "Unmodified". Orders can have certain Order # ranges be marked as modified/unmodified, but products, categories, and customers will just mark all items.

For initial testing & debugging, it can be helpful to set a handful of entities as "Modified" and enable the Modification Key's "Manually Reset Modified Items" setting. This will allow you to easily keep refreshing or recalling a URL without having to keep modifying entities.

Page Items

The DOE module creates 5 new Page Items for a Store: doe_adminpage, doe_modifiedproducts, doe_modifiedcategories, doe_modifiedcustomers, doe_modifiedorders

The doe_adminpage allows you to add Miva Admin session validation to a regular User Interface > Page.

The doe_modifiedproducts, doe_modifiedcategories, doe_modifiedcustomers, and doe_modifiedorders items allow you to load in the list of Modified entities for their corresponding item. If you provide the Modification Key Code into the <mvt:item>'s param attribute, then it will load in all of the corresponding Modified items:

For Example:

<mvt:item name="doe_modifiedproducts" param="key_code">
    <mvt:foreach iterator="product" array="doe_modifiedproducts">
        &mvte:product:code;<br/>
    </mvt:foreach>
</mvt:item>

Using DOE Page Items

The following steps can be used to illustrate how a page can be created to output the core-data for modified products, categories, customers, and orders.

By the end of these steps you will be able to have a page that outputs all of the core-data in JSON format. This would be helpful for a 3rd-party system that would like to poll for updates that happen in the store. Outputting the data as JSON isn't the only thing that you can do with the data. You could perform <mvt:call>'s, update store custom fields, send emails, etc. The JSON just helps illustrate all of the data that is available to you.

Install the module if it has not been installed already.
Create a new Modification Key from the Miva Admin > Menu > Utilities > Dynamic Order Export page.
1. Click the "Add Modification Key" button
2. Set the Param to "sample_doe_output"
3. Check to track all of the entities (Track Products, Track Categories, Track Customers, Track Orders)
4. Check the "Manually Reset Modified Items" setting.
5. Click the "Add" button.
Create a new Page
1. Go to Menu > User Interface > Pages > Click the plus (+) button
2. Give the page a Code of "sample-doe-output", and a Name of "Sample DOE Output"
3. (optional) Check the "Link to This Page Using HTTPS" box
4. Leave the Template section empty
5. Click the "+ Add" button
Assign the DOE Page items to our new page
1. Click the Items tab
2. Assign the following items:
  1. doe_modifiedproducts
  2. doe_modifiedcategories
  3. doe_modifiedcustomers
  4. doe_modifiedorders
3. The doe_adminpage item is not necessary for this example so please do not assign it to the page unless you understand how it works.
Add the following template code the page:

<mvt:item name="doe_modifiedproducts" param="sample_doe_output">
    <mvt:foreach iterator="product" array="doe_modifiedproducts">
        &mvt:product:code; | &mvt:product:name;<br>
    </mvt:foreach>
</mvt:item>

Visit this page on the front-end of your store
1. It could be accessed at http://www.yourstore.com/mm5/merchant.mvc?Screen=sample-doe-output
2. Also, if you're using URI Management, then it should be available at one of the URI's listed for the "sample-doe-output" page.
If no entities have been modified since you created your key, then you should see an empty response.
We need to set some entities as modified in order for them to start showing up on our "sample-doe-output" page. So let's modify a product:
1. Go to the Edit Product page in Miva admin for any product.
2. Click the Update button (you don't even need to change any product data).
3. Visit the front-end sample-doe-output page (http://www.yourstore.com/mm5/merchant.mvc?Screen=sample-doe-output). You should now see some output. Something like "product-code-abc | Product Name ABC"
Let's modify several products from a batch list.
1. Go to Menu > Catalog > Products
2. Select about five products and click the Pencil/Edit button.
3. Change one of the fields for-each product that you have chosen to edit
  1. Note: Unlike the Edit Product page, clicking Save/Update will not mark all of the Selected/Edited products as modified. Only the Selected/Edited products that had their field values actually change will be updated
4. Click the Floppy-Disk/Save button
5. Visit the front-end sample-doe-output page, and now you should see several products listed in out output.
Let's demonstrate how the "Manually Reset Modified Items" setting works.
1. Go to the Menu > Utilities > Dynamic Order Export page.
2. Click on the "sample_doe_output" param link
3. Uncheck the "Manually Reset Modified Items" setting.
4. Click the Save button.
5. Visit the front-end sample-doe-output page. You should see the same several products listed in out output.
6. Refresh the front-end sample-doe-output page, and you should see an empty result. When "Manually Reset Modified Items" is not checked, as soon as an entity it rendered using the DOE item, it will not output until it has been Modified again.
Let's Mark Products as Modified
1. From the Menu > Utilities > Dynamic Order Export page.
2. Click the Mark Products button.
3. Set the Status to Modified
4. Select your sample_doe_output Param.
5. Click the Mark Button.
6. Visit the front-end sample-doe-output page. You should see a list of the product codes & names for all of the products in the store.
7. Refresh the front-end sample-doe-output page to ensure that there are no more "Modified" products displaying.
8. Go back to the Menu > Utilities > Dynamic Order Export page and check the "Manually Reset Modified Items" setting so we can keep testing
Let's Output all of the Product information that is available
1. Go to the Miva Admin > Menu > User Interface > Pages > sample-doe-output page.
2. Replace the Template code with the following:

<mvt:assign name="l.null" value="miva_output_header( 'Content-type', 'application/json' )" />
<mvt:item name="doe_modifiedproducts" param="sample_doe_output">
    <mvt:do file="g.Module_JSON" name="l.success" value="JSON_Output( l.settings:doe_modifiedproducts )" />
</mvt:item>

1. The previous code sample will load in all of the Modified sample_doe_output products. The DOE module makes that product information available on the `l.settings:doe_modifiedproducts` variable structure. Then we can use `<mvt:do>` to output all of the data to the page in the JSON format.
1. The `doe_modifiedproducts` item gives us more information than just product codes & names. A lot of other core product details are available (See the `doe_modifiedproducts` Data section below.)

Let's try outputting other modified entities
- Categories
  1. Update the sample-doe-output page to use the following template code:

<mvt:assign name="l.null" value="miva_output_header( 'Content-type', 'application/json' )" />

<mvt:item name="doe_modifiedproducts" param="sample_doe_output">
    <mvt:assign name="l.settings:data:products" value="l.settings:doe_modifiedproducts" />
</mvt:item>
<mvt:item name="doe_modifiedcategories" param="sample_doe_output">
    <mvt:assign name="l.settings:data:categories" value="l.settings:doe_modifiedcategories" />
</mvt:item>
<mvt:item name="doe_modifiedcustomers" param="sample_doe_output">
    <mvt:assign name="l.settings:data:customers" value="l.settings:doe_modifiedcustomers" />
</mvt:item>
<mvt:item name="doe_modifiedorders" param="sample_doe_output">
    <mvt:assign name="l.settings:data:orders" value="l.settings:doe_modifiedorders" />
</mvt:item>

<mvt:do file="g.Module_JSON" name="l.success" value="JSON_Output( l.settings:data )" />

1. Edit a couple different categories and customers to set them as Modified.
1. Orders can be marked by opening the Order's Order Processing detail page > Clicking the Dynamic Order Export Modification Keys link > and setting it to be Modified.
1. After marking several products, categories, customers, and orders as Modified and previewing the sample-doe-output page's JSON data you should have a great idea of all the data that is available by default with the DOE module.

Entity Specifics

Entity Specifics > Products

Entity Specifics > Products > Modified Events

The following events will mark a product as being Modified:

Adding a new product
Clicking the Update button while editing an individual product in the Miva admin.
Changing an input's value while editing a product from a Batch List page in the Miva admin.
Specifying "Yes", "1", or "True" in the product's "Set Modified" field on a Batch List
Specifying "Yes", "1", or "True" in the product's "Set Modified" field on a Product Import
Go to the Menu > Utilities > Dynamic Order Export page > Click on the Mark Products button > Set the Status to Modified > Choose your Param > Click the Mark button

The following events will not mark a product as being Modified:

Adding a product to a category.
A customer adding a product to their basket.
An order being placed with a product in it.
When a product is deleted.
Selecting a product to edit on a Batch List but not changing any of its values.

The following events will un-modify an already modified product:

Specifying "No", "0", or "False" in the product's "Set Modified" field on a Batch List
Specifying "No", "0", or "False" in the product's "Set Modified" field on a Product Import
Go to the Menu > Utilities > Dynamic Order Export page > Click on the Mark Products button > Set the Status to Unmodified > Choose your Param > Click the Mark button

Entity Specifics > Products > `doe_modifiedproducts` Data

active
agrpcount
cancat_id
catcount
code
cost
descrip
disp_order
id
image
inv_active
inv_available
inv_instock
inv_level
inv_long
inv_low_level
inv_low_track
inv_out_level
inv_out_track
inv_short
name
page_id
page_title
pgrpcount
price
sku
taxable
thumbnail
weight

Entity Specifics > Categories

Entity Specifics > Categories > Modified Events

The following events will mark a category as being Modified:

Adding a new category
Clicking the Update button while editing an individual category in the Miva admin.
Changing an input's value while editing a category from a Batch List page in the Miva admin.
Specifying "Yes", "1", or "True" in the category's "Set Modified" field on a Batch List
Specifying "Yes", "1", or "True" in the category's "Set Modified" field on a Product Import
Go to the Menu > Utilities > Dynamic Order Export page > Click on the Mark Categories button > Set the Status to Modified > Choose your Param > Click the Mark button

The following events will not mark a category as being Modified:

Adding a product to a category.
When a category is deleted.
Selecting a category to edit on a Batch List but not changing any of its values.

The following events will un-modify an already modified category:

Specifying "No", "0", or "False" in the category's "Set Modified" field on a Batch List
Specifying "No", "0", or "False" in the category's "Set Modified" field on a Product Import
Go to the Menu > Utilities > Dynamic Order Export page > Click on the Mark Categories button > Set the Status to Unmodified > Choose your Param > Click the Mark button

Entity Specifics > Categories > `doe_modifiedcategories` Data

active
agrpcount
code
disp_order
id
name
page_id
page_title
parent_id
validated_parent_id

Entity Specifics > Customers

Entity Specifics > Customers > Modified Events

The following events will mark a customer as being Modified:

Adding a new customer
Clicking the Update button while editing an individual customer in the Miva admin.
Changing an input's value while editing a customer from a Batch List page in the Miva admin.
Specifying "Yes", "1", or "True" in the customer's "Set Modified" field on a Batch List
Specifying "Yes", "1", or "True" in the customer's "Set Modified" field on a Product Import
Go to the Menu > Utilities > Dynamic Order Export page > Click on the Mark Customers button > Set the Status to Modified > Choose your Param > Click the Mark button

The following events will not mark a customer as being Modified:

When a customer is deleted.
Selecting a customer to edit on a Batch List but not changing any of its values.
Adding an Account Credit through the Miva admin.

The following events will un-modify an already modified customer:

Specifying "No", "0", or "False" in the customer's "Set Modified" field on a Batch List
Specifying "No", "0", or "False" in the customer's "Set Modified" field on a Product Import
Go to the Menu > Utilities > Dynamic Order Export page > Click on the Mark Customers button > Set the Status to Unmodified > Choose your Param > Click the Mark button

Additionally, the following store-front customer actions can have certain Modification Events too:

Page Code	Description	Action	Set Modified?
ACAD	Customer Create	ICST	Yes
ACED	Customer Edit	UCST	Yes
CPWD	Change Password	CPWD	Yes
CPWD	Change Email Address	CEML	Yes
OCST	Customer checks, "Update Customer Record With This Information" checkbox	ORDR	Yes
-	Customer Address set as Default Address	CCSA	Yes
-	Customer Address Added	ICSA	No
-	Customer Address Edited	UCSA	No
-	Customer Address Removed	DCSA	No
LOGN	Customer Login	LOGN	No
-	Customer Logout	LOGO	No
RGFT	Redeem Git Certificate	RDGC	No

Entity Specifics > Customers > `doe_modifiedcustomers` Data

account_id
bill_addr
bill_addr1
bill_addr2
bill_city
bill_cntry
bill_comp
bill_email
bill_fax
bill_fname
bill_id
bill_lname
bill_phone
bill_state
bill_zip
credit
id
login
note_count
password
pgrpcount
pw_email
ship_addr
ship_addr1
ship_addr2
ship_city
ship_cntry
ship_comp
ship_email
ship_fax
ship_fname
ship_id
ship_lname
ship_phone
ship_res
ship_state
ship_zip

Entity Specifics > Orders

Entity Specifics > Orders > Modified Events

The following events will mark an order as being Modified:

Adding a new order
Adding/Removing items to an order in the Miva admin
Changing the quantity of an order item.
Changing an input's value while editing an order from a Batch List page in the Miva admin.
Specifying "Yes", "1", or "True" in the order's "Set Modified" field on a Batch List
Specifying "Yes", "1", or "True" in the order's "Set Modified" field on a Product Import
Open the Order's Order Processing detail page > Clicking the Dynamic Order Export Modification Keys link > and set it to be Modified
Go to the Menu > Utilities > Dynamic Order Export page > Click on the Mark Orders button > Set the Status to Modified > Choose your Param > Click the Mark button

The following events will not mark an order as being Modified:

Changing Bill-to or Ship-to of an order on the Order Processing page.
Setting an order-item as Cancelled
Setting an order-item as Backordered
Setting a Return as received/restock
Creating a Shipment
Adding Shipment Tracking information
Marking an item as Shipped
Adding/Removing a note
Adding/Removing a Coupon
Adding/Removing order charges
Deleting an order

The following events will un-modify an already modified order:

Specifying "No", "0", or "False" in the order's "Set Modified" field on a Batch List
Specifying "No", "0", or "False" in the order's "Set Modified" field on a Product Import
Open the Order's Order Processing detail page > Clicking the Dynamic Order Export Modification Keys link > and set it to be Unmodified
Go to the Menu > Utilities > Dynamic Order Export page > Click on the Mark Orders button > Set the Status to Unmodified > Choose your Param > Click the Mark button

Entity Specifics > Orders > `doe_modifiedorders` Data

batch_id
bill_addr
bill_addr1
bill_addr2
bill_city
bill_cntry
bill_comp
bill_email
bill_fax
bill_fname
bill_lname
bill_phone
bill_state
bill_zip
bord_count
cust_id
dt_instock
id
net_capt
note_count
orderdate
orderpayment_id
pay_data
pay_id
pay_secdat
pay_secid
pay_seckey
pay_status
pend_count
processed
ship_addr
ship_addr1
ship_addr2
ship_city
ship_cntry
ship_comp
ship_data
ship_email
ship_fax
ship_fname
ship_id
ship_lname
ship_phone
ship_res
ship_state
ship_zip
source
source_id
status
stk_status
total
total_auth
total_capt
total_rfnd

You may have noticed that there is not data that describes the actual order items, charges, discounts, etc. To get that information, it can be easier to not use the Page Item method. Alternatively, you can use a Template Based Batch Report method. Keep reading to find out more about how Dyanmic Order Export can use Batch Reports

Exporting Template Based Batch Reports

Dynamic Order Export can run/output Template Based Batch Reports by making a web-request to the json.mvc module using specific parameters to control which orders are returned.

The following methods will return Template Based Batch reports by pinging a store's https://www.example.com/mm5/json.mvc file with valid Miva admin credentials.

Authentication

We need to have a valid Miva admin login and/or Miva admin session in order for your to make web-requests to the json.mvc module and execute Dyanmic Order Export module functions.

There are two options for ensuring the requests are authenticated properly: the first method would be to always pass the Miva Admin's username & password. The Second method would be to pass the username & password the first time, then retrieve the Session_ID and make all subsequent requests with the Session_ID. The first method can often times be easier to program.

Authenticating or testing the authentication requests while you're already logged into the Miva admin in the same browser will return a null result. Try starting a private-browsing window or a fresh-browser session.

Also, it is important to note that authenticated requests to the json.mvc will utilize a store's Miva admin Seat License. This can bring about scenarios where requests are not able to be performed because too many seats are being used. Applying for a Reserved Seat license can help resolve this.

Additionally, using the TemporarySession=1 parameter will help ensure that your session is not kept open until the Store's timeout period has occurred. It's best to always pass the TemporarySession=1 parameter for each web-request.

Here is a sample web-request that illustrates the basics parameters that are needed to successfully access Miva admin functionality through the json.mvc module:

{{JSON_URL}}?Session_Type=admin&Store_Code={{Store_Code}}&UserName={{Username}}&Password={{Password}}&TemporarySession=1

https://www.example.com/mm5/json.mvc?Session_Type=admin&TemporarySession=1&Store_Code=ABC-123&UserName=admin&Password=open_sesame!

Template Based Batch Report Exports

Template Based Batch reports are typically seen by going into the Miva Admin > Menu > Order Processing > Selecting a range of orders > Clicking the Batch Actions button > Selecting the Batch Report option > Selecting the Batch Report you want > and then clicking the Run Report button.

Rather than doing that process manually, we can use Dynamic Order Export to get/execute Batch Report's through web-requests.

All orders start out as "Unprocessed" and once DOE has output a Batch Report for a specific order, it considers it "Processed". The date, time, IP, and output file can all be listed in the Miva admin's Order Processing detail page. One order can be considered Processed/Unprocessed for each Template Based Batch Report that exists in the store.

Here are some sample requests that illustrate what kinds of Batch Report operations you can do:

By Processed/Unprocessed Status

By Processed Status - Get all Unprocessed Orders

{{JSON_URL}}?Session_Type=admin&TemporarySession=1&Store_Code={{Store_Code}}&UserName={{Username}}&Password={{Password}}&Function=Module&Module_Code=dynamicorderexport&ReportModule=templatebatchreports&Module_Function=Export_OrderBatchReport&Report_Code={{Report_Code}}

By Processed Status - Get a Specific Order

{{JSON_URL}}?Session_Type=admin&TemporarySession=1&Store_Code={{Store_Code}}&UserName={{Username}}&Password={{Password}}&Function=Module&Module_Code=dynamicorderexport&ReportModule=templatebatchreports&Module_Function=Export_OrderBatchReport&Report_Code={{Report_Code}}&Order_IDs=111

By Processed Status - Get Multiple Specific Orders

{{JSON_URL}}?Session_Type=admin&TemporarySession=1&Store_Code={{Store_Code}}&UserName={{Username}}&Password={{Password}}&Function=Module&Module_Code=dynamicorderexport&ReportModule=templatebatchreports&Module_Function=Export_OrderBatchReport&Report_Code={{Report_Code}}&Order_IDs=111,222,333

By Processed Status - Get all Orders After an Order ID

{{JSON_URL}}?Session_Type=admin&TemporarySession=1&Store_Code={{Store_Code}}&UserName={{Username}}&Password={{Password}}&Function=Module&Module_Code=dynamicorderexport&ReportModule=templatebatchreports&Module_Function=Export_OrderBatchReport&Report_Code={{Report_Code}}&First_Order_ID=111

By Processed Status - Get all Orders Before an Order ID

{{JSON_URL}}?Session_Type=admin&TemporarySession=1&Store_Code={{Store_Code}}&UserName={{Username}}&Password={{Password}}&Function=Module&Module_Code=dynamicorderexport&ReportModule=templatebatchreports&Module_Function=Export_OrderBatchReport&Report_Code={{Report_Code}}&Last_Order_ID=999

By Processed Status - Get all Orders in Range of Order Numbers

{{JSON_URL}}?Session_Type=admin&TemporarySession=1&Store_Code={{Store_Code}}&UserName={{Username}}&Password={{Password}}&Function=Module&Module_Code=dynamicorderexport&ReportModule=templatebatchreports&Module_Function=Export_OrderBatchReport&Report_Code={{Report_Code}}&First_Order_ID=888&Last_Order_ID=999

By Processed Status - Mark Orders After a Date as Processed

{{JSON_URL}}?Session_Type=admin&TemporarySession=1&Store_Code={{Store_Code}}&UserName={{Username}}&Password={{Password}}&Function=Module&Module_Code=dynamicorderexport&Report_Module_Code=templatebatchreports&Module_Function=DOE_Mark_Orders&Mark_Type=date_after&Report_Code={{Report_Code}}&After_Month=8&After_Day=30&After_Year=2015&After_Hour=17&After_Minute=26&After_Second=4&Processed=1

By Processed Status - Mark Orders Before a Date as Unprocessed

{{JSON_URL}}?Session_Type=admin&TemporarySession=1&Store_Code={{Store_Code}}&UserName={{Username}}&Password={{Password}}&Function=Module&Module_Code=dynamicorderexport&Report_Module_Code=templatebatchreports&Module_Function=DOE_Mark_Orders&Mark_Type=date_before&Report_Code={{Report_Code}}&Before_Month=8&Before_Day=30&Before_Year=2015&Before_Hour=17&Before_Minute=26&Before_Second=4&Processed=0

By Modification Key

The previous examples all used the Dynamic Order Export's Processed/Unprocessed methodology for keeping track of whether an order has been handled yet. DOE can also output order Batch Reports based on their Modification Key too.

The main differentiation is that the Module_Function parameter is changed from Export_OrderBatchReport to Export_OrderBatchReport_ModificationKey

Modification Key - Get Orders - All

{{JSON_URL}}?Session_Type=admin&TemporarySession=1&Store_Code={{Store_Code}}&UserName={{Username}}&Password={{Password}}&Function=Module&Module_Code=dynamicorderexport&ReportModule=templatebatchreports&Module_Function=Export_OrderBatchReport_ModificationKey&Modification_Key={{Modification_Key}}&Report_Code={{Report_Code}}

Modification Key - Manually Reset - Orders - Specific Orders

{{JSON_URL}}?Session_Type=admin&TemporarySession=1&Store_Code={{Store_Code}}&UserName={{Username}}&Password={{Password}}&Function=Module&Module_Code=dynamicorderexport&ReportModule=templatebatchreports&Module_Function=ModificationKey_Reset&Modification_Key={{Modification_Key}}&Modification_Type=orders&Order_IDs=1001,1002,1009

Modification Key - Manually Reset - Orders - Range of Orders

{{JSON_URL}}?Session_Type=admin&TemporarySession=1&Store_Code={{Store_Code}}&UserName={{Username}}&Password={{Password}}&Function=Module&Module_Code=dynamicorderexport&ReportModule=templatebatchreports&Module_Function=ModificationKey_Reset&Modification_Key={{Modification_Key}}&Modification_Type=orders&First_Order_ID=1000&Last_Order_ID=1010

Modification Key - Manually Reset - Categories, Products, and Customers

{{JSON_URL}}?Session_Type=admin&TemporarySession=1&Store_Code={{Store_Code}}&UserName={{Username}}&Password={{Password}}&Function=Module&Module_Code=dynamicorderexport&ReportModule=templatebatchreports&Module_Function=ModificationKey_Reset&Modification_Key={{Modification_Key}}&Modification_Type=products,categories,customers

Example Template Based Batch Report Integration

In the Miva admin, create a new Template Based Batch Report
1. Menu > Utilities > Template Based Batch Reports > Click the plus (+) button
2. Set the Type to Order
3. Give it a code of JSON
4. Give it a Name of JSON
5. Click the Add button
Edit the JSON page template
1. Replace the automatically generated template with:

<mvt:assign name="l.header" value="miva_output_header( 'Content-type', 'application/json' )" />

<mvt:if expr="g.Download">
    <mvt:assign name="l.header" value="miva_output_header( 'Content-Disposition', 'attachment; filename=orders.json' )" />
</mvt:if>

<mvt:do file="g.Module_JSON" name="l.null" value="JSON_Output( l.settings:admin_order )" />

1. Expand the "Order Contents" section
1. Configure & select any relevant Custom Fields, Images, Additional Price Displays, and Coupons
1. Click Update
1. Go to the page's Items tab
1. Remove the `inline_css` item

Mark All Existing Orders as Processed
1. Menu > Utilities > Dynamic Order Export
2. Click the "Mark Batch Report Orders" button
3. Set Status to Processed
4. Set Report to JSON
5. Set Mark to "All orders before date"
6. Click the Mark button
Prepare a Miva admin User
1. Menu > Users > Click the plus (+) button
2. Fill out the new user's username, password, confirm password.
3. Set them as an Administrator.
4. For License, you can use Concurrent, if you know that you have enough seats to allow a new user to access the Miva admin without filling up your store's Concurrent Seat License quota.
  1. For production/live integration purposes it would be best to sign up for a Reserved Seat, select the Reserved Seat option, and enter your Reserved Seat license.
5. Click the "+ Add" button.
6. The first time a User is created, it can help-out to login into the Miva admin as that user so that the User Agreement license can be accepted.
Test the DOE module for specific Orders
1. Take note of a recent order number that exists in the store
2. Open up a browser where you are not logged into the Miva admin, use a command-line-interface to cURL, or prepare a script that can call the following url as tailored to your store:

https://www.example.com/mm5/json.mvc?Session_Type=admin&TemporarySession=1&Store_Code={{Store_Code}}&UserName={{Username}}&Password={{Password}}&Function=Module&Module_Code=dynamicorderexport&ReportModule=templatebatchreports&Module_Function=Export_OrderBatchReport&Report_Code=JSON&Order_IDs=123456

1. You should see a JSON output for all of the order details for that specific order.

Completing the Integration
1. Now that the page has been confirmed to work when providing an order Id, try getting it to work so that it just outputs all of the unprocessed orders. You should be able to remove the Order_IDs parameter, like this:

https://www.example.com/mm5/json.mvc?Session_Type=admin&TemporarySession=1&Store_Code={{Store_Code}}&UserName={{Username}}&Password={{Password}}&Function=Module&Module_Code=dynamicorderexport&ReportModule=templatebatchreports&Module_Function=Export_OrderBatchReport&Report_Code=JSON

1. You probably wont have any Unprocessed orders, since we Marked them all as Processed in a previous step. The output from the last request will probably look like this:

{
  "orders": ""
}

1. Wait for an order to be placed, or:
    1. Go in to the Miva admin > Order Process > Double-click and order > Click the "Dynamic Order Export Reports" link
    1. Check the box in the Mark Unprocessed column for the JSON report.
    1. Click the Save Button
1. Refresh/recall the last DOE json.mvc url and now it should output all of the order details for the order you marked as Unprocessed.

Request Parameters

The following section will give a more detailed explanation of each of the parameters that can be present in a DOE request.

Session_Type

Description: This field is required and will always need to be "admin". Sample: Session_Type=admin

TemporarySession

Description: This field is optional but highly recommended. Miva has a limited number of Admin sessions that are allowed to be open according to the Store's Seats. This tells Miva not to create a lasting session that would hold one of the store's seats. Sample: TemporarySession=1

Store_Code

Description: This field is optional for most sites, but it is good practice to keep it. It is required for mall sites (sites with multiple stores running on one Miva installation). Sample: Store_Code=TS

UserName

Description: This field is required. This needs to be a valid Miva admin username. It is recommended to use a Reserved Seat in a production environment, but a regular user can be used for development. Sample: UserName=admin

Password

Description: This field is required. This needs to be the matching password for the Miva admin user. Sample: Password=P@ssw0rd

Passphrase[1]

Description: This is an optional parameter that is used if you need to export encrypted payment information. The store's Order Encryption Key (or multiple encryption keys) can be passed if you need the credit-card/payment details. Sample: Passphrase[1]=opensesame or Passphrase[1]=opensesame&Passphrase[2]=abra-ka-dabra

Function

Description: This field is required and will always be "Module". This tells the json.mvc module which type of process to run. Sample: Function=Module

Module_Code

Description: This field is required and will always be "dynamicorderexport". This tells the json.mvc module which external module it will be invoking a function on. Sample: Module_Code=dynamicorderexport

ReportModule

Description: This field is required and will always be: "templatebatchreports". This tells the dynamicorderexport module which module will report module it will be using. Sample: ReportModule=dynamicorderexport

Report_Code

Description: This field is required and will change depending on the Template Based Batch Report that you want to run. This is the Template Based Batch Report's Page Code without the "ORDER_". For example, all stores come with an "ORDER_INVOICE" page/batch-report by default. The Report_Code would just be "INVOICE". Sample: Report_Code=INVOICE or Report_Code=JSON

Module_Function

Description: This field is required and will be one of two values: "Export_OrderBatchReport" or "Export_OrderBatchReport_ModificationKey". This tells the json.mvc module which external module it will be invocing a function on. Sample: Module_Function=Export_OrderBatchReport or Module_Function=Export_OrderBatchReport_ModificationKey

Modification_Key

Description: This field is optional, but required when using, "Module_Function=Export_OrderBatchReport_ModificationKey". The Modification_Key allows you to group and track orders so that they can be output for their proper service/endpoint. Sample: Modification_Key=sample_doe_output

First_Order_ID

Description: This is an optional parameter that would be used to export a specific range of orders. If specified, it will export all orders greater-than-or-equal to that order id until it gets to the most recent order, or it gets to the Last_Order_ID (if it was passed). Sample: First_Order_ID=12345

Last_Order_ID

Description: This is an optional parameter that would be used to export a specific range of orders. If specified, it will export all orders less-than-or-equal to that order id until it get's to the first order in the store, or it gets to the First_Order_ID (if it was passed). Sample: Last_Order_ID=12345

Order_IDs

Description: This is an optional parameter that would be used to export one or more specific orders. It accepts a comma separated listed of order ids. If specified, it will export each order that is listed. Sample: Order_IDs=12345 or Order_IDs=111,222,333

Request Parameter Senarios

If you include First_Order_ID AND Last_Order_ID, then it will export all orders within that range.
If you only include First_Order_ID, then it will export all orders after that id
If you only include Last_Order_ID, then it will export all orders before that id
If you only include Order_IDs, then it will export those specific order(s)
If you don't include any of the above parameters, then it will export all new/unprocessed orders

Other Dynamic Order Export Capabilities

The following methods are available through the Dynamic Order Export module, but it is often more ideal an convenience to use one of the web-request methods described above.

Provisioning Batch Report Export

You can export a batch report through provisioning. Here is the XML provisioning that is required to execute a Batch Report:

<Export_OrderBatchReport>
    <Module>templatebatchreports</Module>
    <Report>JSON</Report>
    <OutputFile suffix="timestamp">sample_doe_output.txt</OutputFile>
    <FirstOrderID>1000</FirstOrderID>
    <LastOrderID>1100</LastOrderID>
</Export_OrderBatchReport>

Provisioning Page Export

You can export content of any page through provisioning.

You can even pass in variables through the parameters provisioning tag. This allows those variables and their values to be set prior to the page being rendered. The assignments are processed after the page has been loaded so that settings may be injected into the page by specifying a variable name such as "l.page:settings:xxx".

Here is an example of how you would load a page and inject settings

<Module code="dynamicorderexport" feature="util">
    <Export_Page>
        <OutputFile suffix="none">sample_doe_output.txt</OutputFile>
        <Code>test</Code>
        <Parameters>
            <Parameter name="l.page:settings:test">Value</Parameter>
            <Parameter name="g.Globals_Work">Too</Parameter>
        </Parameters>
    </Export_Page>
</Module>

JSON Page Export

You can export content of any page through json.mvc. You can also pass in variables through the parameters variable in the URL. This allows those variables and their values to be set prior to the page being rendered. The assignments are processed after the page has been loaded so that settings may be injected into the page by specifying a variable name such as "l.page:settings:xxx".