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

FMS6 - eProcurement Details

Outline

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:

  • The documentation and help files for FMS.

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

  1.        The required working knowledge of FMS, its processes, and the reasons for those processes. That formal training will acquired as needed through Capita Children’s Services.
  2.        Web Services and their implementation. Capita Children’s Services will not provide training or expertise in this area.
  3.         XML its use, implementation, or integration with other systems. Capita Children’s Services will not provide training or expertise in this area.

Process

Outline

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

  1.        A number of users are authorised by the establishment to access a purchasing web site provided by a supplier or suitable portal. The user is able to assemble a “shopping basket” of desired items. At point of checkout these are not paid for in the traditional manner, but are packaged as “Content Order” messages for transmission to the establishment via Web Service calls.
  2.        The establishment receives the “Content Order” message which is automatically saved in FMS as an unauthorised order and appears in the Purchase Order screen. This can be processed in the familiar manner meeting the requirements of budget control and authorisation as laid down in the Financial Regulations of the relevant Local Authority; alternatively it can undergo limited editing before authorisation, or can be discarded completely.
  3.        The Authorised Order is returned to the supplier using the same Web Service that sent the original Content Order to FMS.
  4.       Functionality included in FMS 6.132 Summer 2010, will allow Authorised Orders that have only been generated in FMS to be transferred via Web Services to the portal as well as Content Orders.
  5.        The supplier is able to queue suitable Invoice document messages for transmission to the establishment via Web Service calls. This only applicable when more than one Web Server has been defined in FMS.
  6.        The supplier is able to queue suitable Credit Note document messages for transmission to the establishment via Web Service calls. This only applicable when more than one Web Server has been defined in FMS.

Supported Documents

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

Transmission of Documents

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.

Orders

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. CAPITA Children’s Services is a certificated provider.

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.

Editing

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.

Encryption

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.

CAPITA Children’s Services is unable to provide support for encryption, beyond that normally provided to users of FMS under the terms of their support contract.

Invoices and Credit Notes

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”

Entity Heirachy for eGov 3.09
Entity Heirarchy

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

Language and Currency Validations.

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

  1.               include the century
  2.              not omit any leading zeroes for either the month and/or day.

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.

Customer – Supplier Recognition

Content Orders transferred via Web Services – FMS 6.124 Autumn 2009

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.

Content Orders transferred by email

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.

Invoices and Credit Notes

The handshake for Invoices and Credit Notes makes use of the DUNS numbers as identifiers for both supplier and establishment.

Import – Content Order

FMS attributes populated by import of a Content Order message.

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.

  • <Order / OrderHead / Parameters / Language>

First 2 characters should match (ignore case) Establishment Details | tab 3 System Parameters | System Language. If not fail import.

  • <Order / OrderHead / Parameters / DecimalSepartor>

Use to interpret values during import

  • <Order / OrderHead / Parameters / Precision>

If less than 2 decimals default pence as zero, if grater than 2 round to 2 decimal places.

  • <Order / OrderHead / TestFlag / Test / Mode>

Must be 0 (boolean zero) if not fail import. FMS does not support handling of test messages.

  • <Order / OrderHead / OrderType / Code>

Should be “CTO” if not fail import.

  • <Order / OrderHead / OrderCurrency / Currency / Code>

Should match Establishment Details | tab 3 System Parameters | Transaction Currency, if not fail import.

  • <Order / OrderHead / Checksum>

Calculated, must match the value +-1 tolerance from the XML File, if not fail import.

  • <Order / OrderReferences / ContractOrderReference>

Fills Supplier Details | tab 1 | Contract number

  • <Order / OrderDate>

Used to calculate the checksum

  • <Order / Supplier / SupplierReferences / BuyersCodeForSupplier>

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.

  • <Order / Supplier / SupplierReferences / TaxNumber>

Updates Supplier Details | tab1 | VAT Registration Number

  • <Order / Supplier / SupplierReferences / DUNS>

Ignored. NOTE: May be used later to confirm the supplier is correctly identified.

  • <Order / Supplier / Contact / Name>

Fills Order Header/ Supplier’s Contact Name, if available.

  • <Order / Supplier / Narrative>

Fills Order Header/ Supplier’s Order Reference, if available. Not used by FMS but returned in a confirmed order XML file.

  • <Order / Buyer / BuyerReferences / SuppliersCodeForBuyer>

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.

  • <Order / Buyer / BuyerReferences / DUNS>

Ignored. NOTE: May be used later to confirm the buyer is correctly identified.

  • <Order / Buyer / Contact / Name>

Supplier to enter users web site logon ID. Stored at order header level to indicate who raised the order on the web site.

  • <Order / OrderLine / Action>

