1 of 4

NetSuite (prebuilt connector)

Description

NetSuite is a cloud-based solution that helps businesses manage all aspects of their operations.

API documentation

API documentation for NetSuite (used to build this connector) can be found via the link below:

Required NetSuite setup

Before your Patchworks Netsuite connector can be used in process flows, some setup is required in your NetSuite environment so that Patchworks to authorise API calls with token-based authentication.

Please see our Preparing your NetSuite environment to work with Patchworks page and ensure this setup is completed before you start working with the Patchworks NetSuite connector.

Authentication

When adding connector instances of the Patchworks (prebuilt) connector, the following authentication methods are supported:

OAuth 2 authentication (client credentials flow)
OAuth 1 authentication

Preparing your NetSuite environment to work with Patchworks

Introduction

Before your Patchworks Netsuite connector can be used in process flows, some setup is required in your NetSuite environment. This setup allows Patchworks to authorise API calls with token-based authentication.

When you add a Patchworks connector instance for NetSuite, you can choose to authenticate using OAuth 1 or OAuth 2. The OAuth protocol authenticates users via tokens, so this setup is imperative.

Prerequisites

You will need NetSuite administrator permissions to complete tasks detailed on this page.

The steps

The required setup is detailed in five stages:

Stage 1: Enable REST API features
Stage 2: Create a role to give access to the REST API & token-based authentication
Stage 3: Check/assign permissions for your Patchworks role
Stage 4: Assign the role to a user
Stage 5: Add a Patchworks integration

Stage 1: Enable REST API features

Follow the steps below:

Step 1 In NetSuite, login as an admin user and navigate to setup | company | enable features:

Step 2 Select the SuiteCloud tab - all available features are listed within a series of categories.

Step 3 Scroll to the SuiteTalk (Web Services) category and ensure that the following features are selected/enabled:

SOAP WEB SERVICES
REST WEB SERVICES
REST RECORD SERVICE (BETA) - if available

For example:

If you don't see the the REST RECORD SERVICE (BETA) option and there's no banner for you to opt in, don't worry - it's not required.

Step 4 Scroll to the Manage Authentication category and ensure that the following features are selected/enabled:

TOKEN-BASED AUTHENTICATION
OAUTH 2.0

For example:

You may find that some features (including other authentication settings) are already set when you access the enable features page in NetSuite. This is fine.

Step 5 Save changes.

Stage 2: Create a role to give access to the REST API & token-based authentication

Adding a new role is optional - if you have an existing role that you would like to use that's fine - you can simply select that role (via setup | users/roles | manage roles) and go straight to stage 3.

Step 1 In NetSuite, login as an admin user and navigate to setup | users/roles | manage roles:

Step 2 Click the new role button:

Step 3 In the name field enter a name for this role, we suggest:

Patchworks Integration

For example:

Step 4 Go directly to stage 3.

Stage 3: Check/assign permissions for your Patchworks role

Step 1 In the lower panel, select the permissions tab:

Here, you use permission tabs to navigate between different permission categories:

Step 2 Switch between these categories and ensure that the following permissions are granted:

Stage 4: Assign the role to a user

The steps below assume that you already have a NetSuite user ready to associate with the permissions granted above. However, you can create a new user if required.

Step 1 In NetSuite (logged in as an admin user), navigate to setup | users/roles | manage users:

Step 2 From the list of users, select the user that you want to update with new permissions.

Step 3 In the lower panel, select the access tab:

Step 4 Assign the Patchworks integration role that you saved in stage 3.

Step 5 Save changes.

Stage 5: Add a Patchworks integration

Step 1 In NetSuite (logged in as an admin user), navigate to setup | integration | manage integrations.

Step 2 Click the new button:

Step 3 In the name field we suggest entering:

Patchworks Integration

Step 4 Set the state field to enabled.

Step 5 Move down to the token-based authentication section and select/de-select options as per your requirements:

Step 6 Move down to the OAuth 2.0 section and select/de-select options as per your requirements:

Step 7 Save changes. At this point, client credentials are provided for this integration - add these to your password manager:

These credentials are only displayed once and are needed to add Patchworks instances of the NetSuite connector - make sure that you have them noted securely for future reference.

