===== XML Processor =====

The TSM XML Processor is used to process data from a third party source for the purpose of creating or updating TSM job records.

This document will describe how to create an XML document for direct import to TSM.  

As this is a direct import, the TSM application has no control over the quality or suitability of the data being imported – it is up to the XML developer to ensure that the data provided is free from errors and that the data is mapped correctly.  Importing incorrect data can result in inconsistencies and errors in the TSM application which may need to be repaired by the TSM Support department at a cost.

If the data needs additional parsing or processing before being imported to TSM, please provide support@theservicemanager.com with a specification of what is required and you will be provided with an estimate to write the parser.

The TSM Support team should be contacted if you require clarification or assistance with testing.


Basic XML example:

  <?TSMXML Version="OZ1.0"?> 
  <TSM_JOB>

  <JOB_DETAIL>
    <SERVCARDID>6329</SERVCARDID> 
    <Job_WorkPerf>Attended job. Pumped down system and removed old evaporator.</Job_WorkPerf> 
  </JOB_DETAIL>

  <TSM_PART>
  <PRODUCTID>EQ2</PRODUCTID> 
  <QTY>1</QTY> 
  </TSM_PART>
  <TSM_PART>
  <PRODUCTID>S3</PRODUCTID> 
  <QTY>3</QTY> 
  </TSM_PART>

  <TSM_TIME>
  <DATE>21/04/2006</DATE> 
  <EMPLOYEEID>RICHARD</EMPLOYEEID> 
  <START>15:00</START> 
  <FINISH>18:10</FINISH> 
  </TSM_TIME>

  </TSM_JOB>


 
The above example would be used to update an existing Job card.  

It shows: 
  *The job number
  *A description of the work performed
  *Two parts used records
  *One timesheet record

Additional fields can be used as described below.  

Not all of these fields need to be used and in some cases they may in fact cancel each other out.  

In most cases, if a field is already populated in the TSM job and that field is referenced in the XML being processed, the original value will be completely overwritten with the new data.

If the XML requires a field in TSM which is not present in this example, please contact TSM Support for clarification

Please refer to the comments after each tag for more information

Expanded XML, showing all commonly used fields:

<?TSMXML Version="OZ1.0"?> 
<TSM_JOB>
; The TSM_JOB tag indicates that this is a new job record.  A new XML Document should be used per TSM Job

<JOB_CUSTOMER>
; Determines that this section is for customer related data.
<CUSTOMERID>Coles866</CUSTOMERID>
; This is the Customer ID for the job.  Should only be used for new jobs. 
If this matches a customer record which already exists in TSM, the related fields (Company, Custcont, Phone) will be populated by TSM.  
If this Customer ID does not already exist in TSM, it will be created and the new record will be populated with the information from the XML

</JOB_CUSTOMER>

<JOB_BILLCUST>
; Determines that this section is for billing customer related data.

<CUSTOMERID>ColesHQ</CUSTOMERID>
; This is the Customer ID for the Billing customer on the job.  Should only be used for new jobs. 
If this matches a customer record which already exists in TSM, the related fields (Company, Custcont, Phone) will be populated by TSM.  
If this Customer ID does not already exist in TSM, it will be created and the new record will be populated with the information from the XML

</JOB_BILLCUST>

<JOB_SITECUST>
; Determines that this section is for site customer related data.

<CUSTOMERID>ColesHQ</CUSTOMERID>
; This is the Customer ID for the Site customer on the job.  Should only be used for new jobs. 
If this matches a customer record which already exists in TSM, the related fields (Company, Custcont, Phone) will be populated by TSM.  
If this Customer ID does not already exist in TSM, it will be created and the new record will be populated with the information from the XML

</JOB_SITECUST>

<JOB_DETAIL>
; Determines that the following fields refer to the whole TSM job

<SERVCARDID>6329</SERVCARDID>
; This is the job number we are updating.  
Must match the existing TSM Job number – you cannot make these up.  
If left blank, TSM will create a new job using the next available job number.  

<CUSTOMERID>Coles866</CUSTOMERID>
; This is the Customer ID for the job.  Do not use if Job_Customer / CustomerID is used.  This should only be used for new jobs.  CustomerIDs must match the existing code in TSM exactly.

<COMPANY>Coles Pavillion, 866</COMPANY>
; This is the full company name.  Do not use if Job_Customer / CustomerID is used.  This should only be used for new jobs.

<CUSTCONT>Brett Banfield</CUSTCONT>
; This is the contact person for the client (customerid).  Do not use if Job_Customer / CustomerID is used.  This should only be used for new jobs.

<PHONE>02 9269 0910</PHONE>
; Phone number for the Company requesting the work.  Do not use if Job_Customer / CustomerID is used.  This should only be used for new jobs.

