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. WebSphere Partner Gateway supplies a PIP document flow package for PIP 5C4 V01.02.00. The procedures, therefore, 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 about the XSD files, see About validation.

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

  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.
    4. 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 on another version of the package and want to reuse a definition from the other version, perform the following steps 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 information:
      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, perform the following steps 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 information:
      name="ContactInformation"
      type="ContactInformation_localType1"   

      Figure 35 shows the productProviderFieldApplicationEngineer element before it is modified.

      Figure 35. Element productProviderFieldApplicationEngineer before modification
      <xsd:element name="productProviderFieldApplicationEngineer">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element ref="ContactInformation"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>

      Figure 36 shows the productProviderFieldApplicationEngineer element after it is modified.

      Figure 36. 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, in a PIP 5C4 V01.03.00 message, the GlobalRegistrationComplexityLevelCode can have only 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, perform the following steps 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 information:
      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, perform the following steps for any element with enumerated values in the guidelines:

    1. Delete the definition of the element. For example, delete the GlobalRegistrationComplexityLevelCode element.
    2. Create the replacement definition. For example, create the GlobalRegistrationComplexityLevelCode_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 information:
      name="GlobalRegistrationComplexityLevelCode"
      type="GlobalRegistrationComplexityLevelCode_localType"   

      Figure 37 shows the Element DesignAssemblyInformation element before it is modified.

      Figure 37. 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>

      Figure 38 shows the Element DesignAssemblyInformation after it was modified.

      Figure 38. 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.

    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, perform the following steps 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 information:
      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, perform the following steps 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 information:
      name="DateStamp" type="DateStamp_localType"

      Figure 39 shows the Element beginDate before it is modified.

      Figure 39. Element beginDate before modification
      <xsd:element name="beginDate">
        <xsd:complexType">
          <xsd:sequence>
            <xsd:element ref="DateStamp"/> 
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>

      Figure 40 shows the Element beginDate after it is modified.

      Figure 40. 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_Package_RNIFV02.00_5C4V01.03.zip and BCG_Package_RNSC1.0_RNIFV02.00_5C4V01.03.zip. The following procedure describes how to create the XML file for the RNIF package:

  1. Extract the XML file from an RNIF PIP document flow package file. If you are upgrading, extract the file from the previous version of the package (for example, 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 (for example, BCG_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 might appear more than once in the file. Make sure that you update all instances.
    Table 37. 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_5C4RegistrationStatus
    Notification_V01.02
    BCG_5C4RegistrationStatus
    Notification_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 Pip5C4RegistrationStatus
    Notification
    Pip5C4RegistrationStatus
    Notification
    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 might not have to update these values.
    Table 38. 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 might not have to update these values.
    Note: If you are creating the Backend Integration package, skip this step and go to step 6.
    Table 39. 5C4 PIP attribute updates
    Information to update Description Value in the 5C4 package Element path in the XML file
    NonRepudiation
    Required
    Specified in Table 3-3 N ns1:Package
    ns1:Protocol
    ns1:Process
    ns1:Attribute (Its ATTRIBUTEKEY is NonRepudiationRequired)
    ns1:AttributeValue
    AttributePickListItem
    ATTRVALUEKEY
    NonRepudiationOf
    Receipt
    Specified in Table 3-3 N ns1:Package
    ns1:Protocol
    ns1:Process
    ns1:Attribute (Its ATTRIBUTEKEY is NonRepudiationOfReceipt)
    ns1:AttributeValue
    AttributePickListItem
    ATTRVALUEKEY
    DigitalSignature
    Required
    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.

To create the Backend Integration package, repeat step 1 through 6 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, perform the following steps:

  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 steps 1 through 3 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 RNIF and PIP document flow packages.

Copyright IBM Corp. 2003, 2005