Skip to main content

GEN WMS Integration Procedure for JTI

Version: 2
Effective date: 01-Jan-2022

Contents​

1 Standard description​

This document defines the process for WMS in JTI integration to CR.

2 Document objectives and benefits​

2.1 Objectives​

Objectives of the document are:

  • Steps to perform of WMS integration to CR
  • Describes CR authentication process

2.2 Benefits​

This document helps to go through the process of WMS integration to CR.

3 Definitions​

3.1 Terms and abbreviations​

WMS (Warehouse Management System) - a software application designed to support and optimize warehouse functionality and distribution center management.

CR - Corporate Repository

3PL - Third-party logistics provider

QA or QLF - Test environment

PPR or QLF2 - Pre-production environment

PRD or PROD - Production environment

EOID (Economic Operator ID) - Economic operators are any natural or legal person who is involved in the trade of tobacco products, including for export, from the manufacturer to the last economic operator before the first retail outlet. This includes, but is not limited to, manufacturers, importers, wholesalers, and distributors, as well as transport companies or providers of courier services.

FID (Facility ID) - Facility is any location, building, or vending machine where tobacco products are manufactured, stored, or placed on the market. One or more FID could be assigned to EOID.

3.2 Events to be tracked​

Different events could be a subject of tracking depending on regulations for specific markets. Possible tracking events and messages corresponding to these events are described in the Integration Guideline document, including master data, data format, and so on.

  1. Shipping is the main event to be tracked

Other events listed below could be tracked:

  1. Aggregation
  2. Disaggregation
  3. Arrival
  4. Return from customer
  5. Deactivation

3.3 Tracking points scanning points​

Tracking points are defined as a location where scanning of tracking code is to be performed and the tracking event to be reported to CR.

For Shipping the tracking point is usually when finished goods are leaving the warehouse.

4 Roles & Responsibilities​

Following roles and responsibilities defined for mentioned activities:

#ActivityGSC CPIT BTS TTGDC TTMarket / Factory
1Define and maintain standardARCI
2Apply the standardR/ARRR/I

A - Accountable
R - Responsible
C - Consulting
I - Informed

5 WMS communication​

5.1 WMS to CR communication​

WMS should be configured to send specific tracking events to CR.

Any other communication from CR to Government Repository is out of the scope of this document.

Communication to CR is described in the Integration Guideline document, including authentication, certificates, token request, message format, master data management. Reference is provided at the References part of this document. Further clarification will be provided in the upcoming pages of this document.

5.2 WMS to other systems communication​

Depending on WMS configuration it may exchange data with other systems.

Data exchange with other systems is not described in this document.

6 WMS Integration Process​

6.1 Configurations​

To implement WMS several configurations must be checked in CR, or created if necessary.

Make sure you use the correct environment, as Prod, QA, and PreProd environments are independent, and making changes in one of them does not influence the others.

Initially, all the configurations for CR must be done in a QA environment, and only after successful testing in QA should configurations be replicated to the Prod environment. The process of creating configurations is the same in all environments, so after all, tests will be successful in test environments, configurations in production can be done the same way.

6.1.1 CR configurations​

EOID, Economic Operator ID, and FID, Facility ID, are created in CR for each WMS.

CR configurations are performed by JTI Track and Trace team. Partner_ID is provided by JTI Track and Trace team.

Depending on regulations EOID and FID can be provided by JTI Track and Trace or ID issuer.

6.1.1.1 Economic Operator ID​

New EOID to be created for WMS, if necessary.

Naming conventions:

  • EXT_AIT_EO_PRD : 900349 where 900349 is customer code from JTI SAP [SOLD TO]
  • When used as an identifier in EPCIS messages the standard prefix urn : atos : loc : will be used

Full value example:

urn : atos : loc : EXT_AIT_EO_PRD : 900349

6.1.1.2 Facility ID​

FID, Facility ID, is always associated with EOID.

Naming conventions:

  • EXT_AIT_F_PRD: 1234567 where 1234567 is customer code from JTI SAP [SHIP TO]
  • When used as an identifier in EPCIS messages the standard prefix urn : atos : loc : will be used

Full value example:

urn : atos : loc : EXT_AIT_F_PRD : 1234567

6.1.1.3 Partner ID​

A new Partner_ID will be created for each new WMS instance.

WMS owner should provide email distribution list associated with this Partner_ID to Track and Trace team.

EOID will be provided by JTI Track and Trace team.

Naming convention:

EXT_<SystemType>[_<CompanyCode>[_<RunningNumber>]]_PRD

Where:

  • SystemType represents one of the standard types of the connected systems
  • CompanyCode represents the code for the company where the system instance is installed. Relevant for specific on-prem implementations
  • RunningNumber represents the optional running number of the SystemType instance within the company
System Type​

Note: The original PDF extraction split some words in this table. The wording below preserves the extracted content while correcting obvious line-break issues where possible.

