Oracle–NetSuite PBCS Sync

July 5, 2017 2017.1

General Notices
Sample Code

Oracle may provide sample code in SuiteAnswers, the Help Center, User Guides, or elsewhere through
help links. All such sample code is provided "as is” and “as available”, for use only with an authorized
NetSuite Service account, and is made available as a SuiteCloud Technology subject to the SuiteCloud
Terms of Service at www.netsuite.com/tos.

Oracle may modify or remove sample code at any time without notice.

No Excessive Use of the Service

As the Service is a multi-tenant service offering on shared databases, Customer may not use the
Service in excess of limits or thresholds that Oracle considers commercially reasonable for the Service.
If Oracle reasonably concludes that a Customer’s use is excessive and/or will cause immediate or
ongoing performance issues for one or more of Oracle’s other customers, Oracle may slow down or
throttle Customer’s excess use until such time that Customer’s use stays within reasonable limits. If
Customer’s particular usage pattern requires a higher limit or threshold, then the Customer should
procure a subscription to the Service that accommodates a higher limit and/or threshold that more
effectively aligns with the Customer’s actual usage pattern.

Beta Features

Oracle may make available to Customer certain features that are labeled “beta” that are not yet
generally available. To use such features, Customer acknowledges and agrees that such beta features
are subject to the terms and conditions accepted by Customer upon activation of the feature, or in the
absence of such terms, subject to the limitations for the feature described in the User Guide and as
follows: The beta feature is a prototype or beta version only and is not error or bug free and Customer
agrees that it will use the beta feature carefully and will not use it in any way which might result in
any loss, corruption or unauthorized access of or to its or any third party’s property or information.
Customer must promptly report to Oracle any defects, errors or other problems in beta features
to support@netsuite.com or other designated contact for the specific beta feature. Oracle cannot
guarantee the continued availability of such beta features and may substantially modify or cease
providing such beta features without entitling Customer to any refund, credit, or other compensation.
Oracle makes no representations or warranties regarding functionality or use of beta features and
Oracle shall have no liability for any lost data, incomplete data, re-run time, inaccurate input, work
delay, lost profits or adverse effect on the performance of the Service resulting from the use of beta
features. Oracle’s standard service levels, warranties and related commitments regarding the Service
shall not apply to beta features and they may not be fully supported by Oracle’s customer support.
These limitations and exclusions shall apply until the date that Oracle at its sole option makes a beta
feature generally available to its customers and partners as part of the Service without a “beta” label.

Integration with Third Party Applications

Oracle may make available to Customer certain features designed to interoperate with third party
applications. To use such features, Customer may be required to obtain access to such third party
applications from their providers, and may be required to grant Oracle access to Customer’s account(s)
on such third party applications. Oracle cannot guarantee the continued availability of such Service
features or integration, and may cease providing them without entitling Customer to any refund, credit,
or other compensation, if for example and without limitation, the provider of a third party application
ceases to make such third party application generally available or available for interoperation with the
corresponding Service features or integration in a manner acceptable to Oracle.

Copyright
This document is the property of Oracle, and may not be reproduced in whole or in part without prior
written approval of Oracle. For Oracle trademark and service mark information for the Service, see
www.netsuite.com/portal/company/trademark.shtml.
Table of Contents
Oracle-NetSuite PBCS Sync ..................................................................................................... 1
Overview .......................................................................................................................... 1
Oracle-NetSuite PBCS Sync Administrator Guide .................................................................... 1
Prerequisites for Installing the Oracle-NetSuite PBCS Sync SuiteApp ..................................... 1
Installing the Oracle-NetSuite PBCS Sync SuiteApp ............................................................. 2
Setting Up Oracle-NetSuite PBCS Sync .............................................................................. 2
Setting Up Token-Based Authentication (TBA) .................................................................... 3
Creating Custom Saved Searches for PBCS ........................................................................ 4
Oracle-NetSuite PBCS Sync User Guide ................................................................................. 4
Oracle-NetSuite PBCS Sync RESTlets ................................................................................. 4
Error Codes and Messages ............................................................................................. 8
 Oracle-NetSuite PBCS Sync 1

Oracle-NetSuite PBCS Sync

Overview
The Oracle-NetSuite PBCS Sync SuiteApp enables you to extract accounting reports from NetSuite
saved searches and use them in Oracle Planning and Budgeting Cloud Service (PBCS).

For information how to install and set up Oracle-NetSuite PBCS Sync in a NetSuite account, see Oracle-
NetSuite PBCS Sync Administrator Guide.

For information how a PBCS user can execute saved searches and extract data from NetSuite, see
Oracle-NetSuite PBCS Sync User Guide.

Oracle-NetSuite PBCS Sync Administrator Guide

