sn\_erp\_integration API - Scoped, Global

concept australia Updated Sep 10, 2026 17 min read sn_erp_integrationBothAPI.md
Raw file servicenow.com

Script include providing a chainable API for interacting with Zero Copy Connector for ERP (Enterprise Resource Planning) models.

Purpose

  • Metadata

    Use metadata methods to discover the system, model, and IDoc information available in your Zero Copy Connector for ERP environment.

    • getAvailableIdocConfigs()
    • getAvailableInputs()
    • getAvailableModels()
    • getAvailableOperations()
    • getAvailableOutputs()
    • getAvailableSystems()
    • getRequiredInputs()
    • getRowCount()

  • Configuration

    Use configuration methods to select available systems, models, operations, and IDoc configurations for processing. You can also use these methods to filter model field return values.

    • system()
    • model()
    • operation()
    • idocConfig()
    • fields()
    • limit()
    • offset()

  • Query building

    Use query building methods to filter results.

    • addEncodedQuery()
    • addQuery()
    • addOrQuery()

  • Data input

    Use the data input methods to set field values. The withJSON()method can be used for input on nested objects and IDoc fields. The set() method is used to set a single field value.

    • set()
    • withJSON()

  • Operation execution

    Use the execute() method when working with multiple records, and the get() method for results of a single record.

    • execute()
    • get()

Access requirements

This script include requires the Zero Copy Connector for ERP (com.sn_erp_integration) store application and the Zero Copy Connector for ERP (com.snc.sn_erp_integration) plugin. This script is provided within the sn_erp_integration namespace. For more information, refer to Zero Copy Connector for ERP.

Role required: sn_erp_integration.erp_user

Parent Topic:Server API reference

API - API constructor

Initializes a new Zero Copy Connector for ERP API instance.

Name Type Description
None

The following examples show how to create an instance of the API to access an ERP system.

JavaScript
// Select the system1 systemconst api = new sn_erp_integration.API().system('system1');

API - addEncodedQuery(String encodedQuery)

Filters records using an encoded query.

See also:

Name Type Description
encodedQuery String An encoded query string.
Type Description
Object Returns this instance for chaining.

The following example shows how to use an encoded query to retrieve company codes in the US.

JavaScript
const api = new sn_erp_integration.API()  .system('system1')  .model('company_code')  .operation('read')  .addEncodedQuery('company_codes_countryregion_key=US')  .execute();

API - addOrQuery(String field, String operator, String value)

Add an OR query condition.

See also:

Name

Type

Description

field

String

The name of the field to be queried.

operator

String

Optional. Query operator. The query option used depends on whether data provided for the value parameter is a number or string.Default value: =

Numbers:

  • =
  • !=
  • >
  • >=
  • <
  • <=

Strings (must be in upper case):

  • =
  • !=
  • IN
  • NOT IN
  • STARTSWITH
  • ENDSWITH
  • CONTAINS
  • DOES NOT CONTAIN

Note: Use CONTAINS instead of the LIKE operator.

value

String

Value on which to query (not case-sensitive).
|Type|Description| |----|-----------| |Object|Returns this instance for chaining.|

The following example shows how to return all company codes in the US and Canada.

JavaScript
const api = new sn_erp_integration.API();const companyCodes = api  .system('system1')  .model('company_code')  .operation('read')  .addQuery('company_codes_countryregion_key', 'US')  .addOrQuery('company_codes_countryregion_key', 'CA')  .fields(['company_codes_company_code', 'company_codes_company_name', 'company_codes_countryregion_key', 'company_codes_currency'])  .execute();
// Process the resultscompanyCodes.forEach(companyCode => {  gs.info('Company Code: ${companyCode.company_codes_company_code}, Name: ${companyCode.company_codes_company_name}, Country: ${companyCode.company_codes_countryregion_key}');    // Do something with each company code  if (companyCode.company_codes_countryregion_key === 'US') {    // Process US company codes  } else {    // Process Canadian company codes  }});