Step 8 The required NetSuite setup is now complete. If you haven't done so already, install the NetSuite connector from the Patchworks marketplace, then add required instances and make connections in process flows!

OAuth 2 (client credentials) authentication

Introduction

When a user chooses to add a connector instance using OAuth 2 (client credentials) authentication, they are required to enter the following credentials:

Credential

Notes

Consumer key

Account id

Note that this value is case sensitive and must be entered exactly as it shows in your NetSuite URL. For example, in NetSuite where the account ID is 1234567-SB1 we must use whatever shows in the URL, which generally changes upper to lowercase (e.g. 1234567-sb1).

Private key

Certificate id

If you are using a custom version of our prebuilt NetSuite connector (i.e. if authentication method and/or endpoint settings have been updated after the original installation), please be aware that your settings and requirements may vary.

Setting up OAuth 2 (client credentials) authentication

In order to add connector instances for NetSuite using OAuth 2 (client credentials) authentication, you must have completed all generic setup detailed in our Preparing your NetSuite environment to work with Patchworks guide.

Then, please complete the steps detailed in the following sections to enable OAuth 2 (client credentials) authentication:

Stage 1: Gather NetSuite credentials
Stage 2: Create a certificate
Stage 3: Upload certificate to NetSuite
Stage 4: Add/install a custom script
Stage 5: Apply the pre-request script

Stage 1: Gather NetSuite credentials

Consumer key

If you have followed our Preparing your NetSuite environment to work with Patchworks guide, you will have added a Patchworks integration and saved your client credentials (consumer key/client id and consumer secret/client secret) to a password manager. Make sure that you have these to hand.

If you can't find these credentials, you can generate a new set.

Be aware that if you reset credentials that have already been used to configure Patchworks connector instances, process flows will fail until you apply the new credentials.

Account ID

This is always the first element of the URL that you can see having logged into NetSuite. For example, with the following URL: https://tstdrv1431250.app.netsuite.com/app/center/card.nl?sc=-29&whence=

...the account id would be: tstdrv1431250

Stage 2: Create a certificate

Follow the steps below:

Step 1 From a command line or terminal window, use the command below to generate a certificate:

openssl req -x509 -newkey rsa:4096 -sha256 -keyout auth-key.pem -out auth-cert.pem -nodes -days 730

Step 2 You'll be prompted to enter information such as company name, email, etc. Complete each prompt as appropriate and press Enter.

Step 3 Two files will be generated:

auth-cert.pem
auth-key.pem

For more information about certificate requirements in NetSuite, please see the following NetSuite article:

Stage 3: Upload certificate to NetSuite

Follow the steps below:

Step 1 Log into NetSuite as an admin user.

Step 2 Navigate to setup > integration > OAuth 2.0 Client Credentials (M2M) Setup:

Step 3 Click the create new button:

...the create a new credentials mapping page is displayed:

Step 4 Select your name (or a preferred alternative) from the entity dropdown field, followed by the role (this should be administrator) and finally the application (the name of your Patchworks integration).

Step 5 Click the choose a file button:

Step 6 Upload the auth-cert.pem file that you generated in Stage 1:

Step 7 Add the certificate id to your password manager - you'll need this to add connector instances for NetSuite later:

Stage 4: Add/install a custom script

Having done this, you can go straight to Stage 5.

Follow the steps below if you want to create the script manually:

Step 1 Log into the Patchworks dashboard and select scripts from the left-hand navigation menu.

Step 2 Click the create script button:

Step 3 In the name field, type the following:

NetSuite OAuth 2 - Generate Client Assertion

Step 4 In the description field, type the following:

NetSuite OAuth 2 - Generate Client Assertion

Step 5 Click in the language field and select JavaScript:

Step 6 Click the create button.

Step 7 The script is created and opened in edit mode - select and remove any placeholder code:

Step 8 Paste in the code below.

Step 9 Click the save and deploy button:

Stage 5: Apply the pre-request script

Step 1 From the Patchworks dashboard, select connectors and instances from the left-hand navigation menu to access your installed connectors.

Step 2 If the NetSuite connector is not already installed, install it now.

Step 3 Find your NetSuite connector and click the settings icon:

Step 4 Click the authentication option:

Step 5 Select the Netsuite OAuth2 Auth Client Credentials authentication method.

Step 6 Select the pre-request script tab:

