Documentation and interface documentation for the "history" task on the soloPress FMP integration.
This task is complex enough to require an algorithm!

== Basic process ==
  * The operator has an existing session on the !SilkStream management interface. 
  * Uses the "view history" function (details of this have to be determined).
  * The web-system sends a request to Matatiro code to generate historical data placed by the current operator. 
  * Matatiro code generates basic details on the operator account, and a list of all the jobs placed against that account.
  * The web-system renders this as a webpage.
  * The operator selects a given historical job.
  * The web-system asks for a more detailed version from Matatiro code.
  * Matatiro code generates a detailed XML response on that specific job and references to scaled versions of the all the images in that job.
  * The web-system renders this as a webpage, embedding the image references.
  * Matatiro code generates the scaled images as the operators browser asks for them.
  
== Publically visible changes ==
This list omits what is necessary for !SilkStream, but that is outside the scope of the current document. 

The base URL is
  * https//payment.solopress.com/?/

The additions are
  * https://payment.solopress.com/?/history/view/user
  * https://payment.solopress.com/?/history/view/job
  * https://payment.solopress.com/?/media/$orderid/
  * https://payment.solopress.com/?/media/$orderid/30x34/FrontPage.jpg
  * https://payment.solopress.com/?/media/$orderid/1024x800/FrontPage.jpg
  * https://payment.solopress.com/?/media/$orderid/30x30/BackPage.jpg
  * https://payment.solopress.com/?/media/$orderid/1024x800/BackPage.jpg
  * https://payment.solopress.com/?/media/$orderid/thumb/BackPage.jpg
  * https://payment.solopress.com/?/media/$orderid/preview/BackPage.jpg
  * https://payment.solopress.com/?/media/$orderid/30/BackPage.jpg
  * https://payment.solopress.com/?/media/$orderid/1024/2/Newedition.pdf
  * https://payment.solopress.com/?/media/$orderid/1024x800/2/Newedition.jpg
 
The security hashes are applied to the end of the URL as another "URL directory", making the 
resultant URL look like this:
payment.solopress.com/?/media/$orderid/thumb/NewEdition.pdf/46ea0745cdea8feabb08ef6f314f1e08

Please see the appendices for more detail on security hashes.

== XML requests ==
There is a second copy of this section in colourised XML, in the same "docs" directory.
Please note for requests, the security hash is in the URL, and should be built over the entire body of the XML.  
There are test cases in the test directory for most possible options and formats.

{{{#!xml
<?xml version="1.0" encoding="utf-8"?>
<Request>
  <UserHistoricalJobs>
    <ID>FMP-346534-53453-345345-34534-5345</ID>
    <Results start="0" count="12" />
  </UserHistoricalJobs>
</Request>
}}}
{{{#!xml
<?xml version="1.0" encoding="utf-8"?>
<Request>
  <UserHistoricalJobs>
    <ID>1234</ID>
    <Results start="12" count="12" />
  </UserHistoricalJobs>
</Request>
}}}
{{{#!xml
<?xml version="1.0" encoding="utf-8"?>
<Request>
  <UserHistoricalJobs>
    <ID>1234</ID>
    <Results start="24" count="48" />
  </UserHistoricalJobs>
</Request>
}}}
{{{#!xml
<?xml version="1.0" encoding="utf-8"?>
<Request>
  <UserJob>
    <Jobnum>125534</Jobnum>
    <PreviewSize>800</PreviewSize>
  </UserJob>
</Request>
}}}
{{{#!xml
<?xml version="1.0" encoding="utf-8"?>
<Request>
  <UserJob>
    <Jobnum>125534</Jobnum>
  </UserJob>
</Request>
}}}

