Punchout Catalog - Procurement¶

Purpose of this document is to provide development related information on OCI and cXML protocols when using punchout in IFS Procurement solution.

OCI Protocol¶

When the user navigates to the webshop, URL setup in the administrative data, get appended with procurement system HOOK_URL and other query parameters. This is done in the method;

Self_Srv_Punchout_Req_Util_API.Prepare_Oci_Punchout_Request()

In IFS Procurement system, HOOK_URL will be a service endpoint deployed in the APPSVC container.

Once the user checks out from the webshop, the response needs to be sent as a POST request to the service endpoint. A sample OCI response message would look like below:

NEW_ITEM-VENDORMAT[1]=<Text>
NEW_ITEM-DESCRIPTION[1]=<Text>
NEW_ITEM-QUANTITY[1]=<Number>
NEW_ITEM-UNIT[1]=<Text>
NEW_ITEM-CURRENCY[1]=<Text>
NEW_ITEM-EXT_PRODUCT_ID[1]=<Text>
NEW_ITEM-PRICEUNIT[1]=<Text>
NEW_ITEM-MATGROUP[1]=<Text>
NEW_ITEM-VENDOR[1]=<Text>
NEW_ITEM_CERT[1]=<Text>
NEW_ITEM-CUST_FIELD1[1]=<Text>
NEW_ITEM-CUST_FIELD2[1]=<Text>
NEW_ITEM-LEADTIME[1]=<Number>
NEW_ITEM-EXT_SCHEMA_TYPE[1]=<Text>
NEW_ITEM-PRICE[1]=<Number>
NEW_ITEM-ADDITIONAL_COST[1]=<Number>
NEW_ITEM-VENDORMAT[2]=<Text>
NEW_ITEM-DESCRIPTION[2]=<Text>
...

In the service endpoint, query parameters sent back will be added to a JSON object. These parameters are used to identify the transaction. Then the OCI message will be extracted from the response and added to the JSON object and posted to the DB method;

Self_Serv_Shop_Cart_Util_API.Receive_Punchout_Response()

IFS Procurement Punchout solution right now only uses following fields:

OCI Protocol attribute	self_serv_shop_cart_line_tab column	Required	comments
NEW_ITEM-QUANTITY	quantity	Yes
NEW_ITEM-PRICE	fbuy_unit_price	Yes
NEW_ITEM-CURRENCY	currency_code	Yes
NEW_ITEM-VENDORMAT	vendor_part_no	No	Converted to upper case. Required for the punchout parts.
NEW_ITEM-DESCRIPTION	vendor_part_description	No	Required for the punchout parts.
	description	No	NEW_ITEM-VENDORMAT - NEW_ITEM-DESCRIPTION
NEW_ITEM-UNIT	buy_unit_meas and price_unit_meas	No

Since the entire message is sent to the DB method, and if additional parameters are needed to be customized, it can be done within the method.

Sample JSON object:

{
    "UserId": Text,
    "BuyerCookie": Text,
    "Supplier": Text,
    "Lines": [
        {
            "NEW_ITEM-CURRENCY": Text,
            "NEW_ITEM-DESCRIPTION": Text,
            "NEW_ITEM-EXT_PRODUCT_ID": Text,
            "NEW_ITEM-MATGROUP": Text,
            "NEW_ITEM_CERT": Text,
            "NEW_ITEM-PRICEUNIT": Text,
            "NEW_ITEM-QUANTITY": Number,
            "NEW_ITEM-EXT_SCHEMA_TYPE": Text,
            "NEW_ITEM-VENDORMAT": Text,
            "NEW_ITEM-LEADTIME": Number,
            "NEW_ITEM-VENDOR": Text,
            "NEW_ITEM-CUST_FIELD1": Text,
            "NEW_ITEM-CUST_FIELD2": Text,
            "NEW_ITEM-UNIT": Text,
            "NEW_ITEM-PRICE": Number,
            "NEW_ITEM-ADDITIONAL_COST": Number,
        },
        {
            "NEW_ITEM-CURRENCY": Text,
            "NEW_ITEM-DESCRIPTION": Text,
            ...
        },
        ...
    ]
}

Note: Since the response text is sent bearing the OCI standard, the converted JSON object structure will be the same.

cXML Protocol¶

Unlike OCI, there are some initial authentication transactions happens when the protocol is cXML for which PunchOutSetupRequest cXML document is used. And PunchOutOrderMessage cXML document is used to POST data back to the procurement system.

PunchOutSetupRequest¶

Information related to the PunchOutSetupRequest document HEADER elements is defined in the Administration Guide. In this section, information related to the REQUEST elements will be described.

BuyerCookie
A unique id is generated to identify the transaction. This will be generated each time the punchout request is initiated from the Self-Service Procurement Portal and will be obsoleted once the transaction is completed successfully.
BrowserFormPost/URL
Endpoint where the webshop response requires to be posted in the procurement system. This will be a service endpoint deployed in the APPSVC container.
Extrinsic Elements
Contains the end user information defined in the person object. ATM FirstName, LastName, UserEmail and PhoneNumber is added.
ShipTo Address
Contains the address defined in the default delivery address of the end user Self-Service Procurement Catalog Owning Site.

If more attributes are required, they need to be configured in the method;

Self_Srv_Punchout_Req_Util_API.Prepare_Cxml_Punchout_Request()

Then append them to the cXML document in the method;