Step 7 Click in the select script field and select your NetSuite OAuth 2 - Generate Client Assertion script::

Step 8 Select the latest version:

Step 9 Save changes:

Step 10 You can now add connector instances for NetSuite using OAuth 2 (client credentials) authentication.

OAuth 1 authentication

Introduction

When a user chooses to add a connector instance using OAuth 1 authentication, they are required to enter the following credentials:

Credential

Notes

Consumer key

Consumer secret

Account id

Token

Token secret

Signature algorithm

Always set to sha256.

Signature method

Always set to HMAC-SHA256.

Realm

For a NetSuite sandbox the accountid shown in NetSuite (as opposed to your NetSuite URL) typically includes an -SB element - for example: 1234567-SB1.

The realm will be the same value EXCEPT that the -SB element changes from a dash to an underscore.

So, an accountid of 1234567-SB1 becomes 1234567_SB1 for the realm.

Setting up OAuth 1 authentication

In order to add connector instances for NetSuite using OAuth 1 authentication, you must have completed all generic setup detailed in our Preparing your NetSuite environment to work with Patchworks guide.

Finding your credentials

Consumer key & consumer secret

If you can't find these credentials, a new set can be generated.

Be aware that if you reset credentials that have already been used to configure Patchworks connector instances, process flows will fail until you apply the new credentials.

Account ID

...the account id would be: tstdrv1431250

Token key & token secret

A token key and token secret can be generated for users with a Patchworks integration role. In NetSuite, navigate to setup | users/roles | access tokens.

These values should be added to a password manager at the time they are generated as they can't be re-accessed in NetSuite. If you can't find these credentials, a new set can be generated.

Be aware that if you reset credentials that have already been used to configure Patchworks connector instances, process flows will fail until you apply the new credentials.

OAuth 1 authentication

Introduction

When a user chooses to add a connector instance using OAuth 1 authentication, they are required to enter the following credentials:

Credential

Notes

Consumer key

Generated in Netsuite as part of your initial Patchworks integration. For more information see:

Consumer secret

Generated in Netsuite as part of your initial Patchworks integration. For more information see:

Account id

This is always the first element of the URL that you can see having logged into NetSuite. For more information see:

Token

Generated per user in Netsuite. For more information see: .

Token secret

Generated per user in Netsuite. For more information see: .

Signature algorithm

Always set to sha256.

Signature method

Always set to HMAC-SHA256.

Realm

For a NetSuite sandbox the accountid shown in NetSuite (as opposed to your NetSuite URL) typically includes an -SB element - for example: 1234567-SB1.

The realm will be the same value EXCEPT that the -SB element changes from a dash to an underscore.

So, an accountid of 1234567-SB1 becomes 1234567_SB1 for the realm.

Setting up OAuth 1 authentication

Finding your credentials

Consumer key & consumer secret

If you can't find these credentials, a new set can be generated.

Show me

Be aware that if you reset credentials that have already been used to configure Patchworks connector instances, process flows will fail until you apply the new credentials.

Account ID

...the account id would be: tstdrv1431250

Show me

Token key & token secret

A token key and token secret can be generated for users with a Patchworks integration role. In NetSuite, navigate to setup | users/roles | access tokens.

These values should be added to a password manager at the time they are generated as they can't be re-accessed in NetSuite. If you can't find these credentials, a new set can be generated.

Show me

Be aware that if you reset credentials that have already been used to configure Patchworks connector instances, process flows will fail until you apply the new credentials.

Preparing your NetSuite environment to work with Patchworks

Introduction

When you add a Patchworks connector instance for NetSuite, you can choose to authenticate using OAuth 1 or OAuth 2. The OAuth protocol authenticates users via tokens, so this setup is imperative.

Prerequisites

You will need NetSuite administrator permissions to complete tasks detailed on this page.

The steps

The required setup is detailed in five stages:

Stage 1: Enable REST API features
Stage 2: Create a role to give access to the REST API & token-based authentication
Stage 3: Check/assign permissions for your Patchworks role
Stage 4: Assign the role to a user
Stage 5: Add a Patchworks integration

Stage 1: Enable REST API features

Follow the steps below:

Step 1 In NetSuite, login as an admin user and navigate to setup | company | enable features:

Step 2 Select the SuiteCloud tab - all available features are listed within a series of categories.

