Export and Import

in this tutorial, we will walk you through the steps to export and import business objects in nue this process is essential for backing up your data, migrating data between environments, or sharing configurations across different instances by the end of this tutorial, you will be able to seamlessly export business objects from a nue environment, and import business objects into a nue environment understanding data storage nue operates as a dual platform system, meaning that core business objects are housed either on the salesforce platform or within nue core services and are mirrored in the other service please check out for detailed information about the data storage and mirroring nue offers a set of export and import apis to work with business objects, regardless of where they are stored export and import product catalog users can use nue api to seamless export and import the entire product catalog, including all products and their pricing details the product catalog consists of the following object types object type name uom unit of measure credit type credit type credit pool credit pool credit conversion credit conversion price book price book price tag price tag product group product group product product bundle product bundle suite bundle suite custom setting custom setting for the most current list of supported object types, please refer to https //api docs nue io/#import products and pricing data export product catalog data exports are performed asynchronously please follow the 3 step process below create the data export job; get the data export job status retrieving export results create data export job users have two options for creating a data export job 1\ export all object types used in the product catalog, with products filtered through graphql 2\ export all records for a selected list of business objects export all object types through graphql endpoint post https //api nue io/async/graphql/exports example the following is a curl example that exports nue products and bundles and their related objects through a graphql query curl location 'https //api nue io/cpq/async/exports' \\ \ header 'content type application/json' \\ \ header 'nue api key {{nue api key}}' \\ \ data '{"query" "query {\n product(where {sku { is null false}}) {\n autorenew\n bundletemplate\n configurable\n createdbyid\n createddate\n defaultrenewalterm\n defaultsubscriptionterm\n defaultuomid\n description\n enddate\n freetrialtype\n freetrialunit\n id\n imageurl\n lastmodifiedbyid\n lastmodifieddate\n longdescription\n name\n pricebookid\n pricemodel\n productcategory\n recordtype\n referenceproductid\n showincludedproductoptions\n sku\n soldindependently\n startdate\n status\n }\n}\n","variables" {}}' after the api is executed, a job id will be returned, which can be used to retrieve the asychrounous export job status for example { "jobid" "f7531328 90d9 4b60 8ac1 85387b052f07" } export all records for a selected list of business objects endpoint post https //api nue io/api/cpq/async/exports example here is an example using curl to export all records from a selected list of business objects in nue curl location 'https //api nue io/api/cpq/async/exports' \\ \ header 'content type application/json' \\ \ data '{ "format" "json", "objectnames" \["uom", "pricebook", "credittype", "creditpool", "creditconversion", "pricetag", "productgroup", "product", "bundle", "bundlesuite", "customsetting"] }' after the api is executed, a job id will be returned, which can be used to retrieve the asychronous export job status get export job status endpoint the endpoint requires a request parameter called exportjobid , which corresponds to the job id provided by the preceding api get https //api nue io/cpq/async/exports/\ exportjobid example here is an example curl command that uses the apito get the status of the job returned curl location 'https //api nue io/cpq/async/exports/f7531328 90d9 4b60 8ac1 85387b052f07' \\ \ header 'nue api key {{nue api key}}' here is an example response before the job finished (truncated for brevity) { "status" "processing", "format" "json", "objects" \[ { "name" "uom", "status" "completed", "totalsize" 8, "fileurls" \[ "https //cpq export job s3 amazonaws com/7f9e1463 7c23 4c5f bc08 acace0115616/f6eea805 4a3e 4bd8 8408 ba9260572fec/uom jsonl?x amz security token=\[redacted]\&x amz algorithm=aws4 hmac sha256\&x amz date=20240729t232358z\&x amz signedheaders=host\&x amz expires=7200\&x amz credential=\[redacted]\&x amz signature=\[redacted]" ] }, , { "name" "pricetag", "status" "processing", "totalsize" 0 } ] } an incomplete but still processing job will have the status processing as shown above each completed object will provide the object name, status, the size of the output measured in rows of data, and one or more fileurls the fileurls can be used as a parameter in curl to retrieve the export results for that object, which is demonstrated in the next and final example of the export process incomplete object exports may be listed as processing indicating that they are in the process of being exported, as in the example above for the pricetag objects; or incomplete object exports may not yet be listed at all if the process of exporting that object has yet to begin in the full (non truncated) results for the example above, the following objects were returned with status completed uom, credittype, creditpool, creditconversion, and pricebook pricetag is returned with the status processing finally, productgroup, product, bundle, bundlesuite, and customsetting were not returned at all because they had not yet begun to be exported retrieving export results after you have used the https //api docs nue io/#get data export job status , as demonstrated in the previous section, you can use curl to retrieve the data for each object one by one here is an example curl command to retrieve the uom objects from the previous example curl location 'https //cpq export job s3 amazonaws com/7f9e1463 7c23 4c5f bc08 acace0115616/f6eea805 4a3e 4bd8 8408 ba9260572fec/uom jsonl?x amz security token=\[redacted]\&x amz algorithm=aws4 hmac sha256\&x amz date=20240729t232358z\&x amz signedheaders=host\&x amz expires=7200\&x amz credential=\[redacted]\&x amz signature=\[redacted]' note that the fileurls returned by the https //api docs nue io/#get data export job status include all necessary authentication credentials, which have been redacted for these examples you do not need to provide any extra credentials for these queries here is an example response (truncated for brevity) {"meta objectname" "uom"} {"roundingmode" "up","termdimension" "quarter","decimalscale" 0,"name" "user/quarter","active"\ true,"id" "user/quarter","quantitydimension" "user"} {"roundingmode" "up","decimalscale" 0,"name" "each","active"\ true,"id" "each","quantitydimension" "each"} note that although we specified json format, the output is technically in https //jsonlines org/ format this means that line breaks are meaningful do not try to edit the json, because it can result in errors when importing the first line of the output is used for validation when importing, to double check that we are importing the correct objects {"meta objectname" "uom"} the remaining lines are rows of objects exported from the tenant in order to import these objects into another tenant, save the entire results to a file such as uom jsonl and remember the path to this file, as it will be used when importing data import product catalog similar to exporting data, import data jobs are performed asynchronously, meaning the api doesn’t wait for the job to finish before returning the response this means that importing data is a 2 step process import products and pricing data, and get import job status import products and pricing data endpoint post https //api nue io/cpq/async/imports/revenue builder data?import operation=upsert example here is an example curl command that imports all importable objects using the https //api docs nue io/#import products and pricing data curl location 'https //api nue io/cpq/async/imports/revenue builder data?import operation=upsert' \\ \ form 'uom=@"uom jsonl"' \\ \ form 'credit type=@"credittype jsonl"' \\ \ form 'credit pool=@"creditpool jsonl"' \\ \ form 'credit conversion=@"creditconversion jsonl"' \\ \ form 'price book=@"pricebook jsonl"' \\ \ form 'price tag=@"pricetag jsonl"' \\ \ form 'product group=@"productgroup jsonl"' \\ \ form 'product=@"product jsonl"' \\ \ form 'bundle=@"bundle jsonl"' \\ \ form 'bundle suite=@"bundlesuite jsonl"' \\ \ form 'custom setting=@"customsetting jsonl"' here is a breakdown of the parameters provided to the api in this example parameter example description import operation upsert this parameter relates to some special behavior of pricebookentry objects if you know that you are not importing any new pricebookentry objects, you can safely omit this parameter such that the location becomes https //api nue io/cpq/async/imports/revenue builder data otherwise, if you are re importing any existing pricebookentry objects, or if you are not sure, please include this parameter uom @"uom jsonl" this tells curl to use the file uom jsonl in the same directory as the import file to import uom objects if you are not importing uom objects, feel free to omit this parameter credit type @"credittype jsonl" similarly for credittype objects credit pool @"creditpool jsonl" similarly for creditpool objects credit conversion @"creditconversion jsonl" similarly for creditconversion objects price book @"pricebook jsonl" similarly for pricebook objects price tag @"pricetag jsonl" similarly for pricetag objects product group @"productgroup jsonl" similarly for productgroup objects product @"product jsonl" similarly for product objects bundle @"bundle jsonl" similarly for bundle objects bundle suite @"bundlesuite jsonl" similarly for bundlesuite objects custom setting @"customsetting jsonl" similarly for customsetting objects the following is an example response of the api { "jobid" "a06d0e8f 9046 439d b336 d24d55d2d7fa" } import jobs are performed asynchronously, meaning the api doesn’t wait for the job to finish before returning the response instead, the api returns a jobid that the user can provide as the parameter to a https //api docs nue io/#get import job status call in order to check the status of the given job get import job status endpoint get https //api perftest nue io/cpq/async/imports/revenue builder data/{{importjobid}} example here is an example curl command that gets the status of an import job using the https //api docs nue io/#get import job status , using the jobid returned in the previous example curl location 'https //api perftest nue io/cpq/async/imports/revenue builder data/a06d0e8f 9046 439d b336 d24d55d2d7fa' in this api, the only parameter aside from authentication is the jobid that was the output of the https //api docs nue io/#import products and pricing data call in the previous step example results from the above query (truncated for brevity) { "jobid" "a06d0e8f 9046 439d b336 d24d55d2d7fa", "status" "completed", "integrationtype" "salesforce", "format" "json", "starttime" "2024 07 26t00 05 28z", "endtime" "2024 07 26t00 05 40z", "importjobs" \[ , { "objectname" "credittype", "status" "completed", "integrationtype" "salesforce", "format" "json", "starton" "2024 07 26t00 05 28z", "endon" "2024 07 26t00 05 40z" }, ] } note that the above results have been truncated so that they only include the results for credittype complete results will include similar result json objects for each object type (e g , uom , credittype , etc ) being exported if the process is not yet complete, these results will show the object currently being imported with status processing as in the export example, and objects that have not started being imported will not be listed any errors will be returned in the result json object along with details that explain what went wrong import orders and subscriptions users can import subscriptions into nue via api by following these steps 1\ prepare the https //docs nue io/import subscriptions into nue# file 2\ execute the import api to upload the subscription csv file after the import, one active order is created for each subscription in the import file the orders and subscriptions can be viewed in salesforce create import job endpoint post https //api nue io/cpq/async/imports example the following example creates a subscription import job that accepts a subscription csv file curl location 'https //api nue io/cpq/async/imports' \\ \ header 'content type application/json' \\ \ header 'nue api key {{nue api key}}' \\ \ data '{ "format" "csv", "objectname" "subscription" }' this api returns a status code of 201 and includes a job id in the response payload, representing the id of the asynchronous job created for the import upload subscription csv file endpoint patch https //api nue io/cpq/async/imports/{{importjobid}}/content example `` the following example demonstrates how to upload a subscription csv file to an import job specified by the importjobid curl location request patch 'https //api nue io/cpq/async/imports/{{importjobid}}/content' \\ \ header 'nue api key {{nue api key}}' \\ \ form 'data=@"3smrwts y/subscriptionuploadfile csv"' get subscription import result endpoint get https //api nue io/cpq/async/imports/{{importjobid}} example the following example retrieves the subscription import result of an import job specified by the importjobid curl location 'https //api nue io/cpq/async/imports/{{importjobid}}' \\ \ header 'nue api key {{nue api key}}' export transaction data export via api users can utilize the https //api docs nue io/#create data export job to export up to 10,000 records of the following transactions into csv files orders and order products invoice, invoice items, and invoice item details credit memo, credit memo items, and credit memo item details usage tax codes transaction hub create export job endpoint post https //api nue io/cpq/async/exports example this example demonstrates how to export the results of a graphql query on usage records into a csv file curl location 'https //api nue io/cpq/async/exports' \\ \ header 'nue api key {{nue api key}}' \\ \ data '{ "format" "csv", "objectnames" \[ "usage" ], "query" "query { usage( where { and \[{ and \[ { starttime { lte \\"2024 07 31t23 59 59 07 00\\" } } { starttime { gte \\"2024 07 01t00 00 00 07 00\\" } } ] } { and \[ { and \[ { starttime { lte \\"2024 07 31t23 59 59 07 00\\" } } { starttime { gte \\"2024 07 01t00 00 00 07 00\\" } } ] }{ customer { id { eq \\"001rr00000jcgicyar\\" } } }] } { iscash { eq true } } { currencyisocode { eq \\"usd\\" } } ] } orderby { starttime desc } ){ customer { name} id name subscriptionnumber product { name, sku} status starttime endtime quantity termedtotalquantity ratedamount termstartdate termenddate ordernumber orderproductnumber createddate lastmodifieddate subscriptionid zoneid windowsize ratabletime ratedtime orderproductid properties errorcode errormessage invoiceid invoiceitemid invoiceitemnumber invoicenumber creditsapplied invoiceitemdetailid invoiceitemdetailnumber iscash salesaccount { name} }}" }' upon successful execution of the api, an export job id will be created get export job result endpoint post https //api nue io/cpq/async/exports/{{exportjobid}} this endpoint retrieves the status and details of a specific export job export via ui users can click the 'download' action icon above the list for the following objects in nue to export transactions into csv files order, invoice, credit memo, usage users can choose to export either the currently selected fields or all fields additionally, users can use the search box and filters to refine the list of objects and their related records for export when users export a set of records, their related child records will be exported as a separate csv file for example, when users click the 'download' action on the invoice list, a popup will appear, allowing them to select the types of records to export options include invoices, invoice items, and invoice item details import transaction hub records in addition to exporting transaction hub records through the api and ui, users can also import custom transaction hub records via both methods this enables admin users to bring in records for custom integrations, allowing them to establish pre existing mapping data between nue and external systems (optional) create custom transaction hub type if you need to upload transaction hub records for a custom integration, you can create a custom external system type the platform currently supports the following external systems netsuite, business central, rightrev, stripe, quickbooks, avalara, and salesforce to view all existing external system types configured in your tenant, you can use the api endpoint below curl location 'https //api nue io/metadata/valuesets/externalsystem' \\ \ header 'nue api key {{nue api key}}' you can use the following api to create a new value set for a custom external system, such as microsoft dynamics curl location request patch 'https //api nue io/api/metadata/valuesets/externalsystem/values' \\ \ header 'nue api key {{nue api key}}' \\ \ data '{ "values" \[ { "apiname" "microsoftdynamics", "name" "microsoft dynamics" } ] }' import transaction hub records users can bulk import transaction hub records through either the api or the ui during import, the tool validates that the provided nue ids exist for the specified transaction type supported transaction types currently include customer, order, invoice, credit memo, product, order product, debit memo, invoice item, credit memo item, and debit memo item each request supports up to 5,000 records note the import tool (api and ui) cannot be used to import standard transaction hub records for stripe, quickbooks, or netsuite for these integrations, please use the dedicated ui to upload customer and product mappings import transaction hub records via api step 1 create import job endpoint https //api nue io/revenue/transaction hub\ upload description create an import job with the request payload containing the transaction hub records the following example creates an import job that uploads one microsoftdynamic transaction hub record for a nue invoice curl location 'https //api nue io/revenue/transaction hub\ upload' \\ \ header 'content type application/json' \\ \ header 'nue api key {{nue api key}}' \\ \ data '{ "data" \[ { "transactiontype" "invoice", "nueid" "61d9628d 80f0 48d1 b916 2dec7503b20f", "externalsystem" "microsoftdynamics", "externalsystemid" "ext 01", "externalid" "inv 0001", "direction" "outbound", "description" "the invoice has been transferred " } ] } ' the job id will be available in the api response { "status" "success", "description" "job created successfully!", "jobid" "89b8cda2 5538 4abb 85d9 fe1265ec25a9" } step 2 get import job status endpoint https //api nue io/revenue/transaction hub/async job/\ jobid description retrieve the import job status by job id the following shows a sample response { "status" "completed", "result" { "successcount" 1, "skipcount" 0, "failurecount" 0, "errors" \[] }, "errorcode" "", "errormessage" "" } import transaction hub records on ui to import transaction hub records via the ui, follow these steps log in to nue and go to revenue manager → transaction hub click upload above the transaction hub grid select download template to get the csv template populate the csv using the template and then import the file after the import job completes, refresh the page to view the newly imported records