If = “Original” add line to order otherwise ignore line.

  • <Order / OrderLine / LineNumber>

Fills Purchase Order Processing | Line Number

  • <Order / OrderLine / OrderLineReferences / ProjectCode>

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.

  • <Order / OrderLine / Originator / Contact / Name>

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.

  • <Order / OrderLine / Product / SuppliersProductCode>

Fills Order Line Details | Part number

  • <Order / OrderLine / Product / Description>

Fills Order Line Details | Description

  • <Order / OrderLine / Product / CommodityClass>

Fills Order Line Details/ Commodity class, if available. Not used by FMS but returned in a confirmed order XML file.

  • <Order / OrderLine / Quantity / UOMCode>

Fills Order Line Details | UOM Code, if available. Not used by FMS but returned in a confirmed order XML file.

  • <Order / OrderLine / Quantity / Amount>

Fills Order Line Details | Quantity. (NOTE: Integer required for FMS)

  • <Order / OrderLine / Price / UnitPrice>

Fills Order line Details | Unit Cost

  • <Order / OrderLine / LineTax / TaxRate>

Use to determine VAT Code in FMS

  • <Order / Narrative>

Fills Purchase Order Processing | Special instructions

  • <Order / OrderTotal / GoodsValue>

Used to calculate the checksum

Export – Authorised Order

FMS attributes exported to an Authorised Order message.

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.

  • <Order / OrderHead / Schema / Version>

Constant = Schema version currently supported by FMS e.g. "3.09-UKGov.20030911"

  • <Order / OrderHead / Parameters / Language>

Establishment Details | tab 3 System Parameters | System Language.

  • <Order / OrderHead / Parameters / DecimalSepartor>

Constant = “.”

  • <Order / OrderHead / Parameters / Precision>

Constant = “13.2”

  • <Order / OrderHead / OriginatingSoftware / SoftwareManufacturer>

Constant = “SIMS

  • <Order / OrderHead / OriginatingSoftware / SoftwareProduct>

Constant = “FMS6”

  • <Order / OrderHead / OriginatingSoftware / SoftwareVersion>

Constant = current FMS version.

  • <Order / OrderHead / TestFlag / Test / Mode>

Constant = “0” as a numeric. FMS does not support handling of test messages.

  • <Order / OrderHead>

A value is not be supplied

  • <Order / OrderHead / OrderType / Code>

Constant = “PUO”.

  • <Order / OrderHead / OrderType / CodeList>

Constant = “BASDA”

  • <Order / OrderHead / OrderType>

A value is not be supplied

  • <Order / OrderHead / Function / Code>

Constant = “original” for the first file, “copy” for all other files.

  • <Order / OrderHead / Function / CodeList>

Constant = “UKGov-DocStatus”

  • <Order / OrderHead / Function / Preserve>

Constant = “true”

  • <Order / OrderHead / Function>

A value is not be supplied

  • <Order / OrderHead / OrderCurrency / Currency / Code>

Establishment Details | tab 3 System Parameters | Transaction Currency.

  • <Order / OrderHead / OrderCurrency / Currency / CodeList>

Constant = “UKGov -CurrencyCode”

  • <Order / OrderHead / OrderCurrency / Currency>

A value is not be supplied

  • <Order / OrderHead / InvoiceCurrency / Currency / Code>

Establishment Details | tab 3 System Parameters | Transaction Currency.

  • <Order / OrderHead / InvoiceCurrency / Currency / CodeList>

Constant = “UKGov -CurrencyCode”

  • <Order / OrderHead / InvoiceCurrency / Currency>

A value is not be supplied

  • <Order / OrderHead / Checksum>

Calculate

  • <Order / OrderReferences / ContractOrderReference>

Supplier Details | tab 1 | Contract number

  • <Order / OrderReferences / TermConditions>

Accounts Payable Parameters | Tab 1 | Free Text

  • <Order / OrderReferences / BuyersOrderNumber / Preserve>

Constant = “true”

  • <Order / OrderReferences / BuyersOrderNumber>

Purchase Order Processing | Number

  • <Order / OrderDate / Preserve>

Constant = “true”

  • <Order / OrderDate>

Purchase Order Processing | Date

  • <Order / Supplier / SupplierReferences / BuyersCodeForSupplier>

Supplier Details | tab 5 | XML Supplier Reference

  • <Order / Supplier / SupplierReferences / TaxNumber>

Supplier Details | tab1 | VAT Registration Number

  • <Order / Supplier / SupplierReferences / GLN>

