Creating PIP document flow packages

Because RosettaNet adds PIPs from time to time, you might need to create your own PIP packages to support these new PIPs or to support upgrades to PIPs. Except where noted, the procedures in this section describe how to create the PIP document flow package for PIP 5C4 V01.03.00. Business Integration Connect supplies a PIP document flow package for PIP 5C4 V01.02.00 so the procedures actually document how to perform an upgrade. However, creating a PIP document flow package is similar and the procedures identify any additional steps.

Before you begin, download the PIP specifications from www.rosettanet.org for the new version, and if you are performing an upgrade, the old version. For example, if you are performing the upgrade described in the procedures, download 5C4_DistributeRegistrationStatus_V01_03_00.zip and 5C4_DistributeRegistrationStatus_V01_02_00.zip. The specification includes the following file types:

Creating or upgrading a PIP document flow package involves the following procedures:

Creating the XSD files

A PIP document flow package contains XML schema files that define message formats and acceptable values for elements. The following procedure describes how to create these files based on the contents of the PIP specification file.

You create at least one XSD file for each DTD file in the PIP specification file. For the example of upgrading to PIP 5C4 V01.03.00, because the message format changed, the procedure describes how to create the BCG_5C4RegistrationStatusNotification_V01.03.xsd file as an example. For information on the XSD files, see About validation.