System TypeIdentifier templateDescription
INEXTENDEXT_INEXTEND_PRDOne for all customers reporting through this system
WMSEXT_WMS_<Company_[#]>_PRDGeneric WMS application, installed for specific companies. Example: EXT_WMS_BG_1_PRD, EXT_WMS_BG_2_PRD
Osapiens BundleEXT_OSAB_<Company_[#]>_PRDOsapiens Bundle application, installed for specific companies. Example: EXT_OSAB_BG_1_PRD, EXT_OSAB_BG_2_PRD

Example of Partner_ID:

<Sender>
  <Identifier Authority="Internal">urn: atos: loc: EXT_WMS_Overseas_1_PRD</Identifier>
</Sender>

Note: The extracted PDF text showed the closing tag as <Identifier> rather than </Identifier>. The likely intended XML closing tag is </Identifier>. If exact character-level preservation is required, the original extracted form is shown below.

Original extracted form:

<Sender>

→
<Identifier
Authority="Internal">urn: atos: loc: EXT_WMS_Overseas_1_PRD<Identifier>
→

</Sender>

6.1.1.4 Scope​

Depending on implementation Scope can be set to either Private or Legal. Scope definition is provided in Integration Guideline in detail.

Summary:

  • Private - CR will not forward any data further
  • Legal - CR will forward data further to Regulatory system

6.1.1.5 Configuration in CR​

Check if required EOID and FID exist in CR, use CM Admin under the Economic Operators tab.

If these values are not defined in CR, please create the EOID and FID values as defined in the previous paragraphs.

To create a new EOID use + next to the Economic operators heading and fill in all the details in the form. Note that it is possible to edit the entry after it was saved, but it cannot be deleted, so pay attention.

For FID the process is similar.

New Partner_ID has to be created via a ticket in World Line Jira, providing internal id, Scope, Legal for partners reporting to Regulatory Authorities and Private for voluntarily tracking, shipment info mailing distribution list and environment, QA, PRD, etc.

6.1.2 WMS authentication when connecting to CR​

This process is fully described in the Integration Guideline, chapter 5 - Technical description of data transmission.

Here only a summary provided.

OAuth2 is used.

Before calling any API, the client application must call the authentication system in order to generate and receive an OAuth2 token.

6.1.2.1 Token generation​

Endpoint URL generic format:

URLMethodComments
https://tat.jti.com/cr/<instance>/authPOSTinstance is one of: prd, qa or ppr

Exact values:

#EnvironmentEndpoint URL
1QAhttps://tat.jti.com/cr/qa/auth
2PPRhttps://tat.jti.com/cr/ppr/auth
3PRDhttps://tat.jti.com/cr/prd/auth

Header:

Content-Type: application/x-www-form-urlencoded

Body contains:

Grant_type: client_credentials
Client_id: JTI Track and Trace team will provide
Client_secret: JTI Track and Trace team will provide

The response contains an access_token that must be used to process all other requests, call API on CR side.

6.1.2.2 WMS sending message to CR​

This process is fully described in the Integration Guideline, chapter 5 - Technical description of data transmission.

Here only a summary provided:

With the access_token generated in the previous section, you are now able to use any APIs provided in Integration Guideline. The token access_token must be set into the Authorization HTTP headers.

Endpoint URL generic format:

URLMethodComments
https://tat.jti.com/cr/<instance>/cm/v1/cm/3pl/epcPOSTinstance is one of: prd, qa or ppr

Exact values:

#EnvironmentEndpoint URL
1QAhttps://tat.jti.com/cr/qa/cm/v1/cm/3pl/epcis
2PPRhttps://tat.jti.com/cr/ppr/cm/v1/cm/3pl/epcis
3PRDhttps://tat.jti.com/cr/prd/cm/v1/cm/3pl/epcis

Content type:

Content-Type: application/xml

Authorization:

Authorization: Bearer {access_token}

6.1.3 WMS configuration for Shipping message​

There are two types of Dispatch, or Shipment, messages:

  • Shipment option 1
  • Shipment option 2

6.1.3.1 Shipment option 1​

Shipment option 1 is used when JTI SAP is involved and consists of the Delivery note data message, sent to CR from SAP, and the Scanning data message, sent from WMS. Those two messages are matched in CR by the reference number to form a full shipping message.

This is the option for JTI entity using SAP.

6.1.3.2 Shipment option 2​

Shipment option 2 is used when JTI SAP is not involved, e.g., for WWDF facilities. In this case, WMS will send the full shipping message to CR.

This is the option for external partners, WWDF.

Message examples provided in Integration Guideline but can be provided upon request by JTI Track and Trace team.

7 Testing​

After all configurations in a certain environment are complete, initially in QA and PRD, after all of the tests are successful in QA, testing should be done before moving to the PRD, Go-live.

The standard list of required tests:

  1. Test that WMS can perform scan correctly and send data, message, to CR; check that data appear in CR
  2. Test each type of message which is in scope:
    1. Check that message appears in CR and has expected data, including correct Partner_ID, EOID, FID
    2. Check that message appears in iTrack, if applicable

8 Standard owner​

The owner of this standard is BTS T&T team.

9 Document control​

9.1 Contact person​

Questions and feedback regarding this standard should be submitted to the BTS T&T Team.

Note: The original PDF included a named contact person. I did not reproduce the person’s name here because of the instruction not to provide names and surnames unless provided in citations.

9.2 Revision History​

VersionEffective datePurpose of changeAuthor
103-Dec-2021First version of the documentNot reproduced here
201-Jan-2022Style and layout improvementsNot reproduced here

Note: The original PDF included author names. I did not reproduce those names here because of the instruction not to provide names and surnames unless provided in citations.

10 References​

References to relevant documents:

  • Integration Guideline (CR)