generatePunchoutSetupRequest() in SelfServiceProcurementPortalHandlingActionsImpl.java

Sample REQUEST elements generated for cXML PunchOutSetupRequest document:

<Request>
    <PunchOutSetupRequest operation="create">
        <BuyerCookie>Text</BuyerCookie>
        <Extrinsic name="FirstName">Text</Extrinsic>
        <Extrinsic name="LastName">Text</Extrinsic>
        <Extrinsic name="UserEmail">Text</Extrinsic>
        <Extrinsic name="PhoneNumber">Text</Extrinsic>
        <BrowserFormPost>
            <URL>Text</URL>
        </BrowserFormPost>
        <ShipTo>
            <Address addressID="Text">
                <Name xml:lang="Text"/>
                <PostalAddress>
                    <Street>Text</Street>
                    <City>Text</City>
                    <State>Text</State>
                    <PostalCode>Text</PostalCode>
                    <Country isoCountryCode="Text">Text</Country>
                </PostalAddress>
            </Address>
        </ShipTo>
    </PunchOutSetupRequest>
</Request>

PunchOutOrderMessage¶

Once the user checks out from the webshop, the cXML document containing checked out lines will be posted to the endpoint provided in the BrowserFormPost/URL which is a service endpoint deployed in APPSVC container. A sample PunchOutOrderMessage elements in cXML document would look like below:

<PunchOutOrderMessage>
    <BuyerCookie>Text</BuyerCookie>
    <PunchOutOrderMessageHeader operationAllowed="create">
        <Total>
            <Money currency="Text">Number</Money>
        </Total>
        <Shipping>
            <Money currency="Text">Number</Money>
            <Description xml:lang="Text">Text</Description>
        </Shipping>
        <Tax>
            <Money currency="Text">Number</Money>
            <Description xml:lang="Text">Number</Description>
        </Tax>
    </PunchOutOrderMessageHeader>
    <ItemIn quantity="Number">
        <ItemID>
            <SupplierPartID>Text</SupplierPartID>
            <SupplierPartAuxiliaryID>Text</SupplierPartAuxiliaryID>
        </ItemID>
        <ItemDetail>
            <UnitPrice>
                <Money currency="Text">Number</Money>
            </UnitPrice>
            <Description xml:lang="Text">Text</Description>
            <UnitOfMeasure>Text</UnitOfMeasure>
            <Classification domain="Text">Text</Classification>
            <ManufacturerPartID>Text</ManufacturerPartID>
            <ManufacturerName xml:lang="Text">Text</ManufacturerName>
            <ManufacturerName />
            <LeadTime>Number</LeadTime>
        </ItemDetail>
    </ItemIn>
</PunchOutOrderMessage>

ATM service endpoint can only consume a cXML document that is url-encoded (once) or send in plain text. The response will be converted to a JSON object and posted to the DB method ;

Self_Serv_Shop_Cart_Util_API.Receive_Punchout_Response()

IFS Procurement Punchout solution right now only uses following fields:

cXML Protocol element/attribute	self_serv_shop_cart_line_tab column	Required	Comments
quantity	quantity	Yes
ItemDetail/UnitPrice/Money	fbuy_unit_price	Yes
ItemDetail/UnitPrice/Money - currency	currency_code	Yes
ItemID/SupplierPartID	vendor_part_no	No	Converted to upper case. Required for the punchout parts.
ItemDetail/Description	vendor_part_description	No	Required for the punchout parts.
	description	No	ItemID/SupplierPartID - ItemDetail/Description
ItemDetail/UnitOfMeasure	buy_unit_meas and price_unit_meas	No

Note: PunchOutOrderMessage/ItemIn elements contains the information that will be saved to shopping cart line

Since the entire message is sent to the DB method and if additional parameters need to be customized, it can be done here.

Sample JSON object:

"PunchOutOrderMessage": {
    "PunchOutOrderMessageHeader": {
        "Total": {
            "Money": {
                "currency": "Text",
                "content": Number
            }
        },
        "operationAllowed": "create",
        "Tax": {
            "Money": {
                "currency": "Text",
                "content": Number
            },
            "Description": {
                "xml:lang": "Text",
                "content": "Text"
            }
        },
        "Shipping": {
            "Money": {
                "currency": "Text",
                "content": Number
            },
            "Description": {
                "xml:lang": "Text",
                "content": "Text"
            }
        }
    },
    "BuyerCookie": "Text",
    "ItemIn": {
        "quantity": Number,
        "ItemDetail": {
            "UnitPrice": {
                "Money": {
                    "currency": "Text",
                    "content": Number
                }
            },
            "Description": {
                "xml:lang": "Text",
                "content": "Text"
            },
            "ManufacturerName": [
                {
                    "xml:lang": "Text",
                    "content": "Text"
                }
            ],
            "UnitOfMeasure": "Text",
            "LeadTime": Number,
            "Classification": {
                "domain": "Text",
                "content": "Text"
            },
            "ManufacturerPartID": "Text"
        },
        "ItemID": {
            "SupplierPartID": "Text",
            "SupplierPartAuxiliaryID": "Text"
        }
    }
}

Note: When there are multiple lines added, ItemIn will be a JSON array.

If a customization needed to be added to store extra attributes send in the cXML document, find the correct JSON element added and do the alterations in the method;

Self_Serv_Shop_Cart_Util_API.Add_Cxml_Punchout_Lines___()