FS 305796 Partnerlink EPOD Interfaces: Difference between revisions

From Calidus HUB
VisualWikitext
(v0.1 - Initial Creation)
 
(v0.3 - added details of a new Vigo-requested web service.)
 
(3 intermediate revisions by the same user not shown)
Line 4: Line 4:
{{#vardefine:System|''CALIDUS'' EPOD}}
{{#vardefine:System|''CALIDUS'' EPOD}}
{{#vardefine:Doc_Title|EPOD TMS Interfaces}}
{{#vardefine:Doc_Title|EPOD TMS Interfaces}}
{{#vardefine:Version|0.1}}
{{#vardefine:Version|0.3}}
{{#vardefine:Date|11th February 2013}}
{{#vardefine:Date|12th February 2013}}
{{#vardefine:Reference|305796}}
{{#vardefine:Reference|305796}}
{{#vardefine:Year|2013}}
{{#vardefine:Year|2013}}
Line 36: Line 36:
* All jobs marked as Palletforce job group require update messages sent to palletforce as well, in the palletforce formats.
* All jobs marked as Palletforce job group require update messages sent to palletforce as well, in the palletforce formats.


VIGO: To send out to the provided Vigo web service, using the OBS XML format
VIGO: To send out to the provided Vigo web service, using the OBS XML format. {{Note}} This may now be that the Vigo system will request the data specifically from our Job or Load web services. This is awaiting definition, but a tentative description is included below.
STIRLING: To send out to a specific folder a flat file, in CSV format. Naming convention of the file will be unique to the partner.
STIRLING: To send out to a specific folder a flat file, in CSV format. Naming convention of the file will be unique to the partner.
MANDATA: To send out to a specific folder a flat file, in CSV format. Naming convention of the file will be unique to the partner.
MANDATA: To send out to a specific folder a flat file, in CSV format. Naming convention of the file will be unique to the partner.
Line 63: Line 63:
''CALIDUS'' EPOD's configuration for exporting data is at Site (and to a much lesser extent, Job Group). This level configures both whether to export, and how (i.e. where to connect to, what to send, what format, etc).  
''CALIDUS'' EPOD's configuration for exporting data is at Site (and to a much lesser extent, Job Group). This level configures both whether to export, and how (i.e. where to connect to, what to send, what format, etc).  


* The system will hold configuration against Site L03 that says export to Knights of Old through a web service, in OBS XML format, to a defined web service address.
* The system will hold configuration against Site L03 that says export to Knights of Old through a web service, in OBS XML format, to a defined web service address. {{Note}} This may not be required.
* The system will hold configuration against all other sites that says export to the partner systems as a text file, in CSV format, to a defined shared folder.
* The system will hold configuration against all other sites that says export to the partner systems as a text file, in CSV format, to a defined shared folder.
* The system will hold configuration against the palletforce job group alone that says export out to the Palletforce destination, in this correct Palletforce format.
* The system will hold configuration against the palletforce job group alone that says export out to the Palletforce destination, in this correct Palletforce format.
Line 85: Line 85:
This specification chooses the latter option, which requires confirmation from the client.
This specification chooses the latter option, which requires confirmation from the client.


The way I understand it is so far is that both Stirling and Mandata will send in a CSV format (similar to JobShare, with additional fields).  
Both Stirling and Mandata will send in a CSV format (similar to JobShare, with additional fields). A mapping spreadsheet exists. Note that an extremely similar import has been done in the existing Upload.aspx for site PLINK. This will form the basis of this new import code. Sample files exist from Mandata to test against.
Questions:
* This file will be collected by EPOD via FTP. This requires a completely new EPOD process to be written to poll for message files coming in.
* How will they be delivering this CSV format to EPOD? Web Services or Flat File? I will assume flat file, but this requires confirmation. Note: If flat file on inbound, this requires a completely new EPOD process to be written to poll for message files coming in.
* EPOD will export completed or cancelled job data out in OBS XML format, in a flat file. This will be delivered via flat file FTP.
* I have messages from Deborah Burbridge of Mandata that say they will match OBS format when EPOD exports completed job data out to them. How will this be delivered, web services or flat file? Again, I will assume web services and requires confirmation.
* If there are flat file transfers on inbound, I need to know the file naming conventions to pick up the files. They should be providing me this information, but I understand if they want us to spell out a convention that's all-new for them.
* If there are flat file transfers on outbound, I need to know the file naming conventions. If they want to follow our formats, I will specify a naming format that includes the partner code somewhere.
* If I'm sending out via web services, the TMS suppliers will need to supply a web service, like we specified in the Vigo doc. As this is new development, I suspect that this will be in flat file, through folders, which is why I've assumed that for all (except Vigo of course).
<!-- NEW PAGE -->  
<!-- NEW PAGE -->  
= Set-up  =
= Set-up  =
Line 109: Line 105:
Site L01/L02/L04 set up as  
Site L01/L02/L04 set up as  
* [EPL_XF_DIRECTION] - "O"
* [EPL_XF_DIRECTION] - "O"
* [EPL_XF_TYPE] - "FILE"
* [EPL_XF_TYPE] - "FTP"
* [EPL_XF_DESTINATION] - defined shared folder
* [EPL_XF_DESTINATION] - FTP Server
* [EPL_XF_ID] - "PART"
* [EPL_XF_ID] - "PART"
* [EPL_EXPORT_FULLHEADERS] - "N"
* [EPL_EXPORT_FULLHEADERS] - "N"
* [EPL_WEB_PARAMETER] - file naming convention
* [EPL_WEB_PARAMETER] - file naming convention
* [EPL_WEB_USER] - Flag to indicate naming as TMP file first.
* [EPL_WEB_USER] - FTP User
* [EPL_WEB_PASSWORD]
* [EPL_WEB_PASSWORD] - FTP Password
* [EPL_SOAP_ACTION]
* [EPL_SOAP_ACTION]
* [EPL_SOAP_NS]
* [EPL_SOAP_NS]
Line 121: Line 117:
and  
and  
* [EPL_XF_DIRECTION] - "I"
* [EPL_XF_DIRECTION] - "I"
* [EPL_XF_TYPE] - "FILE"
* [EPL_XF_TYPE] - "FTP"
* [EPL_XF_DESTINATION] - defined shared folder
* [EPL_XF_DESTINATION] - FTP Server
* [EPL_XF_ID] - "PART"
* [EPL_XF_ID] - "PART"
* [EPL_EXPORT_FULLHEADERS] - "N"
* [EPL_EXPORT_FULLHEADERS] - "N"
* [EPL_WEB_PARAMETER] - file naming convention
* [EPL_WEB_PARAMETER] - file naming convention
* [EPL_WEB_USER]
* [EPL_WEB_USER] - FTP User
* [EPL_WEB_PASSWORD]
* [EPL_WEB_PASSWORD] - FTP Password
* [EPL_SOAP_ACTION]
* [EPL_SOAP_ACTION]
* [EPL_SOAP_NS]
* [EPL_SOAP_NS]
Line 144: Line 140:
* [EPL_SOAP_NS] - other Webservice parameters, as defined.
* [EPL_SOAP_NS] - other Webservice parameters, as defined.
* [EPL_SOAP_NS_PREFIX] - other Webservice parameters, as defined.
* [EPL_SOAP_NS_PREFIX] - other Webservice parameters, as defined.
{{Note}} If the Vigo system is retrieving this data directly, this is not required.


Job Group "PALLET" set up as  
Job Group "PALLET" set up as  
* [EPL_XF_DIRECTION] - "O"
* [EPL_XF_DIRECTION] - "O"
* [EPL_XF_TYPE] - "FILE"
* [EPL_XF_TYPE] - "FTP"
* [EPL_XF_DESTINATION] - defined shared folder
* [EPL_XF_DESTINATION] - FTP Server
* [EPL_XF_ID] - "PF"
* [EPL_XF_ID] - "PF"
* [EPL_EXPORT_FULLHEADERS] - "N"
* [EPL_EXPORT_FULLHEADERS] - "N"
* [EPL_WEB_PARAMETER]
* [EPL_WEB_PARAMETER]
* [EPL_WEB_USER]
* [EPL_WEB_USER] - FTP User
* [EPL_WEB_PASSWORD]
* [EPL_WEB_PASSWORD] - FTP Password
* [EPL_SOAP_ACTION]
* [EPL_SOAP_ACTION]
* [EPL_SOAP_NS]
* [EPL_SOAP_NS]
Line 169: Line 166:
All data currently on table EPOD_XF_CONFIG will have the value of EPL_XF_DIRECTION set to "O".
All data currently on table EPOD_XF_CONFIG will have the value of EPL_XF_DIRECTION set to "O".


All packages that currectly access EPOD_XF_CONFIG will be modified to ensure that they link to this table explicitly for EPL_XF_DIRECTION = "O". Additionally, they will also be modified to check for jobs with EPL_XFER_FLAG = "P" as well as "N", so that they will retrieve jobs that are partially sent.
All packages that currently access EPOD_XF_CONFIG will be modified to ensure that they link to this table explicitly for EPL_XF_DIRECTION = "O". Additionally, they will also be modified to check for jobs with EPL_XFER_FLAG = "P" as well as "N", so that they will retrieve jobs that are partially sent.


== Inbound Process ==
== Inbound Process ==
Line 176: Line 173:
This will retrieve all sites with Inbound XF Configuration.
This will retrieve all sites with Inbound XF Configuration.


In sequence, it will check all directories identified for all files matching the specification.
In sequence, it will check all directories identified for all files matching the specification, via FTP.


Depending on the ID, these files will then be processed. initially this process will support only type "PART".
Depending on the ID, these files will then be processed. initially this process will support only type "PART".
Line 184: Line 181:
* Job Group
* Job Group
* Owning Partner
* Owning Partner
* others TBC
A mapping spreadsheet has been created showing all the fields and their destinations.


An audit record will be written per job uploaded, indicating the job and load, and the file in which it was imported.  
An audit record will be written per job uploaded, indicating the job and load, and the file in which it was imported.  
Line 194: Line 191:


The process will:
The process will:
* Retrieve all jobs with XFER Flag = "P" or "N".
Retrieve all jobs with XFER Flag = "P" or "N" that have a "PART"-type XF-CONFIG.
 
* For each job:
* For each job:
** Create the file in the format identified (OBS XML format)
** Extract the data in OBS format XML into a string.
** If the XFER Flag is "N", or if "P" and the first character of XF_VALUES is "N":
*** Create the file in the format identified (OBS XML format) for the Operating Partner, as a TMP file.
*** FTP to destination and rename to CSV file.
*** Mark the first character of EPL_XF_VALUES = "Y".
** If the job has an Owning Partner different to the Operating Partner:
*** Retrieve the Site and XF Config associated.
*** If not found, set EPL_XF_VALUES 2nd character to "Y".
*** If found and type PART and the 2nd character of EPL_XF_VALUES = "N":
**** Create the file in the format identified (OBS XML format) for the Owning Partner, as a TMP file.
**** FTP to destination and rename to CSV file.
**** Mark the 2nd character of EPL_XF_VALUES = "Y".
** Retrieve the Job Group and XF Config associated (if set to "PALLET").
*** If not found, set EPL_XF_VALUES 3rd character to "Y".
*** If found and type PF and the 3rd character of EPL_XF_VALUES = "N":
**** Create the file in the format identified (Palletforce format, as can be seen in the existing code PFExport.aspx).
**** FTP to destination..
**** Mark the 3rd character of EPL_XF_VALUES = "Y".


An audit record will be written per job uploaded, indicating the job and load, and the file in which it was exported, per export completed.


If this fails, an audit record will be written, indicating the issue with the job.


== New Web-service Job Request ==
Optionally, Vigo have requested that a web service be created so that they can request the jobs not yet sent.


In this instance:
* All jobs with interface flag of "N" will be polled.
* If found, all jobs' XML will be created and returned in one record.
* All jobs will be marked as interfaced (EPL_XFER_FLAG = "Y").


 
This new webservice request will be called EPOD_EXPORT_JOB_COMPLETE, with the response called EPOD_EXPORT_JOB_COMPLETE_RESPONSE. This should be created under ePOD_dataservice and ePOD_dataservice2.
 
# New processes as part of the Job data objects to export in CSV format as required.
# New processes as part of the Job data object to export in Palletforce formats as required.
# Parameters required for these additional outbound processors (how to transport the file, where to put the file, naming of the file, etc).
# Parameters required on the Job records to indicate whether the messages have been sent to these systems.
 
 
 
 


<!-- MEDIA LANDSCAPE NO -->  
<!-- MEDIA LANDSCAPE NO -->  

Latest revision as of 12:32, 12 February 2013





Aptean Logo.png







PartnerLink

EPOD TMS Interfaces

CALIDUS EPOD

12th February 2013 - 0.3
Reference: FS 305796











































Functional Overview

The document is intended to describe the exact requirements for the TMS system interfacing to and from the CALIDUS EPOD system.

Client Requirement

INBOUND VIGO: To send in over the existing Web Services, using the OBS XML format STIRLING: To send in, over flat file transfer, using CSV format, similar to JobShare format. MANDATA: Identical to above.

OUTBOUND NOTES:

  • All jobs completed or cancelled will be exported out to the partner indicated in the Site ID, in their required formats, by their required mechanism.
  • All jobs marked as JobShare jobs (with Owner and Site different values), require update messages sent to the Owning partner indicated as well, in their required formats, by their required mechanism.
  • All jobs marked as Palletforce job group require update messages sent to palletforce as well, in the palletforce formats.

VIGO: To send out to the provided Vigo web service, using the OBS XML format. Note Note: This may now be that the Vigo system will request the data specifically from our Job or Load web services. This is awaiting definition, but a tentative description is included below. STIRLING: To send out to a specific folder a flat file, in CSV format. Naming convention of the file will be unique to the partner. MANDATA: To send out to a specific folder a flat file, in CSV format. Naming convention of the file will be unique to the partner.

Work required:

  1. New process to troll for inbound files on a timed basis.
  2. Parameters required for this inbound processor (i.e., where to look, what to look for, etc).
  3. New processes to import Loads and Jobs in CSV format as required (based on existing Trial import).
  4. New processes as part of the Job data objects to export in CSV format as required.
  5. New processes as part of the Job data object to export in Palletforce formats as required.
  6. Parameters required for these additional outbound processors (how to transport the file, where to put the file, naming of the file, etc).
  7. Parameters required on the Job records to indicate whether the messages have been sent to these systems.

Solution Overview

In normal operation, a job has a Site, an Owner and a Job Group. These will define, in order:

  • Executing (operating) partner
  • Owning Partner
  • whether this is a Palletforce job

A job is operated by the partner identified in the Site ID field. So, a job is received for Site "L03", it is a "Knights of Old" job.

A job is Owned by the partner identified in the Owner Name field. So, if the Owner is also L03, it's a standard partner-operated job. If it isn't, it's been shared.

The Job Group will be set for all jobs to a generic pre-agreed value ("PART"). If the job group is 'PALLET', it is a palletforce job.

CALIDUS EPOD's configuration for exporting data is at Site (and to a much lesser extent, Job Group). This level configures both whether to export, and how (i.e. where to connect to, what to send, what format, etc).

  • The system will hold configuration against Site L03 that says export to Knights of Old through a web service, in OBS XML format, to a defined web service address. Note Note: This may not be required.
  • The system will hold configuration against all other sites that says export to the partner systems as a text file, in CSV format, to a defined shared folder.
  • The system will hold configuration against the palletforce job group alone that says export out to the Palletforce destination, in this correct Palletforce format.
  • The system will link from the Owner against the job to the Site configuration to find out where to export for a shared job.

Scope

Multiple systems per partner cannot be supported without additional work within the TMS systems.

KOO ("L03") could be coming from Vigo (webservice) or Stirling (flat file). This would depend on how EPOD received it. Unless these are imported as separate sites (and the same in the Owner when this is shared, which requires the TMSs to do a some work as well), EPOD can't work out the return destination and would export out to whatever the standard site code says we should (as stated above, a web service).

Even if we hold a flag against the job, saying it came from Stirling or not, wouldn't work when it was shared, in the example where the KOO site using Stirling shares a job with another partner (for example, AKW, L01, etc), so L01 sends through:

  • Site: L01
  • Job X (a unique ID)
  • Owner L03

We send it back to the webservice for L03, which is wrong - it should have gone to the CSV instead.

The only solutions to this issue are:

  • Different site code (i.e. L03-V and L03-S) operated for the two KOO sites on different systems.
  • Ignore (i.e. assume the Partnerlink operation will consolidate onto one system before go-live).

This specification chooses the latter option, which requires confirmation from the client.

Both Stirling and Mandata will send in a CSV format (similar to JobShare, with additional fields). A mapping spreadsheet exists. Note that an extremely similar import has been done in the existing Upload.aspx for site PLINK. This will form the basis of this new import code. Sample files exist from Mandata to test against.

  • This file will be collected by EPOD via FTP. This requires a completely new EPOD process to be written to poll for message files coming in.
  • EPOD will export completed or cancelled job data out in OBS XML format, in a flat file. This will be delivered via flat file FTP.

Set-up

Pre-requisites

Menu Structure

None

Data

Table EPOD_XF_CONFIG

New EPL_XF_ID values of "PART" and "PF".

New EPL_XF_DIRECTION field, with values of "I" or "O". Default value "O". Indexed.

Site L01/L02/L04 set up as

  • [EPL_XF_DIRECTION] - "O"
  • [EPL_XF_TYPE] - "FTP"
  • [EPL_XF_DESTINATION] - FTP Server
  • [EPL_XF_ID] - "PART"
  • [EPL_EXPORT_FULLHEADERS] - "N"
  • [EPL_WEB_PARAMETER] - file naming convention
  • [EPL_WEB_USER] - FTP User
  • [EPL_WEB_PASSWORD] - FTP Password
  • [EPL_SOAP_ACTION]
  • [EPL_SOAP_NS]
  • [EPL_SOAP_NS_PREFIX]

and

  • [EPL_XF_DIRECTION] - "I"
  • [EPL_XF_TYPE] - "FTP"
  • [EPL_XF_DESTINATION] - FTP Server
  • [EPL_XF_ID] - "PART"
  • [EPL_EXPORT_FULLHEADERS] - "N"
  • [EPL_WEB_PARAMETER] - file naming convention
  • [EPL_WEB_USER] - FTP User
  • [EPL_WEB_PASSWORD] - FTP Password
  • [EPL_SOAP_ACTION]
  • [EPL_SOAP_NS]
  • [EPL_SOAP_NS_PREFIX]

Site L03 set up as

  • [EPL_XF_DIRECTION] - "O"
  • [EPL_XF_TYPE] - "SOAP"
  • [EPL_XF_DESTINATION] - URL of webservice
  • [EPL_XF_ID] - "PART"
  • [EPL_EXPORT_FULLHEADERS] - "N"
  • [EPL_WEB_PARAMETER]
  • [EPL_WEB_USER]
  • [EPL_WEB_PASSWORD]
  • [EPL_SOAP_ACTION] - Action to call on web service
  • [EPL_SOAP_NS] - other Webservice parameters, as defined.
  • [EPL_SOAP_NS_PREFIX] - other Webservice parameters, as defined.

Note Note: If the Vigo system is retrieving this data directly, this is not required.

Job Group "PALLET" set up as

  • [EPL_XF_DIRECTION] - "O"
  • [EPL_XF_TYPE] - "FTP"
  • [EPL_XF_DESTINATION] - FTP Server
  • [EPL_XF_ID] - "PF"
  • [EPL_EXPORT_FULLHEADERS] - "N"
  • [EPL_WEB_PARAMETER]
  • [EPL_WEB_USER] - FTP User
  • [EPL_WEB_PASSWORD] - FTP Password
  • [EPL_SOAP_ACTION]
  • [EPL_SOAP_NS]
  • [EPL_SOAP_NS_PREFIX]

Table EPOD_JOB

Add new field EPL_XF_VALUES, 10 characters, default ' '.

Functional Description

Database

Modifications will be made to the database fields as described.

All data currently on table EPOD_XF_CONFIG will have the value of EPL_XF_DIRECTION set to "O".

All packages that currently access EPOD_XF_CONFIG will be modified to ensure that they link to this table explicitly for EPL_XF_DIRECTION = "O". Additionally, they will also be modified to check for jobs with EPL_XFER_FLAG = "P" as well as "N", so that they will retrieve jobs that are partially sent.

Inbound Process

A new process will be built, based on the AutoExport process.

This will retrieve all sites with Inbound XF Configuration.

In sequence, it will check all directories identified for all files matching the specification, via FTP.

Depending on the ID, these files will then be processed. initially this process will support only type "PART".

This will upload the files into the EPOD system, utilising a format similar to the Partnerlink Upload process. Additional fields will be specified, unknown at this time, but must also include:

  • Site ID
  • Job Group
  • Owning Partner

A mapping spreadsheet has been created showing all the fields and their destinations.

An audit record will be written per job uploaded, indicating the job and load, and the file in which it was imported.

If this fails, an audit record will be written, indicating the issue with the job.

Outbound Process

A new outbound process will be written, based on the ID "PART".

The process will: Retrieve all jobs with XFER Flag = "P" or "N" that have a "PART"-type XF-CONFIG.

  • For each job:
    • Extract the data in OBS format XML into a string.
    • If the XFER Flag is "N", or if "P" and the first character of XF_VALUES is "N":
      • Create the file in the format identified (OBS XML format) for the Operating Partner, as a TMP file.
      • FTP to destination and rename to CSV file.
      • Mark the first character of EPL_XF_VALUES = "Y".
    • If the job has an Owning Partner different to the Operating Partner:
      • Retrieve the Site and XF Config associated.
      • If not found, set EPL_XF_VALUES 2nd character to "Y".
      • If found and type PART and the 2nd character of EPL_XF_VALUES = "N":
        • Create the file in the format identified (OBS XML format) for the Owning Partner, as a TMP file.
        • FTP to destination and rename to CSV file.
        • Mark the 2nd character of EPL_XF_VALUES = "Y".
    • Retrieve the Job Group and XF Config associated (if set to "PALLET").
      • If not found, set EPL_XF_VALUES 3rd character to "Y".
      • If found and type PF and the 3rd character of EPL_XF_VALUES = "N":
        • Create the file in the format identified (Palletforce format, as can be seen in the existing code PFExport.aspx).
        • FTP to destination..
        • Mark the 3rd character of EPL_XF_VALUES = "Y".

An audit record will be written per job uploaded, indicating the job and load, and the file in which it was exported, per export completed.

If this fails, an audit record will be written, indicating the issue with the job.

New Web-service Job Request

Optionally, Vigo have requested that a web service be created so that they can request the jobs not yet sent.

In this instance:

  • All jobs with interface flag of "N" will be polled.
  • If found, all jobs' XML will be created and returned in one record.
  • All jobs will be marked as interfaced (EPL_XFER_FLAG = "Y").

This new webservice request will be called EPOD_EXPORT_JOB_COMPLETE, with the response called EPOD_EXPORT_JOB_COMPLETE_RESPONSE. This should be created under ePOD_dataservice and ePOD_dataservice2.


Appendix A: Document References

A.1 References

Ref NoDocument Title & IDVersionDate
1   


A.2 Glossary

Term Definition
EPOD Electronic Proof of Delivery. The OBS EPOD system is CALIDUS ePOD.
CALIDUS eSERV The OBS mobile system to complete Service functionality in the field. This is part of the CALIDUS ePOD system.
PDA The mobile device on which the C-ePOD system will run in the field. This can be a Phone, EDA or industrial PDA, running Android.
DAL Data Access Layer. A mechanism for accessing data by the system that is removed from the application, allowing for simplified access and providing protection to the data, as only approved DAL methods can be used to modify it.
GPS Global Positioning System. A mechanism of retrieving accurate positioning information in the form of Latitude and Longitude (Lat-Long) co-ordinates from a device.
GPRS, 3G, HSDPA, Data Service All terms referring to mobile device network connectivity, and the speed at which the device connects to the internet.


A.3 Authorised By


Andrew Allison
Client Representative		_____________________________
Retrieved from ‘https://calidusassist.adcservices.apteancloud.com/calidus-assist/OBS/index.php?title=FS_305796_Partnerlink_EPOD_Interfaces&oldid=1009’