API - addQuery(String field, String operator, String value, String joinType)

Add a query condition for filtering data.

See also:

Name

Type

Description

field

String

The name of the field to be queried.

operator

String

Optional. Query operator. The query option used depends on whether data provided for the value parameter is a number or string.Default value: =

Numbers:

  • =
  • !=
  • >
  • >=
  • <
  • <=

Strings (must be in upper case):

  • =
  • !=
  • IN
  • NOT IN
  • STARTSWITH
  • ENDSWITH
  • CONTAINS
  • DOES NOT CONTAIN

Note: Use CONTAINS instead of the LIKE operator.

value

String

Value on which to query (not case-sensitive).

joinType

String

Optional. Join type.Possible values:

  • AND
  • OR

Default value: AND
|Type|Description| |----|-----------| |Object|Returns this instance for chaining.|

The following example shows how to use the > operator to return results that are priority one or a priority greater than two.

JavaScript
// Results in: priority=1^ORpriority>2const api = new sn_erp_integration.API();  .system('system1')  .model('request')  .operation('read')  .addQuery('priority', '1)  .addOrQuery('priority', '>', '2')  .execute();

API - execute()

Executes the configured operation.

To execute an operation on a single result, use API - get().

Name Type Description
None
Type Description
Object|Array The result of the operation. Error if unsuccessful.

The following example shows how to create a new company code.

JavaScript
const newCompanyCode = new sn_erp_integration.API()  .system('system1')  .model('company_code')  .operation('create')  .withJSON({    company_codes_company_code: '1234',    company_codes_company_name: 'New York Office',    company_codes_countryregion_key: 'US',    company_codes_language_key: 'EN'  })  .execute();

API - fields(Array fields)

Specifies the model fields to return. This is the primary method for field selection.

To retrieve a list of fields available for a model, use API - getAvailableOutputs().

See also:

Name Type Description
fields Array One or more model field names listed as strings.
Type Description
None

The following example shows how to return specific fields for all company codes in the US.

JavaScript
const companyCodes = new API()  .system('system1')  .model('company_code')  .operation('read')  .addQuery('company_codes_countryregion_key', 'US')  .fields(['company_codes_company_code', 'company_codes_company_name', 'company_codes_countryregion_key'])  .execute();

API - get()

Alias for the execute() method for retrieving a single record in the results.

See also API - execute().

Name Type Description
None
Type Description
Object The first result of the operation.

The following example shows how to retrieve a specific sales document.

JavaScript
const salesDoc = new sn_erp_integration.API()  .system('system1')  .model('sales_document')  .operation('read')  .addQuery('document_number', '0000123456')  .get();

API - getAvailableIdocConfigs()

Gets the available IDoc configuration details for the selected system.

Name Type Description
None

Type

Description

Array of objects

List of available IDoc configurations. Throws an error if no system has been selected.See also API - system(String systemId).

object.id

IDoc ID. Use this value to select an IDoc with the API - idocConfig(String configId) method.Data type: String

object.name

IDoc display name.Data type: String

object.description

Description of the IDoc.Data type: String
The following example shows how to get all available IDoc configurations for a selected system.
JavaScript
const idocConfigs = new sn_erp_integration.API()  .system('system1')  .getAvailableIdocConfigs();
gs.info(JSON.stringify(idocConfigs, null, 2));

Output:

JSON
[  {    "id": "OBC0001002",    "name": "Sales Order IDoc",    "description": "IDoc for sales order processing"  },  {    "id": "OBC0001003",    "name": "Material IDoc",    "description": "IDoc for material core data"  }]

API - getAvailableInputs()

Returns a list of all available input fields for the selected operation.

For a list of only the required input fields for a selected model, use the API - getRequiredInputs() method.

See also:

Name Type Description
None

Type

Description

Object

Object describing available inputs and their types.See also API - system(String systemId).

object.variable_name

Variable name of the input field.Data type: String

object.label

Display name of the input field.Data type: String

object.data_type

Data type of the operation input.Data type: String

object.required

