history-docs – Solopress FileMaker support

Context Navigation

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

httpspayment.solopress.com/?/

The additions are

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 version="1.0" encoding="utf-8"?>
<Request>
  <UserHistoricalJobs>
    <ID>FMP-346534-53453-345345-34534-5345</ID>
    <Results start="0" count="12" />
  </UserHistoricalJobs>
</Request>

<?xml version="1.0" encoding="utf-8"?>
<Request>
  <UserHistoricalJobs>
    <ID>1234</ID>
    <Results start="12" count="12" />
  </UserHistoricalJobs>
</Request>

<?xml version="1.0" encoding="utf-8"?>
<Request>
  <UserHistoricalJobs>
    <ID>1234</ID>
    <Results start="24" count="48" />
  </UserHistoricalJobs>
</Request>

<?xml version="1.0" encoding="utf-8"?>
<Request>
  <UserJob>
    <Jobnum>125534</Jobnum>
    <PreviewSize>800</PreviewSize>
  </UserJob>
</Request>

<?xml version="1.0" encoding="utf-8"?>
<Request>
  <UserJob>
    <Jobnum>125534</Jobnum>
  </UserJob>
</Request>

XML responses

<?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 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 version="1.0" encoding="utf-8"?>
<Request>
  <UserHistoricalJobs>
    <ID>8839</ID>
    <Results start="0" count="12" />
  </UserHistoricalJobs>
</Request>

returns

<?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 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 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

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

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

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 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.

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/

Last modified 7 years ago Last modified on Jul 10, 2018, 8:45:31 AM

Download in other formats:

Plain Text