Articles in this section

See more

Configure catalog import jobs in SFCC

  • Updated

As per the previous setup step, the data sync between SFCC and Marketplacer is set up in SFCC as catalog jobs. After the cartridge installation, the following jobs are added to SFCC and can be configured to suit business and technology requirements:

  • MKP-ImportCatalog
  • MKP-ImportInventory
  • MKP-ImportPricebook
  • MKP-ImportSellers
  • MKP-ExportOrders
  • MKP-OrderStatusUpdates

A common set up is:

  • product (hourly)
  • order export (1 mins)
  • order updates (5 min)
  • inventory (15 mins)
  • pricing (15 mins)
  • seller (hourly)

IMPORTANT: After jobs are configured, all product, price, inventory, status changes, etc, must be made in Marketplacer, not SFCC Business Manager. If you make changes in SFCC for information that syncs from Marketplacer, it can cause data errors.

Jobs

MKP-ImportCatalog

This job is used for importing Marketplacer catalog data into SFCC. This will make use of the custom object named marketplacerCatalogConfig for the query configurations. 

The job creates three types of XML file (categories, products, and assignments). This job has three steps.

STEP: GenerateTaxon
This step calls the API with the taxon query (using taxonQueryAttributes) and gets the categories from the Marketplacer end point. The output of this step will be a catalog-category XML file stored in the path Impex/src/marketplacer/catalog.

Job parameters:

Name

Purpose

sfCatalogID

The ID of the storefront catalog of the site. This is where the categories will be stored.

depth

The length of the tree level up to which the categories are to be fetched.

pagination

Categories retrieved from Marketplacer are paginated with site preference ‘advertsPerAPICall’.

Example Query format:

{

  taxons{

    pageInfo{

      hasNextPage

      endCursor

    }

    totalCount

    nodes{

      id

      legacyId

      displayName

      title

      description

      image {

        id

        url

      }

      parent {

        id

        legacyId

        displayName

      }

      children(showOnlineOnly: true) {

        nodes {

          id

         legacyId

          displayName

          title

          description

          image {

            id

            url

          }

          parent {

            id

            legacyId

            displayName

          }

          children(showOnlineOnly: true) {

            nodes {

              id

              legacyId

              displayName

              title

              description

              image {

                id

                url

              }

              parent {

                id

               legacyId

               displayName

              }

            }

          }

        }

      }

    }

  }

}
STEP: GenerateAdverts (listings)

This step calls the API with the advert query (using advertQuery) and gets the adverts from the Marketplacer end point. The output of this step will be catalog-products XML file stored in the path Impex/src/marketplacer/catalog. 

It is recommended to run the job with isInitialFeed checked if you are running it for the first time and then unchecked in the following job runs.

Job parameters:

Name

Purpose

masterCatalogID

The ID of the master catalog of the site. This is where the products will be stored.

sfCatalogID

The ID of the storefront catalog of the site. This is where the category -> product assignments will be stored.

isInitialFeed

Identify whether the job run is for the first time or not.

Example Query format:

{

advertSearch(attributes: {

saleTypes: [BUY_ONLINE]

}) {

adverts {

  pageInfo {

    hasNextPage

    hasPreviousPage

    endCursor

  }

  totalCount

  nodes {

    id

    title

    taxonNullable {

      id

      legacyId

      displayName

      taxCode

    }

    taxCode

    legacyId

    lowestPriceCents

    productFeatures

    images {

      nodes {

        swatch: url(height: 53, width: 53, fit:clip)

        large: url(height: 540, width: 540, fit:clip)

        medium: url(height: 247, width: 247, fit:clip)

        small: url(height: 90, width: 90, fit:clip)

      }

    }

    brand {

      id

      name

      logo {

        url(height: 90, width: 90)

      }

    }

        featureOptionValues {

          edges {

            node {

              displayName

              id

              name

              position

              optionType {

                category

                description

                name

                displayName

                optionValues {

                  edges {

                    node {

                      id

                      name

                      displayName

                    }

                  }

                }

              }

            }

          }

        }

    saleType

    condition

    isFeatured

    isPromoted

    priceUnit

    bookingTerms

    createdAt

    updatedAt

    descriptionHtml

    productFeatures

    baseDomesticShippingCost

    externalId

    gender

    hasFreeInternationalShipping

    hasFreeDomesticShipping

    baseInternationalShippingCost

    internationalShippingEnabled

    customIframeThumbnail {

  url

    }

    customIframeUrl

    youtubeVideoId

    youtubeVideoUrl

    lowestOriginalPriceCents  

    year

    specificationsHtml

    seller {

      id

      businessName

      logo {

        url(width: 100, height:100)

      }

    }

    variants(displayableOnly: false) {

      nodes {

        id

        sku

        legacyId

        label

        barcode

        countOnHand

        infiniteQuantity

        lowestOriginalPriceCents     

        lowestPriceCents

        displayable

        taxCode

        images {

          nodes {

            swatch: url(height: 53, width: 53, fit:clip)

            large: url(height: 540, width: 540, fit:clip)

            medium: url(height: 247, width: 247, fit:clip)

            small: url(height: 90, width: 90, fit:clip)

          }

        }

        optionValues {

          nodes {

            displayName

            optionType {

              id

              displayName

            }

          }

        }

      }

    }

  }

}

}

}
 
 

