pidx pip specification p11: send field ticket · pidx pip specification p11: send field ticket ......

PIDX PIP Specification

P11: Send Field Ticket

Version 1.0

July 8, 2014

PIDX RNIF PIP Specification P11 of 13 PIDX PIP P11 Field Ticket v1_0

Document ID: version 1.0 07/08/2014

© PIDX, Inc. 2014 Use of this copyrighted material is subject to the PIDX End User License Agreement available at www.pidx.org/license.

Each user agrees to such End User License Agreement by making any use of the copyrighted material.

This document was prepared and is maintained in accordance with the PIDX Procedures for Standards Development, a copy of which is available at www.pidx.org/procedures, and the PIDX Antitrust Guidelines, a copy of which is available at www.pidx.org/antitrust.

Table of Contents

1 Introduction ......................................................................................................................... 4

1.1 Document Purpose ....................................................................................................... 4

1.2 Document Conventions ................................................................................................ 4

1.3 Intended Audience ....................................................................................................... 4

1.4 References ................................................................................................................... 4

1.4.1 PIDX XML Transaction Standards, version 2.0 ..................................................................... 5

1.4.2 RosettaNet Implementation Framework, version 2.0 (RNIF2) ............................................... 5

1.4.3 PIDX Dictionary Framework ................................................................................................. 5

1.4.4 Other References ..................................................................................................................... 5

1.5 Scope ........................................................................................................................... 5

2 Send Field Ticket Partner Interface Process .................................................................... 6

2.1 PIP Roles ..................................................................................................................... 7

2.2 PIP Activities ................................................................................................................ 7

3 PIP P11 Business Rules and Constraints ......................................................................... 7

4 Data Requirements .............................................................................................................. 8

4.1 Optional Service Content Data ..................................................................................... 9

4.2 Service Header Data: Fundamental Business Data Entities ........................................ 9

5 Business Signals............................................................................................................... 10

5.1 Scope of Business Signals ......................................................................................... 10

5.2 Base-level Validation Rules ........................................................................................ 11

5.3 Process Control .......................................................................................................... 11

6 TRP requirements ............................................................................................................. 13

6.1 Transport security ....................................................................................................... 13

6.2 Routing ....................................................................................................................... 13






Document Version History

Date Version Author(s) Description

30 Jan 2014 0.02 Gary Strickland, Rick Conner, Larry Dyer

Created PIP outline

20 Jun 2014 0.1 Gary Strickland Added PIP content

24 Jun 2014 0.11 Rick Conner, Larry Dyer, Darren Ebanks, Gary Strickland

Edited PIP for completeness, accuracy, and readability

1 Jul 2014 0.9 Rick Conner, Larry Dyer, Darren Ebanks, Gary Strickland

Added content

8 Jul 2014 1.0 Darren Ebanks, Paul O’Shaughnessy, Gary Strickland

Edited for completeness, accuracy, and readability






1 Introduction

1.1 Document Purpose

The Partner Interface Process (PIP) P11 Send Field Ticket is used to align a seller’s field ticket creation and

delivery processes with a buyer’s field ticket approval process. This PIP specification provides information

necessary to accomplish that alignment:

• Trading partner business roles

• Business activities executed by the roles

• The type and sequence of business documents exchanged by the role interactions while executing these

activities

• The time, security, authentication, and performance constraints of these interactions

The PIP specification focuses on the public business processes buyers and sellers use to create, transform,

transmit, and process field ticket action messages. The specification does NOT identify the field ticket action

message payload requirements; the buyer and seller MUST agree on payload requirements, and those

requirements MUST be included in the buyer’s field ticket implementation guide. The trading partners executing

the Send Field Ticket PIP must understand the processes in order to determine how trading partner data

requirements can be addressed.

1.2 Document Conventions

The Send Field Ticket PIP specification adopts the conventions expressed in the Internet Engineering Task

Force’s (IETF) Request for Comments (RFC) 2119 “Key Words for Use in RFCs to Indicate Requirement

Levels.” The key words “MUST,” “MUST NOT,” “REQUIRED,” “SHALL,” “SHALL NOT,” “SHOULD,”

“SHOULD NOT,” “RECOMMENDED,” “MAY,” and “OPTIONAL” in this document are to be interpreted as

described in RFC 2119.

1.3 Intended Audience

The targeted audience of the Send Field Ticket PIP specification includes trading partner technical and business

personnel responsible for creating, sending, and approving field tickets, as well as third party technology

