You are here: Commerce Process > Use Case - Renewals

Use Case - Renewals


The renewals feature can take on many forms. A general use case can be implemented into the CPQ Cloud Commerce Process to bring existing items from a previous sale to sell again for a new term. Using a repeatable scope, many different interpretations of the renewals feature can be accomplished by starting from a well worked out base template.


Before using this tutorial, you must:


ClosedStep 1: Creating Commerce Attributes

  1. Navigate to the quote level of a Commerce Process.
  2. Create the following main-document attributes:
  3. Navigate to back to the Document List page and create the following sub-document attributes:

ClosedStep 2: Creating Commerce Actions

  1. Navigate to the Document List page.
  2. Create the main-document modify actionAdd Renewals.
  3. Select the Advanced Validation option “Modify Without Saving or Validating”, on the General Tab.
  4. Create the main-document modify action Set Co-Term.

ClosedStep 3: Creating a Commerce Library Function

  1. Navigate to the Document List page and create a commerce library called Renewal Add Line Items.
  2. ClosedClick here to see the BML Script.


    Quote > Add Renewal Line Items

    Function: Takes in renewalsHolderString_quote and parses it out and makes webservice 1) add line items and 2) set attributes of said line items

    Format: Asset1!!Asset2!!

    Individual format: value1#value2#value3!!value1#value2#value3!!


    //Function will add items passed in to the desired quote

    //remove the last “!!” from the string and turn into an array to loop over

    itemArray = split(substring(renewalsHolderString_quote,0, len(renewalsHolderString_quote)-2), “!!”); bmiSessionId = _system_user_session_id;

    siteName = lower(_system_company_name);

    commerceProcess = “quickstart_commerce_process”;

    quoteProcess = “quote_process”;

    buyerCompanyName = “HT-QSDev”;

    NumOfAssets = 0; //will count how many assets we add dynamically

    UpdatePartsXML = “”;

    //prep for addToTransaction API

    addTransactionURL = “https://” + lower(siteName) +””+ lower(siteName) + “/image/WebServices/addToTransaction.xml”;

    soapString = urldatabyget(addTransactionURL,””,”error”);

    soapString = replace(soapString, “SESSION_ID”, bmiSessionId);

    soapString = replace(soapString, “SITE_NAME”, lower(siteName));

    soapString = replace(soapString, “PROCESS_VAR_NAME”, commerceProcess);

    soapString = replace(soapString, “TRANSACTION_ID”, transactionID_quote);

    soapString = replace(soapString, “DOCUMENT_VAR_NAME_MAIN”, quoteProcess);


    itemsToAdd = “”;

    //Loop through items that are passed into function to add to quote

    for item in itemArray {

    //PartNumber = [0];

    //Quantity = [1];

    thisItem = split(item, “#”);

    itemsToAdd = itemsToAdd + “<bm:partItem>”

    + “<bm:part>” + thisItem[0]

    + “</bm:part>”

    + “<bm:quantity>” + substring(thisItem[1],0,find(thisItem[1],”.”))

    + “</bm:quantity>”

    + “<bm:price_book_var_name>”;

    //+ thisItem[2]

    //+ “_default_price_book” if(_quote_process_price_book_var_name <> “”) {

    itemsToAdd = itemsToAdd + _quote_process_price_book_var_name; }

    else{ itemsToAdd = itemsToAdd +”_default_price_book”; }

    itemsToAdd = itemsToAdd + “</bm:price_book_var_name>”

    + “</bm:partItem>”;

    NumOfAssets = NumOfAssets + 1;


    soapString = replace(soapString , “ITEMS_TO_ADD”, itemsToAdd);

    //print soapString;

    //soap call to add items

    result = “”;

    result = urldatabypost(“https://”+siteName +””, soapString, “”);


    //print result;


    /* The result of adding line items will tell us the last document number. We can auto assume what the next document numbers will be by finding this document number that is returned



    ldnIndex1 = find(result,”<bm:last_document_number>”);

    ldnIndex2 = find(result,”>”,ldnIndex1);

    ldnIndex3 = find(result,”</bm:last_document_number>”);

    ldnStr = substring(result,ldnIndex2+1,ldnIndex3);


    //print ldnStr;

    if (isnumber(ldnStr)) {

    ldn = atoi(ldnStr);

    //print ldn;

    curDocNum = ldn - numOfAssets;

    //print curDocNum;


    else {

    curDocNum = 2;


    curSeqNum = 0;

    updateTransactionURL = “https://” + lower(buyerCompanyName) +””+ lower(buyerCompanyName) + “/image/WebServices/update_transaction.xml”;

    //print updateTransactionURL;

    SoapUpdate = urldatabyget(updateTransactionURL,””,”error”);

    //print “SOAPSTRING: “ + soapString;

    SoapUpdate = replace(SoapUpdate, “SESSION_ID”, bmiSessionId);

    SoapUpdate = replace(SoapUpdate, “SITE_NAME”, lower(siteName));

    SoapUpdate = replace(SoapUpdate, “PROCESS_VAR_NAME”, commerceProcess);

    SoapUpdate = replace(SoapUpdate, “TRANSACTION_ID”, transactionID_quote);

    SoapUpdate = replace(SoapUpdate, “BUYER_COMPANY_NAME”, buyerCompanyName);

    SoapUpdate = replace(SoapUpdate, “SUPPLIER_COMPANY_NAME”, _system_supplier_company_name);

    SoapUpdate = replace(SoapUpdate, “DOCUMENT_VAR_NAME_MAIN”, quoteProcess);

    SoapUpdate = replace(SoapUpdate, “ACTION_VAR_NAME”, “_update_line_items”);

    SoapUpdate = replace(SoapUpdate, “LOGIN_NAME”, _system_user_login);

    //Get sequence number that is required for updateTransaction API

    for line in line_process{

    if(line._sequence_number > curSeqNum) {

    curSeqNum = line._sequence_number;



    for item in itemArray {

    //Asset Start Date(previous) = [2]

    //Asset End Date(previous)/Auto Set Asset Start Date (new) = [3]

    //Asset SFDC ID = [5]

    curDocNum = curDocNum + 1;

    curSeqNum = curSeqNum + 1;

    thisItem = split(item, “#”);

    UpdatePartsXML = UpdatePartsXML + “<bm:line_process bm:bs_id=’” + transactionID_quote + “’ bm:buyer_company_name=’” + buyerCompanyName + “’ bm:buyer_user_name=’superuser’ bm:currency_pref=’USD’ bm:data_type=’3’ bm:document_name=’Line’ bm:document_number=’” + string(curDocNum) + “’ bm:document_var_name=’line_process’ bm:process_var_name=’quickstart_commerce_process’ bm:supplier_company_name=’” + buyerCompanyName + “’>”

    + “<bm:_document_number>” + string(curDocNum) + “</bm:_document_number>”

    + “<bm:_sequence_number>” + string(curSeqNum) + “</bm:_sequence_number>”

    + “<bm:assetStartDate_line>” + thisItem[2]+ “ 00:00:00” + “</bm:assetStartDate_line>”

    + “<bm:assetEndDate_line>” + thisItem[3]+ “ 00:00:00” + “</bm:assetEndDate_line>”

    + “<bm:assetId_line>” + thisItem[5] + “</bm:assetId_line>”;


    //Do calculation for base contractEndDate on contractTermMenu_quote

    if(thisItem[3] <> “”) {

    contractEndDate = strtojavadate(thisItem[3],”yyyy-MM-dd”);

    contractStartDate = adddays(strtojavadate(thisItem[3],”yyyy-MM-dd”),1);

    if(contractTermMenu_quote == “12”) {

    contractEndDate = adddays(contractStartDate,365);


    UpdatePartsXML = UpdatePartsXML + “<bm:contractEndDate_line>” + datetostr(contractEndDate,”yyyy-MM-dd HH:mm:ss”) + “</bm:contractEndDate_line>”

    + “<bm:contractStartDate_line>” + datetostr(contractStartDate,”yyyy-MM-dd HH:mm:ss”)+ “</bm:contractStartDate_line>”;



    UpdatePartsXML = UpdatePartsXML + “</bm:line_process>”;




    SoapUpdate = replace(SoapUpdate, “LINE_PROCESS”, UpdatePartsXML);

    //print SoapUpdate;

    update_result = urldatabypost(“https://”+siteName +””, SoapUpdate, “”);

    //print update_result;

    return “”;

ClosedStep 4: File Manager

  1. Navigate to the File Manager and create a Web Services folder. Here you will store two XML files: 

ClosedStep 5: Integration XSL Files

  1. Create two XSL files on your computer: 
  2. Navigate to the Integration XSL Files page for the Commerce Process.
  3. Create a new Integration XSL.
  4. Select Integration Type Import (Query Generator and Result Parser).
  5. Name the Integration XSL:  SFDC Assets - Import (sfdcAssetsImport).
  6. Enter quote_process.none into the ID Field.
  7. Browse for the Integration XSL Generator file you created and select it for the SOAP Generator XSL file.
  8. Browse for the Integration XSL Parser file you created and select it for the Results Parser XSL file.
  9. Click Add.

ClosedPutting It All Together

The integration XSL file that pulls in assets will run whenever a quote is opened. It stores the asset information in a delimited string within the renewalsHolderString_quote attribute. The format of the delimited string is:

The Add Renewals button can be clicked only during the Pending steps. This action then invokes the commerce library function Renewal Add Line Items. This will take the renewalsHolderString_quote and parse it out to add line items to the quote. It will also update the attributes through 2 Web Service calls: addToTransaction and updateTransaction. The destination redirects to the same page to display the newly added line items and ‘refresh’ the page.

Line items are now added to the quote based on clicking the Add Renewals button. You can start terming items using the contract start and end date attributes.

Co term is set at global level. The co term date attribute is dispersed to all monthly items and sets that date to ALL recurring line items. The co term action runs the pricing script with the ‘coterm’ as the action. The pricing function has been adapted to set the contract end dates of all recurring items and use that date in recalculating the price.



Related Topics Link IconSee Also