To create the XSD files for the PIP document flow package, do the following:

  1. Import or load the DTD file into an XML editor such as WebSphere Studio Application Developer. For example, load the 5C4_MS_V01_03_RegistrationStatusNotification.dtd file.
  2. Using the XML editor, convert the DTD into an XML schema. The following steps describe how to do this using Application Developer:
    1. In the Navigation pane of the XML perspective, open the project containing the imported DTD file.
    2. Right click the DTD file and select Generate > XML Schema.
    3. In the Generate panel, type or select where you want to save the new XSD file. In the File name field, type the name of the new XSD file. In the case of the example, you would type a name such as BCG_5C4RegistrationStatusNotification_V01.03.xsd. Click Finish.
  3. Compensate for elements that have multiple cardinality values in the RosettaNet XML guidelines by adding specifications to the new XSD file. The guidelines show the elements in the message using a tree and displaying the cardinality of each element to the left of the element:

    Generally, the elements in the guidelines match the definitions of the elements in the DTD file. However, the guidelines might contain some elements that have the same names but different cardinalities. Because the DTD cannot provide the cardinality in this case, you need to modify the XSD. For example, the 5C4_MG_V01_03_00_RegistrationStatusNotification.htm guidelines file has a definition for ContactInformation on line 15 that has five child elements with the following cardinalities:

    The ContactInformation definition on the line 150 has four child elements with the following cardinalities:

    In the XSD file, however, each child of ContactInformation has a cardinality that complies with both definitions:

    <xsd:element name="ContactInformation">
      <xsd:complexType>
        <xsd:sequence>
          <xsd:element ref="contactName"/>
          <xsd:element maxOccurs="1" minOccurs="0" ref="EmailAddress"/>
          <xsd:element maxOccurs="1" minOccurs="0" ref="facsimileNumber"/>
          <xsd:element maxOccurs="1" minOccurs="0" ref="PhysicalLocation"/>
          <xsd:element maxOccurs="1" minOccurs="0" ref="telephoneNumber"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:element>

    If you are updating the PIP document flow package based of another version of the package and want to reuse a definition from the other version, do the following for each of these definitions:

    1. Delete the definition of the element. For example, delete the ContactInformation element.
    2. Open the PIP document flow package of the version being replaced. For example, open the BCG_Package_RNIFV02.00_5C4V01.02.zip file.
    3. Find the definition you want to reuse. For example, the ContactInformation_type7 definition in the BCG_ContactInformation_Types.xsd file matches the definition you need for line 15 of the guidelines.
      <xsd:complexType name="ContactInformation_type7">
        <xsd:sequence>
          <xsd:element name="contactName" type="common_FreeFormText_R"/>
          <xsd:element name="EmailAddress" type="common_EmailAddres_R"
              minOccurs="0"/>
          <xsd:element name="facsimileNumber"
              type="common_CommunicationsNumber_R" minOccurs="0"/>
          <xsd:element name="PhysicalLocation"
              type="PhysicalLocation_type1" minOccurs="0" />
          <xsd:element name="telephoneNumber"
              type="common_CommunicationsNumber_R minOccurs="0" />
        </xsd:sequence>
      </xsd:complexType>
    4. In the new XSD file you are creating for the updated PIP document flow package, create a reference to the XSD file containing the definition you want to reuse. For example, create a reference to BCG_ContactInformation_Types.xsd in the BCG_5C4RegistrationStatusNotification_V01.03.xsd file as follows:

      <xsd:include schemaLocation="BCG_ContactInformation_Types.xsd"/>

    5. In the new XSD file, delete the ref attribute of any elements that refer to the element you deleted. Add a type attribute that refers to the definition you are reusing. For example, in the productProviderFieldApplicationEngineer element, delete ref="Contact Information" and add the following:
      name="ContactInformation
      type="ContactInformation_type7"

    If you are creating a PIP document flow package, or are upgrading a PIP document flow package but the definition you need does not exist in the other version, do the following for each instance of the element you found in the guidelines:

    1. Delete the definition of the element. For example, delete the ContactInformation element.
    2. Create the replacement definition. For example, create the ContactInformation_localType1 definition to match the definition in line 15 of the guidelines.
      <xsd:complexType name="ContactInformation_localType1">
        <xsd:sequence>
          <xsd:element ref="contactName"/>
          <xsd:element maxOccurs="1" minOccurs="0" ref="EmailAddress"/>
          <xsd:element maxOccurs="1" minOccurs="0"
              ref="facsimileNumber"/>
          <xsd:element maxOccurs="1" minOccurs="0"
              ref="PhysicalLocation"/>
          <xsd:element maxOccurs="1" minOccurs="0"
              ref="telephoneNumber"/>
        </xsd:sequence>
      </xsd:complexType>
    3. For any elements that refer to the element you deleted, delete its ref attribute and add a type attribute that refers to the appropriate complex type you defined in the previous step. For example, in the productProviderFieldApplicationEngineer element, delete ref="Contact Information" and add the following:
      name="ContactInformation
      type="ContactInformation_localType1"   

      Element productProviderFieldApplicationEngineer before modification

      <xsd:element name="productProviderFieldApplicationEngineer">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element ref="ContactInformation"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>

      Element productProviderFieldApplicationEngineer after modification

      <xsd:element name="productProviderFieldApplicationEngineer">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="ContactInformation"
                type="ContactInformation_localType1"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
  4. Specify the enumeration values for elements that can only have specific values. The guidelines define the enumeration values in the tables in the Guideline Information section. For example, GlobalRegistrationComplexityLevelCode has the following table:

    Therefore, in a PIP 5C4 V01.03.00 message, the GlobalRegistrationComplexityLegelCode can only have the following values: Above average, Average, Maximum, Minimum, None and Some.

    If you are updating the PIP document flow package based on another version of the package and want to reuse a set of enumeration values from the other version, do the following for each set:

    1. Delete the definition for the element. For example, delete the GlobalRegistrationComplexityLevelCode element:
    2. Open the PIP document flow package of the version being replaced. For example, open the BCG_Package_RNIFV02.00_5C4V01.02.zip file.
    3. Find the definition containing the enumeration values you want to reuse. For example, the _GlobalRegistrationComplexityLevelCode definition in the BCG_GlobalRegistrationComplexityLevelCode.xsd file contains the enumeration value definitions defined by the Entity Instance table.
      <xsd:simpleType name="_GlobalRegistrationComplexityLevelCode">
        <xsd:restriction base="xsd:string">
          <xsd:enumeration value="Above average"/>
          <xsd:enumeration value="Average"/>
          <xsd:enumeration value="Maximum"/>
          <xsd:enumeration value="Minimum"/>
          <xsd:enumeration value="None"/>
          <xsd:enumeration value="Some"/>
        </xsd:restriction>
      </xsd:simpleType>
    4. In the new XSD file you are creating for the updated PIP document flow package, create a reference to the XSD file containing the definition you want to reuse. For example, create a reference to BCG_GlobalRegistrationComplexityLevelCode.xsd in the BCG_5C4RegistrationStatusNotification_V01.03.xsd file as follows:
      <xsd:include schemaLocation=
          "BCG_GlobalRegistrationComplexityLevelCode_Types.xsd" />
    5. In the new XSD file, delete the ref attribute of any elements that refer to the element you deleted. Add a type attribute that refers to the definition you are reusing. For example, in the DesignAssemblyInformation element, delete ref="GlobalRegistrationComplexityLevelCode" and add the following:
      name="GlobalRegistrationComplexityLevelCode"
      type="_GlobalRegistrationComplexityLevelCode"

    If you are creating a PIP document flow package or are upgrading a PIP document flow package but the enumeration value definitions you need do not exist in the other version, do the following for any element with enumerated values in the guidelines:

    1. Delete the definition of the element. For example, delete the GlobalRegistrationComplexityLegelCode element.
    2. Create the replacement definition. For example, create the GlobalRegistrationComplexityLegelCode_localType definition and include the enumeration value definitions as described by the table.
      <xsd:simpleType
          name="GlobalRegistrationComplexityLevelCode_localType">
        <xsd:restriction base="xsd:string">
          <xsd:enumeration value="Above average"/>
          <xsd:enumeration value="Average"/>
          <xsd:enumeration value="Maximum"/>
          <xsd:enumeration value="Minimum"/>
          <xsd:enumeration value="None"/>
          <xsd:enumeration value="Some"/>
        </xsd:restriction>
      </xsd:simpleType>
    3. For any elements that refer to the element you deleted, delete its ref attribute and add a type attribute that refers to the appropriate complex type you defined in the previous step. For example, delete ref="GlobalRegistrationComplexityLevelCode" and add the following:
      name="GlobalRegistrationComplexityLevelCode"
      type="GlobalRegistrationComplexityLevelCode_localType"   

      Element DesignAssemblyInformation before modification

      <xsd:element name="DesignAssemblyInformation">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element maxOccurs="1" minOccurs="0"
                ref="assemblyComments"/>
            <xsd:element maxOccurs="1" minOccurs="0"
                ref="demandCreatorTrackingIdentifier"/>
            <xsd:element maxOccurs="unbounded" minOccurs="0"
                ref="DesignPartInformation"/>
            <xsd:element ref="DesignRegistrationIdentification"/>
            <xsd:element maxOccurs="1" minOccurs="0"
                ref="GeographicRegion"/>     
            <xsd:element maxOccurs="1" minOccurs="0"
                ref="GlobalRegistrationComplexityLevelCode"/>
            <xsd:element maxOccurs="1" minOccurs="0"
                ref="GlobalRegistrationInvolvementLevelCode"/>
            <xsd:element maxOccurs="1" minOccurs="0"
                ref="RegistrationStatus"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>

      Element DesignAssemblyInformation after modification

      <xsd:element name="DesignAssemblyInformation">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element maxOccurs="1" minOccurs="0"
               ref="assemblyComments"/>
            <xsd:element maxOccurs="1" minOccurs="0"
               ref="demandCreatorTrackingIdentifier"/>
            <xsd:element maxOccurs="unbounded" minOccurs="0"
               ref="DesignPartInformation"/>
            <xsd:element ref="DesignRegistrationIdentification"/>
            <xsd:element maxOccurs="1" minOccurs="0"
               ref="GeographicRegion"/>     
            <xsd:element maxOccurs="1" minOccurs="0"
               name="GlobalRegistrationComplexityLevelCode"
                 type="GlobalRegistrationComplexityLevelCode_localType"/>
      
            <xsd:element maxOccurs="1" minOccurs="0"
               ref="GlobalRegistrationInvolvementLevelCode"/>
            <xsd:element maxOccurs="1" minOccurs="0"
               ref="RegistrationStatus"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
  5. Set the data type, minimum length, maximum length, and representation of the data entities. The RosettaNet XML Message Guidelines provide this information in the Fundamental Business Data Entities table as shown in the following figure:

    If you are updating the PIP document flow package based on another version of the package and want to reuse a data entity definition from the other version, do the following for each set:

    1. Delete the definition for the data entity element. For example, delete the DateStamp element:
    2. Open the PIP document flow package of the version you are replacing. For example, open the BCG_Package_RNIFV02.00_5C4V01.02.zip file.
    3. Find the definition you want to reuse. For example, the _common_DateStamp_R definition in the BCG_common.xsd file contains the following definition, which complies with the information given in the guidelines.
      <xsd:simpleType name="_common_DateStamp_R">
        <xsd:restriction base="xsd:string">
          <xsd:pattern value="[0-9]{8}Z" /> 
        </xsd:restriction>
      </xsd:simpleType>
    4. In the new XSD file you are creating for the updated PIP document flow package, create a reference to the XSD file containing the definition you want to reuse. For example, create a reference to BCG_common.xsd in the BCG_5C4RegistrationStatusNotification_V01.03.xsd file as follows:
      <xsd:include schemaLocation="BCG_common.xsd" />
    5. In the new XSD file, delete the ref attribute of any elements that refer to the element you deleted. Add a type attribute that refers to the definition you are reusing. For example, in the DesignAssemblyInformation element, delete ref="DateStamp" and add the following:
      name="DateStamp" type="_common_DateStamp_R"  

    If you are creating a PIP document flow package or are upgrading a PIP document flow package but the data entity definition you need does not exist in the other version, do the following for each data entity element:

    1. Delete the definition of the element. For example, delete the DateStamp element.
    2. Create the replacement definition. For example, use the data type, minimum length, maximum length, and representation information to create the DateStamp_localType definition.
      <xsd:simpleType name="DateStamp_localType">
        <xsd:restriction base="xsd:string">
          <xsd:pattern value="[0-9]{8}Z" /> 
        </xsd:restriction>
      </xsd:simpleType>
    3. For any elements that refer to the element you deleted, delete its ref attribute and add a type attribute that refers to the appropriate complex type you defined in the previous step. For example, delete ref="DateStamp" and add the following:
      name="DateStamp" type="DateStamp_localType"

      Element beginDate before modification

      <xsd:element name="beginDate">
        <xsd:complexType">
          <xsd:sequence>
            <xsd:element ref="DateStamp"/> 
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>

      Element beginDate after modification

      <xsd:element name="beginDate">
        <xsd:complexType">
          <xsd:sequence>
            <xsd:element name="DateStamp" type="DateStamp_localType"/> 
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>