<LOGGEDBY>Pedro Orokosaki</LOGGEDBY>
; This is the person who logged the job.


<BILLCUST>ColesHQ</BILLCUST>
; This is the Billing ID on the job, behaves the same as Customer ID but with billing information.  Do not use if Job_Billcust / CustomerID is used.  This should only be used for new jobs.  CustomerIDs must match the existing code in TSM exactly.

<SITEID>Coles866</SITEID>
; This is the Site ID on the Job, behaves the same as Customer ID but with site information.

<CONTACT>Pedro Orokosaki</CONTACT>
; This is the contact person for the Site.

<MOBILE>0400 000 000</MOBILE>
; Mobile phone number for the site contact person

<WORKPHONE>02 9000 0000</WORKPHONE>
; Phone number for the site.  If the SITEID is present, this will be inherited from the contact record for the site customer.

<EMAIL>email@host.com</EMAIL>
; Email address for the site.  If the SITEID is present, this will be inherited from the contact record for the site customer.

<FAX>02 9000 0001</FAX>
; Fax number for the site.  If the SITEID is present, this will be inherited from the contact record for the site customer.

<BILLING>67 Penny Lane</BILLING>
; Street address for the site.  Should not be used if the SITEID field is also used, or the job already has a SITEID.

<SITESUB>Liverpool</SITESUB>
; Suburb of the site.  Should not be used if the SITEID field is also used, or the job already has a SITEID.

<SITEPCODE>2099</SITEPCODE>
; Postcode of the site.  Should not be used if the SITEID field is also used, or the job already has a SITEID.

<SITESTATE>NSW</SITESTATE>
; State for the site.  Should not be used if the SITEID field is also used, or the job already has a SITEID.

<RECEIVED>24/04/2009 12:25</RECEIVED>
; Date field for reporting purposes.  Must be formatted as DD/MM/YYYY HH:mm.
Incorrectly formatted dates may cause problems in TSM.

<ORDERNO>1138</ORDERNO>
; Order number supplied by the customer.

<REFERENCE>TK421</REFERENCE>
; Reference number related to the job

<CUSTREF>TK421</CUSTREF>
; Reference number related to the job

<BOOKNUMBER>TK421</BOOKNUMBER>
; Reference number related to the job

<OTHER>Other text</OTHER>
; Field used for reporting / sorting.  This may be either plain text or a value from a list of pre-defined options. Check with the client.  

<OTHER2>Other text 2</OTHER2>
; Field used for reporting / sorting.  This may be either plain text or a value from a list of pre-defined options. Check with the client.  

<JOBNAME>Evaporator fail light is on in plant room #2</JOBNAME>
; This is the Job Name field on the job card.

<JOBDATE>24/04/2009 12:25</JOBDATE>
; Date field for reporting purposes.  Must be formatted as DD/MM/YYYY HH:mm.
Incorrectly formatted dates may cause problems in TSM.

<DEPT>CODE TEXT</DEPT>
; Code field used for reporting / sorting.  This field must be in upper case.  This field is a preset list – refer to the client and/or TSM Support for a list of available codes.

<PRIORITY>CODE TEXT</PRIORITY>
; Code field used for reporting/sorting/escalation.  This field must be in upper case.  This field is a preset list – refer to the client and/or TSM Support for a list of available codes.

<STATUSCODE>CODE TEXT</STATUSCODE>
; Code field used for reporting / sorting.  This field must be in upper case.  This field is a preset list – refer to the client and/or TSM Support for a list of available codes.

<SERVICECOD>CODE TEXT</SERVICECOD>
; Code field used for reporting / sorting.  Used in TSM for tracking Territory.  This field must be in upper case.  This field is a preset list – refer to the client and/or TSM Support for a list of available codes.

<JOBTYPE>CODE TEXT</JOB TYPE>
; Code field used for reporting / sorting.  This field must be in upper case.  This field is a preset list – refer to the client and/or TSM Support for a list of available codes.

<DEFLOC>CODE TEXT</DEFLOC>
; Code field used for reporting / sorting.  Also determines the Default Product location against the job.  This field must be in upper case.  This field is a preset list – refer to the client and/or TSM Support for a list of available codes.

<DEFLABTYPE>CODE TEXT</DEFLABTYPE>
; Code field used for reporting / sorting.  Also determines the Default Labour type for timesheets added in TSM for this job.  This field must be in upper case.  This field is a preset list – refer to the client and/or TSM Support for a list of available codes.

<PAYTYPE>CODE TEXT</PAYTYPE>
; This field must be in upper case.  This field is a preset list – refer to the client and/or TSM Support for a list of available codes.

<EMPLOYEEID>CODE TEXT</EMPLOYEEID>
; Field for the Primary Employee on the job.  This field is a preset list – refer to the client and/or TSM Support for a list of available codes.