== XML responses ==
{{{#!xml
<?xml version="1.0" encoding="utf-8"?>
<Response>
  <status errorid="0">Operation successful.</status>
  <SecurityString>98d1edad3280ce6db674bc475a5d5921</SecurityString>
  <UserAccount>
    <AccountType>Chair</AccountType>
    <BillingAddress>
      <CompanyName>the corner shop</CompanyName>
      <Address>the big corner</Address>
      <Address2>End street</Address2>
      <Address3></Address3>
      <TownCity>middleton</TownCity>
      <County>yorkshire</County>
      <Postcode>DL34 666</Postcode>
      <TypeofBuilding>Sales-frontage Shop</TypeofBuilding>
    </BillingAddress>
  </UserAccount>
  <JobsList>
    <Job>
      <Jobnum>123123123</Jobnum>
      <DateOrdered>20-04-2011</DateOrdered>
      <Description>fghfgh ghf ghsghsfghs ghsg.</Description>
    </Job>
    <Job>
      <Jobnum>123123124</Jobnum>
      <DateOrdered>21-04-2011</DateOrdered>
      <Description>fghfgh ghfdfgdfgdfg ghsghsfghs ghsg.</Description>
    </Job>
    <!-- And so on for many more items -->
  </JobsList>
</Response>

}}}


This XML lists all the files attached to the job, and a number of other data points.  Please note of these URLs MAY include a page number and some don't.  The JPEGs will only hold a single image, the PDFs multiple pages, and the TIFFs may also.


{{{#!xml
<?xml version="1.0" encoding="utf-8"?>
<Response>
  <status errorid="0">Operation successful.</status>
  <SecurityString>98d1edad3280ce6db674bc475a5d5921</SecurityString>
  <DetailedJob>
    <JobDetails>
      <DateCreated>04/18/2011 19:26:56</DateCreated>
      <JobNum>181526</JobNum>
      <Description>printed full colour to one side ribex 2011 exhibitor pass - authorised helmsman</Description>
      <Name>Flyers Recycled Silk (standard)</Name>
      <Material>350gsm Silk</Material>
      <Quantity>250</Quantity>
      <Size>55mm x 85mm</Size>
      <Option>None</Option>
      <CountOfSides>1</CountOfSides>
      <netPrice>97</netPrice>
      <vatRate>20</vatRate>
      <vatAmount>19.4</vatAmount>
      <grossPrice>116.4</grossPrice>
    </JobDetails>
    <DeliveryAddress>
      <CompanyName>the corner shop</CompanyName>
      <Address>the big corner</Address>
      <Address2>End street</Address2>
      <Address3></Address3>
      <TownCity>middleton</TownCity>
      <County>yorkshire</County>
      <Postcode>DL34 666</Postcode>
      <TypeofBuilding>Sales-frontage Shop</TypeofBuilding>
    </DeliveryAddress>
    <ImagesList>
      <Image type="thumb" url="https//payment.solopress.com/?/media/$orderid/30x34/BackPage.jpg" />
      <Image type="thumb" url="https//payment.solopress.com/?/media/$orderid/30x34/FrontPage.jpg" />
      <Image type="preview" url="https//payment.solopress.com/?/media/$orderid/1024x800/BackPage.jpg" />
      <Image type="preview" url="https//payment.solopress.com/?/media/$orderid/1024x800/frontPage.jpg" />
      <Image type="thumb" url="https//payment.solopress.com/?/media/$orderid/30x34/1/MiddleContent.pdf" />
      <Image type="thumb" url="https//payment.solopress.com/?/media/$orderid/30x34/2/MiddleContent.pdf" />
      <Image type="thumb" url="https//payment.solopress.com/?/media/$orderid/30x34/3/MiddleContent.pdf" />
      <Image type="preview" url="https//payment.solopress.com/?/media/$orderid/1024x800/1/MiddleContent.pdf" />
      <Image type="preview" url="https//payment.solopress.com/?/media/$orderid/1024x800/2/MiddleContent.pdf" />
      <Image type="preview" url="https//payment.solopress.com/?/media/$orderid/1024x800/3/MiddleContent.pdf" />
    </ImagesList>
  </DetailedJob>
</Response>

}}}

