© 2018 Capita Business Services Ltd. All rights reserved.
Capita Education Software Solutions is a trading name of Capita Business Services Ltd. Our Registered office is 30 Berners Street, London, W1T 3LR and our registered number is 02299747. Further information about Capita plc can be found in our legal statement.
SIMS FMS is designed to meet the specialist needs of education users integrating with SIMS Data to improve Finance operations.
FMS supports the electronic exchange of Content Order, Authorised Order, Invoice and Credit Note documents via a Web Services interface from web sites or portals. The exchange of Content Order and Authorised Order by eMail is still available but is no longer recommended and will not be supported at a future date.
This document must be read in conjunction with:
* Provided with permission from BASDA. The available version is 3.10 but we are advised that there was no breaking difference from 3.09.
This document is intended to help support the implementation of the Web Services interface. Any references to the eMail transfer mechanism are only included to aid clarity where the Web Services functionality differs.
This document, and the associated documents and files are not manuals or training guides and assume that the reader has
The intent is to reduce the use of paper documents, formal or informal, to increase the accuracy of the data transferred, to use current prices upon Content Orders, and increase the timeliness of the entire process. Additional benefits of automated price comparison can be obtained if suitable portals/web sites are used for this process.
To support this, it is envisaged that usage will be as follows based upon functionality being included in FMS 6.132 Summer 2010:-
The order documents supported are the Content Order (received by FMS) and the Authorised Order (sent from FMS). These are based on the “eBIS XML 3.09 Order Schema (UK Gov)” order schema.
The invoice documents supported are Invoices and Credit Notes. These are based on the “eBIS XML 3.09 Invoice Schema”.
The documents Content Order, Invoice, and Credit Note should be held in a queue at the supplier or portal for collection by the establishment. Authorised Orders are sent from FMS immediately they are “Printed” in FMS. It is known that some establishments do not have full internet access “24/7” while other establishments do. FMS therefore expects the Web Service to be permanently available.
The checksum is validated. It must therefore be correctly provided. The calculation is included in the official documentation. NOTE: we have found it necessary to use an INT64 to support this as very large numbers can be generated.
The Authorised Order exported from FMS is schema valid and has been validated against the OGC/BASDA test facility.
The mapping section below for order import is not, and is not meant to be, UKGov schema compliant. It is provided solely to indicate what FMS expects in the way of data and how it will handle that data. Any data in the XML file not shown in this section will be ignored by FMS, but will not cause the import to fail.
When importing a Content Order FMS ignores the catalogue that is held in FMS. There is no interface or updating of the FMS held catalogue.
A Content Order can be edited in FMS. Therefore it may not be returned as raised. The user can not edit the part number, the description, or the price. Additional lines can not be added. The user can edit the line quantity to be purchased. Lines can be deleted.
FMS allows for encryption of order messages only. This was provided to enhance security when eMail was the only transfer method. eMail is no longer the recommended transfer method for order documents but is still available for existing users.
The use of encryption is not available for Invoice and Credit Note documents and should not be used for order documents transferred via Web Services. Security is provided by the use of SSL methods in the Web Services.
ESS is unable to provide support for encryption, beyond that normally provided to users of FMS under the terms of their support contract.
The Invoice and Credit Note both use the same schema, and are therefore treated as identical documents. The documents are identified at point of import by the internal identifiers. Additionally, to aid clarity or purpose FMS makes use of the facility to extend the schema by the use of the <Invoice / Extensions> tag. The following schema snippet identifies the extension, and its use can found below under “Import – Invoice and Credit Note”
On import the checksum is not validated, the file is validated against the schema and must therefore be schema compliant.
See also “FMS” below.
FMS does not use any proprietary value lists.
The values in the tags Order / OrderHead / Parameters / Language and Order / OrderHead / OrderCurrency (Code) of a Content Order are validated against user defined system parameters held within FMS. This is to ensure the consistency of data within FMS. It is assumed that the Invoice, and Credit Note if required, will in the same currency as the order.
FMS does not “Expect” a particular value. It is anticipated that for a British school trading with a British supplier that these values would be “en” and “GBP” respectively. NOTE: FMS does not support multiple currencies, or multiple languages. .
An Order, Invoice, or Credit Note line in FMS can not be saved without a valid linked Fund, Ledger Code and Cost Centre. Therefore a valid linked Fund, Ledger Code and Cost Centre is assigned to each order line at import. FMS has template functionality to automate this process.
To assist the user of FMS it is helpful if the supplier can return the login ID or name of the user raising the Content Order. If the supplier’s system also allows the entry of a cost centre or ledger code at order line level on the portal this should also be returned. This permits the full power of the template system within FMS to be used when importing Content Orders.
The template system allows for the definition of valid linked Fund, Ledger Code and Cost Centre to be defined by any combination of login id and/or line level cost centre.
The import/export processes within FMS are automated using standard, non proprietary, XML handling methods. It is therefore imperative that data is compliant with its tag data type; e.g. dates of type “XSD:date” must be correctly entered in accordance with the W3C type definitions as "YYYY-MM-DD" and must
NOTE: Please note this exception. On import FMS expects an integer for the line quantity as FMS will only accept an integer for line quantity.
The handshake for Content Orders makes use of the DUNS numbers as identifiers for both supplier and the establishment. Consequently, the suppliers “Account Number” field in FMS should be used to hold the Account Number that the supplier has provided to the school.
FMS continues to use a handshake on the suppliers “Account Number” and the FMS “XML Reference Number”. If this “Handshake” fails then the Content Order will not be imported.
The FMS “XML Reference Number” is the mirror of the supplier’s account number. The supplier uses the account number to identify the customer. The customer (establishment) uses the “XML Reference Number” to identify the supplier. It is recommended that for new systems, or when adding suppliers, the suppliers DUNS number is used as the XML Reference Number.
The FMS “XML Reference Number” is only guaranteed unique within any one FMS database. The “XML Reference Number” is user defined and for any one supplier will not be the same from different customers. It is possible for an LA to require all their schools to use the same number for a single supplier. It is not possible for a supplier to derive this number.
This functionality will not be supported in the future – date to be provided.
The handshake for Invoices and Credit Notes makes use of the DUNS numbers as identifiers for both supplier and establishment.
Each schema tag is listed with a brief comment about the data imported by FMS. This section must be read in conjunction with the eBIS XML 3.09 Order Schema (UK Gov) to ensure the reader understands the relationships and structures. The following does not indicate either relationship or structure.
Any schema tag not listed below is ignored by FMS. Node attributes are identified by italics.
NOTE:
1. For a Content Order that is received via Web Services, it is essential that the Content Order contains the FMS held DUNS Number for both the establishment and supplier. This provides the handshake used in FMS to ensure the order is intended for the recipient and is attached to the correct supplier.
2. For a Content Order that is received via email, it is essential that the Content Order contains the FMS held “Account Number” and “XML Reference”, SuppliersCodeForBuyer and BuyersCodeForSupplier respectively. This provides the handshake used in FMS to ensure the order is intended for the recipient and is attached to the correct supplier.
First 2 characters should match (ignore case) Establishment Details | tab 3 System Parameters | System Language. If not fail import.
Use to interpret values during import
If less than 2 decimals default pence as zero, if grater than 2 round to 2 decimal places.
Must be 0 (boolean zero) if not fail import. FMS does not support handling of test messages.
Should be “CTO” if not fail import.
Should match Establishment Details | tab 3 System Parameters | Transaction Currency, if not fail import.
Calculated, must match the value +-1 tolerance from the XML File, if not fail import.
Fills Supplier Details | tab 1 | Contract number
Used to calculate the checksum
Use to determine/validate supplier in FMS. Used to provide a handshake to verify the buyer – supplier relationship and must be present if file is to import.
Updates Supplier Details | tab1 | VAT Registration Number
Ignored. NOTE: May be used later to confirm the supplier is correctly identified.
Fills Order Header/ Supplier’s Contact Name, if available.
Fills Order Header/ Supplier’s Order Reference, if available. Not used by FMS but returned in a confirmed order XML file.
Use to determine/validate supplier in FMS. Used to provide a handshake to verify the buyer – supplier relationship and must be present if file is to import.
Ignored. NOTE: May be used later to confirm the buyer is correctly identified.
Supplier to enter users web site logon ID. Stored at order header level to indicate who raised the order on the web site.
If = “Original” add line to order otherwise ignore line.
Fills Purchase Order Processing | Line Number
Supplier to enter a cost centre if available to be used by FMS as a mnemonic cost centre. Use to determine Ledger Code, Fund, cost Centre for line.
Supplier to enter line level user ID if available otherwise users web site logon ID. Use to determine Ledger Code, Fund, cost Centre for line.
Fills Order Line Details | Part number
Fills Order Line Details | Description
Fills Order Line Details/ Commodity class, if available. Not used by FMS but returned in a confirmed order XML file.
Fills Order Line Details | UOM Code, if available. Not used by FMS but returned in a confirmed order XML file.
Fills Order Line Details | Quantity. (NOTE: Integer required for FMS)
Fills Order line Details | Unit Cost
Use to determine VAT Code in FMS
Fills Purchase Order Processing | Special instructions
Used to calculate the checksum
Each schema tag is listed with a brief comment about the data populated by FMS. This section must be read in conjunction with the eBIS XML 3.09 Order Schema (UK Gov) to ensure the reader understands the relationships and structures. The following does not indicate either relationship or structure.
Any schema tag not listed below is not populated by FMS. A tag will not be included in the XML file with no value. Node attributes are identified by italics.
Constant = Schema version currently supported by FMS e.g. "3.09-UKGov.20030911"
Establishment Details | tab 3 System Parameters | System Language.
Constant = “.”
Constant = “13.2”
Constant = “SIMS
Constant = “FMS6”
Constant = current FMS version.
Constant = “0” as a numeric. FMS does not support handling of test messages.
A value is not be supplied
Constant = “PUO”.
Constant = “BASDA”
A value is not be supplied
Constant = “original” for the first file, “copy” for all other files.
Constant = “UKGov-DocStatus”
Constant = “true”
A value is not be supplied
Establishment Details | tab 3 System Parameters | Transaction Currency.
Constant = “UKGov -CurrencyCode”
A value is not be supplied
Establishment Details | tab 3 System Parameters | Transaction Currency.
Constant = “UKGov -CurrencyCode”
A value is not be supplied
Calculate
Supplier Details | tab 1 | Contract number
Accounts Payable Parameters | Tab 1 | Free Text
Constant = “true”
Purchase Order Processing | Number
Constant = “true”
Purchase Order Processing | Date
Supplier Details | tab 5 | XML Supplier Reference
Supplier Details | tab1 | VAT Registration Number
Set as Supplier Details | tab1 | “GLN | DUNs” if the supplier’s “GLN | DUNs” companion attribute = “GLN”
Set as Supplier Details | tab1 | “GLN | DUNs” if the supplier’s “GLN | DUNs” companion attribute = “DUNs”
Supplier Details | tab1 | Name
Supplier Details | tab 1 | Address. Repeat tag for each address line.
Supplier Details | tab 1 | Post Code.
Supplier Details | tab 1 | Contact
Supplier Details | tab 1 | Telephone
Supplier Details | tab 1 | Fax
Supplier Details | tab 1 | Email
Order Header/ Order Reference, if available. Otherwise null.
Supplier Details | tab1 | Account Number
Establishment Details | tab 1 | VAT Registration Number
Set as Establishment Details | tab1 | “GLN | DUNs” if the establishment’s “GLN | DUNs” companion attribute = “GLN”
Set as Establishment Details | tab1 | “GLN | DUNs” if the establishment’s “GLN | DUNs” companion attribute = “DUNs”
Establishment Details | tab1 | Name
Establishment Details | tab 1 | Address. Repeat tag for each address line.
Establishment Details | tab 1 | Post Code
Establishment Details | tab1 | Telephone
Establishment Details | tab1 | Fax
Establishment Details | tab 1 | VAT Registration Number
Set as Establishment Details | tab1 | “GLN | DUNs” if the establishment’s “GLN | DUNs” companion attribute = “GLN”
Set as Establishment Details | tab1 | “GLN | DUNs” if the establishment’s “GLN | DUNs” companion attribute = “DUNs”
Establishment Details | tab1 | Name
Establishment Details | tab 1 | Address. Repeat tag for each address line.
Establishment Details | tab 1 | Post Code
Establishment Details | tab1 | Telephone
Establishment Details | tab1 | Fax
Constant = “Original”
Constant = “true”
Purchase Order Processing | Line Number
Order Line Details | Part number
Order Line Details | Description
Order Line Details | Commodity class, if available otherwise constant = “00 00 00 00” (pairs of zeroes separated by single spaces)
Order Line Details | UOM Code, if available otherwise constant = “EA”
Order Line Details | Quantity.
Constant = 1 per line for a free text order.
Order line Details | Unit Cost
Purchase Order Processing | Line total
Calculate
Order Head | Delivery Address Text. First line.
Order Head | Delivery Address Text. Repeat tag for each line starting at the second line.
NOTE: The user should structure their deliver to address so that the establishment’s name is on the first line only. All other lines will be put in here.
This will not be supplied.
NOTE: The delivery address from “Accounts Payable Parameters” is not sufficiently structured to reliably determine this.
Establishment Details | Telephone
Establishment Details | Fax
For delivery term:
ASAP = System date
After = delivery date + 1 day
Before = delivery date – 1 day
Between = earliest date
Not Between = latest delivery date + 1 day
On = delivery date
Confirmation order = system date
Date to be confirmed = system date + 4 weeks
Purchase Order Processing | Delivery Instruction
Order Line Details | Order Unit
Order Line Details | ledger code + Order Line Details | fund. Format to be “<LedgerCode>-<Fund>” e.g. 1001-01.
Purchase Order Processing | Special instructions
Calculated as total net goods value
Calculated as total gross goods value
Each schema tag is listed with a brief comment about the data imported by FMS. This section must be read in conjunction with the “eBIS XML 3.09 Invoice Schema” to ensure the reader understands the relationships and structures. The following does not indicate either relationship or structure.
Note. For an Invoice and Credit Note that is received via Web Services, it is essential that they contain the FMS held DUNS Number for both the school and supplier. This provides the handshake used in FMS to ensure the order is intended for the recipient and is attached to the correct supplier.
Any schema tag not listed below is ignored by FMS. Node attributes are identified by italics.
If present must be Boolean 0 (zero). Not present accepted.
Must be either “INV” or “CRN” (any case). Determines whether the message is treated as an Invoice (“INV”) or as a Credit Note (“CRN”).
Must be “BASDA” (any case). Other Code Lists are not recognised
Provides the Invoice “Order Number, used to link the Invoice to the Order.
Provides the Invoice “Invoice Number”, the Credit Note “Credit Note Number”.
Stored by FMS if provided. Not currently used by or displayed in FMS.
Provides the Credit Note “Invoice Number”, used to link the Credit Note to the Invoice.
References the GUID of the Invoice being credited. Stored by FMS if provided. Not currently used by or displayed in FMS.
Provides the Invoice “Invoice Date”, Credit Note “Credit Date”.
Used to determine the Supplier within FMS. This determines the Invoice / Credit Note from name and address.
Used for matching the Invoice line to the Order line or the Credit Note line to the Invoice Line. If missing the line is treated as a Post and Packing line.
Provides the Line Detail “Part Number”
Provides the Line Detail “Description” for both Invoice and Credit Note.
Stored by FMS if provided. Not currently used by or displayed in FMS.
Provides the Line Detail “Line Number”.
Stored by FMS if provided. Not currently used by or displayed in FMS.
Provides the Line Detail “Qty Inv.”.
Provides the Line Detail “Unit Cost”.
Provides the Line Detail “Disc %”. Only applied if present and <Invoice / InvoiceLine / PercentDiscount / QualifyingTerms / @Code> is not “LPI” (any case).
Used by FMS to determine the FMS VAT Code for the line for both Invoice and Credit Note.
Provides the Line Detail “Net Amount” for both Invoice and Credit Note.
Used to determine the FMS VAT Code for the tax rate and identifies the VAT summary line to validate for both Invoice and Credit Note.
Used to validate the total VAT for the FMS VAT Code determined by the above tag item. The VAT summary line will be updated to match the XML file value for both Invoice and Credit Note.
Provides the Invoice “Invoice Total”, the Credit Note “Credit Note Total”.
The purpose of this document is to define how to implement a web service that will be compatible with the FMS E Procurement system.
This document details all the standards that need to be followed to create an e-procurement web service that can interface with the FMS system. All of these standards will need to be followed explicitly for FMS to be able to access the Web Service.
The documented details include:
This document does not detail out any business rules regarding what is contained within the e-procurement documents of the system, other than what XML schemas they should be validated against.
Each e-procurement web service must support the following methods, soap header, exceptions and namespace at the bare minimum, ensuring the method name, parameter names, parameter types and return value type match.
If required the web service may support additional methods but these will not be accessed by FMS.
The web service must be located on a public internet URL and must use SSL to encrypt all data transferred. The web service will be protected by a Soap Header (AuthHeader) to allow for application level security, HTTP authentication will not be supported.
This method is used by the client to change the connection password of the current authenticated user. The method will return the new password that has been assigned.
There should be no constraints on the number of times this method is called.
Passwords should have a minimum life of 60 days to prevent them needing to be reset over the summer holidays.
This method has no parameters.
A string containing the new password for the logged in user will be returned from this method call.
FMS will be configured to handle the following exceptions from this method. The description of each exception type is shown in section 0 below.
This method will require authentication through the AuthHeader Soap Header.
This method returns an XML string that contains the id, type and create date of all documents that have not been processed and are awaiting collection by the connecting organisation. The document id should be no longer than 100 characters long and must not contain any spaces.
The types of document that can be returned in the XML are:
Please note that FMS does not currently support quotes so these documents will not be downloaded or processed when they appear in the index.
Documents that are not downloaded should expire after a designated period and then be removed. This length of this period should be discussed with ESS.
Only documents that the current authenticated user has access to should be returned in this call.
This method has no parameters.
A string containing XML that adheres to the Fetch Index XML Schema that is defined in section 0 below.
FMS will be configured to handle the following exceptions from this method. The description of each exception type is shown in section 0 below.
This method will require authentication through the AuthHeader Soap Header.
This method, similar to the FetchIndex method, returns an XML string that contains the name, type and create date of all documents that were created after the specified BeginDate parameter. This method will return documents that have and have not been processed.
Only documents that the current authenticated user has access to should be returned in this call.
The BeginDate dateTime parameter in the WSDL must be a valid dateTime XML Schema data type and indicates the date and time value to retreive all documents from.
The returned value will be a string containing XML that adheres to the Fetch Index XML Schema, defined in section 0 below.
FMS will be configured to handle the following exceptions from this method. The description of each exception type is shown in section 0 below.
This method will require authentication through the AuthHeader Soap Header.
This method is used to update a documents status to be processed or unprocessed. Once a document is marked as processed it will not be returned in the next FetchIndex call. It will normally be used to mark an unprocessed document as processed but should also allow for a processed document to be marked as unprocessed.
DocID is a string value that specifies the document ID to update. This ID will match the ID of the document returned in the FetchIndex XML.
Processed is a Boolean value that specifies whether the document has been processed or not.
This method will return a Boolean true value if the call was successful. If the call was not successful then a soap exception should be thrown.
FMS will be configured to handle the following exceptions from this method. The description of each exception type is shown in section 0 below.
This method will require authentication through the AuthHeader Soap Header.
This method is used to return the Contents of the specified document. All documents must be in XML and must be validated against the appropriate XML Schema detailed in section 0 below.
Calling this method should not affect a documents processed status.
DocID is a string value that specifies the document ID to retrieve. This ID will match the ID of the document returned in the FetchIndex XML.
This method will return a string value containing the Contents of the specified document.
FMS will be configured to handle the following exceptions from this method. The description of each exception type is shown in section 0 below.
This method will require authentication through the AuthHeader Soap Header.
This method is used to send the XML of Purchase Order to the web service from FMS. The XML that is sent must conform to the eBIS-XML-UKGov Order 3.09 XML schema.
Document is the XML string of a purchase order.
This method will return a Boolean true value if the call was successful. If the call was not successful then a soap exception should be thrown.
FMS will be configured to handle the following exceptions from this method. The description of each exception type is shown in section 0 below.
This method will require authentication through the AuthHeader Soap Header.
This method must only be made available during the development and testing phases. It should not be made available in a live environment.
This method resets all status of all documents assigned to the currently logged on user to be unprocessed.
This method has no parameters.
This method will return a Boolean true value if the call was successful. If the call was not successful then a soap exception should be thrown.
FMS will be configured to handle the following exceptions from this method. The description of each exception type is shown in section 0 below.
This method will require authentication through the AuthHeader Soap Header.
This Soap Header should be passed on every method call and will be used for authenticating the user against the web service.
Only this Soap Header should be used for authenticating against the web service, other types of authentication such as HTTP, will not be supported.
Username is a string parameter that identifies the user to be logged onto the web service. The username string can be up to 50 characters long.
Password is a string parameter that identifies the password of the user. The password string can be up to 256 characters long.
To prevent any cross system incompatibilities any exceptions that are thrown from the web service will be a Soap Exception whose type will be identified by the exception message itself. There are three identified exceptions that can be thrown from the system whose message should be formatted in the following format:
[Exception Type]:[Exception Message]
This exception can be thrown from any of the web methods in the service and will be thrown if the login credentials passed in the AuthHeader are invalid.
The message should be outputted in the following format:
AuthenticationException:[Exception Message]
This exception can be thrown from the UpdateDocumentStatus and FetchDoc web methods and is thrown if the supplied document id cannot be found. This exception will also be thrown if the document does exist but the current authenticated user does not have access to it.
The message should be outputted in the following format:
DocumentNotExistException:[Exception Message]
This exception can be thrown from the SendOrder web method and will be thrown if the purchase order XML that is passed as a parameter does not validate against the appropriate XML schema or if it contains any invalid data.
The message should be outputted in the following format:
InvalidXmlException:[Exception Message]
The namespace URL of the web service will need to be the following value for it to work with FMS.
http://www.dcsf.gov.uk/open/webservices/ots
The web service name should be called EProcurementService.
The application will be making extensive use of XML, to prevent any invalid XML being passed XML Schemas should be used to validate any XML before it is sent to us.
The following section details out all the different types of XML that will be passed across the system and the XML schema that should be used for each type.
Content Orders should be validated against the UK Gov Order schema version 3.09.
Invoices should be validated against the BASDA Invoice schema version 3.09.
Credit notes should be validated against the BASDA Invoice schema version 3.09.
Purchase orders should be validated against the UK Gov Order schema version 3.09.
This is an XML format that is solely used for this application.
The following code snippet details out the Contents of the FetchIndex xml schema file. This may not be the latest version, to get the latest version please contact ESS Partner support team.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xs:element name="doclist">
<xs:complexType>
<xs:sequence>
<xs:element ref="document" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="document">
<xs:complexType>
<xs:attribute name="uuid" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="100" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="type" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="order"/>
<xs:enumeration value="invoice"/>
<xs:enumeration value="creditnote"/>
<xs:enumeration value="quote"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="date" type="xs:dateTime" use="required"/>
</xs:complexType>
</xs:element>
</xs:schema>