providers facilitating those activities.

1.4 References

The Send Field Ticket PIP specification relies on information in RosettaNet Implementation Framework, version

2.0 (RNIF2) and PIDX standards (Implementation Guide, Dictionary Framework, schemas, message guidelines).

Users of the Send Field Ticket PIP specification MUST understand the content and purpose of the related

documents.






1.4.1 PIDX XML Transaction Standards, version 2.0

PIDX XML Transaction standards consist of the standards master, the implementation guidelines, dictionaries,

schemas, header message guidelines, and PIP specifications. Those documents should be considered integral

parts of this PIP specification. The Send Field Ticket PIP specification does not restate material in those

documents unless restatement adds clarity to the specification.

There may be multiple versions of the field ticket schema. Trading partners implementing this PIP must agree on

the version of field ticket schema that sellers will use to send field tickets to buyers. The field ticket schema used

in the Send Field Ticket PIP MUST be identified in the buyer’s implementation guide.

1.4.2 RosettaNet Implementation Framework, version 2.0 (RNIF2)

RNIF2 describes the transport, routing, and packaging (TRP) data and processing requirements. The PIDX XML

Transaction Standards version 2.0 are based on RNIF2, but do not restate them. Accordingly, to understand how

to execute the Send Field Ticket PIP, trading partners MUST have a solid understanding of RNIF2 and how the

PIDX standards restrict that framework.

1.4.3 PIDX Dictionary Framework

The PIDX standards use the XML Data Dictionary created in the PIDX XML Transaction Standards, version 1.0

to define service content XML elements: Data Dictionary 2001-11-30 V1-0.xls

The elements in the message headers are defined in the following PIDX message guidelines:

• Preamble: PIDXPreambleMessageGuidelineV1_0.html

• Delivery Header: PIDXDeliveryHeaderMessageGuidelineV1_0.html

• Service Header: PIDXServiceHeaderMessageGuidelineV1_0.html

1.4.4 Other References

In addition to standards and specifications described above, trading partners implementing the Send Field Ticket

PIP should be familiar with the following specifications and standards:

• XML 1.0 and W3C XML Schema

• The PIDX field ticket schema version agreed to by trading partners executing the Send Field Ticket PIP

• The PIDX library schema version agreed to by the trading partners executing the Send Field Ticket PIP

• General Internet protocols

• Encryption standards

• MIME and S/MIME

• Digital signatures and the Secure Socket Layer (SSL)

• Buyer and seller process, data and TRP requirements and restrictions

1.5 Scope

The Send Field Ticket PIP describes the processes and choreography to send a field ticket and acknowledge its

receipt and processing status. Other PIDX PIPs may be executed as a requirement to initiating a Send Field

Ticket PIP (Send Purchase Order, for example), and other PIDX PIPs may be executed as a result of a successful






execution of the Send Field Ticket PIP (Send Invoice, for example). Those processes are out of scope in the Send

Field Ticket PIP.

The Send Field Ticket PIP payload requirements are not described in this PIP specification. The payload

requirements of the buyer are described in the buyer’s implementation guide.

2 Send Field Ticket Partner Interface Process

The Send Field Ticket Partner Interface Process (PIP) aligns a seller’s field ticketing process with the buyer’s

field ticket approval process. There are two types of business processes involved in the PIP: private processes,

and public processes. Private processes are business processes internal to each trading partner. Public processes

are business processes that involve interactions with trading partners. The sequence diagram in figure 1 shows

the relationship between public and some well-known private processes.

While PIDX PIPs focus on public processes, private and public processes are interdependent. Accordingly, the

Send Field Ticket PIP references private processes when those references provide clarity to the Send Field Ticket

PIP.

Figure 1: Send Field Ticket PIP public and private processes

The use case diagram in figure 2 shows the trading partner roles in the Send Field Ticket PIP, and the required

activities (public processes) each role must execute.






2.1 PIP Roles

PIDX PIPs are based on a peer-to-peer message exchange model: Messages are exchanged between two trading

partners: a buyer and a seller. The involvement of third parties to facilitate the exchange does not change the

peer-to-peer message exchange model. Accordingly, the only roles described in the Send Field Ticket PIP are

those of a buyer and a seller.

2.2 PIP Activities

There are three required activities in the Send Field Ticket PIP:

1. The seller sends a field ticket action message to the buyer

2. The buyer and the seller validate syntax and structure of inbound messages (base-level validation)

3. The buyer sends a business signal message to the seller