Step 3 Scroll to the SuiteTalk (Web Services) category and ensure that the following features are selected/enabled:

SOAP WEB SERVICES
REST WEB SERVICES
REST RECORD SERVICE (BETA) - if available

For example:

If you don't see the REST RECORD SERVICE (BETA) option, look for a blue banner at the top of the setup | company | enable features page: Use the click here link to view Beta activities and apply to participate in the Oracle NetSuite Umbrella Beta Program Beta activity:

If you don't see the the REST RECORD SERVICE (BETA) option and there's no banner for you to opt in, don't worry - it's not required.

Step 4 Scroll to the Manage Authentication category and ensure that the following features are selected/enabled:

TOKEN-BASED AUTHENTICATION
OAUTH 2.0

For example:

You may find that some features (including other authentication settings) are already set when you access the enable features page in NetSuite. This is fine.

Step 5 Save changes.

Stage 2: Create a role to give access to the REST API & token-based authentication

Step 1 In NetSuite, login as an admin user and navigate to setup | users/roles | manage roles:

Step 2 Click the new role button:

Step 3 In the name field enter a name for this role, we suggest:

Patchworks Integration

For example:

Step 4 Go directly to stage 3.

Stage 3: Check/assign permissions for your Patchworks role

Step 1 In the lower panel, select the permissions tab:

Here, you use permission tabs to navigate between different permission categories:

Step 2 Switch between these categories and ensure that the following permissions are granted:

Stage 4: Assign the role to a user

The steps below assume that you already have a NetSuite user ready to associate with the permissions granted above. However, you can create a new user if required.

Step 1 In NetSuite (logged in as an admin user), navigate to setup | users/roles | manage users:

Step 2 From the list of users, select the user that you want to update with new permissions.

Step 3 In the lower panel, select the access tab:

Step 4 Assign the Patchworks integration role that you saved in stage 3.

Step 5 Save changes.

Stage 5: Add a Patchworks integration

Step 1 In NetSuite (logged in as an admin user), navigate to setup | integration | manage integrations.

Step 2 Click the new button:

Step 3 In the name field we suggest entering:

Patchworks Integration

Step 4 Set the state field to enabled.

Step 5 Move down to the token-based authentication section and select/de-select options as per your requirements:

I want to use OAuth 1 authentication in Patchworks

Ensure that the following options are selected:

TOKEN-BASED AUTHENTICATION
TBA: ISSUETOKEN ENDPOINT
TBA: AUTHORIZATION FLOW
CALLBACK URL set to https://app.wearepatchworks.com/oauth/authenticate for the Patchworks production environment

For example:

I don't want to use OAuth 1 authentication in Patchworks

Ensure that no token-based authentication options are selected.

Step 6 Move down to the OAuth 2.0 section and select/de-select options as per your requirements:

I want to use OAuth 2 (client credentials) authentication in Patchworks

Ensure that the following options are selected:

CLIENT CREDENTIALS (MACHINE TO MACHINE) GRANT
RESTLETS
REST WEB SERVICES

Ensure that the following options are NOT selected:

AUTHORIZATION CODE GRANT

For example:

I don't want to use OAuth 2 (client credentials) authentication in Patchworks

Ensure that no OAuth 2.0 options are selected.

Step 7 Save changes. At this point, client credentials are provided for this integration - add these to your password manager:

These credentials are only displayed once and are needed to add Patchworks instances of the NetSuite connector - make sure that you have them noted securely for future reference.

OAuth 2 (client credentials) authentication

Introduction

When a user chooses to add a connector instance using OAuth 2 (client credentials) authentication, they are required to enter the following credentials:

Credential

Notes

Consumer key

Generated in Netsuite as part of your initial Patchworks integration. For more information see .

Account id

This is always the first element of the URL that you can see having logged into NetSuite. For more information see .

Private key

Paste in the entire contents of the private key (auth-key.pem) that has been generated for NetSuite. For more information see .

Certificate id

Paste in the certificate id associated with the certificate file (auth-cert.pem) that has been uploaded to NetSuite. For more information see e.

Setting up OAuth 2 (client credentials) authentication

Then, please complete the steps detailed in the following sections to enable OAuth 2 (client credentials) authentication:

Stage 1: Gather NetSuite credentials
Stage 2: Create a certificate
Stage 3: Upload certificate to NetSuite
Stage 4: Add/install a custom script
Stage 5: Apply the pre-request script

Stage 1: Gather NetSuite credentials

Consumer key

If you can't find these credentials, you can generate a new set.

Show me

Be aware that if you reset credentials that have already been used to configure Patchworks connector instances, process flows will fail until you apply the new credentials.

Account ID

...the account id would be: tstdrv1431250

Stage 2: Create a certificate

Follow the steps below:

Step 1 From a command line or terminal window, use the command below to generate a certificate:

openssl req -x509 -newkey rsa:4096 -sha256 -keyout auth-key.pem -out auth-cert.pem -nodes -days 730

Step 2 You'll be prompted to enter information such as company name, email, etc. Complete each prompt as appropriate and press Enter.

Step 3 Two files will be generated:

auth-cert.pem
auth-key.pem

For more information about certificate requirements in NetSuite, please see the following NetSuite article:

NetSuite Applications SuiteOracle Help Center

Stage 3: Upload certificate to NetSuite

Follow the steps below:

Step 1 Log into NetSuite as an admin user.

Step 2 Navigate to setup > integration > OAuth 2.0 Client Credentials (M2M) Setup:

Step 3 Click the create new button:

...the create a new credentials mapping page is displayed:

Step 5 Click the choose a file button:

Step 6 Upload the auth-cert.pem file that you generated in Stage 1:

Step 7 Add the certificate id to your password manager - you'll need this to add connector instances for NetSuite later:

Stage 4: Add/install a custom script

We've added the required to our script marketplace, so you can download it directly from there if preferred. To do this, select scripts from the left-hand navigation bar, then install the Netsuite Prereq Oauth2 CC script:

Having done this, you can go straight to Stage 5.

Follow the steps below if you want to create the script manually:

Step 1 Log into the Patchworks dashboard and select scripts from the left-hand navigation menu.

Step 2 Click the create script button:

Step 3 In the name field, type the following:

NetSuite OAuth 2 - Generate Client Assertion

Step 4 In the description field, type the following:

NetSuite OAuth 2 - Generate Client Assertion

Step 5 Click in the language field and select JavaScript:

Step 6 Click the create button.

Step 7 The script is created and opened in edit mode - select and remove any placeholder code:

Step 8 Paste in the code below.

Pre-request script code

/**
 * @param data
 * @param {string} data.payload the payload as a string|null
 * @param {Object.<string, any>} data.variables any variables as key/value
 * @param {Object.<string, any>} data.meta any meta as key/value
 */
module.exports = async function (data) {
  const rs = require('jsrsasign')

  const jwtHeader = {
    alg: 'PS256',
    typ: 'JWT',
    kid: data.variables['certificate_id'], // Certificate Id on the client credentials mapping
  }

  // Create JWT payload
  const jwtPayload = {
    iss: data.variables['client_id'], // consumer key of integration record
    scope: ['restlets', 'rest_webservices'], // scopes specified on integration record
    iat: new Date() / 1000,
    exp: new Date() / 1000 + 3600,
    aud: `https://${data.variables['accountid']}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token`,
  }

  const signedJWT = rs.KJUR.jws.JWS.sign(
    'PS256',
    JSON.stringify(jwtHeader),
    JSON.stringify(jwtPayload),
    data.variables['client_secret'],
  )

  // The signed JWT is the client assertion (encoded JWT) that is used to retrieve an access token
  data.variables['client_assertion'] = signedJWT

  return data;
}

Step 9 Click the save and deploy button:

Stage 5: Apply the pre-request script

Step 1 From the Patchworks dashboard, select connectors and instances from the left-hand navigation menu to access your installed connectors.

Step 2 If the NetSuite connector is not already installed, install it now.

Step 3 Find your NetSuite connector and click the settings icon:

Step 4 Click the authentication option:

Step 5 Select the Netsuite OAuth2 Auth Client Credentials authentication method.

Step 6 Select the pre-request script tab:

Step 7 Click in the select script field and select your NetSuite OAuth 2 - Generate Client Assertion script::

Step 8 Select the latest version:

Step 9 Save changes:

Step 10 You can now add connector instances for NetSuite using OAuth 2 (client credentials) authentication.