As an administrator, you must perform the following tasks to set up the SuiteApp:

1. Enable the required features. See Prerequisites for Installing the Oracle-NetSuite PBCS Sync
SuiteApp.
2. Install the Oracle–NetSuite PBCS Sync SuiteApp. See Installing the Oracle-NetSuite PBCS Sync
SuiteApp.
3. Set up the Oracle-NetSuite PBCS Sync SuiteApp. This includes:
■ Setting up a password for file encryption.
■ Creating user records for PBCS users. These user records must have the PBCS Integration
role.
■ Customizing default saved searches that are created by the SuiteApp.
For more information, see Setting Up Oracle-NetSuite PBCS Sync.
4. Set up token-based authentication (TBA) for PBCS users. See Setting Up Token-Based
Authentication (TBA).
5. Create custom saved searches to be used by PBCS. Creating Custom Saved Searches for PBCS.

Roles and Permissions

Only administrators can install the Oracle—NetSuite PBCS Sync SuiteApp. A user with the Administrator
role must also create PBCS user records in NetSuite.

Prerequisites for Installing the Oracle-NetSuite PBCS Sync

SuiteApp
Before installing the SuiteApp, you must enable the following features.

■ Custom Records
■ Server SuiteScript
■ Token-Based Authentication
■ Client SuiteScript

Oracle–NetSuite PBCS Sync

 Oracle-NetSuite PBCS Sync Administrator Guide 2

To enable these features, go to Setup > Company > Enable Features, and click the SuiteCloud subtab.

Installing the Oracle-NetSuite PBCS Sync SuiteApp

For general information on installing a bundle, see the help topic Installing a Bundle.

Important: The Oracle-NetSuite PBCS Sync SuiteApp is a shared bundle. To install this
SuiteApp, it must be provisioned in your account.

To install the Oracle-NetSuite PBCS Sync SuiteApp:

1. Make sure all prerequisites are met. See Prerequisites for Installing the Oracle-NetSuite PBCS
Sync SuiteApp.
2. Go to Customization > SuiteBundler > Search & Install Bundles.
3. In the Keywords box, enter the bundle name or ID:
■ Bundle ID: 168463
■ Bundle Name: Oracle-NetSuite PBCS Sync
4. Click Search.
5. Click the link for the Oracle-NetSuite PBCS Sync SuiteApp.
6. On the Bundle Details page, click Install.

Note: The Oracle-NetSuite PBCS Sync SuiteApp is a managed SuiteApp. When improvements
or new features are added to the SuiteApp, it is automatically updated in your NetSuite account.

Setting Up Oracle-NetSuite PBCS Sync

After installing the Oracle-NetSuite PBCS Sync SuiteApp, an administrator must perform the following
tasks:

1. Set up a password for file encryption.

See Setting Up a Password for File Encryption.
2. Create PBCS user records and assign the PBCS Integration role to them.
See Creating PBCS User Records.
3. Customize default saved searches created by the SuiteApp.
See Customizing Default Saved Searches.

Setting Up a Password for File Encryption

CSV files that contain saved search results are encrypted with a password that you must set.

Set the file encryption password at Setup > Integration > PBCS File Encryption Password. This password
must have 16, 24, or 36 characters.

Creating PBCS User Records

Follow instructions in Adding an Employee to create PBCS user records. You must assign the PBCS
Integration role to these records.

Oracle–NetSuite PBCS Sync

 Oracle-NetSuite PBCS Sync Administrator Guide 3

Customizing Default Saved Searches

The following saved searches are included in the Oracle-NetSuite PBCS Sync SuiteApp:

■ PBCS All Posting Transactions Last Period - Summary

■ PBCS All Posting Transactions Last Period - Detail
■ PBVS All Posting Transactions Last Period – Trial Balance

After installing the SuiteApp, you must update these saved searches to assign PBCS users as owners
and to add any custom segments you might need to have in these searches.

For information about custom segments, see the help topics Custom Segments and Custom Segments
in Record Searches.

To customize a saved search:

1. Edit the saved search.
2. Change the saved search title.
3. Click Save As.
This creates a copy of the saved search.
4. On the Saved Searches page, click Edit next to the new saved search.
5. Select an owner for the saved search.
The owner must have the PBCS Integration role.
6. To change the search ID, click Change ID.
7. On the Criteria subtab, add or remove filters.
8. On the Results subtab, add or remove columns.
9. Click Save.

Setting Up Token-Based Authentication (TBA)

For general information about the Token-Based Authentication (TBA) feature, see the help topic Token-
based Authentication.

To authenticate users using the OAuth protocol with RESTlets, you must set up TBA by doing the
following:

■ Enable the NetSuite Token-Based Authentication feature. See the help topic Enabling the Token-
based Authentication Feature.
■ Create an integration record representing PBCS at Setup > Integration > Manage Integrations.
On the integration record, you must check the Token-Based Authentication box. By enabling this
option, NetSuite generates the consumer key and consumer secret that represent PBCS.
For more information, see the help topic Creating an Integration Record.
■ Save the consumer key and consumer secret generated on the integration record. The consumer
key and secret show only one time. If you lose these credentials, you can regenerate new ones. For
more information, see the help topic Regenerating a Consumer Key and Secret.
■ Create a token and token secret for users who will call the RESTlets. For information, see the help
topic Managing TBA Tokens.
The token and token secret show only one time. If you lose these credentials, you must create a new
token.

Oracle–NetSuite PBCS Sync

 Oracle-NetSuite PBCS Sync Administrator Guide 4

Creating Custom Saved Searches for PBCS

To create custom saved searches, go to Reports > Saved Searches > All Saved Searches > New. For
detailed information on defining a saved search, see the help topic Defining a Saved Search.

Oracle-NetSuite PBCS Sync User Guide

PBCS users can call RESTlets to perform the following tasks:

1. Retrieve the list of available saved searches.

2. Retrieve columns and filters of a specific saved search.
3. Execute a saved search.
4. Check the status of the request for executing a saved search.
5. Request downloading a file that contains theresults of a saved search.

The following diagram shows the flow of REStlet calls.

Oracle-NetSuite PBCS Sync RESTlets

For general information about RESTlets, see the help topic Getting Started with RESTlets.

Before calling these RESTlet URLs, you must dynamically generate the RESTlet domain. See Dynamically
Generating RESTlet Domains.

The following table lists RESTlets in the Oracle-NetSuite PBCS Sync SuiteApp.

RESTlet Restlet URL Method Parameters Returns

Description
Retrieving the List https://rest.netsuite. Get n/a List of saved
of Available Saved com/app/site/hosting/ searches that
Searches restlet.nl?script= are owned
customscript_nspbcs_rl_ by the user

Oracle–NetSuite PBCS Sync

 Oracle-NetSuite PBCS Sync User Guide 5

RESTlet Restlet URL Method Parameters Returns

Description
saved_search&deploy= who sends the
customdeploy_nspbcs_ request.
rl_saved_search
Retrieving Columns https://rest.netsuite. Get searchid Returns
and Filters for a com/app/site/hosting/ columns and
Specific Saved restlet.nl?script= available filters
Search customscript_nspbcs_rl_ for the search
saved_search&deploy= specified by
customdeploy_nspbcs_ the searchid
rl_saved_search parameter
Executing a Saved https://rest.netsuite. Post ■ searchid ■ requestid
Search com/app/site/hosting/ ■ filters ■ status
restlet.nl?script=
customscript_nspbcs_rl_ ■ exception
search_request&deploy=
customdeploy_nspbcs_
rl_search_request
Checking the https://rest.netsuite. Get requestid ■ status
Status of Saved com/app/site/hosting/ ■ files
Search Execution restlet.nl?script=
Request customscript_nspbcs_rl_ ■ exception
search_request&deploy=
customdeploy_nspbcs_
rl_search_request
Downloading https://rest.netsuite. Get ■ requestid Returns the
Saved Search com/app/site/hosting/ ■ fileid result of a
Results restlet.nl?script= saved search
customscript_nspbcs_rl_ as a stringified
download_file&deploy= CSV file.
customdeploy_nspbcs_
rl_download_file

Dynamically Generating RESTlet Domains

Before calling the RESTlet URL, you must dynamically generate the RESTlet domain.

The RESTlet domain is the first part of the URL. It appears as https://rest.netsuite.com, https://
rest.na1.netsuite.com, or a similar variant.

You must dynamically generate this portion of the URL. The domain for your account can change
because NetSuite hosts accounts in multiple data centers, and accounts are sometimes moved from
one data center to another.

To dynamically generate the domain, use NetSuite’s REST roles service. For more details, see the help
topics The REST roles Service and URLs for Accessing the REST roles Service.

REStlet Request and Response Samples

Request samples listed below use the NLAuth authentication instead of token-based authentication
(TBA) and are only for illustration.

Retrieving the List of Available Saved Searches

cURL Request Sample

curl -X GET -H "Content-Type: application/json" -H "Authorization: NLAuth nlauth_account=123456

Oracle–NetSuite PBCS Sync

 Oracle-NetSuite PBCS Sync User Guide 6

, nlauth_email=jsmith@example.com, nlauth_signature=password" 'https://rest.netsuite.com/app/si

te/hosting/restlet.nl?script=customscript_nspbcs_rl_saved_search&deploy=customdeploy_nspbcs_rl_
saved_search'

Output Example