All other processes in the Send Field Ticket PIP are private processes.

3 PIP P11 Business Rules and Constraints

Trading partners executing the Send Field Ticket PIP must agree on the business rules and process constraints for

the PIP. The business rules that MUST be agreed to by the trading partners are listed in Table 1. The buyer and

seller MAY business add rules and constraints not included in this list.

Figure 2: Send Field Ticket PIP required activities






Business rule/constraint Required value

Non-repudiation required Yes/No

Time to acknowledge hh:mm:ss

Retry count limit for technical failures 0 – count limit

Authorization required to send field ticket Yes/No

Non-repudiation of origin and content Yes/No

Secure transport required Yes/No

Payload encryption required Yes/No

Validation limited to message syntax, structure (base-level validation) Yes/No

Payload will be validated against buyer’s business rules and data

requirements before sending a business signal (content-level validation)

Yes/No

URL to which the Seller must send the PIDX field ticket action message URL

URL to which the Buyer must send the PIDX business signal message URL

SSL required Yes/No

Buyer’s server certificate required for seller to identify buyer server Yes/No

Seller certificate required to identify seller to the buyer Yes/No

Table 1: Send Field Ticket business rules

4 Data Requirements

Payload data requirements are specified in the buyer’s implementation guide.

There may be multiple versions of the XML schemas controlling the structure and syntax of the Send Field Ticket

PIP service content. The buyer and the seller MUST agree on which version of the PIDX library and the field

ticket schema to use. The schemas agreed to by the buyer and seller MUST be published in the buyer’s Send

Field Ticket Implementation Guidelines.






The PIDX XML Transaction Standards define many optional information items in the PIDX schemas that control

the structure, syntax, and required content of the field ticket service content. The buyer and seller MUST agree on

which of the elements are required, and which are conditional. The buyer MUST publish an implementation

guide that includes the schemas and schema versions to be used, the service content required data, and any

required attachments.

4.1 Optional Service Content Data

Most of the data elements in PIDX XML schemas are optional. Required and conditional data elements MUST

be agreed to by the buyer and seller, and described in the buyer’s implementation guide. When the buyer’s

implementation guide does not define an optional XML information item as required or conditional, the

information item is optional, and it MAY be included in the Send Field Ticket PIP service content. Optional

information items included in the service content MUST NOT cause the field ticket to fail validation in the

buyer’s system.

4.2 Service Header Data: Fundamental Business Data Entities

PIDX standards require each PIP specification to prescribe the values of certain business data elements. Table 2

contains a list of those elements, their definition, and, if possible the values that MUST be specified in each

instance of this PIP. The values that must be used are in quotes. If a value cannot be specified in this section, the

trading partners executing the PIP MUST agree on the value to use.

Other service header elements and their values are described in the PIDX General Implementation Guidelines,

version 2.0.

Element Name Definition Required Value

BusinessActivityIdentifier • An identifier which specifies a

business activity

• PIDX requires the name of the XML

schema to be used

Trading partners

to agree

fromRole.GlobalPartnerRoleClassificationCode Code identifying a party's role in the

supply chain

“Seller”

toRole.GlobalPartnerRoleClassificationCode Code identifying a party's role in the

supply chain

“Buyer”

fromService.GlobalBusinessServiceCode Code identifying a business service

network component

“Seller Service”

toService.GlobalBusinessServiceCode Code identifying a business service

network component

“Buyer Service”

GlobalBusinessActionCode Code identifying a business action Trading partners

to agree






5 Business Signals

The Send Field Ticket PIP requires the buyer to send to the seller a business signal containing the validation status

of the field ticket action message.

5.1 Scope of Business Signals

Business signals communicate the status of processing events of the field ticket action message in the buyer’s

system. The buyer’s system MUST return a business signal reporting the base-level validation status of the

following events:

1. The receipt and successful base-level validation of

a message (Receipt Acknowledgment)

2. The receipt of an out-of-sequence message

(Exception with a type of “General Exception”)

a. Example: If a buyer requires the seller to

send a field ticket before sending an invoice, and the buyer

receives the invoice before receiving the field ticket, the

buyer MUST return a receipt acknowledgement exception

with exception type of “General Exception”

3. The receipt of a message that has invalid grammar;

it did not pass base-level validation (Exception with a type

of “Receipt Acknowledgment Exception”)

Optionally, trading partners MAY agree to report content

validation events in the business signal. Content validation

includes validating that the field ticket action message’s

