The following is a tutorial I wrote way back in 2006 as a way of introducing new members of our team (in a former job) to the hateful task of creating and modifying templates for VSI Fax. Putting it up here for preservation more than anything!
If the task has fallen upon you to become the next in a long line of AS noob’s whose duty, nay life’s meaning, it is to create, modify and hack VSIFax documents then I present to you, the chosen one, the (probably not) definitive guide on how to go about this turgid task with as much expididity as is possible.
Firstly you need to establish what the customer wants form their new document or what they want changing or moving where on an existing document. As of writing the call loggers do a pretty good job of putting this in the call details but should the quality ever fall off the best thing to do is to get an example of their printed stationary and ask if that’s how they want it. If they don’t want it like their printed stationary ask them if there are any companies documents they do like, chances are that you have them as the nuts and bolts world is fairly insular and OGL has most of them over a barrel. Once you know what they want you can get down to the delightful job of actually editing the things in Word 2000 on a Win98 PC, this is how it is now and how it shall ever always be, amen.
Situation 1 – The Customer wants a new document
In this situation we will take the example of a company currently using VSIFax frequently who have found they need a Purchase Order (PO) document. The best thing to do is look through the “local fax docs” folder on the 98 PC or get an archive from oglsoft that may contain a PO doc. They are located in
and are tar archives that have often been tar’d many many times. Copy the file over to the 98 box using something like WinSCP and extract it using the tools on the 98 box (7zip at time or writing). As soon as you have a PO document from another company it would be best to get all of the current documents that exist for the company you are creating the document for onto the 98 box and into a folder of their very own. This way you can see what type of docs they currently have and can locate a PO document comparable to their style. Getting these documents also gives you the advantage of being able to copy over such items as logos and address text boxes easily and therefore matching the style of the current documents. You should be able to edit the document without too much trouble, the one piece of advice I have for you is always use text boxes, don’t type text directly on to the page as it will make layout changes nigh on impossible. So once we have our completed PO document in Word we need to get it approved by the customer, just print it out and fax it to them with a cover sheet explaining what you have done. Once approved you should print the document again using the “VSI Docs” printer, this prints to file and produces a pure PCL document. Make sure you select the type of file to be “all files *” and give the document a name in the same scheme as the existing files i.e. if their invoice file is companyin.pcl then call it companypo.pcl. Make sure the file has the .pcl extension as this helps differentiate the different file types as we progress. Once we have the PCL document we need to move it to oglsoft via WinSCP again then get a shell on oglsoft. The next step is to convert the PCL file to a useable little-endian TIFF File using VSIFax’s pcltotiff script. If your teammates have been prudent enough to furnish you with a good .bashrc file then you should be able to type “v companypo.pcl” and you’ll get a useable TIFF. If you get “v: command not found” then you can get a copy of my .bashrc off this board or type the actual command that it is aliased to: /usr/vsifax3/lbin/pcltotif -EFine. Before you go about implementing this document you should get it back over to the 98 box and open it up in image viewer to make sure it looks right. The VSIFax “pcltotiff” script has a nasty habit of cutting off the left edge of documents when it converts them, if you see that this has happened you will need to move the documents margins until it no longer gets cut-off. Pay special attention to the right edge when doing this as if you move it too much pcltotiff will start cutting that edge off too. If this starts to happen you may have to start changing column widths which is not a fun task but is very occasionally necessary. Assuming all is OK with the document it is now time to implement it, get linked up then follow the below section “Implementation is not for chumps”
Situation 2 – Changes across all documents
Oftentimes a customer will change their address, website, phone/fax numbers, name or a multitude of other details that they want amending on their VSIFax documents. These are (normally) the most favorable and preferred kind of VSIFax calls that come in as they tend to involve small changes across all docs. It can sometimes get a little difficult if the customer wants additional information adding to all documents and there is not a space in the same location on all docs. In this situation produce several examples and fax them to the customer for them to decide and consult the customer heavily on what they want. It also may be worth talking to Mick (PS) about it as if it is a small amount of text like a company registration number it is possible that the software could do it and the documents won’t need amending at all. But let’s take the example of an address change. First have a look at all the documents and see if the address is laid out in a unified way, if they are then modify the address on one document then delete the text box containing the address on the other documents and copy and paste the text box containing the new address over to the other documents. That’s it, just follow the instructions for printing and converting the document as in situation 1 and you can implement the document (see below). If the address is laid out differently on each document then you may want to see if there is a way to standardize it (this is often impossible due to the layout of the doc or the opinion of the customer). If you can’t standardize the layout then you’ll just have to modify the details on all the docs by hand.
Situation 3 – Changing a single document
While you may be thinking that this is just the same as changing all the docs I can assure you that modifications to individual documents tend to be more involved and specific than changes to multiple documents involving small global changes. Often the customer will want columns moving around, box labels/sizes changing and lots of other seemingly small modifications that can take a long time to do. My number one piece of advice for this type of call is get too much information and too many examples from the customer, you can never have enough information when going in to this type of call, also fax them regular updates to make sure that you have understood (or more likely that they have articulated) the change they want correctly. When modifying column layout you will notice that there tend to be four layers of text/graphics that you need to manipulate this is where using Word’s rather flawed layering feature tends to be useful. If you are finding that you can’t edit a column header graphic because you keep selecting the text layer, send the text layer to the back, you can always send all the other layers to the back to get the text layer back to the front again (that seemed really confusingly obfuscated when writing but when doing it I’m sure you’ll get it!). Another technique is always using the keyboard to move an item, be it text or graphics, as they keyboard will move it in unified amounts whereas the mouse is imprecise and can lead to layout nightmares. Once you have changed the document to the customers liking, follow the guide to creating a usable document as found in Situation 1 followed by the below guide on implementation.
Situation 4 – Cover sheets
Cover sheets tend to be the easiest of the documents as they contain few graphics and are actually a different type of document than all the others. Most cover sheets will only need details like logos and contact details amending. You will find yourself editing them somewhat frequently however as detail changes tend to be frequent. After you are done changing all you need to on the document you need to print it using the “Cover Sheets” printer which produces a pure postscript file, consequently you should call it “whatevercompanyco.ps” That tends to be it with the cover sheets, you are done. There is, however, a frequent issue that occurs with cover pages. You will sometimes find that the cover sheet will print all the comment lines correctly except one where it will have something like “FXMESS” This has happened because the driver did not produce the postscript correctly and you need to either reprint the document or edit the postscript manually and remove the malformed block. A correctly formatted block looks like this:
(FXMESSAGE01)S ^M ; : 234 1747 2071 1373 rc 0 0 0 sco F3_50^M Ji ^M 564 1747 M ^M ( )S ^M ; : 234 1747 2071 1373 rc 0 0 0 sco F3_50^M Ji ^M 234 1797 M ^M
A badly formed block will look like this:
(FXMESS)S ^M ; : 234 1747 2071 1373 rc 0 0 0 sco F3_50^M Ji ^M 564 1747 M ^M ( )S ^M ; : 234 1747 2071 1373 rc 0 0 0 sco F3_50^M Ji ^M 234 1797 M ^M > (AGE01)S ^M > ; : 234 1747 2071 1373 rc 0 0 0 sco F3_50^M > Ji ^M > 564 1747 M ^M > ( )S ^M > ; : 234 1747 2071 1373 rc 0 0 0 sco F3_50^M > Ji ^M > 234 1797 M ^M
Notice how the first line of the block is truncated and there is a duplicate block that begins with the truncated part of the “FXMESSAGE” tag. All you need to do is delete one of these blocks and fill in the munged part of the FXMESSAGE01 tag. In the above example the lines with the preceding “>” characters are the ones that I would remove but you can remove either block. All you need to do is then save the file and you’re done. Congratulations you can now implement the document.
Implementation is not for chumps
So you’ve created your documents, they are all nicely bundled together in a folder on oglsoft so how do we get them to the customer’s server and once they’re there what do we do with them? Firstly it is best to get your docs into a compressed tar file, I prefer bz2 compression but if you’d rather gzip you can, it’s up to you. All you need is the tif and ps documents so issue a command like this:
tar cvf companydocs.tar *.tif *.ps bzip2 companydocs.tar
You should now have a file called “companydocs.tar.bz2” obviously replace the word company with the name of the company you are doing the work for. Now you have the file you are going to transfer it is time to get linked up. There are, currently, 3 ways in which we link to sites that use VSIFax; SSH, PPP and CU. The link script is often used to get on to SSH and PPP sites so you will need to either just type “link companyname” to get on via SSH or get the customer to link the modem then do the same. Either way you need the same bit of information; the customer’s IP. For SSH customers it will be an external IP and you will copy the file over in the following way.
SCPing files to customers:
The format of this command is:
scp FILE USER@IPADDRESS:/PATH/TO/WHERE/YOU/WANT/FILE -- e.g. -- scp companydocs.tar.bz2 email@example.com:/tmp
To get the file over to a PPP customer (sometimes referred to as telnet customers) you need their PPP IP which is attainable by getting them to link then typing “link customername” you will then get some output like this:
PING 10.13.45.250: 56 data bytes 64 bytes from pinstructure.customers.ogl.co.uk(10.13.45.250): icmp_seq=0 ttl=62 time=303.473 ms 64 bytes from pinstructure.customers.ogl.co.uk(10.13.45.250): icmp_seq=1 ttl=62 time= 303.655 ms
The highlighted IP address is the one you need. We then need to ftp to this IP as in the following:
FTPing files to customers:
The sections highlighted in purple approximate what you will see, the UPPERCASE sections are what you need to type
ftp IPADDRESS Connected to CUSTOMER. 220 CUSTOMER FTP server (Version wu-2.6.2(1) Fri Feb 22 16:34:38 EST 2002) ready. 530 Please login with USER and PASS. Name (CUSTOMER:admin):root 331 Password required for root. Password:password 230 User root logged in. Remote system type is UNIX. Using binary mode to transfer files. ftp-> put /home/yourusername/companydocs.tar.bz2 /tmp/companydocs.tar.bz2 local: /home/yourusername/companydocs.tar.bz2 remote: /tmp/companydocs.tar.bz2 200 PORT command successful. 150 Opening BINARY mode data connection for /tmp/deanwooden.zip. 226 Transfer complete. 4451 bytes sent in 0.0067 seconds (6.5e+02 Kbytes/s) ftp-> quit
The last way to get files over to a customers box is a little antiquated and is only used when getting files over to a Unix box to which either we dial or we link via cu (giving a line number and connecting up via, for example, modem9).
Getting files over with cu:
We need to prepare the file initially as it is going to go over a link that can only handle transferring “uuencoded” files. So we need to uuencode our file like so:
The format is:
uuencode INPUTFILENAME OUTPUTFILENAME > FILENAME.UUE
uuencode customerdocs.tar.bz2 customerdocs.tar.bz2 > customerdocs.uue
Once we have this file link up, login, then type:
~% (tilde and percent: shift+#+4)
You’ll then get the following line of output, type the red text :
oglsoft:%put /home/username/companydocs.uue /tmp/companydocs.uue
Make sure you type it exactly right first time or you’ll get errors, there is no error checking with this method of transfer meaning that any noise on the line or slight drop in connection may result in corruption. You will get an output of numbers until it is done at which point it will return you to the command prompt. The final step is to uudecode the file with a command like this:
uudecode FILENAME > OUTPUTFILENAME
uudecode customerdocs.uue > customerdocs.tar.bz2
Once decoded the file should be a regular old bzipped tar again. Move onto the next step.
Now we have our bzipped tar on the customers server in /tmp I find it is good to create a temporary working directory called fax and to move the file into this directory:
mkdir fax mv customerdocs.tar.bz2 fax cd fax pwd /tmp/fax
Then extract the archive:
On newer Linux systems (post about RH7.2):
tar xvjf customerdocs.tar.bz2
on older systems:
bunzip2 customerdocs.tar.bz2 tar xvf customerdocs.tar
We will now have our created tif’s and ps’s in the /tmp/fax directory. cd into the directory where live VSIFax documents are kept:
then backup the existing VSIFax documents:
mkdir old cp *.tif old cp *.ps old
then copy over the new document(s)
cp /tmp/fax/*.tif .
change permissions on the file:
chmod 777 *.tif
it is also a good idea to change the ownership of the file to the vsifax user/group:
chown vsifax:vsifax *.tif
This should now be working. It is best to mention that if there has been a significant layout change the call should be passed to PS to modify the print tabs, otherwise contact the customer and advise that it is done!
Whew, that took longer than expected. Have fun and remember that the newest member of AS is always the VSIFax stooge 😉