Set as Supplier Details | tab1 | “GLN | DUNs” if the supplier’s “GLN | DUNs” companion attribute = “GLN”

  • <Order / Supplier / SupplierReferences / DUNS>

Set as Supplier Details | tab1 | “GLN | DUNs” if the supplier’s “GLN | DUNs” companion attribute = “DUNs”

  • <Order / Supplier / Party>

Supplier Details | tab1 | Name

  • <Order / Supplier / Address / Addressline>

Supplier Details | tab 1 | Address. Repeat tag for each address line.

  • <Order / Supplier / Address / PostCode>

Supplier Details | tab 1 | Post Code.

  • <Order / Supplier / Contact / Name>

Supplier Details | tab 1 | Contact

  • <Order / Supplier / Contact / Switchboard>

Supplier Details | tab 1 | Telephone

  • <Order / Supplier / Contact / Fax>

Supplier Details | tab 1 | Fax

  • <Order / Supplier / Contact / Email>

Supplier Details | tab 1 | Email

  • <Order / Supplier / Narrative>

Order Header/ Order Reference, if available. Otherwise null.

  • <Order / Buyer / BuyerReferences / SuppliersCodeForBuyer>

Supplier Details | tab1 | Account Number

  • <Order / Buyer / BuyerReferences / TaxNumber>

Establishment Details | tab 1 | VAT Registration Number

  • <Order / Buyer / BuyerReferences / GLN>

Set as Establishment Details | tab1 | “GLN | DUNs” if the establishment’s “GLN | DUNs” companion attribute = “GLN”

  • <Order / Buyer / BuyerReferences / DUNS>

Set as Establishment Details | tab1 | “GLN | DUNs” if the establishment’s “GLN | DUNs” companion attribute = “DUNs”

  • <Order / Buyer / Party>

Establishment Details | tab1 | Name

  • <Order / Buyer / Address / AddresLine>

Establishment Details | tab 1 | Address. Repeat tag for each address line.

  • <Order / Buyer / Address / PostCode>

Establishment Details | tab 1 | Post Code

  • <Order / Buyer / Contact / SwitchBoard>

Establishment Details | tab1 | Telephone

  • <Order / Buyer / Contact / Fax>

Establishment Details | tab1 | Fax

  • <Order / InvoiceTo / InvoiceToReferences / TaxNumber>

Establishment Details | tab 1 | VAT Registration Number

  • <Order / InvoiceTo / InvoiceToReferences / GLN>

Set as Establishment Details | tab1 | “GLN | DUNs” if the establishment’s “GLN | DUNs” companion attribute = “GLN”

  • <Order / InvoiceTo / InvoiceToReferences / DUNS>

Set as Establishment Details | tab1 | “GLN | DUNs” if the establishment’s “GLN | DUNs” companion attribute = “DUNs”

  • <Order / InvoiceTo / Party>

Establishment Details | tab1 | Name

  • <Order / InvoiceTo / Addressline / AddressLine>

Establishment Details | tab 1 | Address. Repeat tag for each address line.

  • <Order / InvoiceTo / Addressline / PostCode>

Establishment Details | tab 1 | Post Code

  • <Order / InvoiceTo / Contact / SwitchBoard>

Establishment Details | tab1 | Telephone

  • <Order / InvoiceTo / Contact / Fax>

Establishment Details | tab1 | Fax

  • <Order / OrderLine / Action>

Constant = “Original”

  • <Order / OrderLine / LineNumber / Preserve>

Constant = “true”

  • <Order / OrderLine / LineNumber>

Purchase Order Processing | Line Number

  • <Order / OrderLine / Product / SuppliersProductCode>

Order Line Details | Part number

  • <Order / OrderLine / Product / Description>

Order Line Details | Description

  • <Order / OrderLine / Product / CommodityClass>

Order Line Details | Commodity class, if available otherwise constant = “00 00 00 00” (pairs of zeroes separated by single spaces)

  • <Order / OrderLine / Quantity / UOMCode>

Order Line Details | UOM Code, if available otherwise constant = “EA”

  • <Order / OrderLine / Quantity / Amount>

Order Line Details | Quantity.

Constant = 1 per line for a free text order.

  • <Order / OrderLine / Price / UnitPrice>

Order line Details | Unit Cost

  • <Order / OrderLine / NetLineTotal>

Purchase Order Processing | Line total

  • <Order / OrderLine / LineTotal>

Calculate

  • <Order / OrderLine / Delivery / DeliverTo / Party>

Order Head | Delivery Address Text. First line.

  • <Order / OrderLine / Delivery / DeliverTo / Address / AddressLine>

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.

  • <Order / OrderLine / Delivery / DeliverTo / Address / PostCode>