payload complies with the buyer’s business rules and data

requirements.

If the buyer validates the payload before sending the receipt

acknowledgment/exception, then the buyer and seller MAY

agree that the business signal returned includes both base-

level validation and content-level validation. If the payload

does not comply with the buyer’s business rules and service

content data requirements, the buyer MUST return an

exception business signal. The exception type is “General

Exception” and the error code to use is

PRF.DICT.VALERR. The activity diagram in figure 3

shows the process and message flow when the payload of a

field ticket is validated before creating a receipt

acknowledgment or exception signal.

Figure 3: Content-level validation activity diagram






5.2 Base-level Validation Rules

The four XML parts of a PIDX message (preamble, delivery header, service header and service content) MUST

be validated against a PIDX DTD and message guidelines (for the three header documents) or a PIDX field ticket

schema (for the service content). The following is the minimum level of validation required for each of the XML

body parts. Validating for compliance with these rules is called “base-level” validation:

1. The XML document MUST be compliant with its corresponding DTD or schema

2. Where an element’s data type and/or length is specified in the corresponding schema (in the case of the

service content) or Message Guideline (in the case of the header parts), the element MUST be validated

against the schema or Message Guideline

3. In validating header documents, where the cardinality specification of an element in the Message

Guideline is different from the corresponding specification in the DTD, the specification in the Message

Guideline is more accurate and MUST be adhered to

4. In validating header documents, where the sequence or naming of an element in the Message Guideline is

different from the corresponding specification in the DTD, the specification in the DTD is more accurate

and MUST be adhered to

If a message does not comply with one or more of the above rules, then it MUST be deemed invalid, and the

buyer MUST return an exception business signal.

5.3 Process Control

While executing a Send Field Ticket PIP, if an exception occurs in the buyer’s system after the buyer

returns a receipt acknowledgement business signal to the seller, the buyer MUST return a Notification of

Failure process control message. RosettaNet defines process control PIP 0A1 Notification of Failure to

communicate process exceptions occurring outside of the context of the current process instance. For

example, if the buyer and seller agree to base-level validation, the buyer will return a business signal to

the seller with base-level validation status. After the seller receives the business signal from the buyer,

the Send Field Ticket process has completed in the seller’s system. However, the buyer continues to

process the payload of the seller’s field ticket action message to determine compliance with the buyer’s

business rules and service content data requirements. If the seller’s payload does not comply with the

buyer’s business rules

and data requirements,

the process ends in an

exception state in the

buyer’s system. When

this happens, the buyer

MUST notify the seller

of the exception event

by sending a

Notification of Failure.

Figure 4 illustrates the

process sequence and

Figure 4: Out of bounds processing error sequence diagram






flow of messages in this example.






6 TRP requirements

The PIDX transport, routing, and packaging (TRP) standard is based on the RosettaNet Implementation

Framework 2.0 (RNIF2). RNIF2 utilizes existing standards including MIME multi-part/related, MIME multi-

part/signed, multipart/mixed, HTTP(S), SSL, PKCS#7, SMTP, and XML. Trading partners implementing the

Send Field Ticket PIP MUST understand RNIF2, PIDX restrictions to RNIF2, and the standards used by RNIF2

including MIME, HTTP(S), and PKCS#7.

6.1 Transport security

Secure transport (SSL) is REQUIRED for the field ticket action message and the signal message exchanged

between the buyer and seller.

6.2 Routing

The buyer and the seller executing the Send Field Ticket PIP MUST use HTTP/S to send the action and signal

messages. Accordingly, each trading partner must specify the URL to which the other trading partner must send

messages:

• The buyer must specify the URL to which the seller sends the field ticket action message

• The seller must specify the URL to which the buyer sends the business signal

One or both of the trading partners executing the Send Field Ticket PIP may direct the other trading partner to

send messages to a third party technology service provider for processing. The trading partner that engages the

third party technology service provider MUST provide the other trading partner with the service provider’s URL.

The engagement of a third party technology service provider by a trading partner does not change the PIDX peer-

to-peer message exchange model: Delivering a PIDX message to an intermediary at the direction of the intended

receiving trading partner is considered to be the same as delivering the message directly to the intended receiving

trading partner. The trading partner engaging the third party technology service provider MUST ensure that

PIDX messages received by the third party technology service provider are processed timely and in accordance

with PIDX XML Transaction Standards and trading partner agreements.

pidx pip specification p11: send field ticket · pidx pip specification p11: send field ticket ......

Documents