STEP: ImportTaxonsAndAdverts

This is the OOB ImportCatalog step which imports the created catalog files. After importing these files will be moved to Impex/archive/marketplacer/catalog (This path is configurable in the job).

Job parameters:

Name

Purpose

WorkingFolder

The path of the source folder from where the XML files are to be imported.

FileNamePattern

The pattern of the filenames to be accepted.

NoFilesFoundHandling

Denotes how to handle the ’No Files Found’ situation.

ImportFailedHandling

Denotes how to handle Import failure.

AfterImportFileHandling

Denotes how to handle Import succeeded files.

ArchiveFolder

The target folder to store the imported files.

MKP-ImportInventory

This job is used for importing Marketplacer inventory data into SFCC. This will make use of the custom object named marketplacerCatalogConfig for the query configurations. The job will create a single type of XML file (inventory) and has two steps:

STEP: GenerateInventory

This step calls the API with the advert query (using advertQuery) and gets the advert inventory from the Marketplacer end point. The output of this step will be an inventory XML file stored in the path Impex/src/marketplacer/inventory. 

It is recommended to run the job with isInitialFeed checked if you are running for the first time and then unchecked in the following job runs.

Job parameters:

Name

Purpose

inventoryListID

The ID of the inventory of the site. This is where the product inventory will be stored.

isInitialFeed

Identify whether the job run is for the first time or not.

 

STEP: Import-MKP-Inventory

This is the OOB ImportInventoryLists step which imports the created inventory files. After importing these files will be moved to Impex/archive/marketplacer/inventory (This path is configurable in the job).

Job parameters:

Name

Purpose

WorkingFolder

The path of the source folder from where the XML files are to be imported

FileNamePattern

The pattern of the filenames to be accepted.

NoFilesFoundHandling

Denotes how to handle the ’No Files Found’ situation.

ImportFailedHandling

Denotes how to handle Import failure.

AfterImportFileHandling

Denotes how to handle Import succeeded files.

ArchiveFolder

The target folder to store the imported files.

MKP-ImportPricebook

This job is used for importing Marketplacer product prices data into SFCC. This will make use of the custom object named marketplacerCatalogConfig for the query configurations. This job creates two types of XML files (list price and sale price) and has two steps.

Not included by default: Wholesale prices and minimum order/quantity requirements. However, wholesale prices can be accessed via Marketplacer’s APIs.

STEP: GeneratePricebook

This step calls the API with the advert query (using advertQuery) and gets the advert prices from the Marketplacer end point. The output of this step will be pricebook XML files stored in the path Impex/src/marketplacer/pricebook. It is recommended to run the job with isInitialFeed checked if you are running for first time and then unchecked in the following job runs.

Job parameters:

Name

Purpose

listPricebookName

The name of the list pricebook of the site. This is where the product list prices will be stored.

listPricebookID

The ID of the list pricebook of the site. This is where the product list prices will be stored.

salePricebookName

The name of the sale pricebook of the site. This is where the product sale prices will be stored.

salePricebookID

The ID of the sale pricebook of the site. This is where the product sale prices will be stored.

currency

The currency for the pricebooks.

isInitialFeed

Identify whether the job run is for the first time or not.

 

STEP: ImportMKPPricebook

This is the out of the box ImportPriceBook step which imports the created pricebook files. After importing these files will be moved to Impex/archive/marketplacer/pricebook (This path is configurable in the job).

Job parameters:

Name

Purpose

WorkingFolder

The path of the source folder from where the XML files are to be imported

FileNamePattern

The pattern of the filenames to be accepted.

NoFilesFoundHandling

Denotes how to handle the ’No Files Found’ situation.

ImportFailedHandling

Denotes how to handle Import failure.

AfterImportFileHandling

Denotes how to handle Import succeeded files.

ArchiveFolder

The target folder to store the imported files.

MKP-ImportSeller

This job is used for importing Marketplacer product seller data into SFCC. This will make use of the custom object named marketplacerSellerConfig for the query configurations. This job will create a single type of XML file (seller custom object). The data imported is saved as the custom objects of type: marketplacerSellerDetails. This job has two steps.

STEP: GenerateSellers

This step calls the API with the seller query (using sellerQuery) and gets the seller data from the Marketplacer end point. The output of this step will be seller custom object XML files stored in the path Impex/src/marketplacer/seller.

Job parameters:

Name

Purpose

isFullFeed

Identify whether the job run is for full feed or delta feed.

Example Query format:

{

  sellerSearch {

    sellers {

      pageInfo {

          hasNextPage

          endCursor

        }

        nodes {

          id

          businessName

          online

          address {

            address

            subaddress

            city

            country {

              name

            }

            state {

              name

            }

            postcode

            lat

            lng

          }

          businessNumber

          emailAddress

          logo {

            url(height: 100, width: 100)

          }

          openingHours

          phone

          policies {

            returnPolicy

            servicePolicy

            shippingPolicy

            storePickupPolicy

          }

          storeDescription

          storeImages {

            filename

            url

          }

          updatedAt

        }

      }

    }

  }

STEP:ImportMKPSellers

This is the out of the box ImportCustomObjects step which imports the created custom object files. After importing these files will be moved to Impex/archive/marketplacer/seller (This path is configurable in the job).

Job parameters:

Name

Purpose

WorkingFolder

The path of the source folder from where the XML files are to be imported

FileNamePattern

The pattern of the filenames to be accepted.

NoFilesFoundHandling

Denotes how to handle the ’No Files Found’ situation.

ImportFailedHandling

Denotes how to handle Import failure.

AfterImportFileHandling

Denotes how to handle Import succeeded files.

ArchiveFolder

The target folder to store the imported files.

MKP-ExportOrders

Note: The following export functionality does not represent options where SFCC code contains WebHooks to push orders or if there is a third party OMS. You can adjust the implementation to account for these kinds of business scenarios.

This job is used for exporting SFCC orders that contain Marketplacer products into a Marketplacer endpoint. This will make use of the custom object named marketplacerOrderConfig for the query configurations. 

This job does not create any XML files. If the export of an order is successful, then that order’s custom attribute: marketplacerExportStatus will be changed from value “NOT_EXPORTED” to “EXPORTED” and the corresponding Marketplace order ID will be received from response and stored in the custom attribute: marketplacerOrderId. 

If an error response is received from the API for an order during export, then that error type (response code) will be stored in the order’s custom attribute: marketplacerExportError, and the error message will be logged. 

The recommended time for the job to run is between 5-15 minutes. Implementation partner should confirm this with the operator.

When the job runs, Marketplacer checks all orders, but only syncs the ones that contain products sold by Marketplacer sellers, filtering out all other products. For example:

When this happens in SFCC

This happens in Marketplacer

A customer makes an order for 1 first-party item

Marketplacer checks this order, determines that it contains no items sold by Marketplacer sellers, and ignores it.

A customer makes an order for 3 items - 1 first-party item, 1 item sold by Marketplacer seller A, and 1 item sold by Marketplacer seller B.

Marketplacer checks this order and determines it contains items sold by Marketplacer sellers. It filters out the 1 first-party item and creates an order on Marketplacer for the 2 remaining items from sellers A and B. The order is split accordingly in Marketplacer.

STEP: ExportOrders

This step calls the API with the qualified (contains Marketplacer products and not yet exported) orders list using the query (requiredExportParams) configured the custom object. This query is not complete and indicates only the required response parameters from the API call. There are no specific job parameters.

The merchant has the option to send the payment token to Marketplacer to support further transactions e.g. capture or refund. A developer needs to populate the mpPaymentToken field if you wish to send the payment token to Marketplacer.

How to identify Marketplacer orders?