This will not be supplied.

NOTE: The delivery address from “Accounts Payable Parameters” is not sufficiently structured to reliably determine this.

  • <Order / OrderLine / Delivery / DeliverTo / Contact / SwitchBoard>

Establishment Details | Telephone

  • <Order / OrderLine / Delivery / DeliverTo / Contact / Fax>

Establishment Details | Fax

  • <Order / OrderLine / Delivery / PreferredDate>

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

  • <Order / OrderLine / Delivery / Narrative>

Purchase Order Processing | Delivery Instruction

  • <Order / OrderLine / ExtendedDescription>

Order Line Details | Order Unit

  • <Order / OrderLine / Narrative>

Order Line Details | ledger code + Order Line Details | fund. Format to be “<LedgerCode>-<Fund>” e.g. 1001-01.

  • <Order / Narrative>

Purchase Order Processing | Special instructions

  • <Order / OrderTotal / GoodsValue>

Calculated as total net goods value

  • <Order / OrderTotal / GrossValue>

Calculated as total gross goods value

Import – Invoice and Credit Note

FMS attributes populated by import of an Invoice or Credit Note message

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.

  • <Invoice / InvoiceHead / TestFlag / @Mode>

If present must be Boolean 0 (zero). Not present accepted.

  • <Invoice / InvoiceHead / InvoiceType / @Code>

Must be either “INV” or “CRN” (any case). Determines whether the message is treated as an Invoice (“INV”) or as a Credit Note (“CRN”).

  • <Invoice / InvoiceHead / InvoiceType / @Codelist>

Must be “BASDA” (any case). Other Code Lists are not recognised

  • <Invoice / InvoiceReferences / BuyersOrderNumber>

Provides the Invoice “Order Number, used to link the Invoice to the Order.

  • <Invoice / InvoiceReferences / SuppliersInvoiceNumber>

Provides the Invoice “Invoice Number”, the Credit Note “Credit Note Number”.

  • <Invoice / InvoiceReferences / GloballyUniqueID>

Stored by FMS if provided. Not currently used by or displayed in FMS.

  • <Invoice / Extensions / CN2InvoiceReferences / InvoiceNumber>

Provides the Credit Note “Invoice Number”, used to link the Credit Note to the Invoice.

  • <Invoice / Extensions / CN2InvoiceReferences / InvoiceGloballyUniqueID>

References the GUID of the Invoice being credited. Stored by FMS if provided. Not currently used by or displayed in FMS.

  • <Invoice / InvoiceDate>

Provides the Invoice “Invoice Date”, Credit Note “Credit Date”.

  • <Invoice / Supplier / SupplierReferences / DUNS>

Used to determine the Supplier within FMS. This determines the Invoice / Credit Note from name and address.

  • <Invoice / InvoiceLine / InvoiceLineReferences / OrderLineNumber>

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.

  • <Invoice / InvoiceLine / Product / SuppliersProductCode>

Provides the Line Detail “Part Number”

  • <Invoice / InvoiceLine / Product / Description>

Provides the Line Detail “Description” for both Invoice and Credit Note.

  • <Invoice / InvoiceLine / Product / Properties / Quantity / @UOMCode>

Stored by FMS if provided. Not currently used by or displayed in FMS.

  • <Invoice / InvoiceLine / LineNumber>

Provides the Line Detail “Line Number”.

  • <Invoice / InvoiceLine / Product / CommodityClass>

Stored by FMS if provided. Not currently used by or displayed in FMS.

  • <Invoice / InvoiceLine / Quantity / Amount>

Provides the Line Detail “Qty Inv.”.

  • <Invoice / InvoiceLine / Price / UnitPrice>

Provides the Line Detail “Unit Cost”.

  • <Invoice / InvoiceLine / PercentDiscount / Percentage>

Provides the Line Detail “Disc %”. Only applied if present and <Invoice / InvoiceLine / PercentDiscount / QualifyingTerms / @Code> is not “LPI” (any case).

  • <Invoice / InvoiceLine / LineTax / TaxRate >

Used by FMS to determine the FMS VAT Code for the line for both Invoice and Credit Note.

  • <Invoice / InvoiceLine / NetLineTotal>

Provides the Line Detail “Net Amount” for both Invoice and Credit Note.

  • <Invoice / TaxSubTotal / TaxRate>

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.

  • <Invoice / TaxSubTotal / TaxAtRate>

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.

  • <Invoice / InvoiceTotal / GrossPaymentTotal>

Provides the Invoice “Invoice Total”, the Credit Note “Credit Note Total”.

E Procurement Web Service Standards

1         Purpose