Creating the XML file

After you have created the XSD files for your PIP document flow package, you are ready to create the XML file for the RNIF package and the XML file for the Backend Integration package. For example, these packages are called BCG_RNIFV02.00_5C4V01.03.zip and BCG_RNSC1.0_RNIFV02.00_5C4V01.03.zip respectively. The following procedure describes how to create the XML file for the RNIF package:

  1. Extract the XML file from a RNIF PIP document flow package file. If you are upgrading, extract the file from the previous version of the package such as BCG_Package_RNIFV02.00_5C4V01.02.zip. If you are creating a new package, extract the file from a PIP document flow package that is similar to the one you are creating. For example, if you are creating a package to support a two-action PIP, copy the XML file from another two-action PIP package.
  2. Copy the file and rename it appropriately such as RNIFV02.00_5C4V01.03.xml.
  3. In the new file, update the elements that contain information about the PIP. For example, the following table lists the information you need to update in the 5C4 PIP example. Note that the information may appear more than once in the file, so make sure that you update all instances.
    Table 8. 5C4 PIP update information
    Information to change Old value New value

    PIP ID

    5C4

    5C4

    Version of the PIP

    V01.02

    V01.03

    The name of the request message DTD file without the file extension

    5C4_MS_V01_02_
    RegistrationStatusNotification

    5C4_MS_V01_03_
    RegistrationStatusNotification

    The name of the confirmation message DTD file without the file extension (for two-action PIPs only)

    N/A

    N/A

    The name of the request message XSD file without the file extension

    BCG_5C4RegistrationStatusNotification_
    V01.02

    BCG_5C4RegistrationStatusNotification_
    V01.03

    The name of the confirmation message XSD file without the file extension (for two-action PIPs only)

    N/A

    N/A

    Root element name in the XSD file for the request message

    Pip5C4RegistrationStatusNotification

    Pip5C4RegistrationStatusNotification

    Root element name in the XSD file for the confirmation message (for two-action PIPs only)

    N/A

    N/A

  4. Open the PIP Specification document and use it to update the information listed in the following table. If you are doing an update, compare the specifications for the versions because you may not have to update these values.
    Table 9. 5C4 PIP update information from the PIP specification
    Information to update Description Value in the 5C4 package

    Activity name

    Specified in Table 3-2

    Distribute Registration Status

    Initiator role name

    Specified in Table 3-1

    Product Provider

    Responder role name

    Specified in Table 3-1

    Demand Creator

    Request action name

    Specified in Table 4-2

    Registration Status Notification

    Confirmation action name

    Specified in Table 4-2 (for two-action PIPs only)

    N/A

  5. Update the package attribute values. If you are doing an update, compare the specifications for the versions because you may not have to update these values.
    Table 10. 5C4 PIP attribute updates
    Information to update Description Value in the 5C4 package Element path in the XML file

    NonRepudiationRequired

    Specified in Table 3-3

    N

    ns1:Package
    ns1:Protocol
    ns1:Process
    ns1:Attribute (Its ATTRIBUTEKEY is NonRepudiationRequired)
    ns1:AttributeValue
    AttributePickListItem
    ATTRVALUEKEY

    NonRepudiationOfReceipt

    Specified in Table 3-3

    N

    ns1:Package
    ns1:Protocol
    ns1:Process
    ns1:Attribute (Its ATTRIBUTEKEY is NonRepudiationOfReceipt)
    ns1:AttributeValue
    AttributePickListItem
    ATTRVALUEKEY

    DigitalSignatureRequired

    Specified in Table 5-1

    Y

    ns1:Package
    ns1:Protocol
    ns1:Process
    ns1:Attribute (Its ATTRIBUTEKEY is DigitalSignatureRequired)
    ns1:AttributeValue
    AttributePickListItem
    ATTRVALUEKEY

    TimeToAcknowledge

    Specified in Table 3-3

    2
    (120 min)

    ns1:Package
    ns1:Protocol
    ns1:Process
    ns1:Attribute (Its ATTRIBUTEKEY is TimeToAcknowledge)
    ns1:AttributeValue
    ATTRVALUE

    TimeToPerform

    Specified in Table 3-3

    2
    (120 min)

    ns1:Package
    ns1:Protocol
    ns1:Process
    ns1:Attribute (Its ATTRIBUTEKEY is TimeToPerform)
    ns1:AttributeValue
    ATTRVALUE

    RetryCount

    Specified in Table 3-3

    3

    ns1:Package
    ns1:Protocol
    ns1:Process
    ns1:Attribute (Its ATTRIBUTEKEY is RetryCount)
    ns1:AttributeValue
    ATTRVALUE

  6. Update the ns1:Package/ns1:Protocol/GuidelineMap elements to remove unused XSD files and to add any XSD files you created or referenced as shown in the following example for BCG_common.xsd.

To create the Backend Integration package, repeat the above procedure except for the following differences:

After you have created the XML and the XSD files, you are ready to create the PIP documentation flow packages.

Creating the package

To create the RNIF package, do the following:

  1. Create a GuidelineMaps directory and copy the package's XSD files into this directory.
  2. Create a Packages directory and copy the RNIF XML file into this directory.
  3. Go to the parent directory and create a PIP document flow package (ZIP file) that contains the GuidelineMaps and Packages directory. You must preserve the directory structure in the ZIP file.

To create the Backend Integration package, perform the above procedure but use the Backend Integration XML file instead of the RNIF file.

After you have created the PIP package, you can upload it using the procedure in Uploading RNIF packages.

Copyright IBM Corp. 2003, 2004