{
"searches": [
{
"id": "saved_search1",
"name": "My Saved Search"
},
{
"id": "saved_search2",
"name": "My Saved Search 2"
}
]
}

Response Sample

{"searches":[{"id":"customsearch_all_transactions","name":"2. PBCS All Posting Transactions Las

t Period -Detail"},{"id":"customsearch_lsa_customer_2","name":"Leads, prospects, and customer w
ithout sales activity in the last week2"}]}

Retrieving Columns and Filters for a Specific Saved Search

cURL Request Sample

curl.exe -H "Content-Type: application/json" -H "Authorization: NLAuth nlauth_account=123456,n

lauth_email=jsmith@example.com, nlauth_signature=password " \
'https://rest.netsuite.com/app/site/hosting/restlet.nl?script=customscript_nspbcs_rl_saved_sear
ch&deploy=customdeploy_nspbcs_rl_saved_search&searchid= customsearch_all_transactions '

Output Example

{
"cols":[{id: "firstname", label: "First Name"},
{id: "lastname", label: "Last Name"}],
"filters":["status","age"]
}

Response Sample

{"cols":[{"id":"account","label":"Account"},{"id":"type","label":"Type"},{"id":"tranid","label"
:"Document Number"},{"id":"entity","label":"Name"},{"id":"amount","label":"Amount"},{"id":"debi
tamount","label":"Amount (Debit)"},{"id":"creditamount","label":"Amount (Credit)"},{"id":"posti
ngperiod","label":"Period"}],"filters":["postingperiod","posting","mainline","postingperiod"]}

Oracle–NetSuite PBCS Sync

 Oracle-NetSuite PBCS Sync User Guide 7

Executing a Saved Search

cURL Request Sample

curl -H "Content-Type: application/json" -X POST -d '{"searchid":"customsearch_all_transactions

","filters":[{"name":"postingperiod","operator":"anyof","value":["TP", "LP"]}]}' -H "Authorizat
ion: NLAuth nlauth_account=123456,nlauth_email=jsmith@example.com, nlauth_signature=password "
'https://rest.netsuite.com/app/site/hosting/restlet.nl?script=customscript_nspbcs_rl_search_re
quest&deploy=customdeploy_nspbcs_rl_search_request'

Input Example

{
"searchid": <searchid>
"filters": [
{
"name": <filter_name>,
"value": <value>,
"operator": <operator>
},
{
"name": <filter_name>,
"value": <value>,
"operator": <operator>
}
]
}

Output Example

{
"requestid": "123",
"status": "QUEUED",
"errcode": "",
"exception": ""
}

Response Sample

{"requestid":2302,"status":"QUEUED","errcode":"","exception":""}

Checking the Status of Saved Search Execution Request

cURL Request Sample

curl.exe -H "Content-Type: application/json" -H "Authorization: NLAuth nlauth_account=123456,nl

auth_email=jsmith@example.com, nlauth_signature=password" 'https://rest.netsuite.com/app/site/
hosting/restlet.nl?script=customscript_nspbcs_rl_search_request&deploy=customdeploy_nspbcs_rl_s

Oracle–NetSuite PBCS Sync

 Oracle-NetSuite PBCS Sync User Guide 8

earch_request&requestid=2302'

Output Example

{
"status": "SUCCESS",
"files": [
305,
4472
],
"errcode": "",
"exception": ""
}

Response Sample

{"status":"SUCCESS","files":["6745"],"errcode":"","exception":""}

Downloading Saved Search Results

cURL Request Sample

curl.exe -H "Authorization: NLAuth nlauth_account=123456,nlauth_email=jsmith@example.com, nlau

th_signature=password " \
'https://rest.netsuite.com/app/site/hosting/restlet.nl?script=customscript_nspbcs_rl_download_f
ile&deploy=customdeploy_nspbcs_rl_download_file&requestid=2302&fileid=6745'

Output Example

Account, Type, Document Number, Name, Amount, Amount (Debit), Amount ( redit)
Sales,Sales Order,1,1 Mesto Prostejov,250.00,,250.00

Error Codes and Messages

The following table lists error codes and error messages.

Error Code Error Message

INVLD _DOWN_REQ Could not resolve request for downloading a file

INVLD _FILT An exception during Filters evaluation

INVLD _NUM Given value cannot be parsed as a number

INVLD_OPER Unknown operator used in Filters

PARAM_MISS Required parameter is missing

REQ_CREA An error occurred during request creation

REQ_PROC An error occurred during request processing

Oracle–NetSuite PBCS Sync

 Oracle-NetSuite PBCS Sync User Guide 9

Error Code Error Message

REQ_STAT An error occurred during obtaining Request status

SRCH_NOT_FOUND Cannot find saved search with specified ID

UNKNWN Unexpected error

Oracle–NetSuite PBCS Sync