The purpose of this document is to define how to implement a web service that will be compatible with the FMS E Procurement system.

2         Overview

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:

  • The web methods that are required, including details of:
    • What they are used for
    • The parameter types and values
    • What data is returned from the method and the return data type
    • What exceptions can be thrown from the method
    • How this method is secured to a user
  • The soap headers that are required, including details of:
    • What they are used for
    • The parameter types and values
  • How exceptions should be handled
  • The namespace and name of the web service
  • The XML schemas used for validation

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.

3         Portal Web Service Definition Standard

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.

3.1         Web Methods

3.1.1    string ChangePassword();

Description

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.

Parameters

This method has no parameters.

Return value

A string containing the new password for the logged in user will be returned from this method call.

Expected Exceptions

FMS will be configured to handle the following exceptions from this method. The description of each exception type is shown in section 0 below.

  1. AuthenticationException
Security

This method will require authentication through the AuthHeader Soap Header.

3.1.2    string FetchIndex();

Description

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:

  1. order – Content Orders (not purchase orders)
  2. invoice – Invoices
  3. creditnote – Credit notes
  4. quote – Quotes

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 Capita Childrens Services.

Only documents that the current authenticated user has access to should be returned in this call.

Parameters

This method has no parameters.

Return value

A string containing XML that adheres to the Fetch Index XML Schema that is defined in section 0 below.

Expected Exceptions

FMS will be configured to handle the following exceptions from this method. The description of each exception type is shown in section 0 below.

  1. AuthenticationException
Security

This method will require authentication through the AuthHeader Soap Header.

3.1.3     string FetchIndexFromDate(DateTime BeginDate);

Description

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.

Parameters

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.

Return value

The returned value will be a string containing XML that adheres to the Fetch Index XML Schema, defined in section 0 below.

Expected Exceptions

FMS will be configured to handle the following exceptions from this method. The description of each exception type is shown in section 0 below.

  1. AuthenticationException
Security

This method will require authentication through the AuthHeader Soap Header.

3.1.4    bool UpdateDocumentStatus(string DocID, bool Processed);

Description

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.

Parameters

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.

Return value

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.

Expected Exceptions

FMS will be configured to handle the following exceptions from this method. The description of each exception type is shown in section 0 below.

  1. DocumentNotExistException
  2. AuthenticationException
Security

This method will require authentication through the AuthHeader Soap Header.

3.1.5    string FetchDoc(string DocID);

Description

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.

Parameters

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.

Return value

This method will return a string value containing the Contents of the specified document.

Expected Exceptions

FMS will be configured to handle the following exceptions from this method. The description of each exception type is shown in section 0 below.

  1. DocumentNotExistException
  2. AuthenticationException
Security

This method will require authentication through the AuthHeader Soap Header.

3.1.6    bool SendOrder(string Document);

Description

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.

Parameters

Document is the XML string of a purchase order.

Return value

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.

Expected Exceptions

FMS will be configured to handle the following exceptions from this method. The description of each exception type is shown in section 0 below.

  1. InvalidXmlException
  2. AuthenticationException
Security

This method will require authentication through the AuthHeader Soap Header.

3.1.7    bool ResetAll();

Description

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.

Parameters

This method has no parameters.

Return value

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.

Expected Exceptions

FMS will be configured to handle the following exceptions from this method. The description of each exception type is shown in section 0 below.

  1. AuthenticationException
Security

This method will require authentication through the AuthHeader Soap Header.

3.2         Soap Headers

3.2.1     AuthHeader(string Username, string Password);

Description

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.

Parameters

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.

3.3         Exceptions

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]

3.3.1     AuthenticationException

Description

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.

Exception message format

The message should be outputted in the following format:

AuthenticationException:[Exception Message]

3.3.2     DocumentNotExistException

Description

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.

Exception message format

The message should be outputted in the following format:

DocumentNotExistException:[Exception Message]

3.3.3     InvalidXmlException

Description

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.

Exception message format

The message should be outputted in the following format:

InvalidXmlException:[Exception Message]

3.4         Namespace

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

3.5         Web Service Name

The web service name should be called EProcurementService.

4         XML Schemas

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.

4.1         Content Orders

Content Orders should be validated against the UK Gov Order schema version 3.09.

4.2         Invoices

Invoices should be validated against the BASDA Invoice schema version 3.09.

4.3         Credit notes

Credit notes should be validated against the BASDA Invoice schema version 3.09.

4.4         Purchase Orders

Purchase orders should be validated against the UK Gov Order schema version 3.09.

4.5         Fetch Index XML

This is an XML format that is solely used for this application.

4.5.1     FetchIndex.xsd file

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 Capita Children’s Services.

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