Flag that indicates whether the input field is required.Valid values:

  • true: The input field is required.
  • false: The input field isn’t required.

Data type: Boolean
Get available inputs for creating a company code.
JavaScript
const inputs = new sn_erp_integration.API()  .system('system1')  .model('company_code')  .operation('read')  .getAvailableInputs();
gs.info(JSON.stringify(operations, null, 2));

Output:

JSON
[  {    "variable_name": "company_codes_company_code",    "label": "Company Code",    "data_type": "string",    "required": true  },  {    "variable_name": "company_codes_company_name",    "label": "Company Name",    "data_type": "string",    "required": true  }]

API - getAvailableModels()

Returns a list of available models for the selected system.

For more information, see

Name Type Description
None

Type

Description

Array of objects

List of available models listed as a JSON object with an ID, name, and description property. Throws an error if no system has been selected.See also API - system(String systemId).

object.id

Model ID. Use this value to select a model with the API - model(String modelId) method.Data type: String

object.name

Model label, that is, the display name.Data type: String

object.description

Description of the model.Data type: String
The following example shows how to retrieve all available models for a selected system.
JavaScript
// Get all available models for system1const models = new sn_erp_integration.API()  .system('system1')  .getAvailableModels();
gs.info(JSON.stringify(models, null, 2));

Output:

JSON
[  {    "id": "company_code",    "name": "Company Code",    "description": "Company Code"  },  {    "id": "country",    "name": "Country",    "description": "Country"  },  {    "id": "currency",    "name": "Currency",    "description": "Currency"  },  {    "id": "customer_invoice",    "name": "Customer Invoice",    "description": "Customer Invoice"  },  {    "id": "language",    "name": "Language",    "description": "Language"  }]

API - getAvailableOperations()

Gets the available operations for the selected model.

See also:

Name Type Description
None

Type

Description

Array

List of available ERP model operations. Throws an error if no model or system has been selected.

object.id

Model operation ID. Use this value to select a model operation with the API - operation(String operationId) method.Data type: String

object.name

Model operation label, that is, the display name.Data type: String
The following example shows how to get all available operations for the **company\_code** model.
JavaScript
const operations = new sn_erp_integration.API()  .system('system1')  .model('company_code')  .getAvailableOperations();
gs.info(JSON.stringify(operations, null, 2));

Output:

JSON
[  {    "id": "create",    "name": "Company Code - Create"  },  {    "id": "read",    "name": "Company Code - Read"  }]

API - getAvailableOutputs()

Gets a list of all available output fields for the selected operation.

The field names returned by this method can be used with the API - fields(Array fields) method to filter field results.

Name Type Description
None

Type

Description

Array of objects

List of available output fields. Throws an error if no model or system has been selected.See also API - system(String systemId).

object.variable_name

Variable name of the output field.Data type: String

object.label

Display name of the output field.Data type: String

object.data_type

Data type of the operation output.Data type: String
The following example shows how to get the available output provided by reading a model operation called **vendor**.
JavaScript
// Get available outputs for read operation on a vendor modelconst outputs = new sn_erp_integration.API()  .system('system1')  .model('vendor')  .operation('read')  .getAvailableOutputs();
gs.info(JSON.stringify(outputs, null, 2));

Output:

JSON
[  {    "variable_name": "supplier_country",    "label": "Country",    "data_type": "string"  }  {    "variable_name": "supplier_city",    "label": "City",    "data_type": "string"  },  {    "variable_name": "supplier_location",    "label": "Location",    "data_type": "string"  },  {    "variable_name": "supplier_street",    "label": "Street",    "data_type": "string"  },  {    "variable_name": "supplier_name",    "label": "Name",    "data_type": "string"  },  {    "variable_name": "supplier_postal_code",    "label": "Postal Code",    "data_type": "string"  },  {    "variable_name": "supplier_state",    "label": "State",    "data_type": "string"  }]

API - getAvailableSystems()

Gets a list of all available ERP systems that can be accessed through the API.

