Purchase Inwards Goods Journal

  • Workflow Page
  • Workflow Rules Overview
  • Workflow Rules Details Page
  • View Page
  • View Overview
  • Defining a SapphireOne View Area
  • Using a SapphireOne View Area
  • SapphireOne View Form Events  
  • Converting SapphireOne View Documents  
  • SapphireOne View Database References
  • Project Method References  
  • Field References  
  • Purchase Inwards Goods Journal Overview

    Purchase Inwards Goods Journal is an essential requirement for warehouse logistics inventory management. The main purpose of an Inwards Goods Transaction is to allow goods to be receipted into stock before the final paperwork has arrived. More often that not, the receipting of inventory is processed before the finalised Vendor Invoice has arrived. Warehouse and logistics management will typically arrive stock from a delivery docket. It is essential that these goods are physically receipted and are available for immediate dispatch or manufacturing to the client. These inwards goods inventory items can be arrived at an estimated cost, and when finally receipted an Inwards Goods Journal will be created automatically, reversing the estimated or average cost and replacing it with the final arrived cost. This may include on-costs such as freight, insurance, tax and duties. Inwards goods supports the consolidation and receipting of stock across multiple purchase orders in one delivery.

    Purchase Inwards Goods Journal (PGJ) is the third item in the SapphireOne Inventory Purchases Data Entry menu. This function allows the user to receive goods into inventory stock before the final paperwork has arrived. SapphireOne’s Inwards Goods functionality compares the actual quantity delivered with the consignment/delivery note or EDI record (Electronic Data Interchange) and helps to identify if the delivery matches from a commercial point of view. SapphireOne’s Inwards Goods function allows for quick and easy checking, and in doing so keeps the tight schedule of the logistics and warehouse department running smoothly. In addition, errors made when recording the larger quantities of counted inventory are eliminated. This process saves time and money and improves the productivity within the business.

    There are two main steps in the processing of a Purchase Inwards Goods Journal transaction. These are:

    1. Once the Purchase Inwards Goods Journal transaction is saved with , the arrived inventory items contained in it are immediately available for use. The financial component of the Vendor Order, now a Purchase Inwards Goods Journal transaction, is stored in a General Ledger inventory suspense account.
    2. When the Purchase Inwards Goods Journal transaction is Posted, the financial values are then written to your Inventory Asset General Ledger accounts.

    Purchase Inwards Goods Journal Operation

    When creating a new Purchase Inwards Goods Journal (PGJ) for purchasing, by entering the Vendor ID you will be presented with a list of all available current Order Vendor Invoices (OVIs) for this Vendor. You will be able to select a particular order which will automatically populate the Order Vendor Invoice data and allocate all lines from the OVI into the Inwards Goods Journal. 

    Two General Ledger accounts are required to be established before creating a Purchase Inwards Goods Journal.

    1. A suspense account to hold the value of all Inwards Goods transactions while they are held in the Purchase Inwards Goods Journal function before they are transferred to your General Ledger accounts.
    2. A General Ledger account to hold any variations between the Inwards Goods values and the Invoice when it arrives. For example, an FX profit and loss account.

    Any Inwards Goods transaction must be linked to a Vendor Order, and there are two methods of doing this:

    1. Enter the Vendor ID or do a search using the ‘@’ or ‘?’ symbols. SapphireOne will display a list of all Vendors with available orders in SapphireOne. By selecting the correct Vendor you will be presented with a new screen which will now have a list of all available OVIs. Select the correct OVI in order to populate all the transaction lines within the PGJ.
    2. In the Tracking Area, enter the exact Order Number or the External Reference number into the Purchase Inwards Goods Journal transaction. You can search for the Order Number by entering the ‘@’ or ‘?’ symbols and selecting the correct order. SapphireOne will then populate the Purchase Inwards Goods Journal transaction with all Vendor order details. 

    How to Save a Purchase Inwards Goods Journal Transaction

    There are two outcomes when saving a Purchase Inwards Goods Journal Transaction with the green tick icon  

    1. When a Purchase Inwards Goods Journal transaction is created from an Order that is complete with all items listed as arrived, SapphireOne will store all of the inventory stock within the Purchase Inwards Goods Journal transaction. It will then delete the original Vendor Order.
    2. If the order is incomplete, not all items have arrived, SapphireOne will proceed as follows:
      • The original Vendor Order will be re-written with the reduced Inventory quantities that have not arrived yet, and save it.
      • The arrived stock is now moved to the new Purchase Inwards Goods Journal transaction and saved. Once saved, Inventory items within it may then may be processed immediately through to sales as with other items in your inventory.

    The new stock in a Purchase Inwards Goods Journal transaction is usually sold on as based on the Last Cost or Average Cost for the Inventory items.

    Posting the Purchase Inwards Goods Transaction using the Arrivals function

    This is not necessary if the Auto Post checkbox is selected in Master Defaults.

    The Invoice or costs have arrived so the following procedure is followed. It is important to note, a second PGJ will be created that is an exact reversal of this one when the shipment has arrived using the Arrival function.

    Note that the new Purchase Inwards Goods Journal Transaction has the same Order number/internal reference numbers of the original order which has been deleted as all or part of the order has been transferred into the Purchase Inwards Goods Journal Transaction. Remember that Inventory stock levels are updated at this point.

    Open up the un-posted Purchase Inwards Goods Journal transactions and enter in the actual cost into each transaction.

    • Then post these transactions. SapphireOne will move the values from the suspense General Ledger account through to your normal General Ledger accounts.
    • Any variation in the cost that you have just entered will be sent to the plus or minus general Ledger account that has been created to hold these values. Your account will be best placed to work out how to manage these profit and Loss account.
    • At the same time a Purchase order will be raised in the same manner as when converting an Order directly to a Purchase in Inventory mode.

    Details Page in Purchase Inwards Goods Journal

    Details Area

    • Vendor ID – Is a linked field and if the user can selects the Wildcard @ symbol SapphireOne will display a list of Vendor orders in SapphireOne for the user to select from. If there are a lot of Orders in SapphireOne this could be a very long list!
    • Contact – Accept the default contact person or select the contact person you wish to attach to this vendor invoice.
    • Address – This field is the mailing address which automatically populates from the vendor record.
    • Delivery address from defaults – If you have alternative delivery addresses saved in the vendor address page you can select them from a drop-down list.
    • Copy Mailing address to the delivery address – Copy the mailing address to the delivery address field using the .
    • Document Paperclip – Scan and attach any documents relating to the Purchase Inwards Goods.

    If you attempt to create a Purchase Inwards Goods Journal for a Vendor Order that has already been partly processed, and it had not all arrived at the time of creating the initial Purchase Inwards Goods Journal transaction, SapphireOne will only display the quantity remaining in the Vendor Order as it was re-written when the earlier Purchase Inwards Goods Journal transaction was processed.

    SapphireOne Document Management System (DMS) includes a Paper Clip icon on all data entry and inquiry screens and allows users to attach relevant documents or files to every transaction or record. Additionally, every data entry and inquiry screen within SapphireOne also contains a separate Page specifically for managing documents related to the transaction i.e. version control.

    The red colour of the paper clip indicates that there are currently no documents attached to this transaction. When a document has been attached, the paperclip will turn green and the word Items will be prefixed by the number of documents currently attached to this transaction or record.

    SapphireOne Document Management functionality can store any type of file or document, and an infinite number of documents may be stored for an unlimited amount of time. Examples of types of documents include Adobe Acrobat, Spreadsheet Documents, Word Processor Documents, Photo Files, JPEG, CSV, HEIF, MP4 files.

    Within SapphireOne Master Defaults, there are settings available for the user to restrict the size of each individual document, and also to select where the documents are to be stored – within the data file itself or in a seperate folder. These options may be altered by going to Utilities > Controls > Master Defaults > System Page. Within the Documents area in the right hand corner of SapphireOne Page, there is a provision for the user to set the ‘Document Size Limit’ (the default size is 10Mb). There are also two radio buttons where the user can select ‘Store with Data File’ as part of the data file, and ‘Store as Files’ seperate to the data file.

    To attach a document to a transaction, select either the or Paperclip icon and the following Document List window will be displayed.

    How to Attach Documents Using SapphireOne Paperclip

    Documents can be attached using SapphireOne Drag & Drop functionality. To use this functionality, simply drag a document from the local computer into the Document List screen and it will append automatically. If SapphireOne detects that the document name already exists, a pop-up will be displayed alerting the user. Alternatively, the user can also select the Plus icon to select a document to upload from the local computer.

    Once a document has been attached, the user has the ability to rename any document by right clicking on the file and selecting Rename as seen above. Renaming documents will ensure that document names remain consistent across all records.

    Documents Area within Document Management System (DMS)
    • Open – When the button is selected, SapphireOne will open the currently selected document for viewing.
    • Update – When the button is selected, SapphireOne will display a pop-up which asks the user if they want to Import a New Version of the currently highlighted document. This functionality allows users to update and keep records of different versions of the same document. When the new version has been selected, the user will be asked to enter in a new version number. The new version will now be the document available, and all previous versions will be recorded and available within the History area of Document List screen. The new version of the document will still be linked to any transactions that the old version was.
    • Scan – When the Scan button is selected, SapphireOne will access a local or network scanner, and following the usual prompts allows the user to scan a document directly into the data file and link it to the transaction. The appropriate scanner with software must be installed on the local machine or network.
    • Save – The Save button allows the user to save the currently highlighted document to the disk.
    • Link Documents – The Link Document button allows the user to link the currently highlighted document to another transaction or multiple transactions in the data file. A pop-up will be displayed allowing the user to make their selection. You can learn more about Linked Documents in the Links Area documented below.
    • Link Existing Documents – The Link Existing Documents button allows the user to link an existing document in the data file to this transaction or record. A pop-up will be displayed allowing the user to make their selection from a list of documents. You can learn more about Linked Documents in the Links Area documented below.
    • Delete – The Delete button when selected will delete the currently highlighted document.
    • Plus – When the Plus button is selected SapphireOne will display a search function allowing the user to select a document that is currently on the local computer.

    Details Area within Document Management System (DMS)

    When a document is selected within the Documents area, the Details area will automatically populate to display additional information about the document, including the Title of the document and the Type of file.

    Notes Area within Document Management System (DMS)

    The Notes area is for entering any notes related to the document. The user can select the green clock icon to create a time and date stamp for every note added.

    The Notes area will also keep an automatic user log when any changes are made to the document. For example, if the document is renamed or new links are created. SapphireOne will record the date, time and user that made the modifications.

    Document Details Area within Document Management System (DMS)

    The Document Details area contains additional information relating to the selected document, and will automatically populate when a document is selected from the list. This includes the date and time the document was appended, the document number and the user who added the document.

    History Area within Document Management System (DMS)

    The History area displays a record of the complete version history of the selected document. SapphireOne keeps track of all version changes and will automatically display the documents history within this area.

    The History area will automatically update as new versions of the document are imported when selecting the Update button  . When a new document version is imported, all previous versions of the document will be recorded and available to view within the History area. This enables the user to always view the most recently updated version of the document, however still keep a complete record of the document history.

    The Links area is used to link documents to particular areas or transactions within SapphireOne. The links area can also be used to view all linking information related to the document. For example, if the document was imported using a function with SapphireOne, the links area will have a line containing this linking information.

    To add in additional links to a document, select the document and then select the Link Document icon. The Files pop up window will be displayed. From the File drop down menu, select what you want to link this document to. Then within the Value data entry field, enter in the details (ID). As this data entry field has a blue background, it is user searchable by entering the wildcard ‘?’ or ‘@’ symbols. 

    Updating a Document within Document Management

    The procedure for updating a document is as follows.

    1. When the update button is selected the user will be asked to confirm they would like to import a new version.
    2. Upon confirmation the user will then be asked to choose the updated document to open.
    3. Upon selection a secondary dialogue will prompt the user for the entry of an alphanumeric value for the new version.
    4. Select OK.

    Document Management using SapphireOne Documents Inquiry

    As well as SapphireOne Document Management Paperclip functionality, SapphireOne Documents Inquiry function within SapphireOne Workbook Mode gives users the ability to view a repository of all documents and files stored within the SapphireOne data file. Users have the ability to add New documents, Modify, View or Delete existing documents from within the Documents Inquiry screen.

    Any revisions made to a document within the Documents Inquiry screen will be updated across all areas that the document is linked to across SapphireOne, and similarly any modifications made to documents within the SapphireOne Paperclip Document List window will be reflected within the Documents Inquiry window. For example, if a document is renamed within a transaction Paperclip Document List screen, the document name will also be reflected when viewing the document in the Document Inquiry screen.

    You can learn more about SapphireOne Documents Inquiry functionality within the Documents Inquiry article.

    Document Control within Document Management

    As an example, we have an inventory item with documents attached (installation instructions and a packing checklist amongst others). We add this inventory item to a sales order, manufacture, ship, completely finish the job. One year later we might have a revision of this inventory item along with all the Documents (DMS). Understandably, we don’t want to have to make a whole new inventory item for the revision, just update the DMS that are attached. We update the inventory item with all the new documents, ready for the next sale. When we refer back to the original completed Sales Client Invoice or Job Projects Client Invoice, we will we see the documentation as it was when the Job Project, Sales Client Invoice or Job Projects Client Invoice was completed, or the documents as they are now. In the example above where we have elected to produce an Order Client Invoice (OCI) with the current installation instructions and packing checklist. This will automatically flow into the finished Sales Client Invoice once the OCI has been delivered.

    In the example above we have both the current and historical documents attached. As a SapphireOne user has the ability to edit the list and if they choose not to store the historical document and simply select the Minus button and they can delete the historical document. We also have the ability to modify the existing dociument keeping a log file of each and every time the document has been revised.

    How to arrive the PGJ

    1. Select the arrivals function from the drop-down menu on the main toolbar.
    2. Select the appropriate PGJ and select the 100% column as seen below.
    3. Next select the Process button in the lower right-hand corner of the screen.
    4. The normal Print dialog pop up will be displayed.
    5. You will have to answer yes for the process to complete.
    6. Now note the two PGJ’s in the Transaction list.

    Note: both are now posted in SapphireOne default and the PGJ has been arrived.

    Finally, since the transaction has been posted, SapphireOne will create second General Ledger journal which cancels out the first journal.

    SapphireOne takes the available funds and stock and creates a normal PVI as seen below.

    It also auto posts the PVI immediately.

    Purchase Inwards Goods Journal – Splitting the Order
    • The only difference is that SapphireOne re-saves the OVI Order Vendor Invoice with reduced quantities.
    • Each time a PGJ is created for part of the order, two PGJ’s and one PVI are created.
    • Once SapphireOne determines all of the order has been converted to a final PGJ, only then will it delete the original Order Vendor Invoice OVI.

    Information Tab Area

    The Purchase Inwards Goods Journal Information Tab area is used to display extra information about the current entry. You have the ability to view the information here, not alter it. Click on the Information Tabs to select the details you would like displayed.

    • Vendor – Displays Vendor details including ABN, Total Owing, Credit Remaining, Owing + Unposted, Warning Message, Turnover, Credit terms, Product, last transaction date etc.
    • Invoice – Displays a list of recent invoices. A purchase invoice can be copied by using right click and select Copy Transaction.
      By selecting a historical transaction and then right mouse click you can: Copy Transaction, Copy Lines – Copy the relevant lines and by selecting Open In Inquiry this will open the selected transaction in the new inquiry screen.
    • Lines – When a transaction line is selected, this tab displays history of the Inventory item. Included in each transaction is the Qty ordered and Amount, Sequence N°, any Discount Code and percentage allocated, Date and Type.
      • Create Line – Is for creating a new line and Copy Pricing.
        Inventory – When a transaction line is selected, this tab displays inventory details such as available stock, stock on order, standard price, next arrival date, default vendor.
    • Pricing – When a transaction line is selected, this tab displays Pricebooks which apply to the item for this vendor.
    • Items – When a transaction line is selected, this tab displays additional inventory details.
    • Controls – This tab displays information about the transaction such as the date it was created and who created it.
    • Add/Deduct – This tab displays additions and deductions details.
    • Error Code – Displays any error code such as negative stock, batch error and period error.

    Tracking Details Area

    The Purchase Inwards Goods Journal Tracking Details area stores tracking details relating to the current Date, Delivery Date, Invoice No, Sales Rep and Carrier.

    • Date In – Is the date that this Order has been entered on SapphireOne (usually SapphireOne date).
    • Arrival – When converted from a Vendor Order (OVI) to a Vendor Purchase (PVI), the Arrival Date will automatically become the Date In for the PVI.
    • Order No – External reference number.
      Invoice No – Internal reference number and automatically generated.
    • Rep ID – Sales representative ID.
    • Period – Period matching the date, set in company controls.
      Auto Allocate to Project – Tick checkbox if you would like to automatically allocate to a specific project set up in Job Project mode.

    Transaction Lines Area

    • Inventory – Is a linked field and the user can use the Wildcard [( @ or ? ) and TAB ] option, or simply type part or all of the product name to search for the Inventory code.
    • Arrival – This is the number ordered minus the number on back ordered.
    • Rate – This is the Line Item default rate. You can enter in a new rate but note this is the rate excluding tax.
    • Discount – Enter any Discount percentage allocated.
      Tax code : You may accept the default code or enter in a new tax code.
    • Tax % – For Australia, USA, New Zealand and other countries, the Vendor Tax Code controls the rate. In Australia, the Inventory file will override on GST free or exempt items as required.
    • Tax Amount – This will automatically populate with the total amount of tax for each individual line.
    • Total – This is the total cost for each individual line item including any tax.
    • Arrival Ex-Tax – This is the cost before Tax.
      There are two locations within a Vendor Order where the Ex-Tax value is displayed. In the line entry area where it is displayed on a line by line basis, and in the totals area at the bottom of the screen as a value for the entire order. This is for users who are arriving orders and need to be able to view the Ex-Tax pricing within the Order.
    • Project – Is a linked field and the User can use the Wildcard [ (@ or ? ) and TAB ] option to search for the Project ID. SapphireOne will display the Project Name.
    • Don’t Print – Select Don’t Print to stop the line below from printing on the Invoice. The amount from this line is still included in the total value of the Invoice.
    • Tariff – The Tariff ID number will display in this field.
    • Duty – This is the Duty amount that may be either a fixed dollar amount or a percentage.
    • Duty % – Is the duty amount as a percentage.
    • On Cost Factor – The On Cost Factor is calculated as (Cost of Goods + On Costs) / Cost of Goods. This can be inserted manually or automatically populated.
    • Unit – Populates the unit details as set in the inventory item, for example Set, Each, Ctn, Kg, etc.
    • Ordered – Enter the quantity being ordered.
    • B/O – Enter the quantity to be backordered. For you to be able to access the backorder function, stock type will need to be set to Normal.
    • Weight/Area – This field displays the total weight or area x order quantity. The user may enter the total weight required which will automatically update the order quantity.
    • Carton – Displays the total cartons: quantity multiplied by the carton quantity set in Inventory details.
    • Pallet – Displays the pallet quantity: quantity multiplied by the pallet quantity set in Inventory details.
    • Final Cost – Is the Final Cost of Inventory ordered including Tariff, Duties and On Cost Factors.

    As you enter a transaction, a summary of the transaction appears in a single line. You can view or modify a line by selecting it, then proceed to view or modify in the data entry area above.

    All of the lines in the Transaction Lines area, are listed here. The list itself, only displays the basic details of each Line. You cannot directly edit from this list.
    To view or modify any line in this Line Listing area, select or highlight a line.
    All of the additional data entry fields will then be displayed for you immediately above the list of lines.
    From there the user is able to view or modify all of the data entry fields for the line as required.

    The easiest way to add a line is with the keyboard shortcut. Hold the  (Command or Control key down and select forward slash (/). SapphireOne will then place the cursor in the Account ID data entry field ready for the entry of a new line. Alternatively, selecting the button will also place the cursor in the Account ID data entry field, ready for the entry of a  new line.
    Lines may also be added to the transaction by clicking on the button or selecting the button to delete the currently highlighted line.

    The Purchase Inwards Goods Journal Transaction Footer is the information bar along the bottom of the screen, and allows the user to easily check the critical details of a transaction.

    • Sequence Number – Is the automatically generated unique Sequence number.
    • Batch – The Batch field shows the total for all orders entered in the current group.
    • Amount – Total Amount is the Tax free amount of the order.
    • Arr Ex-Tax – This is the cost before Tax.
    • Ordered Weight – Is the Total Weight of the Vendor Order.
    • Weight Area – Weight/Area is the total weight or area of all lines entered on the order.
    • Cartons – Is the calculated total quantity of Cartons.
    • Pallets – Is the calculated total quantity of Pallets.
    • Discount – This Discount box allows the user to apply an overall discount percentage to the order.
    • Tags – The user can select a saved Tag from this Drop down or add a custom tag. To add a new Tag category, type the name of new tag into the tag box on the screen and then hit the tab key. Then select ‘Yes’ from the pop-up window to confirm. Alternatively, if you wish to remove a Tag from the list, simply select the drop-down menu and click on the name of the Tag you wish to remove whilst simultaneously holding down the Command (MacOS) or Control (Windows) key. Then select ‘Yes’ from the pop-up window to confirm the deletion from your current list. 
    • Access to More Functions Button Zoom For Current Linked Record-Button
      • Export Lines – Export Lines allows the user to export the lines from any inventory or job project base transactions. This allows the user to export lines, then the client or vendor receives an email with a text file attachment, which they can then import into their SapphireOne ERP.
      • Discount – Allows for the generation of an overall discount on the transaction based on either a fixed dollar value or a percentage.
    • Zoom for Current Linked Record Button Zoom For Current Linked Record-Button – Clicking on the icon once minimises the header for a reduced screen view showing only transaction lines. The icon will then change to maximise, and by clicking on it again it will return the screen to the standard view.

    Action Page

    The Action Page is a separate table that can be added to the major records and transaction tables. This includes actionable items such as Calendar Reminders, Meeting Invites, Alarms, Emails, To-Do Lists, General Notes, Private Notes, Meeting Notes with Date and Time, Start and Finish stamps plus All Day Notifications.

    You can Add or Delete Actions . If you double click on an existing Action it will open, ready to be modified.

    • Diary Area
      • Sequence – SapphireOne will automatically enter in a unique sequence number.
      • Title – Enter in a title for this action.
      • Type – Use the user customisable drop down menu to enter in a type. This will then form a permanent type within the drop-down.
      • Action – Use the user customisable drop down menu to enter in an Action. This will then form a permanent action within the drop-down.
      • User – SapphireOne will enter in the user who is creating this action although, this may be altered if required.
      • Private – If this check box is selected SapphireOne will only allow the User as entered to view or modify this action.
      • Status – The user has three options.
        • Open – Action is open and active.
        • Hold – Action is active but no alarms will be active.
        • Completed – Action is now Inactive and will not be displayed in any list of actions.
      • Tag – A tag may be attached to an action. This will then form a permanent tag within the drop-down. To add a new Tag category, type the name of new tag into the tag box on the screen and then hit the tab key. Then select Yes from the pop-up window to confirm. Alternatively, if you wish to remove a Tag from the list, select the drop-down menu and click on the name of the Tag you wish to remove whilst simultaneously holding down the Command (MacOS) or Control (Windows) key. Then select Yes from the pop-up window to confirm the deletion from your current list. 
      • Link – When created from within a transaction or a record, a link to the transaction or record is automatically created by SapphireOne. When created from the Options Menu, Palette or Workbook, the user will have to select from the drop down menu if the action is to be linked to an item or function. There are 12 items on this list from Clients to Manager.
    • Check List area – A user created check list for creating actions. A check box is provided so that a user can selected them off as they progress.
    • Dates and Times Area:
      • Start/Finish – You can set an action to have a Start and a Finish time, or select the check box for an all Day option.
      • Completed – Once an action has a completed date entered it will no longer be active and displayed in any lists of actions.
    • Alarm Area – An alarm can be set to email someone at a certain date and time, or send your user a reminder and/or email if the email has been entered.
    • Recurring Area – If necessary the alarm may be set to at set periods established by the Type drop down menu. The recurring period may also be set by date if required.
    • Notes Area – You can select the Green clock icon to add Time and Date stamps to your notes. You can also highlight the text in the Notes area and right mouse click to customise the Font, Style, Colour and Background Colour to your preference.
    • Invite Attendees Area – You can invite multiple attendees to your event and keep track of if they have accepted or rejected your invite. These attendees can be notified by email if the email has been entered.

    Documents Page

    The Documents Page is used to store and record documents and information relating to data entry, transactions and master tables.

    Documents Area

    Any type of document can be attached to the Documents area. Examples of types of documents include Adobe Acrobat, Spreadsheet Documents, Word Processor Documents, Photo Files, JPEG, CSV, HEIF, MP4 files and more.

    Documents can be attached using Drag & Drop functionality. To use this functionality, simply drag a document or file from the local computer into the Document List screen and it will append automatically.

    Please note that when creating a new record in SapphireOne, you are unable to attach a document until the record has an entered ID.

    There are eight buttons and icons on the Document List screen. These are as follows:

    • When the button is selected SapphireOne will open the currently highlighted document for viewing. (The appropriate software must be installed on the local computer or device).
    • When the button is selected SapphireOne displays a popup which asks the user if they want to Import a New Version of the currently highlighted document. (The new version will still be linked to any transactions as was the old version).
    • When the Scan button is selected SapphireOne will access a scanner, and following the usual prompts allows the user to Scan a Document Directly into the data file and link it to this transaction. (The appropriate scanner with software must be installed on the local computer, device or network).
    • The Save button allows the user to save the currently highlighted document.
    • The Link Document button allows the user to link the currently highlighted document to other transaction or transactions in the data file. A popup will be displayed allowing the user to make their selection.
    • The Link Existing document button allows the user to link an existing document in the data file to this transaction or record. A popup will be displayed allowing the user to make their selection from a list of documents.
    • The Delete button when selected will delete the currently highlighted transaction or record.
    • When the Add button is selected SapphireOne will display a search function allowing the user to select a document that is currently on the local computer or device.

    Details Area

    The Title and Type of the document are displayed in the Details Area.

    Last Modified Area

    The documents area keeps a record of the Time and Date of when the document was last modified in addition to who initially added it.

    Workflow Page

    Workflow Rules Overview

    A Workflow Rule must be established before entering any transactions. The rule is written into the transaction itself upon entry and will remain even if the workflow rule applying to the transaction is deleted. If a workflow rule is altered and there are existing transactions that require the new workflow rule to be applied to them, they will have to be deleted and re-entered under the new Workflow rule.

    The Workflow Rules functionality enables the setting of workflow rules that will require the approval of a user, group of users, a level of users or the creator. SapphireOne has the ability to create workflow rules on any data entry type of transaction within SapphireOne. The data entry can then have any or multiples of the combination of the 12 workflow rules applied to it. For example, these include New Transactions, Modify Transaction, Deleted Transactions, Transaction Above a Particular Dollar ($) Value, Transaction Sales Under Average Cost, Transaction for Client Over Credit Limit, Transaction for Client on Credit Stop, Transaction Sales with Negative Stock, Leave Request, Tracking Notes, Bank Details and Sales under floor price.

    Each workflow rule can have a unique Title and Tag established by the user. Once the transaction type, as well as the rule trigger, has been established, the user has the ability to add unique notes to each workflow rule. The SapphireOne user then proceeds to the flow, which contains stages where the they have the ability to create unlimited stages. The workflow rule can have one stage or multiple stages, often they tend to be sequential. The user can set the amount of stages they require and within each stage they have the ability to set the number of people required to Approve or Notify a workflow rule before authorisation is granted.

    As an example, if you set five stages it will not progress to stage two until stage one has been approved. Within Stage 1 you may have 5 users authorised to approve Stage 1 but it will require a minimum of 3 out of the 5 users to Approve or Notify stage one before it can advance to Stage 2. This is referred to as levels within the stage. You may assign a group of people to a level and assigning a Type can be done either by User, Level or Creator. For each Type, the user also has three checkboxes which are Authorisation Required, Hierarchical Authorisation and Email notification.

    Another example, if you’ve established a workflow rule around Leave Requests, Stage One may be an employee entering a Leave Request. Stage One simply moves straight to Stage Two because that’s been established. Stage Two may then be that the manager is notified. Stage Three may then include the HR department approving the leave and Stage Four may be to the original creator i.e. the employee has an email notification that their leave has been approved or not approved.

    Initially these new transactions will have an error of WF for Workflow and cannot be printed, converted, emailed or posted until they are approved or authorised by the user or a group of users, level and/or creator. If they are rejected, the transactions will then remain in the list with a stratus of error indicating the continuing WF error.  They may then be left as they are and since they will remain un-posted or deleted as required. 

    For each rule with a Workflow entry there must be a user or group of users setup with a restriction where they will create all or some transactions with an error code of WF.

    There must also be a user or group of users set up to approve the transactions. The switch is the selection made from thetwo2 checkboxes, Authorisation Required or Hierarchical Authorisation.

    Workflow Rules Details Page

    Entering a New Workflow Rule

    The Change button seen in the screenshot below is directly linked to the Organisation Chart function on the Controls drop-down menu. The Organisation Chart function is simply a means to place a number of users in a hierarchical group. It is documented in a separate article on Organisation Chart.

    Details Area

    The available options are as follows.

    • Sequence – SapphireOne will enter a sequentially generated number and it may not be altered.
    • Title – Enter in a Name or Title for this workflow entry.
    • Tag – Enter in a Tag if required. Remember that this list of tags may be setup by the user as required.
    • Company – SaphireOne should enter the company but if it does not, enter the company.
    • Department – Enter a department if required. 
    • Transaction – Select from the from the extensive list of transactions when the blue arrow is selected. For every type of transaction the user may then setup individual rules as required.
    • Rules Trigger – Then select from the Rules Trigger list box, a rule that is to be applied. Once the selected rule is broken the workflow function will become active and activate the Workflow function.
      • Transactions – The first three rules will raise a WF error. If the user tries to Create a New Transaction, or Modify or delete a transaction.
      • Above $ – This option will raise a WF error when any transaction is over a specified dollar amount.
      • Average Cost – Any transactions under average cost will raise a WF error.
      • Credit Limit and Stop – These two options will raise a WF error when the conditions are met.
      • Negative stock – Any transaction that will take inventory into a negative stock level will also raise the WF error if this option is selected.
      • Leave Request –  If any user makes a leave request a WF will be displayed enabling the HR officer to be alerted.
      • Tracking Notes – This will generate a WF. This is used to to alert the user responsible for managing tracking notes.
      • Bank Details – This linked to SapphireOne’s G/L accounts that are bank accounts.
      • Floor Price – When this option is selected A WF error will be sent to the selected user allowing them to approve or disapprove the sale.
    • Stages – Next set the number of hierarchical stages that must be navigated before the WF error is removed. Each stage will occupy a column in each row in the flow list towards. If required up to 6 stages or levels of authorisation is provided for, although 6 levels would be challenging to manage. To simplify it, the entry of the number 3 here will setup up three columns in the flow area below with default headings and that is all.
    • Single Stage – If only a single level of approval is required leave the Stage set at 1 for a single level of approval. The flow area below will display just the single item across the entire row as seen to the right.
    • Multiple Stages – If more stages or levels are required enter in a number from 2 to 6. The additional stages will be added as additional columns in the flow area as seen to the right.
    • Notes – Any notes for this workflow rule may be entered here.

    Now that we have created a rule for a transaction we now have to select to how it is to be applied. We now enter into the Flow area the Users or the Level of users that the rule is to be applied to.

    Flow Area

    • New Button – To enter in a new event the following procedure must be followed.
      • Column or Stage Selection – The user must first select select the column and then select the button in the top right-hand corner of the Flow area. SapphireOne will place the word User in the column that was selected.
      • Multiple Stages – Repeat the procedures above for each column or stage in the work flow function. From now on once one of the stages in the line has been selected, it will alter to the orange colour as seen below.
    • Stage Selection – The user must now select each stage in sequence and for every stage set up the following details.
      • Stage – SapphireOne will add a suffix of the stage number to the name Stage. The user may then enter in a column heading name for the stage if required.
      • Type – The user has 2 choices here, Approve or Notify. If approve is selected the user will have to proceed through the approval process before the Work Flow error will be removed for them. If notify is selected the user will only have to open the transaction for viewing.
      • Number – The number entered here indicates the number of users that have to approve this transaction before the WF error is removed from the transaction. Zero means none and 5 means five. Be careful here as the default is usually not wanted so a number will have to be manually entered.

    Party Group

    For each stage this area sets up the users and what tasks they are to perform for this Work Flow function.

    • Type – This will determine how the workflow rule will be applied.
      • User – When this option is selected a data entry field will be displayed allowing the user to enter in a selected users ID linking the rule to a single selected user. Once a user ID has been selected SapphireOne will display the selected users ID.
      • Level – When this option is selected the Change button will be displayed. When it is selected SapphireOne will display the organisational chart allowing the user to select an organisational level for this rule to be applied to. Once a level has been selected SapphireOne will display the name of the level selected.
      • Creator –  When this option is selected, SapphireOne will allow the creator of the transaction to process the transaction.
    • Authorisation Required checkbox – This checkbox is crucial in relation to the Workflow Rules function. When selected, SapphireOne will enforce the WF error for the selection made in the Link radio buttons. If it is not selected SapphireOne will allow the user to create and save transactions as listed without a WF error as normal. However they will also receive the active message pop up dialog when there are transactions within SapphireOne created by other users that meet the criteria as set up in the Workflow rule.
      • Selected – Restricted saving of the selected transactions with WF error.
      • De-Selected – All transactions saved normally and permission to approve selected transactions.
    • Hierarchical Authorisation Checkbox – If this checkbox is selected, SapphireOne will allow anyone above the level that has been entered for the stage to authorise the transaction. 
    • Notes – Finally enter any notes for this workflow entry. 

    SapphireOne’s implementation of both Dictation (MacOS) and Speech to Text (Windows) is a game changer for data entry. Any data entry field you can type into using a keyboard can use this feature.

    You can also use this functionality on all inquiry screens within SapphireOne. For example, the user is in a Contact within a Client. They may have made a phone call to that particular client using the Softphone technology. Consequently, this will automatically date and time stamp both the contact and the phone number you called.

    As soon as the call is completed, the user has the ability to use Speech to Text (Windows) or Dictation (MacOS). They can dictate into the memo field of the CRM contact, adding as much description as they require.

    Dictation and Speech to Text Procedure

    This functionality applies across every single Data Entry screen. For example, the SapphireOne user is entering a Vendor Invoice (VI). Additionally, you may want to add a memo within the Vendor Invoice (VI). The user can utilise the tool and simply dictate the memo.

    Another example is if the user wants to add additional lines to the General Ledger account, within each General Ledger account. When the user is completing data entry using a General Ledger, there’s always a unique memo field for each GL account line. The user can then utilise this feature to quickly add the information they need to add. Alternatively, you may have an interview with an employee. After the interview process is completed, the user can then make notes about the employee.

    Speech to Text or Dictation is an extremely powerful tool. It is something that we at SapphireOne, as well as our clients, utilise daily. It is a massive timesaver. 

    Checking for WF Transactions

    User Work Flow Alert – For any user that is required to approve any work flow transactions there will be an additional button displayed at the right-hand end of the tool bar as seen here .

    When the user selects this button SapphireOne, will display an alert dialog indicating how many work flow transactions that require their attention for processing. 

    Organisation Levels and Mixed Permissions

    Note that the Organisation Levels referred to here are from the Organisation Chart function on the controls drop-down menu. 

    When Organisational Levels are used when setting permissions for Workflow Rules, the Levels are not hierarchical in the level above a user will not have automatic authorisation permissions granted. If this was allowed everyone above the working level would be viewing authorisation alerts including the General Manager or CFO. 

    Authorisation may only be assigned at a particular level by selecting the Authorisation Required checkbox for any user or groups of users in SapphireOne. 

    If authorisation permission is to be set at the User Level the users should not have the Rules Level set in their user file on the first page of a user Inquiry the Details Page. Care will also have to be exercised when Organisation levels are used with users at a user by user basis. 

    Probably be the most common error when setting up this function is the setting up of a conflict. For example, authorisation has been granted for Sales Managers and Authorisation Required for the user SapphireOne Sydney who is also in the Sales Managers group. That is a direct conflict must be avoided at all costs as the user has been included as part of the Sales managers level. 

    Do not mix permissions. Make certain that a specific user who may not authorise transactions does not also form part of any organisational level that may authorise transactions. 

    Workflow In Operation (Restrictions)

    A user creates a transaction and saves it. SapphireOne determines that a workflow rule is to be enforced as it has determined that for the type of transaction there is a rule that is broken and the check box has been selected. SapphireOne will then proceed to save the transaction with a status of err for error. The error code will be WF for Workflow and this means that a user with the appropriate authorisation rule in place has to approve it which will remove the error code enabling further processing of the transaction as documented on the previous page. 

    From SapphireOne setup we have two types of users who will require authorisation or be able to authorise transactions. 

    1. User who starts or creates the Transaction. The users ID will be recorded by SapphireOne and they will be the only user to receive the Active Message pop up for the transactions that they actually create. Until a user actually creates a transaction they will not receive any Active Message authorisation pop ups. OR Specific Users for example, SONE0 SapphireOne Syd. I.e. a new staff member and the management wants to check certain transactions before they are processed. Again, they will be the only users to receive the Active Message pop up only for the transactions that they actually create. 
    2. User Level. This is different as this will be a group of users who have the same Rules Level set in the first page of their User Access Inquiry. Once a transaction has been created by a single member of the Rules Level Group all of the users in the same group would receive the Active message pop up. For example, if there is more than one user with a Level of Sale Manager set in their user file they would all be presented with the Active message pop up. 

    Workflow In operation (Approvals)

    The rules for approvals is the same as for restrictions above only in reverse. For example, some planning will be required for the rules. If the organisational chart levels are used throughout and you have 100 sales staff and 1 sales manager set to authorise transactions the Active Message pop up above will be displayed to 101 users and this may not be what is wanted. 

    Setting up Rules

    The Authorisation Required check box must only be selected for any user who is permitted to authorise transactions. 

    There are three options when selecting a user or users when setting rules for authorisation and these are detailed below. 

    1. On a user by user basis so that the actual user ID will have to be entered and this could be used in two ways. For a specific user who is to authorise transactions, or to a single user that management has selected to check on all transactions created by that user before they are processed further. (New Staff).
    2. On an Organisational Level basis. This could be used when a group of users is to be selected from the organisational chart. For example, Sales Staff could be set up so that all transactions that they create would require authorisation. It should be noted that a problem could arise in that this would mean that not only will all Sales Staff not be permitted to authorise transactions, that they would then all be presented with the Active Message on the previous page for each and every transaction created by each and every user in the Sales Staff grouping and this could become annoying. 
    3. Probably the best option for setting Authorisation Rules is to use the User who start transaction option. While this could be set either way by the selection of the Authorise Required checkbox the normal procedure would be to not select the Authorise Required checkbox. SapphireOne would then require that all transactions created in SapphireOne be authorised, but the only users being presented with the Active Message pop up would be the user who created the transaction and any user that has the Authorisation Required check box selected. 

    Two events per Rule

    As seen below for each and every rule set up there must be at least two events setup. One that requires authorisation and one that does not require authorisation as seen below. It is all very well to have a WF error on a transaction, but there must be at least one staff member who can approve any WF transactions that are created. 

    Examples

    From the Organisation Chart referred to above we will discuss three scenarios. 

    1. Sales Staff – Setup users performing sales or purchases in the AccPayableStaff level.
      • The Authorisation Required checkbox is selected.
    2. Sales Managers- Set up one or more users as Sales Managers in the AccPayableMan level.
      • The Authorisation Required checkbox would not be selected.
    3.  End result – All Sales staff will create transactions with an WF error requiring the Sales Manager to approve them all. The Active Message alert will be displayed to all 100 staff members plus the Sales Manager.
    1. User Who creates the Transaction- For the user who creates the transaction.
      • The Authorisation Required checkbox is selected.
    2. Sales Managers- As above set up one or more users as Sales Managers in the AccPayableMan level.
      • The Authorisation Required checkbox would not be selected.
    3. End Result – All Sales staff will create transactions with an WF error requiring the Sales Manager to approve them all. The Active Message alert will be displayed to the user who created the transaction and the Sales Manager. Even if another user modifies the transaction the only user who receives notification messages will be the user who created the transaction and the Sales manager.
    1. User – If necessary for any transaction created, a specifically selected user may be set up to receive notifications regarding all transactions with workflow errors. This Sales Staff user must not have a Level of Sales Staff set in their user file or else a conflict will arise.
      • Select User from the Change button options.
      • The Authorisation Required checkbox is selected.
    2. Sales Managers- Set up one or more users as Sales Managers in the AccPayableMan level.
      • The Authorisation Required checkbox would not be selected.
    3. End Result – Only the Accounts manager and the entered user would receive any alerts for Workflow.

    Try and make certain that only 1 user has authorisation privileges granted and does not belong to any other group or organisational level.  If 2 specific users or levels have authorisation privileges All of them will have to authorise transactions before the WF error code is released unless they are part of an organisational level. 

    View Page

    View Overview

    The Sapphire View tool enables the user to embed advanced spreadsheet features in their forms. A spreadsheet is an accounting tool or application that allows for the storage, organisation and analysis of data and displays it in a table format. A spreadsheet is comprised of a number of cells in which information or numerical data can be entered into, calculations executed or display pictures.

    The Sapphire View tool gives the SapphireOne user the ability to insert and display a spreadsheet area in your SapphireOne forms. Once you use SapphireOne View areas in your forms, you can import and export spreadsheets documents using the SapphireOne View commands. When executed in forms, SapphireOne View areas provide basic spreadsheet features including cell editing and formula entry. More advanced features are available through the SapphireOne View language.

    Sapphire Web Pack View is a functionality and a SapphireOne form area that enables developers to embed advanced spreadsheet features in their forms. 

    View Installation and Activation  

    Unlike with the legacy SapphireOne View product, SapphireOne View features are directly included in SapphireOne itself, making it easier to deploy and manage. No additional installation is required.

    However, SapphireOne View requires the same license as SapphireOne View. You need to have this license installed in your application in order to use these features. When the SapphireOne View license is not installed, the contents of an object that requires a SapphireOne View feature are not displayed at runtime and an error message is displayed instead.

    In this example, a SapphireOne View license is missing while displaying a SapphireOne View spreadsheet area:

    Defining a SapphireOne View Area

    View Overview  

    SapphireOne View allows you to insert and display a spreadsheet area in your SapphireOne forms. A spreadsheet is an application containing a grid of cells into which you can enter information, execute calculations, or display pictures.

    Once you use SapphireOne View areas in your forms, you can import and export spreadsheets documents using the SapphireOne View commands.

    Creating the Area  

    SapphireOne View documents are displayed and edited manually in a SapphireOne form object named SapphireOne View. This object is available as part of the last tool (Plug-in Area, Web Area, etc.) found in the object bar:

    A SapphireOne View form area is configured by means of standard properties found in the Property List, such as Object Name and Variable or ExpressionCoordinatesDisplayAction, and Events

    • Object Name: name of the SapphireOne form area that contains and displays the SapphireOne View document.
    • Variable or Expression: name of the SapphireOne View form area variable.

    When the form is executed, the SapphireOne View area displays a spreadsheet by default:

    Using a SapphireOne View Area

    View Overview  

    When executed in forms, SapphireOne View areas provide basic spreadsheet features including cell editing and formula entry. More advanced features are available through the SapphireOne View language.

    Selection, Input and Navigation Basics  

    Spreadsheets are composed of rows and columns. A number is associated with each row. A letter (or group of letters once the number of columns surpasses the number of letters in the alphabet) is associated with each column. The intersection of a row and a column makes a cell. Cells can be selected and their contents edited.

    Selection  

    • To select a cell, simply click on it or use the direction arrows on the keyboard. Its content (or formula) is displayed within the cell. 
    • To select several continuous cells, drag the mouse from one end of the selection to the other. You can also click on the two ends of the selection while holding down the Shift key.
    • To select all cells in the spreadsheet, click on the  cell at the top left of the area. 
    • To select a column, click on the corresponding letter (or set of letters).
    • To select a row, click on the corresponding number.
    • To select a group of cells that are not continuous, hold down the Ctrl key (Windows) or Command key (Mac) and click on each cell to be selected. 
    • To deselect cells, simply click anywhere within the spreadsheet.

    Input and Navigation  

    Double-clicking on a cell allows passing into input mode in the relevant cell. If the cell is not empty, the insertion cursor is placed after the content of the cell. 

    Data can be entered directly once a cell is already selected, even if the insertion cursor is not visible. The input then 
    replaces the content of the cell.

    The Tab key validates the cell input and selects the cell to its right. Combining the Shift + Tab keys validates the cell input and selects the cell to its left. 

    The Carriage return key validates the cell input and selects the cell below it. Combining the Shift + Carriage return keys validates the cell input and selects the cell above it. 

    The direction keys (arrows) allow you to move a cell in the direction indicated by the arrow.

    View User Interfaces  

    You can add an interface to SapphireOne View areas to allow end users to perform basic modifications and data manipulations. SapphireOne offers two optional interfaces to choose from, Ribbon and Toolbar. These interfaces can be enabled or disabled from either the Property List or dynamically with code:

    • Property List: In the Appearance section. 
    • Dynamically: Via a JSON file (see Dynamic Forms)
      • “userInterface”: Default value is “none”. To enable a toolbar, it can be set to “ribbon” or “toolbar”.
      • “withFormulaBar”: Default value is “false”. To enable the formular bar, it can be set to “true” . Note: Available only for the “toolbar” interface. 

    Both the Ribbon and the Toolbar interfaces group related actions into the following tabs: 

    Tab  Actions Ribbon Interface Toolbar Interface
    File File manipulation  X  
    Home Text appearance  X  X
    Insert Add items  X  X
    Formulas Formula calculation and library  X  X
    Data Data manipulation  X  X
    View Visual presentation  X  X
    Settings Sheet presentation reference  X  

    User-defined modifications are saved in the SapphireOne View object when the user saves the document.

    View Ribbon  

    The Ribbon interface allows end users to perform comprehensive modifications and data manipulations

    View Toolbar  

    The Toolbar interface allows end users to perform basic modifications and data manipulations. 

    Enabling the Toolbar interface displays the Show Formula Bar option. When selected, the formula bar is visible below the Toolbar interface. If not selected, the formula bar is hidden.

    With visible formula bar:

    Entering a Formula, a Function or a Reference  

    To enter a formula or a function in a SapphireOne View area:

    1. Select the cell into which you will enter the formula or function.
    2. Enter = (the equal sign).
    3. Enter the formula.
      OR
      Click on a cell to enter its reference in the formula.

      OR
      Type the first letter of the function to enter. A pop-up menu listing the availables functions and references appears, allowing you to select the desired elements:

    Context Menu  

    SapphireOne View areas benefit from an automatic context menu that provides users with standard editing features such as copy and paste, but also with basic spreadsheet features:

    Note: The Copy/Cut and Paste features of the context menu only work within the spreadsheet area, they do not have access to SapphireOne pasteboard. System shortcuts such as Ctrl+c/Ctrl+v works however and can be used to exchange data between the area and other applications.

    This menu proposes additional features depending on the clicked area:

    • click on a column or row header: InsertDeleteHide, or Unhide the contents
    • click on a cell or a cell range:
      • Filter: allows hiding row through filters (see Filtering rows in the SpreadJS documentation).
      • Sort: sorts the column contents.
      • Insert Comment: allows user to enter a comment for an area. When a comment has been entered for an area, the top left cell of the area displays a small red triangle:

    SapphireOne View Form Events  

    Overview  

    The following form events are available in the Property List for SapphireOne View areas:

    Some of the events are standard form events (available to all active objects) and some are specific SapphireOne View form events. The specific SapphireOne View form events provide additional information in the object returned by the FORM Event command when they are generated for SapphireOne View areas. The following table shows which events are standard and which are specific SapphireOne View form events:

    Standard SapphireOne events (see Form event code) Specific SapphireOne View events
    On Load   On VP Ready
    On Getting Focus  On Clicked
    On Losing Focus   On Double Clicked
    On Unload   On Header Click
      On After Edit
      On Selection Change
      On Column Resize
      On Row Resize
      On VP Range Changed

    On VP Ready  

    Any SapphireOne View area initialization code, for loading or reading values from or in the area, must be located in the On VP Ready form event of the area. This form event is triggered once the area loading is complete. Testing this event makes you sure that the code will be executed in a valid context. An error is returned if a SapphireOne View command is called before the On VP Ready form event is generated.

    Note: SapphireOne View areas are loaded asynchronously in SapphireOne forms. It means that the standard On load form event cannot be used for SapphireOne View initialization code, since it could be executed before the loading of the area is complete. On VP Ready is always generated after On load.

    On Clicked  

    Clicking anywhere on a SapphireOne View document generates the On Clicked event. The object returned by the FORM Event command contains:

    Property Type Description
    code longint On Clicked
    description text “On Clicked”
    objectName text SapphireOne View area name
    sheetName text Name of the sheet of the event
    range object Cell range

    Example: If(FORM Event.code=On Clicked)
        VP SET CELL STYLE(FORM Event.range;New object("backColor";"green"))
     End if

    On Double Clicked  

    When a user double clicks anywhere on a SapphireOne View document, the On Double Clicked event is generated. The object returned by the FORM Event command contains:

    Property Type Description
    code longint On Double Clicked
    description text “On Double Clicked”
    objectName text SapphireOne View area name
    sheetName text Name of the sheet of the event
    range object Cell range

    Example: If(FORM Event.code=On Double Clicked)
        $value:=VP Get value(FORM Event.range)
     End if

    On Header Click  

    A user clicking on a column or row header in a SapphireOne View document generates the On Header Click event. The object returned by the FORM Event command contains:

    Property Type Description
    code longint On Header Click
    description text “On Header Click”
    objectName text SapphireOne View area name
    sheetName text Name of the sheet of the event
    range object Cell range
    sheetArea longint The sheet location where the event took place: 0: The crossing area between column number/letter headers (top left of the sheet)1: The column headers (area indicating the column numbers/letters)2: The row headers (area indicating the row numbers)

    Example: If(FORM Event.code=On Header Click)
        Case of
           :(FORM Event.sheetArea=1)
              $values:=VP Get values(FORM Event.range)
           :(FORM Event.sheetArea=2)
              VP SET CELL STYLE(FORM Event.range;New object("backColor";"gray"))
           :(FORM Event.sheetArea=0)
              VP SET CELL STYLE(FORM Event.range;New object("borderBottom";New object("color";"#800080";"style";vk line style thick)))
        End case
     End if

    On After Edit  

    Following any user modification in a SapphireOne View document, the On After Edit event is generated. The object returned by the FORM Eventcommand contains:

    Property Type Description
    code longint On After Edit
    description text “On After Edit”
    objectName text SapphireOne View area name
    sheetName text Name of the sheet of the event
    action text “editChange”, “valueChanged”, “DragDropBlock”, “DragFillBlock”, “formulaChanged”, “clipboardPasted”

    Note: See also the On VP Range Changed event.

    Depending on the action property value, the object will contain additional properties.

    action = editChange  

    Editing text generates the following additional properties:

    Property Type Description
    range object Cell range
    editingText variant The value from the current editor

    action = valueChanged  

    Changing value(s) generates the following additional properties: 

    Property Type Description
    range object Cell range
    oldValue variant Value of cell before change
    newValue variant Value of cell after change

    action = DragDropBlock  

    Dragging and dropping actions generate the inclusion of the following additional properties:

    Property Type Description
    fromRange object Range of source cell range (being dragged)
    toRange object Range of the destination cell range (drop location)
    copy boolean Specifies if the source range is copied or not
    insert boolean Specifies if the source range is inserted or not

    action = DragFillBlock  

    Dragging content to fill adjacent cells generates the following additional View:

    Property Type Description
    fillRange object Range used for fill 
    autoFillType longint Value used for the fill. 0: Cells are filled with all data (values, formatting, and formulas)1: Cells are filled with automatically sequential data2: Cells are filled with formatting only3: Cells are filled with values but not formatting4: Values are removed from the cells5: Cells are filled automatically 
    fillDirection longint Direction of the fill. 0: The cells to the left are filled1: The cells to the right are filled2: The cells above are filled3: The cells below are filled

    action = formulaChanged  

    Entering formula(s) generates the following additional properties:

    Property Type Description
    range object Cell range
    formula text The formula entered 

    action = clipboardPasted  

    Pasting content from the clipboard generates the following additional properties:

    Property Type Description
    range object Cell range receiving the contents
    pasteOption longint Specifies what is pasted from the clipboard: 0: Everything is pasted (values, formatting, and formulas)1: Only values are pasted2: Only the formatting is pasted3: Only formulas are pasted4: Values and formatting are pasted (not formulas)5: Formulas and formatting are pasted (not values)
    pasteData object The data from the clipboard to be pasted
       Property Type Descriptiontext textThe text from the clipboardhtml textThe HTML from the clipboard

    View Example  

    Here is an example handling an On After Edit event: If(FORM Event.code=On After Edit)
        If(FORM Event.action="valueChanged")
           ALERT("WARNING: You are currently changing the value from "+String(FORM Event.oldValue)+" to "+String(FORM Event.newValue)+"!")
        End if
     End if

    The above example could generate an event object (see FORM Event) like this:
    {
    "code":45;
    "description":"On After Edit";
    "objectName":"ViewProArea"
    "sheetname":"Sheet1";
    "action":"valueChanged";
    "range": {area:ViewProArea,ranges:[{column:1,row:2,sheet:1}]};
    "oldValue":"The quick brown fox";
    "newValue":"jumped over the lazy dog";
    }

    On Selection Change  

    Modification of the current selection of rows or columns in a SapphireOne View document generates the On Selection Change event. The object returned by the FORM Event command contains:

    Property Type Description
    code longint On Selection Change
    description text “On Selection Change”
    objectName text SapphireOne View area name
    sheetName text Name of the sheet of the event
    oldSelections object Cell range before change. 
    newSelections object Cell range after change. 

    Example: If(FORM Event.code=On Selection Change)
        VP SET CELL STYLE(FORM Event.oldSelections;New object("backColor";Null))
        VP SET CELL STYLE(FORM Event.newSelections;New object("backColor";"red"))
     End if

    On Column Resize  

    When a user modifies the width of a column in a SapphireOne View document, the On Column Resize event is generated. The object returned by the FORM Event command contains:

    Property Type Description
    code longint On Column Resize
    description text “On Column Resize”
    objectName text SapphireOne View area name
    sheetName text Name of the sheet of the event
    range object Cell range of the columns whose widths have changed
    header boolean True if the row header column (first column) is resized, else false

    Example: If(FORM Event.code=On Column Resize)
        VP SET CELL STYLE(FORM Event.range;New object("hAlign";vk horizontal align right))
     End if

    On Row Resize  

    A user modifying the height of a row in a SapphireOne View document generates the On Row Resize event. The object returned by the FORM Eventcommand contains:

    Property Type Description
    code longint On Row Resize
    description text “On Row Resize”
    objectName text SapphireOne View area name
    sheetName text Name of the sheet of the event
    range object Cell range of the rows whose heights have changed
    header boolean True if the column header row (first row) is resized, else false

    Example: If(FORM Event.code=On Row Resize)
        VP SET CELL STYLE(FORM Event.range;New object("vAlign";vk vertical align top))
     End if

    On VP Range Changed  

    When a change occurs within a cell range in the SapphireOne View document, the On VP Range Changed event is generated. The object returned by the FORM Event command contains:

    Property Type Description
    objectName text SapphireOne View area name
    code longint On VP Range Changed
    description text “On VP Range Changed”
    sheetName text Name of the sheet of the event
    range object Cell range of the change
    changedCells object Range containing only the changed View. It can be a combined range. 
    action text The type of operation generating the event:”clear” – A clear range value operation”dragDrop” – A drag and drop operation”dragFill” – A drag fill operation”evaluateFormula” – Setting a formula in a specified cell range”paste” – A paste operation”setArrayFormula” – Setting a formula in a specified cell range”sort” – Sorting a range of cells

    Converting SapphireOne View Documents  

    You can convert your SapphireOne View documents to SapphireOne View areas using the VP Convert from SapphireOne View command. Most properties and information stored in SapphireOne View documents are automatically converted, including formats, styles, borders, values, formulas, selections, zoom, etc. In general, converted SapphireOne View documents will be rendered in SapphireOne View areas exactly as they were rendered in SapphireOne View areas, like the following:

    Original SapphireOne View document:

    Document converted in SapphireOne View area

    We are doing our best to ensure that converted documents remain as true as possible to the original, but some features may not be fully rendered. These are described in the paragraph below.

    View Conversion Process  

    Note: The SapphireOne View document conversion feature is being continuously improved, based on customer feedback. It is highly recommended to always keep a copy of your original SapphireOne View BLOBs or documents, even after a successful conversion. 

    With regards to the current state of your SapphireOne View plug-in document, the conversion process requires the following steps.

    1. Load your SapphireOne View document (.4pv) into a BLOB:
      Note: If your SapphireOne View document is already stored in a BLOB field, go to step 2.
       C_BLOB($pvblob)
       DOCUMENT TO BLOB("document.4PV";$pvblob)
    2. Call the VP Convert from SapphireOne View with the BLOB containing the SapphireOne View document:
       C_OBJECT($vpObj)
       $vpObj:=VP Convert from SapphireOne View($pvblob)
    3. Assign the resulting object to a SapphireOne View area form object or a document to see the results. 
       VP IMPORT FROM OBJECT("SapphireOneViewProArea";$vpObj)

    Conversion Details  

    The following table provides the current status for the primary conversion areas. Note that this list will be updated regularly, as the conversion process is continuously improved. 

    Feature Conversion status Comments
    Document attributes Document display attributes are converted: selected cells, zoom, grid display.
    Document information is converted: version, title, subject author, company, note, creation and modification date.
    Columns and rows All defined columns and rows are converted with their original size.
    Column and row headers are converted without any restrictions.
    Borders Borders are converted with their thickness and color. Grid display settings are converted. Only one single bar border and one double-bar border models are available in SapphireOne View. Single bar borders are converted the same as the original, any double-bar borders are converted to the SapphireOne View double-bar model.
    Splitters Currently not converted
    Styles & fonts Styles and style sheets are converted. Conditional styles are not supported. Deprecated text styles (i.e. Shadow, Condensed, etc.) and QuickDraw fonts are not converted. 
    Rotation styles (oriented text) are currently not converted
    Formats & cell names Cell formats are converted to available formats with similar rendering. All data type formats are supported: text, number, date and time, boolean, picture. Cell names are converted. COMPATIBILITY NOTE: As of SapphireOne v17 R5, SapphireOne View default formats rely on the same regional settings as the SapphireOne host database. 
    User defined SapphireOne formats (starting with “|”) are currently not converted
    Controls created with PV SET CELL CONTROL (button / radio button / check box / drop down / combo box) are currently not supported
    Invisible cells are not supported (not available in SapphireOne View) Only columns, rows, or sheets can be set invisible. An alternate solution is to use VP ADD FORMULA NAME to define non-displayed values or formulas.
    Pictures Pictures are supported and converted with some limitations SapphireOne View picture format included multiple codecs and is deprecated. Converted pictures keep only the most appropriate codec for html rendering (svg, png, jpeg, gif) and are saved in base64. 
    Pictures with truncated centered / replicated format are currently not converted Background pictures are not replicated on each page (this concept does not exist in SapphireOne View).
    Printing Currently not supported Printing options and print settings defined in the SapphireOne View document are converted. 
    Dynamic links Cells or columns linked to fields or variables are currently not supported
    Formulas Formulas are converted but for security reasons, references to SapphireOne project methods, commands, variables, or fields need specific processing (see below) See Converting SapphireOne View plug-in formulas.
    Project methods – supported Project methods must comply with SapphireOne View requirements (see Project method references). A non compliant method name is converted to UNSUPPORTED_SapphireOneMETHOD_NAME(“<method name>”,param1,…paramN).
    Commands – supported Converted to existing SapphireOne View functions (see Functions and SapphireOne commands). SapphireOne commands that are not part of the authorized list are converted to: UNSUPPORTED_SapphireOneCOMMAND(<command name>,param1,…,paramN). 
    Variables – not supported You must use SapphireOne project methods to access variable values (see Project method references). Variables in formulas are converted to UNSUPPORTED_VARIABLE(“<variable name>”).
    Fields – supported Converted to “TABLETITLE_FIELDTITLE()” if available in the database during conversion. If a field or table name is not ECMA compliant, converted to UNSUPPORTED_TABLE_FIELD_TITLE(“virtual structure name”). Only fields belonging to the “virtual structure” of the database can be called in SapphireOne View formulas. See Field references.

    SapphireOne View Database References

    Project method references  

    Field references  

    Project Method References  

    Overview  

    SapphireOne View allows you to call SapphireOne project methods from within your formulas. Using SapphireOne project methods extends the possibilities of your SapphireOne View documents. SapphireOne methods can receive parameters from the SapphireOne View area, and return values. For security reasons, only methods that have been explicitly allowed can be called by the user. 

    Requirements  

    To be called in a SapphireOne View formula, a project method must be:

    • Referenced: it was explicitly declared using the VP SET CUSTOM FUNCTIONS command (recommended) or the VP SET ALLOWED METHODS command.
    • Runnable: it belongs to the host database or a loaded component with the “Shared by components and host database” option enabled (see Sharing of project methods).
    • Not in conflict with an existing SapphireOne View function: if you call a project method with the same name as a SapphireOne View built-in function, the function is called.

    Note: If neither the VP SET CUSTOM FUNCTIONS nor the VP SET ALLOWED METHODS command has been executed during the session, SapphireOne View custom functions rely on allowed methods defined by SapphireOne’s generic SET ALLOWED METHODS command. In this case, the project method names must comply with JavaScript Identifier Grammar (see ECMA Script standard). The global filtering option in the Settings dialog box (see Data Access) is ignored in all cases.

    Hello World example  

    We want to print “Hello World” in a SapphireOne View area cell using a SapphireOne project method:

    1. Create a “myMethod” project method with the following code:
       #DECLARE->$hw Text
       $hw:="Hello World"
    2. In the form method of the form that contains the SapphireOne View area, you can write:
       Case of
          :(Form event code=On Load)
             var $o : Object
             $o:=New object
        // Define "vpHello" function from the "myMethod" method
             $o.vpHello:=New object
             $o.vpHello.formula:=Formula(myMethod)
      ("ViewProArea";$o)
       End case
    3. Edit the content of a cell in a SapphireOne View area and type:

      “myMethod” is then called by SapphireOne and the cell displays:

    Parameters  

    Parameters can be passed to SapphireOne project methods using the following syntax:=METHODNAME(param1,param2,...,paramN)

    These parameters are received in methodName in $1, $2…$N.

    Note that the ( ) are mandatory, even if no parameters are passed:=METHODWITHOUTNAME()

    You can declare the name, type, and number of parameters through the parameters collection of the function you declared using VP SET CUSTOM FUNCTIONS command. Optionally, you can control the number of parameters passed by the user through minParams and maxParams properties.

    If you do not declare parameters, values can be sequentially passed to methods (they will be received in $1, $2…) and their type will be automatically converted. Dates in jstype will be passed as C_OBJECT in SapphireOne methods with two properties:

    Property Type Description
    value Date Date value
    time Real Time in seconds

    SapphireOne project methods can also return values in the SapphireOne View cell formula via $0. The following data types are supported for returned parameters:

    • C_TEXT (converted to string in SapphireOne View)
    • C_REAL/C_LONGINT (converted to number in SapphireOne View)
    • C_DATE (converted to JS Date type in SapphireOne View – hour, minute, sec = 0)
    • C_TIME (converted to JS Date type in SapphireOne View – date in base date, i.e. 12/30/1899)
    • C_BOOLEAN (converted to bool in SapphireOne View)
    • C_PICTURE (jpg,png,gif,bmp,svg other types converted into png) creates a URI (data:image/png;base64,xxxx) and then used as the background in SapphireOne View in the cell where the formula is executed
    • C_OBJECT with the following two properties (allowing passing a date and time):
      PropertyTypeDescriptionvalueDateDate valuetimeRealTime in seconds

    If the SapphireOne method returns nothing, an empty string is automatically returned.

    An error is returned in the SapphireOne View cell if:

    • the SapphireOne method returns another type other than those listed above,
    • an error occurred during SapphireOne method execution (when user click on “abort” button).

    Field References  

    Overview  

    SapphireOne View allows you to use references to SapphireOne database fields in your formulas. When displaying a SapphireOne View area, a field reference is replaced by the field value in the current record. The value is extracted when the form is opened, but if it changes you can just call VP RECOMPUTE FORMULAS so that the SapphireOne View area uses the new value.

    Requirements  

    To be called in a SapphireOne View formula, a SapphireOne field must comply to the following requirements:

    • the field was declared as a formula using the VP SET CUSTOM FUNCTIONS command (see example).
    • the field type must be supported by SapphireOne View (see below).

    An error is returned in the SapphireOne View cell if the formula calls a field which is not compliant.

    Note: For security when the VP SET CUSTOM FUNCTIONS is not used (not recommended), only the fields belonging to the virtual structure of the database, i.e. declared through the SET TABLE TITLES and/or SET FIELD TITLES commands with the * parameter, can be called. In this case, table and field names must be ECMA compliant (see ECMA Script standard). 

    Supported Field Types  

    SapphireOne View supports references to fields of the following types:

    Type Value type in SapphireOne View
    Alpha, Text string
    Integer, Long integer, Integer 64-bit, Real, Float number
    Date JavaScript Date type (hour, minute, sec = 0)
    Time JavaScript Date type (date in base date, i.e. 12/31/1899)
    Boolean bool
    Picture supported picture types: jpg, png, gif, bmp, svg; other types converted into png. Creates an uri (data:image/png;base64,xxxx) set as background for the SapphireOne View cell where the formula is executed

    Example  

    We want to print the name of a person in a SapphireOne View area cell using a SapphireOne field:

    1. Create an “Employee” table with a “L_Name” field:
    2. In the form method of the form that contains the SapphireOne View area, you can write:
       Case of
          :(Form event code=On Load)
             var $o : Object
             $o:=New object
             $o.EMP_NAME:=New object //declare the function
             $o.EMP_NAME.formula:=Formula([Employee]L_Name)
             VP SET CUSTOM FUNCTIONS("ViewProArea";$o)
       End case
    3. Edit the content of a cell in the SapphireOne View area and enter “=e”:
    4. Select EMP_NAME (use the Tab key) and enter the closing ). 
    5. Validate the field to display the name of the current employee:

      Note: The [Employee] table must have a current record.

    Note: When the VP SET CUSTOM FUNCTIONS command is not used (not recommended), fields declared in the virtual structure are entered with a syntax such as TABLENAME_FIELDNAME()


    You can review our Blog and YouTube channel for additional information and resources on SapphireOne ERP, CRM and Business Accounting software.

    Note that a tag with the name of HOLD is built into SapphireOne. When it is selected the transaction may not be posted until the tag status of HOLD is removed or altered to something other than HOLD.

    • Many of the Tag Headings are user configurable.
      • The Tag Headings may be re-named by going to:
        Utilities \ Controls \ Master Defaults \ then select the appropriate functions Page
    • Initially all of the tag menus are blank. This means that the user is able to create customised tag drop down menus as required.
      • These drop-down menus are created by entering an item that is not on the list, then (tab away). SapphireOne will ask if you want to add the new tag to the list.
      • To remove a tag, hold the Control or Command key down and then select the tag that you want to remove. You will be asked if you want to remove it from the list.

    SapphireOne checks that each transaction entry is complete and balanced before allowing any saving operation. When the Out of Balance is 0.00 the tick, will activate in the top tool bar indicating to the user that the transaction is ready to be saved. When more than a single transaction is selected, Blue will also be displayed on the main toolbar. See below for additional details.

    You can save your Transaction in one of three methods:

    Select the Tick when it is activated. This will save the current transaction and return the user to the main tool bar or the list.
    When multiple transactions have been selected the user may click on the tick on the tool bar with the results as seen as above.
    Or
    Click on either of the the Arrows. This will tell SapphireOne to save the current transaction and open the next transaction in the list ready for data entry or modification. Also note that for what ever page is open in the transaction SapphireOne will move to the next transaction displaying the exact same page. I.e. Terms page to Terms page. Very handy when checking the same data in multiple items.
    Selecting the Enter Key on the keypad. SapphireOne will then save the current transaction and opens another transaction of the same type ready for data entry. Very handy when entering multiple transactions of the same type. I.e. Client Receipt, Client Receipt.

    Watch how to enter Purchase Inwards Goods Journal in SapphireOne


    You can review our Blog and YouTube channel for additional information and resources on SapphireOne ERP, CRM and Business Accounting software.

    Was this helpful?

    Previous Article

    Order Vendor Invoice