<SERVREQUES>Attend site and investigate fail light in plant room # 2</SERVREQUES>
; This is the Service Requested Information.

<JOB_SERVREQUES>Attend site and investigate fail light in plant room # 2</JOB_SERVREQUES>
; This is the same as the SERVREQUES field, but will append the text to the end of the record rather than overwriting.  Use one or the other, not both.

<JOBNOTE>Avoid Jenny, she doesnt like us</JOBNOTE>
; This is a note on the job which the customer usually won’t see..

<JOB_JOBNOTE> Avoid Jenny, she doesnt like us </JOB_JOBNOTE>
; This is the same as the JOBNOTE field, but will append the text to the end of the record rather than overwriting. Use one or the other, not both.

<WORKPERF>Attended site and carried out work as requested.  Fan belt on number 3 fan will need replacing next visit.</WORKPERF>
; This is a summary of the work performed on the site

<JOB_JOBNOTE> Attended site and carried out work as requested.  Fan belt on number 3 fan will need replacing next visit. </JOB_JOBNOTE>
; This is the same as the WORKPERF field, but will append the text to the end of the record rather than overwriting.  Use one or the other, not both.

<COMMTIME>24/04/2009 12:25</COMMTIME>
; Date field for reporting purposes.  Must be formatted as DD/MM/YYYY HH:mm.
Incorrectly formatted dates may cause problems in TSM.

<FAULT>CODE TEXT</FAULT>
; This field must be in upper case.  This field is a preset list – refer to the client and/or TSM Support for a list of available codes.

<ACTION>CODE TEXT</ACTION>
; This field must be in upper case.  This field is a preset list – refer to the client and/or TSM Support for a list of available codes.  This is the repair code in TSM.

<DATECOMP>24/04/2009 12:25</DATECOMP>
; Date field for reporting purposes.  Providing this date will complete the job.  Must be formatted as DD/MM/YYYY HH:mm.  Incorrectly formatted dates may cause problems in TSM.

</JOB_DETAIL>
; Closes off the Job Detail section

<TSM_PART>
; Announces that we’re adding a part to this job.  Must use these tags for each new part line item (see simple example above)

<PRODUCTID>EQ2</PRODUCTID>
; This is this is the Product code for the part we’re adding.  Mandatory for each part being added.  If the Product ID exists in TSM, the related fields will be automatically populated with the correct information.

<DESCRIP>Freetext Description of Product</DESCRIP>
; Description of the product being added.  Will overwrite the inherited value from the Products table, if present.

<ACCOUNT>INSTALLATIONS</ACCOUNT>
; Cost Centre.  Code field used for reporting / sorting.  This field must be in upper case.  This field is a preset list – refer to the client and/or TSM Support for a list of available codes.

<EMPLOYEEID>CODE TEXT</EMPLOYEEID>
; Employee code of the person adding the part.  Not mandatory.  This field must be in upper case.  This field is a preset list – refer to the client and/or TSM Support for a list of available codes.


<COST>999.9999</COST>
;Cost of the item being added. Numeric, 4 decimals.  Ex Tax.  Will overwrite the inherited value from the Products table, if present.;

<QTY>999.99</QTY>
;Quantity of the item being added. Numeric, 2 decimals.  Mandatory.

<PRICE>999.9999</PRICE>
;Sell Price of the item being added.  Numeric, 4 decimals.  Ex Tax.  Will overwrite the inherited value from the Products table, if present.;

</TSM_PART>
; Indicates that this part entry is complete.  Use these tags again for the next product.

<TSM_TIME>
; Announces that we’re adding a timesheet record to the job.  These tags need to be reused every time we have a new timesheet line item.

<DATE>21/04/2006</DATE> 
; Date on the timesheet.  Dd/mm/yyyy 

<EMPLOYEEID>RICHARD</EMPLOYEEID> 
; Employee code for the person on the timesheet.  This field must be in upper case.  This field is a preset list – refer to the client and/or TSM Support for a list of available codes.

<START>15:00</START>> 
; Start time on the timesheet.  HH:mm.  24 hours time.

<FINISH>18:10</FINISH>
; Finish time on the timesheet.  HH:mm.  24 hours time.

<TSCOMMENT>Started work and did routine 24.</TSCOMMENT>
; Comments related to the timesheet record.  Will appear on the invoice

<TNOTE>Took so long because I lost my keys. </TNOTE>
; Comments related to the timesheet record.  Will not appear on the invoice.

</TSM_TIME>
; Indicates that this timesheet entry is complete.  Use these tags again for the next timesheet.

</TSM_JOB>
; Indicates that this job XML is complete.  Use a new XML file for the next job.