Other Functions

The "addpartstotransaction" BML function is used to add parts to a quote automatically from within a Transaction.

Syntax:

addpartstotransaction(jsonArray [, priceBookVarName [, resultAttributeArray]])

Parameters:

The "addtotransaction" BML function is used to add Models to a Transaction using BML. This function can be used to automatically add a new Transaction Line which contains a Model which is pending configuration by the sales user.

Syntax:

addtotransaction (items, [priceBookVarName],[resultAttributeArray])

Parameters:

Return Type: JSON Array

Example:

configAttrs1 = json; //initial config attribute values for the first model
jsonput(configAttrs1 , "connectivity", "WiFi/Bluetooth");
jsonput(configAttrs1 , "storage", "128GB");
jsonput(configAttrs1 , "dataplan", "100GB");

modelLine1 = json; // item values for the first model to be added
jsonput(modelLine1 , "_model_variable_name", "vario5000");
jsonput(modelLine1 , "_model_product_line_var_name", "tablets");
jsonput(modelLine1 , "_model_segment_var_name", "varioTablets");
jsonput(modelLine1 , "_price_quantity", 5);
jsonput(modelLine1 , "_price_unit_price_each": 599);
jsonput(modelLine1 , "_config_attr_values", configAttrs1);

configAttrs2 = json; //initial config attribute values for the second model
jsonput(configAttrs2 , "connectivity", "WiFi/Bluetooth/4G LTE");
jsonput(configAttrs2 , "storage", "256GB");
jsonput(configAttrs2 , "dataplan", "100GB");

modelLine2 = json; // item values for the second model to be added
jsonput(modelLine2 , "_model_variable_name", "vPhablet");
jsonput(modelLine2 , "_model_product_line_var_name", "phablets");
jsonput(modelLine2 , "_model_segment_var_name", "varioTablets");
jsonput(modelLine2 , "_price_quantity", 10);
jsonput(modelLine2 , "_price_unit_price_each": 849);
jsonput(modelLine2 , "_config_attr_values", configAttrs2);

items = jsonarray; // items to added to the transaction
jsonarrayappend(items , modelLine1 );
jsonarrayappend(items , modelLine2 );

// list of attributes that we want returned
resultAttributeArray = jsonarray("[\"_document_number\", \"_part_quantity\",
\"_price_item_price_each\"]");

//adds the two models above to the transaction using the default price book
resultArray = addtotransaction(items, "_default_price_book",
resultAttributeArray);

print(resultArray);
//prints a sample response which looks like this

// [{"_document_number":"2", "_price_quantity":"5",
"_price_unit_price_each":"599.00"},
// {"_document_number":"3", "_price_quantity":"10",
"_price_unit_price_each":"849.00"}]

The "generateHmacMessage" BML function is used to create Hash-based Message Authentication Codes for use in securing outbound web service calls to public web services. The "generateHmacMessage" function supports five types of hashing algorithms including: SHA-256, SHA-384, SHA-512, SHA-1, and MD5.

Syntax:

generatehmacmessage("message", "key", ["algorithm"]);

Parameters:

Return Type: String

Example:

key = "cfthsnkjsavjiCe=";
algo = "MD5";
hmac = generatehmacmessage(inputmessage, key, algo);
print(hmac);
//prints eaf3702517fef48d3f114f32a3c3394b

This function returns the delimited string for array attributes with $,$ as the delimiter.

Syntax:

getarrayattrstring(SingleArray arrayIdentifier)

Parameters:

Return Type: String

Example of getarraystr:

This function returns the file name (filename), file content (filecontent), and MIME type (mimetype) of a given file attachment attribute in a dictionary of <anytype>. The file content can be retrieved as a bytearray or as Base64 encoded string based on the input parameters.

Syntax:

Dict<anytype> getattachmentdata(String attachmentId [, Boolean asBytes]

Example:

//consider 'maindocFileAttachment' as main document attachment attribute and 'subdocFileAttachment' as sub document attachment attribute
mainattachment = getattachmentdata(maindocFileAttachment);
print get(mainattachment ,"filename", "string"); // Prints the file name of main attachment attribute
print get(mainattachment ,"filecontent", "string"); // Prints the file content of main attachment attribute as Base64 encoded String
print get(mainattachment ,"mimetype", "string"); // Prints the mime type of main attachment attribute
//To access the file attached to sub document attachment attribute
for line in lineItems {
 subdocattachment = getattachmentdata(line.subdocFileAttachment);
}

This function retrieves the values of configuration attributes in Commerce.

Syntax:

getconfigattrvalue(configAttrVarname)

-OR-

getconfigattrvalue([documentNumber], configAttrVarname)

Parameters:

Return Type: String

Example:

Retrieves an old value for given variable name containing old value and document number.

Syntax:

getoldvalue(variableName [, documentNumber])

Parameters:

Return Type: String

It will return empty string for the following cases:

• When it is called from debugger
• If the document with the given document number does not exist
• If the variable with the given variable name does not exist in the document

Examples:

pre1 = getoldvalue("_quote_bill_to_address");

pre2 = getoldvalue("_price_net_price", 2);

This function returns the status of the reason variable name in an approval sequence.

Syntax:

Integer getreasonstatus(String)

Parameters:

Return Type: Integer (associated with one of the following statuses):

• BM_REASON_STATUS_INVALID: No reason exists in admin reason tree with given variable name.
• BM_REASON_STATUS_INACTIVE: Reason exists in admin reason tree but the condition for the reason is not met, therefore no record for it exists in the user-side tree.
• BM_REASON_STATUS_PENDING: Reason exists in the user-side reason tree and there are pending approvals.
• BM_REASON_STATUS_APPROVED: Reason exists in the user-side tree and it is approved by all approvers, therefore the reason is completely approved.
• BM_REASON_STATUS_REJECTED: Reason exits in user-side tree, but has been rejected by at least one approver.

This function generates unique IDs for assets tracked in Asset-Based Ordering. Every asset is tracked in ABO using an asset key. When a unique ID is generated, it becomes the asset key for an asset. The number of asset keys to generate is dependent on the count parameter in the function.

Syntax:

String[] getuuid(Integer count)

Example:

getuuid(2); // Generates string array with 2 unique IDs.

Output:

[6bafc278-25fd-495f-8360-67bcfb8776b0, 65abced9-5c47-47c6-bf18-ab96fb73935f]

Imports the transaction data. If the transaction with the given bsid doesn't exists, then it throws an exception.

Syntax:

importtransactiondata(Long bsid)

Parameters:

Return Type: Boolean

Example:

importtransactiondata(12345); // Where 12345 is the bsid

This function invokes global table functions.

Syntax:

invoke(globalTableFunction, [delimitedData, [defaultData]])

Parameters:

Return Type: Boolean

Example:

The following script invokes the global function someGlobalFunction. The parameters are passed as a delimited string. If a valid string is not returned by someGlobalFunction, the default string is "error_in_rule"

params = "";
params = var_frequency + "~" + "model number";
return invoke("someGlobalFunction",params,"error_in_rule");

Evaluates whether a particular Object is null or not. Returns true if argument passed is null.

Syntax:

isnull(String (or Date (or Array or (dict))))

Parameters:

Return: Boolean

Example:

This evaluates to false.

If getconfigattrvalue is called for a non-existing attribute, it returns null. If the return value is passed to isnull, it will return true.

Writes an event to the Performance Log table, which is visible by filtering on "BML" for the Event Type. This logging will only occur when executed outside of the debugger.

Syntax:

logtime(tag, timeElapsed)

Parameters:

Return Type: Boolean

Prints into the console window of the Function Editor. Example Use Case:  For debugging.

Syntax:

print(String(or Array(or Dictionary(or Numeric(or Date(or Boolean))))) varName)

Parameters:

Return Type: Boolean

Examples:

To display "abba" in the console window in the Function Editor.

print("abba") 

To display [1,2,3,4,5] in the console window.

intArray = integer[]{1,2,3,4,5};
print(intArray); //

To display {key1=X, key2=Y} in the console window.

testDict =dict("string");
put(testDict,"key1","X");
put(testDict,"key2","Y");
print textDict;//

This function attaches a new element to the end of the string builder object. This function is related to the following BML string builder functions: "stringbuilder" and "sbtostring".

Syntax:

sbappend(stringBuilder, [string[, stringArray[, stringBuilder]]])

Parameters:

Any combination of String, StringArray, and StringBuilder items.

Return Type: String

This function converts the finished stringbuilder element to a string.

Syntax:

sbtostring(stringBuilder)

Parameters:

Any combination of String, StringArray, and StringBuilder items.

Return Type: String

This function sets a Commerce attribute value on a Main document or Sub-document. The "setattributevalue" function is supported for the following:

• Advanced Default (Main document Commerce attributes)

• Advanced Default - Before Formulas (Sub-document Commerce attributes)

• Advanced Default - After Formulas (Sub-document Commerce attributes)

• Advanced Modify - Before Formulas ( Main document Commerce Modify actions)

• Advanced Modify - After Formulas (Main document Commerce Modify actions)

• Advanced Modify - Before Formulas (Sub-document Commerce Modify actions)

• Advanced Modify - After Formulas (Sub-document Commerce Modify actions)

• Commerce BML Libraries (Function Category = Others)

Main Document Syntax:

setattributevalue(mainDocAttrVarName, value)

Sub-Document Syntax:

setattributevalue(documentNumber, subDocAttrVarName, value)

Parameters:

Example:

To set the value of an array set containing a text field, and a single row, named arraySet:

newRow = json;
jsonput(newRow, "textField", "example");
jsonarrayappend(arraySet, newRow);
setattributevalue(1, "arraySet", jsonarrayrefid(arraySet));

The BML string builder object can be used to generate large strings. In some implementations, large strings were built using string concatenation, including loops or other functional blocks. This method can cause performance issues and negative impacts on system memory. The BML string builder object contains three BML functions to build large strings more efficiently: "stringbuilder", "sbappend", and "sbtostring".

The stringbuilder functions initializes string builder objects.

Syntax:

stringbuilder([string[, stringArray[, stringBuilder]]])

Parameters:

Any combination of String, StringArray, and StringBuilder items.

Return Type: String

This function stops the execution of a BML script and displays either a business logic error or a system error to the end user. In the case of a system error, a generic error message displays and the actual error message is logged to the error log file.

Syntax:

throwerror(String errorMessage [, Boolean isSystemError])

Parameters:

Examples

This function validates that all prerequisites are satisfied prior to creation of an agreement.

• The sales user should be able to validate the quote for agreement for potential validation errors during Create Agreement action before submitting it for approval. Hence, a new BML function "validatequoteforagreement" is introduced to validate quote for agreements.

• The function can be invoked from Commerce rule actions, Advanced Modify - Before Formulas and Advanced Modify - After Formulas.

• Function performs the general, header, and line validations. See validations

• Functions takes no parameters and returns an array of strings which contains all the validation errors.

• Validation errors are set in the CmData object of the quote. Hence, the admin does not need to do anything other than calling this method to populate the validation errors.

• The array of validation errors are returned only for debugging purposes or if the admin wants to do anything additional based on these error messages in the BML.

Syntax:

String[] validatequoteforagreement()

Example:

// Calling the validation function from the action of a validation rule.
errors = validatequoteforagreement();
for error in errors { // only for debugging purpose
    print(error);
}
return dict("dict<string>");

Sample Response:

['Contract Name' cannot be empty., 'Customer Company Name' cannot be empty., Following parts have line items with overlapping date ranges: iPhone]

Validations:

• General

  All the required agreement attributes should be explicitly mapped in case of non std process.

• Header Level

  • Agreement Name field cannot be empty.

  • Customer Id field cannot be empty.

  • Customer Name field cannot be empty.

  • Agreement start date should be before agreement end date.

• Line Level

  • Part Number field cannot be empty.

  • Charge Type field cannot be empty.

  • Price Period field cannot be empty for charges where Price Type != One Time.

  • Usage UOM field cannot be empty for Usage charges.

  • For parts with Service Duration Type "F" and "O", multiple line items of the same part should have mutually exclusive date ranges.

  • For parts with Service Duration Type "V", multiple line items of the same part with same service duration and service duration period should have mutually exclusive date ranges.