Skip to content

Instantly share code, notes, and snippets.

@steveosoule

steveosoule/miva-dynamic-order-export.md

Last active June 22, 2022 14:55
Show Gist options
  • Save steveosoule/ced57462958a382aecbc78658293762d to your computer and use it in GitHub Desktop.
Save steveosoule/ced57462958a382aecbc78658293762d to your computer and use it in GitHub Desktop.
Download ZIP
Miva - Dynamic Order Export
Raw
miva-dynamic-order-export.md

Dynamic Order Export

Outline

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:

  1. 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.
  2. Got to Menu > Modules, and click the plus-sign (+) button
  3. Click the Upload button
  4. 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.

  1. Install the module if it has not been installed already.
  2. 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.
  3. 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
  4. 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.
  5. 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>
  1. 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.
  2. If no entities have been modified since you created your key, then you should see an empty response.
  3. 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"
  4. 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.
  5. 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.
  6. 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
  7. 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.)
  1. 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

  1. 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
  2. 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
  1. 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
  2. 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.
  3. 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.
  1. 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".

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

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&Module_Function=Export_Page&Page_Code=sample_doe_output&Parameters=l.page:settings:test~Value&Globals_Work=Too

Sample Integrations

POST Customer Data to 3rd-Party

  • Have Dynamic Order Export Installed
  • Go to the Dynamic Order Export Utility Settings page (Menu > Utilities > Dynamic Order Export)
  • Add a Modification Key
  • Set the Param to a distinguishable value for the source that will be receiving the data. I'll use "AcmeCRM" as the Param for this example.
  • Check the box to Track Customers
  • Check the Manually Reset Modified Items option to help us while we develop the functionality
  • Click the Add button
  • Create a new Page in Miva. I'll give mine a page code of "doe_acme_customers", and a page name of "DOE: Acme Customer Integration"
  • Leave the Template blank for now.
  • Check the "Link to This Page Using HTTPS" if you can.
  • Click the "+ Add" button
  • Go to the doe_acme_customers page's Items tab
  • Assign the doe_modifiedcustomers item.
  • Go back to the Page tab and add the following template:
<h1>&mvt:page:name;</h1>
<hr>
<mvt:item name="doe_modifiedcustomers" param="AcmeCRM">
	<mvt:foreach iterator="customer" array="doe_modifiedcustomers">
		&mvte:customer:login;<br/>
	</mvt:foreach>
</mvt:item>
  • Visit the page on the front-end. It should be accessible at, "https://www.example.com/mm5/merchant.mvc?Screen=doe_acme_customers"
  • You'll most likely just see the "DOE: Acme Customer Integration" heading and a horizontal line on the page. If any customers were added or updated since you originally made the "AcmeCRM" Key, then their logins should be displaying too.
  • If you don't have any customers displaying on the page, then go into the Miva admin, edit a test/sample customer and click the Update button to set the customer as being Modified.
  • Now when you go back to the front-end "doe_acme_customers" page, you should see at least one customer login.
  • Now, we can modify the contents of the for-each loop to do whatever we'd like to. For example's sake, we'll have the page post all of the modified customers to a basic PHP script.
<h1>&mvt:page:name;</h1>
<hr>
<mvt:item name="doe_modifiedcustomers" param="AcmeCRM">
	<mvt:assign name="g.Customers" value="miva_array_serialize(l.settings:doe_modifiedcustomers)" />
	<mvt:call action="'https://www.example.com/sample.php'" method="'POST'" fields="'Customers">
		<mvt:eval expr="s.callvalue" />
	</mvt:call>
	<mvt:if expr="g.MvCALL_Error">
		<!-- @@ &mvt:global:MvCALL_Error; -->
	</mvt:if>
</mvt:item>
  • The sample PHP script is just going to var_dump($_POST) so that we can test how we're communicating with a sample integration. Here's my "sample.php" file:
<?php
echo "Hello from Sample API\n\n";
var_dump($_POST);
?>
  • Now would be the part where you test the integration out with various customers and do some end-to-end testing.
  • Once you're ready to move into a more complete and automated process, you can do the following:
  • Go back to the Dynamic Order Export Utility Settings page, click on the "AcmeCRM" Modification Key Param name link, un-check the "Manually Reset Modified Items" option, and click the Save button.
  • Now when we visit "https://www.example.com/mm5/merchant.mvc?Screen=doe_acme_customers" we should see our sample integration display info for our test customer one last time. We can refresh the page, and it should not output any customers; the modified customer queue is now empty.
  • Now we can setup a service or cron job to call the https://www.example.com/mm5/merchant.mvc?Screen=doe_acme_customers page at a reasonable interval that works for our site & integration needs (Once a month/week/day/hour/etc.)

Create an API Endpoint for Order Data

  • Have Dynamic Order Export Installed
  • Go to the Dynamic Order Export Utility Settings page (Menu > Utilities > Dynamic Order Export)
  • Add a Modification Key
  • Set the Param to a distinguishable value for the source that will be receiving the data. I'll use "AcmeERP" as the Param for this example.
  • Check the box to Track Orders
  • Check the Manually Reset Modified Items option to help us while we develop the functionality
  • Click the Add button
  • Create a new Template Based Batch Report in Miva (Menu > Utilities > Template Based Batch Reports > click the plus (+) sign button).
  • Set the Type to "Order"
  • Set the Code to "AcmeERP"
  • Set the Name to "Acme ERP Order Data"
  • Click the Add button
  • Click-once to highlight the new "Acme ERP Order Data" Batch Report.
  • Click the Edit Template button
  • Replace the Template with:
<mvt:assign name="l.null" value="miva_output_header( 'Content-type', 'application/json' )" />

<mvt:assign name="l.settings:output:order_count" value="miva_array_elements( l.settings:admin_order:orders )" />
<mvt:assign name="l.settings:output:data" value="l.settings:admin_order:orders" />

<mvt:do file="g.Module_JSON" name="l.success" value="JSON_Output( l.settings:output )" />
  • Click the Update button
  • Go to the Items tab
  • Remove the "inline_css" item
  • Try opening new private-browsing/cleared-cache browser and then visit your store's equivalent of:
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_ModificationKey&Modification_Key=AcmeERP&Report_Code=AcmeERP
  • You'll most likely just see basic/empty JSON object like this:
{
  "data": "",
  "order_count": 0
}
  • If you don't have any orders displaying on the page, then go into the Miva admin, edit a test/sample order, and click the "Dynamic Order Export Modification Keys" link, set the Status to Modified, check the "AcmeERP" option, click the Save button.
  • Now when you go back to the front-end and visit the long json.mvc URL above, you should see at more complex JSON data-structure for that order.
  • Now would be the part where you test the integration out with various customers and do some end-to-end testing.
  • Once you're ready to move into a more complete and automated process, you can do the following:
  • Go back to the Dynamic Order Export Utility Settings page, click on the "AcmeERP" Modification Key Param name link, un-check the "Manually Reset Modified Items" option, and click the Save button.
  • Now when we visit the above json.mvc URL we should see our sample integration display info for our test order(s) one last time. We can refresh the page, and it should not output any orders; the modified order queue is now empty.
  • Now we can setup a service or cron job to call above json.mvc URL at a reasonable interval that works for our site & integration needs (Once a month/week/day/hour/etc.)
@colinceo
Copy link

Is there the reverse of this? Order IMPORT?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment