Standard notification of scans/referrals

[arnoud]

Notifications to partners (for scans or referrals) can be done by email or by post:

• Email: The email is in HTML format with a so-called plain-text alternative. The sender of the email is noreply@scancircle.com (add this email address to a white list to avoid blocking by strict spam filters)
  
• Post: An HTTP post of an XML structure called "info" with one root node and one level of sub nodes. Use this method to process notifications automatically.
  

In the definitions below, the variables are enclosed in curly brackets and explained in the variable list below. The XML sub nodes contain the variables indicated by the node name (e.g. <advice>{advice}</advice>).

Scan: when a user performs a scan in your partner environment

• Email subject: "{source} scan results for {name}/{volumeid}/{serial}[ ({reference})]" ([] meaning optional)
  
• Email body contains: {advice}, {make}, {mobo}, {bios}, {os}, {installed}, {cpu}, {memory}, {disk}, {lastboot}, {ip} ({iplocation}), {score}, {targets}, {keys}, {message}
  
• Post XML root node: scan
  
• Post XML sub nodes: advice, language, scanmode, reference, name, volumeid, serial, make, mobo, bios, os, installed, cpu, memory, disks, lastboot, redirect, ip, iplocation, score, targets, keys, oskey*
  
• Post reply: the script should return (echo) "OK" to indicate that it is successful or a URL to redirect the user to a specific webpage. Other responses are regarded as error, then the message will still be sent to the next alternative (separated by a vertical bar). This continues until no more alternatives are available.
  

*)  To support existing scancircle2pcrt v1.35 implementations, the license keys will also be included in an <oskey> node for the moment

Referral: when a user of your own partner environment clicks on one of your advertisements or asks for support (internal referral) or a user of the general www environment clicks on your entry on the map (External referral)

• Email subject: "Internal referral" or "External referral"
  
• Email body contains: {advice}, {from}, {location}, {reference}, {redirect}, {ip}, {message}, {explanation}
  
• Post XML root node: referral
  
• Post XML sub nodes: type, advice, from, location, reference, redirect, ip
  
• Post reply: there is no check on the response (echo).
  

Variable list:

• {advice}: result URL for the expert (the Advice tab)
  
• {bios}: device's Basic IO System
  
• {cpu}: processor specs
  
• {disk}: local storage devices (drive names and size)
  
• {from}: partner code where the scan is performed (your own partner code for an internal referral, www for the general environment)
  
• {installed}: OS installation date
  
• {ip}: external IP address
  
• {iplocation}: city+state+country based on IP address
  
• {language}: active language code (en/nl)
  
• {lastboot}: last system boot date
  
• {keys}: license keys in the format {name}:{value}, separated by semi-colons (only in partner mode)
  
• {location}: a Google Maps link to the city (based on IP address) or the location specified by the user (only for external referrals)
  
• {make}: device brand and model
  
• {memory}: total memory installed and number and size of memory modules
  
• {message}: an optional reply/error message from a post method (scan) or an explanation (referral)
  
• {mobo}: mother board
  
• {name}: device name
  
• {os}: operating system
  
• {redirect}: the URL the end-user is redirected to (Summary tab for results or custom URL for referrals)
  
• {reference}: optional reference code
  
• {scanmode}: d=direct, p=partner, a=automatic, m=manual, e=alternative in MSIE
  
• {score}: total scan score (optionally with one decimal, '?' if OS unknown)
  
• {serial}: device serial number as specified by the manufacturer
  
• {source}: "Partner" (if partner mode), "Reference" (if reference code specified) or "Anonymous" (otherwise)
  
• {targets}: names of the targets that meet your specified advertisement conditions (separated by commas)
  
• {type}: type of referral "Internal" or "External"
  
• {volumeid}: volume serial number of primary hard drive
  

Note: the pre v1.38 layout is listed here for e-mails and here for web posts.

[arnoud]

Updated based on current functionality (zip code deprecated, location, added reference and target).

[arnoud]

Results notification added for release 1.31 (scan-based targeting). This notification is therefore somewhat later than now and with a slightly altered subject and content. Let me know if this causes any problems, then you can get the current notification or both.

[arnoud]

The functionality of release 1.38 is now listed in the first post of this threat.

[arnoud]

For historical purposes, this was the pre v1.38 version (in Dutch):

De melding van een scan of een doorverwijzing wordt normaliter per e-mail aan de partner doorgegeven. Dit is in HTML formaat met een zogenaamde plain-text alternative. De afzender van de e-mail is noreply@scancircle.com. Voeg deze eventueel toe aan een witte lijst om blokkering door strenge spamfilters te voorkomen.

Scan(resultaten)
Zodra de standaard resultaatpagina voor het eerst geopend wordt (normaliter enkele seconden na ontvangst van de scan), wordt een e-mail verstuurd met als onderwerp: {type} scan results for {name}/{volumeid}/{serial} ({reference})

Hierin is:

• {type}: "Partner" (indien in partnermodus), "Reference" (indien met referentiecode) en anders "Anonymous"
  
• {name}: computernaam
  
• {volumeid}: volume serienummer van primaire harde schijf
  
• {serial}: computer serienummer zoals opgegeven door de fabrikant
  
• {reference}: optionele referentiecode (ronde haken blijven weg indien leeg) 
  

En de inhoud bevat:

• advice: de URL voor de expert (naar het tabblad Adviezen)
  
• make: computermerk en -model
  
• os: besturingssysteem
  
• cpu: processornaam
  
• memory: hoeveelheid geheugen
  
• lastboot: datum laatste opstart
  
• IP: extern IP adres
  
• score: de totale scan score (optioneel met 1 decimaal, punt als separator, '?' indien OS onbekend)
  
• targets: namen van de targets die voldoen (gescheiden door komma's)
  

Als echter met een eigen resultaatpagina gewerkt wordt, wordt de standaard resultaatpagina mogelijk niet (direct) geopend wordt. Daarom wordt in dat geval direct na ontvangst van de scan met referentiecode, een e-mail gestuurd met als bijna hetzelfde onderwerp: {type} scan for {name}/{volumeid}/{serial} ({reference}) (dus zonder het woord "results") en bijna dezelfde inhoud maar zonder de velden 'score' en 'targets'. Als daarna alsnog de standaard resultaatpagina wordt geopend voordat de database is bijgewerkt (normaliter om de paar dagen), dan wordt ook de e-mail met de scanresultaten gestuurd. Op verzoek kunnen ook beide e-mails of alleen die n.a.v. de scan verstuurd worden.

Doorverwijzing
Als een gebruiker van de eigen partneromgeving om hulp vraagt, dan wordt een e-mail verstuurd met als onderwerp Internal referral. Wordt een bezoeker van de algemene www-omgeving via de landkaart doorgestuurd naar de ondersteuningspagina van de partner, dan is het onderwerp External referral.

De inhoud bevat:

• advice: de URL voor de expert (naar het tabblad Adviezen)
  
• from: de partnercode van de partner waar de scan gedaan is (www voor de algemene omgeving)
  
• location: de coördinaten (latitude,longitude) van de door de gebruiker opgegeven of de initiële locatie op de kaart (alleen voor externe doorverwijzingen)
  
• reference: optionele referentiecode
  
• target: de URL waarnaar de gebruiker doorverwezen is
  
• IP: extern IP adres
  

Let op: Bovenstaande informatie kan in de toekomst wijzigen. Als u deze geautomatiseerd wilt verwerken, dan kunt u beter de melding scan/doorverwijzing via web post gebruiken.

[arnoud]

In release 1.41, functionality is added to specify other and more alternatives than 1 email address using the vertical bar. This way, you can log the scan to e.g. PC Repair Tracker (PCRT) and/or RepairShopr (RS) and/or email. Since the PCRT plugin requires a pcid and the RS plugin a ticket id, you must use the "category" parameter to handle the scan by the PCRT or RS plugin and use a reference code like pcrt:12345 or rs:6789

1. Set "Notifications to" e.g. to: https://domain.com/pcrt/repair/scancircl...?token=xxx&category=pcrt|https://scancircle.com/plugins/repairshopr.php?subdomain=yyy&apikey=zzz&category=rs|name@domain.com
   
2. This will send the scan to the PCRT plugin first. If the reference code contains* pcrt: then the numerical value of the following characters will be used as the pcid. If not or if there is no match on the pcid, the scan will be sent to the RS plugin. If the reference code contains rs: then the numerical value of the following characters will be used as the ticket id. If not or if there is no match on the ticket id, the scan will be sent to the specified email address;
   
3. Even more alternatives can be added, but remember that this will slow down the client scan (which awaits the response before showing the results).
   

In addition, the functionality of the "category" parameter in the PCRT plugin* and the RS plugin has been modified slightly to support sending the scan to multiple destinations. Instead of just checking if the reference code starts with the specified category (plus a colon), it now checks if the reference code contains the specified category (plus a colon) and uses the numerical value of the following characters. To allow a scan to be logged in PCRT and RS, use the same configuration as above, but add the "copy" parameter to the first option and use a reference code e.g. like pcrt:12345;rs:6789

1. Set "Notifications to" e.g. to: https://domain.com/pcrt/repair/scancircl...egory=pcrt&copy=1|https://scancircle.com/plugins/repairshopr.php?subdomain=yyy&apikey=zzz&category=rs|name@domain.com
   
2. The handling is the same as above, except that the processing continues even after a match is found and that different parts of the reference code are used.
   

*) the RS plugin is installed and maintained in the ScanCircle environment and therefore this update is available immediately. The PCRT plugin is installed in your own PCRT environment so the update for the "category" parameter will be available after the next PCRT release. So just start the reference code with "pcrt:" and this will work immediately too.