Name Type Description
None

Type

Description

Array of objects

List of available ERP systems.

object.id

System ID. Use this value to select a system with the API - system(String systemId) method.Data type: String

object.name

System label, that is, the display name.Data type: String
The following example shows how to get a list of all available ERP systems.
JavaScript
const systems = new sn_erp_integration.API().getAvailableSystems();
gs.info(JSON.stringify(systems));

Output:

JSON
[  {    "id": "system1",    "name": "SAP DEV"  },  {    "id": "system2",    "name": "SAP PROD"  }]

API - getRequiredInputs()

Returns of list of only the required input fields for the selected model and create operation.

Required input fields are set when models are created.

For a complete list of input fields for a selected model, use the API - getAvailableInputs() method.

Name Type Description
None

Type

Description

Array of objects

List of required input field names.

object.variable_name

Variable name of the required input field.Data type: String

object.label

Display name of the required input field.Data type: String

object.data_type

Data type of the operation required input.Data type: String

object.required

Flag that indicates whether the input field is required. This method only returns results if the value is true.Data type: Boolean
The following example shows how to return the required input fields for creating an invoice.
JavaScript
const requiredInputs = new sn_erp_integration.API()  .system('system1')  .model('invoice')  .operation('create')  .getRequiredInputs();
gs.info(JSON.stringify(requiredInputs, null, 2));

Output:

JSON
{  "variable_name": "INVOICE01",  "label": "INVOICE01",  "data_type": "array",  "required": true}

API - getRowCount()

Returns the total number of rows that a Zero Copy Connector for ERP model operation would return, without retrieving the records themselves.

Use getRowCount() as a terminal method in place of execute() when you need only a count. You configure the query the same way you would for a normal run, then call getRowCount() instead.

The source of the count depends on the protocol that the model operation uses, and whether that protocol can report a count without returning the records:

Protocol Source of the count
Read table Total record count reported in the connector response metadata.
OData The OData count endpoint. Supported for both direct execution and execution through a MID Server.
BAPI Uses the default fallback. SAP provides no native count capability for BAPI calls.
REST Uses the default fallback.
Default fallback Counts the items actually returned in the response, which is equivalent to counting the rows that would land in a remote table.
Name Type Description
None
Type Description
None

Basic count

The following example shows how to return the number of US company codes without retrieving the records.

JavaScript
// Count the US company codes    const rowCount = new sn_erp_integration.API()      .system('system1')      .model('company_code')      .operation('read')      .addQuery('company_codes_countryregion_key', 'US')      .getRowCount();
    gs.info(rowCount);

Output:

Text
42

Checking the count before running the operation

The following example shows how to check the row count before deciding whether to run the full operation.

JavaScript
const api = new sn_erp_integration.API()      .system('system1')      .model('company_code')      .operation('read')      .addQuery('company_codes_countryregion_key', 'US');
    const rowCount = api.getRowCount();
    if (rowCount > 1000) {      gs.info(`Skipping retrieval. ${rowCount} records match the query.`);    } else {      const companyCodes = api        .fields(['company_codes_company_code', 'company_codes_company_name'])        .execute();      gs.info(`Retrieved ${companyCodes.length} of ${rowCount} records.`);    }

Output:

Text
Retrieved 42 of 42 records.

API - idocConfig(String configId)

Selects an IDoc configuration to operate on.

See also:

Name Type Description
configId String ID of the IDoc outbound configuration. To retrieve a list of IDoc configuration IDs, use the API - getAvailableIdocConfigs() method.
Type Description
Object Returns this instance for chaining.

The following example shows how to select an IDoc configuration and set values for processing.

JavaScript
const api = new sn_erp_integration.API()  .system('system1')  .idocConfig('OBC0001002')  .withJSON({    idoc_field1: 'value1',    idoc_field2: 'value2'  })  .execute();

API - limit(Number max)

Limits the number of results returned.

Name Type Description
max Number Maximum number of records to return.
Type Description
Object Returns this instance for chaining.

