ITrack/Appraisal Extension

From ISoft Wiki
Jump to navigationJump to search

The Appraisal Extension is used to allow our products to give per-item appraisals by evaluating the item's performance to Berryhill Auctioneers' previous auctions.

General

In general, the Appraisal Extension requires the following:

  • ITrack. It can be Pro, AX, Enterprise, or anything that uses ITrack.exe
    • OR any specially-build applications designed by ISoft.
  • The AppraisalExtension.dll file.
  • Connection configuration data. This is usually located in the host.ini file provided with ITrack.
  • Company permission. This is controlled by ISoft, and those interested in being added should contact our Sales department.

All of these can be arranged by contacting ISoft.

Usage

Once the Appraisal Extension is installed and configured, most appraisals will be done with a list of parts (or, less commonly, a single part) and a button press. ITrack users should look to their Search screens. When the button is pressed, the screen will look up the appraisal data, which may take a few moments, and then report it on your screen.

Code

You can use the Appraisal Extension interface, or make database calls directly.

Appraisal Extension - External Calls

The easiest way to get appraisals is to use the following sequence of remote calls:

  1. Check to see that the appraisal extension is valid by calling something like
    • ITAppraisal::GetInstance()->IsEnabled()
  2. Create an APPRAISALMESSAGE object and set APPRAISALMESSAGE.itData.itOrigin to an appropriate origin. (Use APPRAISALMESSAGESINGLEITEM if you only have a single item)
  3. Optional - Ask the user for the appraisal type
    1. Set APPRAISALMESSAGE.itData.nAuctionID to the current auction you're appraising at (leave it alone if you don't know what this should be)
    2. Call the following to run the dialog:
      • CallExternalFunction(<master window handle>, "Appraisal", "AppraisalOriginDialog", <extension name>, &APPRAISALMESSAGE.itData, NULL)
    3. The user will use the dialog that pops up, and control of the program will be returned.
  4. Create an ITAppraisalItem object.
  5. For each item in the array, set the following values in your ITAppraisalItem (skip if you don't have them)
    • Unique Identifier (integer) (partnum / inventoryid is a good choice)
    • Inventory Type ID (integer)
    • Category (string)
    • Manufacturer (string)
    • Model (string)
  6. Add that item to the appraisal array by calling the following:
    • APPRAISALMESSAGE.mapItems[itItem.GetID()] = ITAppraisalItem
  7. When you've added all the items to appraise, call:
    • Multiple items: CallExternalFunction(<master window handle>, "Appraisal", "AppraiseItems", <extension name>, &APPRAISALMESSAGE, NULL);
    • Single item: CallExternalFunction(<master window handle>, "Appraisal", "AppraiseItem", <extension name>, &APPRAISALMESSAGESINGLEITEM , NULL);
  8. When control is returned, you can retrieve your appraisal values by calling:
    • APPRAISALMESSAGE.mapItems[<unique id>].GetAppraisedValue()
    • OR MapFind(itMessage.mapItems, <unique id>, itItem); itItem.GetAppraisedValue();

Appraisal Extension - Direct Object Calls

In some cases, you'll want to appraise the same data set more than twice, and in this case you can avoid the setup overhead of the objects by calling the appraisal object directly:

  1. Check to see that the appraisal extension is valid by calling something like
    • ITAppraisal::GetInstance()->IsEnabled()
  2. Get an instance of the appraisal object:
    • ITAppraisal *pitAppraisal = ITAppraisal::GetInstance();
  3. Create an empty CString for your session ID.
  4. Create an APPRAISALDATA object and set APPRAISALMESSAGE.itData.itOrigin to an appropriate origin.
    • If it's your first call, you *must* call ITAppraisalExtension::Initialize(m_pwndMaster) OR set itData.pMasterWnd to Master's window handle.
  5. Optional - Ask the user for the appraisal type
    1. Call pitAppraisal->DoAppraisalOriginDialog(APPRAISALMESSAGE.itData);
    2. The user will use the dialog that pops up, and control of the program will be returned.
  6. Create an ITAppraisalItem object.
  7. For each item in the array, set the following values in your ITAppraisalItem (skip if you don't have them)
    • Unique Identifier (integer) (partnum / inventoryid is a good choice)
    • Inventory Type ID (integer)
    • Category (string)
    • Manufacturer (string)
    • Model (string)
  8. Add that item to the appraisal array by calling the following:
    • APPRAISALMESSAGE.mapItems[itItem.GetID()] = ITAppraisalItem
  9. When you've added all the items to appraise, call:
    1. pitAppraisal->OpenSession(sessionID) to get your session id
    2. pitAppraisal->AddItemsToSession(sessionID, APPRAISALMESSAGE.mapItems) to add your items
    3. pitAppraisal->AppraiseSession(sessionID, APPRAISALMESSAGE.itData)
    4. pitAppraisal->GetAppraisedValues(sessionID, APPRAISALMESSAGE.mapItems) to fill out your values
    5. If you wish, alter APPRAISALMESSAGE.itData and go back to step 3 to do a different appraisal
    6. pitAppraisal->CloseSession(sessionID) to clean up your appraisal session.
  10. Let your APPRAISALMESSAGE object go out of scope or deallocate it.

Caveats

You can use the APPRAISALMESSAGE multiple times, and when you're done with it, just let it go out of scope or deallocate it. You never need to worry about cleaning up the ITAppraisal object either.

Don't mess around with the memory location of pitAppraisal. It's a singleton, and anything you do to it will be reflected any place its code is called.

ITAppraisal is *not* thread-safe at the moment.