The marketplacer products and product line items will have custom attributes to store the seller Id, name, and logo image. The orders while getting created will check for product line items which has value for marketplacerSellerId custom attribute, if it has, then a custom attribute: containsMarketplacerProducts of the order will be set as true. Hence orders with this flag as true can be fetched for exporting.

The SFCC Order ID is sent to Marketplacer and appears as an External ID, using the externalIds endpoint.

Example Query format (complete):

  mutation {

    orderCreate (

    input:

      {

        order: {

          firstName: "Customer shipping first name"

          surname: " Customer shipping last name "

          companyName:" Customer shipping company name"

          phone: " Customer shipping phone number"

          emailAddress: " Customer shipping email"

          address: {

            address: " Customer shipping address1"

            city: "Shipping city name"

            state: {

              short: "Two letter state code"

            }

            country: {code: "two letter country code"}

            postcode: "Customer shipping post code"

          }

          billingFirstName: " Customer billing first name "

          billingSurname: " Customer billing last name "

          billingCompanyName: " Customer shipping company name "

          billingPhone: " Customer billing phone number "

          billingEmailAddress: " Customer billing email "

          billingAddress: {

            address: " Customer billing address1"

            city: "Billing city name"

            state: {

              short: "two letter state code"

            }

            country: {code: “two letter country code"}

            postcode: "Customer billing post code "

          }

      }

        lineItems: [

          {

            variantId: "product_id1"

            quantity: total quantity of product1 (Integer)

            totalCents:  total price of product1 in cents (Integer)

            postageCents: total shipping price of product1 (multiplied by quantity) in cents (Integer)

          },

        {

            variantId: " product_id2”

            quantity: total quantity of product2 (Integer)

            totalCents: total price of product2 in cents (Integer)

            postageCents: total shipping price of product2 (multiplied by quantity) in cents (Integer)

          }

      ]

    }

  )

    {

      clientMutationId

      status

      errors {field messages}

      order {

        id

        token

        total

        subtotal

        taxTotal

        postage

        paymentInstrumentType

      }

    }

}

SFCC order logic is based on orders, whereas Marketplacer logic is based on invoices. Invoices are created based on the seller and the products the seller is requested to fulfill. The cartridge unpacks the SFCC order and creates the correct invoices in Marketplacer.  

Note: A SFCC/Marketplacer order can have multiple invoices attached to it.

MKP-ExportStatusUpdates

This job is used for getting order updates from the Marketplacer end point and updating the SFCC order. The data in the update indicates the order shipping status and the tracking link against each line item. 

This job will make use of the custom object named marketplacerOrderConfig for the query configurations. The query used is configured in the custom attribute requiredUpdateParams. This query is not complete and indicates only the required response parameters from the API call. This job will not create any XML files.

If the order update is successful, then that order’s custom attribute: marketplacerShippingStatus will be changed from value “NOT_SHIPPED” to either “SENT” or “PARTIALLY_SENT”.

During an order update success, the shipped product line items custom attributes marketplacerShippingStatus will be set to value ‘SHIPPED’ and marketplacerTrackingLink will be set with the returned tracking link in the response.

Shipment details

Shipments details for Marketplacer products are added by the seller in Marketplacer, and synced to SFCC. Shipment information also syncs with tracking information that is attached to the original order. Partial shipments are supported.

Shipping carriers need to be set up in Marketplacer for the details to come through successfully.

Example shipment / dispatch information in Marketplacer

Insert screenshot

Example of SFCC Order with 2 Marketplacer items that have been shipped

STEP: Generate-MKP-OSU

This step calls the API with the qualified (contains Marketplacer products, exported and not yet shipped) orders list using the query (requiredUpdateParams) configured the custom object. There are no specific job parameters.

Example Query format (complete):

{

  nodes (ids: ["marketplacer_order_id1", " marketplacer_order_id2"]) {

    ... on Order {

      id

      aggregateInvoiceStatus

      aggregateInvoiceStatusFinal

      lineItems {

        nodes {

          id

          quantity

          status

          variant {

            id

            legacyId

          }

          shipment {

            carrier

            id

            trackingLink

            trackingNumber

          }

        }

      }

      shipments {

        carrier

        id

        trackingLink

        trackingNumber

      }

    }

  }
}

 

After configuring catalog import jobs, proceed to updating the storefront catalog in SFCC. 

Was this article helpful?
0 out of 0 found this helpful

Related articles

On this page