The following example shows how to retrieve only the first 10 company code records.

JavaScript
// Get only the first 10 company codesconst api = new sn_erp_integration.API()  .system('system1')  .model('company_code')  .fields(['company_codes_company_code', 'company_codes_company_name'])  .limit(10)  .execute();

API - model(String modelId)

Selects a model to operate on.

Name

Type

Description

modelId

String

The ID of the model.To retrieve a list of all models with their IDs, use API - getAvailableModels().
|Type|Description| |----|-----------| |Object|Returns this instance for chaining.|

The following example shows how to select the company_code model in system1. You can chain additional methods for getting and setting data for the selected model.

JavaScript
const api = new sn_erp_integration.API()  .system('system1')  .model('company_code')  .execute();

API - offset(Number start)

Sets the starting offset for results.

Name Type Description
start Number Starting point at which to begin retrieving results. For example, setting this value to 10 skips the first 10 results returned in a query.
Type Description
Object Returns this instance for chaining.

The following example shows how to retrieve 10 company code records skipping the first 10 results (11-20).

JavaScript
const api = new sn_erp_integration.API()  .system('system1')  .model('company_code')  .fields(['company_codes_company_code', 'company_codes_company_name'])  .limit(10)  .offset(10)  .execute();

API - operation(String operationId)

Selects an operation to use on a selected model.

To return a list of model operations, use API - getAvailableOperations().

Name Type Description
operationId String The ID of the model operation.
Type Description
Object Returns this instance for chaining.

The following example shows how to select the read operation for the company_code model.

JavaScript
const api = new sn_erp_integration.API()  .system('system1')  .model('company_code')  .operation('read')  .execute();

API - set(String field, String value)

Sets a single field value for create or update operations.

Name Type Description
field String Name of the field on which to set a value.
value String Value to set for the field.
Type Description
Object Returns this instance for chaining.

The following example shows how to create a company code entry and assign field values to it.

JavaScript
const api = new sn_erp_integration.API()  .system('system1')  .model('company_code')  .operation('create')  .set('company_codes_company_code', '1234')  .set('company_codes_company_name', 'New York Office')  .set('company_codes_countryregion_key', 'US')  .set('company_codes_language_key', 'EN')  .execute();

The following example shows how to update a sales document with nested properties. For nested data structures with additional levels, use API - withJSON(Object data).

JavaScript
const api = new sn_erp_integration.API()  .system('system1')  .model('sales_document')  .operation('update')  .set('document_number', '0000123456')  .set('header.document_type', 'OR')  .set('header.sales_organization', '1000')  .execute();

API - system(String systemId)

Selects a system to operate on.

See also:

Name Type Description
systemId String The system ID. You can retrieve the system ID using the API - getAvailableSystems() method.
Type Description
Object Returns this instance for chaining.

The following example shows how to select a system. You can chain additional methods to select a model within the system, and additional methods for using data on the selected system.

JavaScript
const api = new sn_erp_integration.API().system('system1');

API - withJSON(Object data)

Sets JSON data for the operation. For read operations, this method sets filter conditions. For create or update operations, this method sets the fields with data to be created or updated.

See also API - set(String field, String value).

Name

Type

Description

data

Object

JSON data listing fields and their values.Format:

Text
{fieldname: 'value'}
|Type|Description| |----|-----------| |Object|Returns this instance for chaining.|

The following example shows how to set data for a create operation.

JavaScript
const api = new sn_erp_integration.API()  .system('system1')  .model('company_code')  .operation('create')  .withJSON({    company_codes_company_code: '1234',    company_codes_company_name: 'New York Office',    company_codes_countryregion_key: 'US'  })  .execute();

The following example shows how to set a nested filter for a read operation.

JavaScript
const api = new sn_erp_integration.API()  .system('system1')  .model('sales_document')  .operation('read')  .withJSON({    header: {      document_type: 'OR',      sales_organization: '1000'    }  })  .operation('read')  .execute();
Search documentation
Search document titles and file paths on the australia branch