Skip to content

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___()