Changes between Initial Version and Version 1 of history-docs


Ignore:
Timestamp:
Jul 10, 2018, 8:45:31 AM (8 years ago)
Author:
steve.winter
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • history-docs

    v1 v1  
     1Documentation and interface documentation for the "history" task on the soloPress FMP integration.
     2This task is complex enough to require an algorithm!
     3
     4== Basic process ==
     5  * The operator has an existing session on the !SilkStream management interface.
     6  * Uses the "view history" function (details of this have to be determined).
     7  * The web-system sends a request to Matatiro code to generate historical data placed by the current operator.
     8  * Matatiro code generates basic details on the operator account, and a list of all the jobs placed against that account.
     9  * The web-system renders this as a webpage.
     10  * The operator selects a given historical job.
     11  * The web-system asks for a more detailed version from Matatiro code.
     12  * Matatiro code generates a detailed XML response on that specific job and references to scaled versions of the all the images in that job.
     13  * The web-system renders this as a webpage, embedding the image references.
     14  * Matatiro code generates the scaled images as the operators browser asks for them.
     15 
     16== Publically visible changes ==
     17This list omits what is necessary for !SilkStream, but that is outside the scope of the current document.
     18
     19The base URL is
     20  * https//payment.solopress.com/?/
     21
     22The additions are
     23  * https://payment.solopress.com/?/history/view/user
     24  * https://payment.solopress.com/?/history/view/job
     25  * https://payment.solopress.com/?/media/$orderid/
     26  * https://payment.solopress.com/?/media/$orderid/30x34/FrontPage.jpg
     27  * https://payment.solopress.com/?/media/$orderid/1024x800/FrontPage.jpg
     28  * https://payment.solopress.com/?/media/$orderid/30x30/BackPage.jpg
     29  * https://payment.solopress.com/?/media/$orderid/1024x800/BackPage.jpg
     30  * https://payment.solopress.com/?/media/$orderid/thumb/BackPage.jpg
     31  * https://payment.solopress.com/?/media/$orderid/preview/BackPage.jpg
     32  * https://payment.solopress.com/?/media/$orderid/30/BackPage.jpg
     33  * https://payment.solopress.com/?/media/$orderid/1024/2/Newedition.pdf
     34  * https://payment.solopress.com/?/media/$orderid/1024x800/2/Newedition.jpg
     35 
     36The security hashes are applied to the end of the URL as another "URL directory", making the
     37resultant URL look like this:
     38payment.solopress.com/?/media/$orderid/thumb/NewEdition.pdf/46ea0745cdea8feabb08ef6f314f1e08
     39
     40Please see the appendices for more detail on security hashes.
     41
     42== XML requests ==
     43There is a second copy of this section in colourised XML, in the same "docs" directory.
     44Please note for requests, the security hash is in the URL, and should be built over the entire body of the XML. 
     45There are test cases in the test directory for most possible options and formats.
     46
     47{{{#!xml
     48<?xml version="1.0" encoding="utf-8"?>
     49<Request>
     50  <UserHistoricalJobs>
     51    <ID>FMP-346534-53453-345345-34534-5345</ID>
     52    <Results start="0" count="12" />
     53  </UserHistoricalJobs>
     54</Request>
     55}}}
     56{{{#!xml
     57<?xml version="1.0" encoding="utf-8"?>
     58<Request>
     59  <UserHistoricalJobs>
     60    <ID>1234</ID>
     61    <Results start="12" count="12" />
     62  </UserHistoricalJobs>
     63</Request>
     64}}}
     65{{{#!xml
     66<?xml version="1.0" encoding="utf-8"?>
     67<Request>
     68  <UserHistoricalJobs>
     69    <ID>1234</ID>
     70    <Results start="24" count="48" />
     71  </UserHistoricalJobs>
     72</Request>
     73}}}
     74{{{#!xml
     75<?xml version="1.0" encoding="utf-8"?>
     76<Request>
     77  <UserJob>
     78    <Jobnum>125534</Jobnum>
     79    <PreviewSize>800</PreviewSize>
     80  </UserJob>
     81</Request>
     82}}}
     83{{{#!xml
     84<?xml version="1.0" encoding="utf-8"?>
     85<Request>
     86  <UserJob>
     87    <Jobnum>125534</Jobnum>
     88  </UserJob>
     89</Request>
     90}}}
     91
     92== XML responses ==
     93{{{#!xml
     94<?xml version="1.0" encoding="utf-8"?>
     95<Response>
     96  <status errorid="0">Operation successful.</status>
     97  <SecurityString>98d1edad3280ce6db674bc475a5d5921</SecurityString>
     98  <UserAccount>
     99    <AccountType>Chair</AccountType>
     100    <BillingAddress>
     101      <CompanyName>the corner shop</CompanyName>
     102      <Address>the big corner</Address>
     103      <Address2>End street</Address2>
     104      <Address3></Address3>
     105      <TownCity>middleton</TownCity>
     106      <County>yorkshire</County>
     107      <Postcode>DL34 666</Postcode>
     108      <TypeofBuilding>Sales-frontage Shop</TypeofBuilding>
     109    </BillingAddress>
     110  </UserAccount>
     111  <JobsList>
     112    <Job>
     113      <Jobnum>123123123</Jobnum>
     114      <DateOrdered>20-04-2011</DateOrdered>
     115      <Description>fghfgh ghf ghsghsfghs ghsg.</Description>
     116    </Job>
     117    <Job>
     118      <Jobnum>123123124</Jobnum>
     119      <DateOrdered>21-04-2011</DateOrdered>
     120      <Description>fghfgh ghfdfgdfgdfg ghsghsfghs ghsg.</Description>
     121    </Job>
     122    <!-- And so on for many more items -->
     123  </JobsList>
     124</Response>
     125
     126}}}
     127
     128
     129This 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.
     130
     131
     132{{{#!xml
     133<?xml version="1.0" encoding="utf-8"?>
     134<Response>
     135  <status errorid="0">Operation successful.</status>
     136  <SecurityString>98d1edad3280ce6db674bc475a5d5921</SecurityString>
     137  <DetailedJob>
     138    <JobDetails>
     139      <DateCreated>04/18/2011 19:26:56</DateCreated>
     140      <JobNum>181526</JobNum>
     141      <Description>printed full colour to one side ribex 2011 exhibitor pass - authorised helmsman</Description>
     142      <Name>Flyers Recycled Silk (standard)</Name>
     143      <Material>350gsm Silk</Material>
     144      <Quantity>250</Quantity>
     145      <Size>55mm x 85mm</Size>
     146      <Option>None</Option>
     147      <CountOfSides>1</CountOfSides>
     148      <netPrice>97</netPrice>
     149      <vatRate>20</vatRate>
     150      <vatAmount>19.4</vatAmount>
     151      <grossPrice>116.4</grossPrice>
     152    </JobDetails>
     153    <DeliveryAddress>
     154      <CompanyName>the corner shop</CompanyName>
     155      <Address>the big corner</Address>
     156      <Address2>End street</Address2>
     157      <Address3></Address3>
     158      <TownCity>middleton</TownCity>
     159      <County>yorkshire</County>
     160      <Postcode>DL34 666</Postcode>
     161      <TypeofBuilding>Sales-frontage Shop</TypeofBuilding>
     162    </DeliveryAddress>
     163    <ImagesList>
     164      <Image type="thumb" url="https//payment.solopress.com/?/media/$orderid/30x34/BackPage.jpg" />
     165      <Image type="thumb" url="https//payment.solopress.com/?/media/$orderid/30x34/FrontPage.jpg" />
     166      <Image type="preview" url="https//payment.solopress.com/?/media/$orderid/1024x800/BackPage.jpg" />
     167      <Image type="preview" url="https//payment.solopress.com/?/media/$orderid/1024x800/frontPage.jpg" />
     168      <Image type="thumb" url="https//payment.solopress.com/?/media/$orderid/30x34/1/MiddleContent.pdf" />
     169      <Image type="thumb" url="https//payment.solopress.com/?/media/$orderid/30x34/2/MiddleContent.pdf" />
     170      <Image type="thumb" url="https//payment.solopress.com/?/media/$orderid/30x34/3/MiddleContent.pdf" />
     171      <Image type="preview" url="https//payment.solopress.com/?/media/$orderid/1024x800/1/MiddleContent.pdf" />
     172      <Image type="preview" url="https//payment.solopress.com/?/media/$orderid/1024x800/2/MiddleContent.pdf" />
     173      <Image type="preview" url="https//payment.solopress.com/?/media/$orderid/1024x800/3/MiddleContent.pdf" />
     174    </ImagesList>
     175  </DetailedJob>
     176</Response>
     177
     178}}}
     179
     180== Appendix: Testing Samples ==
     181==== Sample 1 :: View User ====
     182
     183POST soloPress/?/history/view/user/08e1278f3dabe1c333870db53cbb53fe/db=1
     184
     185{{{#!xml
     186<?xml version="1.0" encoding="utf-8"?>
     187<Request>
     188  <UserHistoricalJobs>
     189    <ID>8839</ID>
     190    <Results start="0" count="12" />
     191  </UserHistoricalJobs>
     192</Request>
     193}}}
     194
     195returns
     196
     197{{{#!xml
     198<?xml version="1.0" encoding="utf-8"?>
     199<Response>
     200  <status error-id="0">Operation successful</status>
     201  <security>34d91acea5f8ef4027c4292f860c6492</security>
     202  <UserAccount>
     203    <AccountType>To Pay</AccountType>
     204    <CompanyId>FMP4-2-144660120012-6856461-04342-121033975791616</CompanyId>
     205    <BillingAddress>
     206      <CompanyName>Miss Mille Haugnaess</CompanyName>
     207      <Address>36 ebor place</Address>
     208      <Address2></Address2>
     209      <Address3></Address3>
     210      <TownCity>leeds</TownCity>
     211      <County>west yorkshire</County>
     212      <Postcode>LS6 1NR</Postcode>
     213      <TypeofBuilding></TypeofBuilding>
     214    </BillingAddress>
     215  </UserAccount>
     216  <JobsList />
     217</Response>
     218}}}
     219
     220==== Sample 2 :: View Job. ====
     221
     222POST soloPress/?/history/view/job/3b255b54cbb8ca902bffeca71b7e2e38/db=1
     223
     224{{{#!xml
     225<?xml version="1.0" encoding="utf-8"?>
     226<Request>
     227<UserJob>
     228<Jobnum>181526</Jobnum>
     229</UserJob>
     230</Request>
     231}}}
     232returns (I have put line breaks in this even though the live version wont, so you may see the data better.) 
     233
     234{{{#!xml
     235<?xml version="1.0" encoding="utf-8"?>
     236<Response>
     237  <status error-id="0">Operation successful</status>
     238  <security>67a5d25e291575a2eec3db769767984d</security>
     239  <DetailedJob>
     240    <JobDetails>
     241      <DateCreated>04/18/2011 19:26:56</DateCreated>
     242      <JobNum>181526</JobNum>
     243      <Description>printed full colour to one side ribex 2011 exhibitor pass - authorised helmsman</Description>
     244      <Name>Flyers Recycled Silk (standard)</Name>
     245      <Material>350gsm Silk</Material>
     246      <Quantity>250</Quantity>
     247      <Size>55mm x 85mm</Size>
     248      <Option>None</Option>
     249      <CountOfSides>1</CountOfSides>
     250      <netPrice>97</netPrice>
     251      <vatRate>20</vatRate>
     252      <vatAmount>19.4</vatAmount>
     253      <grossPrice>116.4</grossPrice>
     254    </JobDetails>
     255    <DeliveryAddress>
     256      <Contact>Michaela Montgomery-Swan</Contact>
     257      <CompanyName>RIB International Ltd</CompanyName>
     258      <Address>Oyster House</Address>
     259      <Address2>Hunters Lodge</Address2>
     260      <TownCity>Kentisbeare</TownCity>
     261      <County>Devon</County>
     262      <Postcode>EX15 2DY</Postcode>
     263      <TypeofBuilding></TypeofBuilding>
     264    </DeliveryAddress>
     265    <ImagesList>
     266      <Image>
     267        <type>thumb</type>
     268        <url>solopress/?/media/181526/59x45/Back+Stage+Pass+2011.pdf</url>
     269      </Image>
     270      <Image>
     271        <type>preview</type>
     272        <url>solopress/?/media/181526/333x259/Back+Stage+Pass+2011.pdf</url>
     273      </Image>
     274      <Image>
     275        <type>thumb</type>
     276        <url>solopress/?/media/181526/59x45/Helmsman+Pass+2011.pdf</url>
     277      </Image>
     278      <Image>
     279        <type>preview</type>
     280        <url>solopress/?/media/181526/333x259/Helmsman+Pass+2011.pdf</url>
     281      </Image>
     282    </ImagesList>
     283  </DetailedJob>
     284</Response>
     285}}}
     286
     287==== Sample 3 :: View Image ====
     288
     289GET soloPress/?/media/181522/50/Back_NEW.jpg
     290
     291<binary response>
     292
     293GET soloPress/?/media/181522/thumb/Back_NEW.jpg
     294
     295<binary response>
     296
     297GET soloPress/?/media/181522/preview/2/BigDocument.pdf
     298
     299<binary response>
     300
     301
     302== Appendix: Error Codes ==
     303The process of building the hash is described in the previous section.
     304The error-id  will map to what FMP returns with the following additions:
     305
     306  * -13 :: "System error: Required subsystem not installed. Please inform administration."
     307  * -12 :: "Badly formed XML document received. Nothing done.",
     308  * -11 :: "Bad request, Unable to locate jobnum.",
     309  * -10 :: "Bad request, Unknown client id",
     310  * -8 ::"Bad request, Unable to locate jobnum.",
     311  * -7 :: "Bad request, unknown history action, try 'user' or 'jobs'.",
     312  * -6 :: "Bad request, unknown webform action requested, try 'order', 'quote', 'sample' or 'orderitem'.",
     313  * -5 :: "System failure: Unknown dB action, no activity possible.",
     314  * -4 :: Unable to connect to the dB.
     315  * -3 :: Security hash mis-match.
     316  * -2 :: Incomplete post, missing data. 
     317  * -1 :: Unknown error (the error mapping is missing an entry). This is the default, case, but
     318  *:      you are never likely to see it.
     319  * 0  :: Operation successful
     320 
     321The status text is a textual rendering on the error-id.
     322In the gross majority of cases, the value returned will be 0.
     323
     324== Appendix: Idempotency ==
     325
     326As noted above the request is signed as an addition to the end of the request URL.
     327The response is signed via a XML element, as the rest of the document is XML. 
     328
     329basic response:
     330
     331{{{#!xml
     332<?xml version"1.0" encoding="utf-8" ?>
     333<Response>
     334  <security>98d1edad3280ce6db674bc475a5d5921</security>
     335  <status errorid="0" >Operation successful.</status>
     336</Response>
     337}}}
     338
     339Firstly, 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.
     340
     341The request hash is included in the response hash, to demonstrate that the message came from the party to which you sent the initial request.
     342
     343
     344Therefore in total the security hash looks like this:
     345
     346'+' is a string concatination
     347
     348!SharedSecret = '*********';
     349
     350The !SharedSecret is specific to integration between !SilkStream and Matatiro Solutions work for soloPress.
     351
     352!RequestHash = md5(!WebCustomerID + !WebOrderNumber + !SharedSecret + '')
     353
     354!ResponseHash =md5(!WebCustomerID + !WebOrderNumber + !SharedSecret + !RequestHash)
     355
     356 
     357== Installation Requirements ==
     358To receive the XML in a non mangled fashion, from a POST body, I need
     359
     360<code conf>
     361always_populate_raw_post_data = 1
     362</conf>
     363adding to the php.ini
     364
     365Please note in PHP 5 the location of the config file is best looked up via phpinfo(), you may have several different
     366 config files on your system.
     367
     368To make the image scaling software feature available, it is necessary to install ImageMagick, and the dependant link
     369 library Ghostscript.   These sources are listed following, and include simple steps for installation.
     370There may be no action necessary if Steve Winter has done the installation
     371
     372To make this operational, there are changes to the interface FMP file (web_interfacev2) and the new PHP files (msxml,
     373solopresscommon, history, webform and media).  There have been changes to config, index and helper files.
     374
     375For a ramp up process I would like to use lots of logging, so we may react to unforseen events better.
     376As such, may I have a '/var/log/apache2/images/' directory, with write permissions for the webserver user.
     377
     378Please ensure the webserver account has read and directory access for all the images directories.
     379
     380  * http://imagemagick.org/script/binary-releases.php
     381  * http://pecl.php.net/package/imagick - the PHP integration
     382  * http://www.francodacosta.com/phmagick/download
     383  * http://mac.softpedia.com/get/System-Utilities/GPL-Ghostscript.shtml
     384 
     385To get things working on a windows box
     386  http://www.imagemagick.org/script/install-source.php
     387  There may be a binary release, i wasn't sure if "foreign" operating systems where supported.
     388  This is a UNIX project.
     389  http://sourceforge.net/projects/ghostscript/
     390 
     391