== Appendix: Testing Samples ==
==== Sample 1 :: View User ====

POST soloPress/?/history/view/user/08e1278f3dabe1c333870db53cbb53fe/db=1

{{{#!xml
<?xml version="1.0" encoding="utf-8"?>
<Request>
  <UserHistoricalJobs>
    <ID>8839</ID>
    <Results start="0" count="12" />
  </UserHistoricalJobs>
</Request>
}}}

returns 

{{{#!xml
<?xml version="1.0" encoding="utf-8"?>
<Response>
  <status error-id="0">Operation successful</status>
  <security>34d91acea5f8ef4027c4292f860c6492</security>
  <UserAccount>
    <AccountType>To Pay</AccountType>
    <CompanyId>FMP4-2-144660120012-6856461-04342-121033975791616</CompanyId>
    <BillingAddress>
      <CompanyName>Miss Mille Haugnaess</CompanyName>
      <Address>36 ebor place</Address>
      <Address2></Address2>
      <Address3></Address3>
      <TownCity>leeds</TownCity>
      <County>west yorkshire</County>
      <Postcode>LS6 1NR</Postcode>
      <TypeofBuilding></TypeofBuilding>
    </BillingAddress>
  </UserAccount>
  <JobsList />
</Response>
}}}

==== Sample 2 :: View Job. ====

POST soloPress/?/history/view/job/3b255b54cbb8ca902bffeca71b7e2e38/db=1

{{{#!xml
<?xml version="1.0" encoding="utf-8"?>
<Request>
<UserJob>
<Jobnum>181526</Jobnum>
</UserJob>
</Request>
}}}
returns (I have put line breaks in this even though the live version wont, so you may see the data better.)  

{{{#!xml
<?xml version="1.0" encoding="utf-8"?>
<Response>
  <status error-id="0">Operation successful</status>
  <security>67a5d25e291575a2eec3db769767984d</security>
  <DetailedJob>
    <JobDetails>
      <DateCreated>04/18/2011 19:26:56</DateCreated>
      <JobNum>181526</JobNum>
      <Description>printed full colour to one side ribex 2011 exhibitor pass - authorised helmsman</Description>
      <Name>Flyers Recycled Silk (standard)</Name>
      <Material>350gsm Silk</Material>
      <Quantity>250</Quantity>
      <Size>55mm x 85mm</Size>
      <Option>None</Option>
      <CountOfSides>1</CountOfSides>
      <netPrice>97</netPrice>
      <vatRate>20</vatRate>
      <vatAmount>19.4</vatAmount>
      <grossPrice>116.4</grossPrice>
    </JobDetails>
    <DeliveryAddress>
      <Contact>Michaela Montgomery-Swan</Contact>
      <CompanyName>RIB International Ltd</CompanyName>
      <Address>Oyster House</Address>
      <Address2>Hunters Lodge</Address2>
      <TownCity>Kentisbeare</TownCity>
      <County>Devon</County>
      <Postcode>EX15 2DY</Postcode>
      <TypeofBuilding></TypeofBuilding>
    </DeliveryAddress>
    <ImagesList>
      <Image>
        <type>thumb</type>
        <url>solopress/?/media/181526/59x45/Back+Stage+Pass+2011.pdf</url>
      </Image>
      <Image>
        <type>preview</type>
        <url>solopress/?/media/181526/333x259/Back+Stage+Pass+2011.pdf</url>
      </Image>
      <Image>
        <type>thumb</type>
        <url>solopress/?/media/181526/59x45/Helmsman+Pass+2011.pdf</url>
      </Image>
      <Image>
        <type>preview</type>
        <url>solopress/?/media/181526/333x259/Helmsman+Pass+2011.pdf</url>
      </Image>
    </ImagesList>
  </DetailedJob>
</Response>
}}}

==== Sample 3 :: View Image ====

GET soloPress/?/media/181522/50/Back_NEW.jpg

<binary response>

GET soloPress/?/media/181522/thumb/Back_NEW.jpg

<binary response>

GET soloPress/?/media/181522/preview/2/BigDocument.pdf

<binary response>


== Appendix: Error Codes ==
The process of building the hash is described in the previous section.
The error-id  will map to what FMP returns with the following additions:

  * -13 :: "System error: Required subsystem not installed. Please inform administration."
  * -12 :: "Badly formed XML document received. Nothing done.",
  * -11 :: "Bad request, Unable to locate jobnum.",
  * -10 :: "Bad request, Unknown client id",
  * -8 ::"Bad request, Unable to locate jobnum.",
  * -7 :: "Bad request, unknown history action, try 'user' or 'jobs'.",
  * -6 :: "Bad request, unknown webform action requested, try 'order', 'quote', 'sample' or 'orderitem'.",
  * -5 :: "System failure: Unknown dB action, no activity possible.", 
  * -4 :: Unable to connect to the dB.
  * -3 :: Security hash mis-match.
  * -2 :: Incomplete post, missing data.  
  * -1 :: Unknown error (the error mapping is missing an entry). This is the default, case, but 
  *:      you are never likely to see it.
  * 0  :: Operation successful
  
The status text is a textual rendering on the error-id.
In the gross majority of cases, the value returned will be 0.

== Appendix: Idempotency ==

As noted above the request is signed as an addition to the end of the request URL. 
The response is signed via a XML element, as the rest of the document is XML.  

basic response:

{{{#!xml
<?xml version"1.0" encoding="utf-8" ?>
<Response>
  <security>98d1edad3280ce6db674bc475a5d5921</security>
  <status errorid="0" >Operation successful.</status>
</Response>
}}}

Firstly, the original documentation would have been clearer, if it said "string concatenation" rather than +. The values may be numerical however, the data needs to be joined in the same fashion as table indices. 

The request hash is included in the response hash, to demonstrate that the message came from the party to which you sent the initial request.


Therefore in total the security hash looks like this:

'+' is a string concatination

!SharedSecret = '*********';

The !SharedSecret is specific to integration between !SilkStream and Matatiro Solutions work for soloPress.

!RequestHash = md5(!WebCustomerID + !WebOrderNumber + !SharedSecret + '')

!ResponseHash =md5(!WebCustomerID + !WebOrderNumber + !SharedSecret + !RequestHash)

 
== Installation Requirements == 
To receive the XML in a non mangled fashion, from a POST body, I need

<code conf>
always_populate_raw_post_data = 1 
</conf>
adding to the php.ini

Please note in PHP 5 the location of the config file is best looked up via phpinfo(), you may have several different
 config files on your system.

To make the image scaling software feature available, it is necessary to install ImageMagick, and the dependant link
 library Ghostscript.   These sources are listed following, and include simple steps for installation.
There may be no action necessary if Steve Winter has done the installation

To make this operational, there are changes to the interface FMP file (web_interfacev2) and the new PHP files (msxml, 
solopresscommon, history, webform and media).  There have been changes to config, index and helper files.

For a ramp up process I would like to use lots of logging, so we may react to unforseen events better.
As such, may I have a '/var/log/apache2/images/' directory, with write permissions for the webserver user.

Please ensure the webserver account has read and directory access for all the images directories. 

  * http://imagemagick.org/script/binary-releases.php
  * http://pecl.php.net/package/imagick - the PHP integration
  * http://www.francodacosta.com/phmagick/download
  * http://mac.softpedia.com/get/System-Utilities/GPL-Ghostscript.shtml
  
To get things working on a windows box
  http://www.imagemagick.org/script/install-source.php
  There may be a binary release, i wasn't sure if "foreign" operating systems where supported.
  This is a UNIX project.
  http://sourceforge.net/projects/ghostscript/