Scripts

Configure Connector Builder scripts that run JavaScript before or after API requests, for every request in a connector or for a single resource, and the order in which they run.

Connector Builder lets you write JavaScript that runs before or after the API requests made by your connector. Use pre-request scripts to modify outgoing requests and post-request scripts to process incoming responses. Scripts on the Global Scripts tab run for every request the connector makes, and scripts on a resource's Scripts tab run only for that resource.

When to use scripts

Scripts are useful when you need to customize how your connector calls the provider, such as:

• Inyectar o anular encabezados, parámetros o cuerpo de la solicitud antes de enviar
• Construir dinámicamente la URL del proveedor en función de los valores de configuración
• Transformar el cuerpo de una respuesta del proveedor antes de que se devuelva al flujo de trabajo
• Detener una solicitud basada en condiciones personalizadas sin llamar a la API del proveedor

Scripts para un solo recurso

Cada recurso también tiene su propia pestaña Scripts , junto con Parámetros, Campos de solicitud, Campos de respuesta y Diseñador de actividades. Proporciona los mismos editores de script previo a la solicitud y posterior a la solicitud , los mismos fragmentos y las done() variables y contrato que la pestaña Scripts globales en el nivel de conector.

La diferencia es el ámbito:

• Un script en la pestaña Scripts globales se ejecuta para cada solicitud que realiza el conector.
• Un script en la pestaña Scripts de un recurso se ejecuta solo para ese recurso.

Utiliza un script de recursos cuando la lógica se aplica a un punto final y un script global cuando se aplica a todo el conector.

Escribir scripts

Para abrir la pestaña Scripts globales:

1. En Integration Service, abre el Creador de conectores y selecciona tu conector personalizado.
2. Selecciona Scripts globales en la navegación superior.
3. Expande Script de solicitud previa o Script de solicitud posterior e introduce tu JavaScript.

Los scripts se ejecutan en un entorno JavaScript aislado, sin acceso a la red y sin forma de importar paquetes.

Los integrados de JavaScript estándar están disponibles: JSON, Date, Array, Object, URL, encodeURIComponent, URLSearchParams, TextEncoder, TextDecoder, btoa, atob, crypto, Blob, FormData, Headers, Intl y BigInt.

Importante:

Buffer no está disponible. Utiliza btoa y atob para la codificación base64 en su lugar.

Lo siguiente no está disponible en el sandbox:

Categoría	No disponible
Evaluación e importaciones	eval, cualquier llamada require(), una instrucción import o export de nivel superior, una expresión dinámica import(...)
Red	fetch, XMLHttpRequest, WebSocket
Temporizadores y trabajadores	setTimeout, setInterval, setImmediate, Worker, importScripts, postMessage
Runtime y globales	Deno, process, globalThis, self, window, WebAssembly, Buffer

La función done()

Cada script debe llamar a done() para indicar la finalización. done() finaliza la ejecución inmediatamente: cualquier código escrito después de done() es inalcanzable.

// Pass through unchanged
done();

// Override one or more output values
done({
  request_vendor_headers: updatedHeaders
});

// Return multiple overrides
done({
  request_vendor_body: newBody,
  request_vendor_headers: newHeaders
});

// Stop the request — do not call the vendor API
done({ continue: false });

// Stop the request and return an error
done({
  continue: false,
  response_status_code: 400,
  response_error_message: "Invalid action"
});

Uso de fragmentos

Selecciona Fragmentos en el panel de script para insertar plantillas de código en el editor de script activo.

El panel Script de solicitud previa ofrece las siguientes plantillas, agrupadas en Scripts de solicitud previa:

• Actualizar URL del proveedor : establece request_vendor_path en una URL completa, reemplazando la URL del proveedor para esa solicitud.
• Usar una configuración : lee un valor de configuration (la URL base del conector, en la muestra) y lo envía al proveedor como encabezado de solicitud.
• Omitir una solicitud de proveedor : establece continue como false para que la solicitud nunca se envíe al proveedor.

El panel Script posterior a la solicitud ofrece las siguientes plantillas, agrupadas en Scripts posteriores a la solicitud:

• Actualizar el cuerpo de la respuesta : copia response_body en una variable local, le añade un campo y devuelve el cuerpo modificado.
• Generación de metadatos de SR a partir de los metadatos del proveedor : crea metadatos de campo de recursos estándar a partir de la respuesta de metadatos de un proveedor, derivando el tipo, el formato, el nombre para mostrar, la descripción, los métodos compatibles y los valores de enumeración de cada campo personalizado.

Scripts de solicitud previa

Se ejecuta un script de solicitud previa antes de enviar cada llamada a la API al proveedor. Las variables con acceso de escritura o lectura y escritura se pueden establecer a través de done().

Variable	Acceso	Descripción
request_method	Leer	Método HTTP de la llamada a la API (GET, POST, etc.).
request_vendor_method	Leer y escribir	Método HTTP que se pasará al proveedor.
request_headers	Leer	Solicitar encabezados pasados como parte de la llamada a la API.
request_vendor_headers	Leer y escribir	Encabezados que se enviarán al proveedor.
request_path	Leer	Solicitar la ruta de la llamada a la API.
request_vendor_path	Leer y escribir	Solicitar la ruta que se enviará al proveedor. Si la ruta comienza con http, se utiliza como la URL de solicitud completa.
request_path_variables	Leer	Variables de ruta extraídas de la plantilla de URL.
request_parameters	Leer	Parámetros de consulta pasados como parte de la llamada a la API.
request_vendor_parameters	Leer y escribir	Parámetros de consulta que se enviarán al proveedor.
request_body	Leer	Cuerpo de la solicitud pasado como parte de la llamada a la API, como una cadena.
request_body_raw	Leer	Cuerpo de la solicitud pasado como parte de la llamada a la API, como una cadena no procesada.
request_vendor_body	Leer y escribir	Cuerpo de la solicitud que se enviará al proveedor. Acepta cadena, lista o mapa al escribir.
request_body_map	Leer	Cuerpo de la solicitud pasado como parte de la llamada a la API, como un mapa.
request_vendor_body_map	Leer	Cuerpo de la solicitud que se enviará al proveedor, como un mapa.
request_vendor_url	Leer	URL del punto final completamente formada que se utilizará para la llamada del proveedor.
request_expression	Leer	El parámetro CEQL where se convirtió en una lista de mapas {attribute, value, operator} .
request_previous_response	Leer	Cuerpo de respuesta del recurso encadenado anterior. null si no forma parte de una cadena.
request_previous_response_headers	Leer	Encabezados de respuesta del recurso encadenado anterior. null si no forma parte de una cadena.
request_root_key	Leer y escribir	Ruta de notación de puntos para crear un subobjeto en la carga útil JSON de la solicitud (p. ej. data.record).
object_name	Leer	Nombre de objeto canónico para la solicitud.
vendor_object_name	Leer	Nombre del objeto del proveedor. Igual que object_name a menos que se anule en el recurso.
configuration	Leer	Propiedades de configuración del conector.
response_status_code	Escribir	Código de estado HTTP que se devolverá cuando continue sea false.
response_error_message	Escribir	Mensaje de error que se devolverá antes de enviar la solicitud al proveedor.
response_body	Escribir	Cuerpo de respuesta que se devolverá cuando continue sea false.
response_body_raw	Escribir	Cuerpo de la respuesta como una cadena que se devolverá cuando continue sea false.
response_root_key	Leer y escribir	Ruta de notación de puntos para limitar la respuesta a un subobjeto (p. ej. data.records).
multipart_hook_context_items	Leer y escribir	Elementos de formulario de varias partes para solicitudes de carga de archivos.
continue	Escribir	Establece en false para omitir la llamada del proveedor. El valor predeterminado es true.

Ejemplo: inyectar un encabezado dinámico desde la configuración

var headers = request_vendor_headers || {};
var config = configuration || {};

headers['Authorization'] = 'Bearer ' + config['oauth_token'];

done({ request_vendor_headers: headers });

Ejemplo: anular la ruta de la URL del proveedor

var baseUrl = configuration['base_url'];
if (!baseUrl) {
  done({ continue: false, response_error_message: "Missing configuration: 'base_url'" });
  return;
}

var apiVersion = configuration['api_version'] || 'v1';
var modelId = request_path_variables.modelId;
var vendorUrl = baseUrl.startsWith('http') ? baseUrl : 'https://' + baseUrl;

done({
  request_vendor_path: vendorUrl + '/' + apiVersion + '/models/' + modelId + '/completions'
});

Ejemplo: modificar el cuerpo de la solicitud

var body = typeof request_body_map === 'string'
  ? JSON.parse(request_body_map)
  : request_body_map;

body.max_tokens = body.max_tokens || 1024;
body.temperature = 0.7;

done({
  request_vendor_headers: { 'Content-Type': 'application/json' },
  request_vendor_body: JSON.stringify(body)
});

Scripts posteriores a la solicitud

Un script posterior a la solicitud se ejecuta después de recibir una respuesta del proveedor. Todas las variables de solicitud previa permanecen disponibles como Lectura. Se añaden las siguientes variables específicas de respuesta, y configuration se convierte en Lectura y escritura. Las variables con acceso de escritura o lectura y escritura se pueden establecer a través de done().

Variable	Acceso	Descripción
response_iserror	Leer	true si la respuesta del proveedor indica un error (códigos de estado fuera de 200–207).
response_status_code	Leer y escribir	Código de estado HTTP del proveedor.
response_body	Leer y escribir	Cuerpo de respuesta del proveedor.
response_body_raw	Leer y escribir	Cuerpo de respuesta sin formato del proveedor, como una cadena.
response_body_raw_map	Leer	Cuerpo de respuesta sin procesar del proveedor, como un mapa.
response_body_map	Leer	Cuerpo de respuesta del proveedor, como un mapa.
response_headers	Leer y escribir	Encabezados de respuesta del proveedor.
response_error_message	Escribir	Mensaje de error a devolver. Convierte la respuesta en un error.
response_root_key	Leer y escribir	Ruta de notación de puntos para limitar la respuesta a un subobjeto (p. ej. data.records).
configuration	Leer y escribir	Propiedades de configuración del conector. Los cambios persisten en la instancia del conector.
multipart_hook_context_items	Leer y escribir	Elementos de formulario de varias partes para solicitudes de carga de archivos.
metadata_merge	Escribir	Establece en true para combinar los metadatos del proveedor con los metadatos del modelo.

Consejo:

Inicia cada script posterior a la solicitud con una protección contra errores. Si la respuesta es un error, llama a done() sin argumentos para pasarlo sin cambios.

Ejemplo: transformar el cuerpo de la respuesta

if (response_iserror) {
  done();
  return;
}

var body = typeof response_body === 'string'
  ? JSON.parse(response_body)
  : response_body;

body.processed = true;
body.timestamp = new Date().toISOString();

done({ response_body: body });

Funciones de utilidad

Las siguientes funciones de utilidad están disponibles en ambos tipos de script:

Función	Descripción
console.log()	Emite un mensaje de depuración.

Traiga su propio caso de uso del conector LLM

Si estás creando un conector para un proveedor de LLM, como un modelo autohospedado o un punto final de inferencia de terceros, los scripts globales te permiten adaptar las solicitudes y respuestas para que coincidan con el contrato esperado sin modificar cada recurso individualmente.

Consejo:

Para los proveedores de LLM comunes (AWS Bedrock, Azure OpenAI, Google Vertex AI, compatible con OpenAI V1), puedes comenzar desde una plantilla de conector que rellena previamente la configuración de autenticación y los scripts por ti. Para obtener más información, consulta Usar plantillas de conector.

Los siguientes scripts muestran una configuración completa previa y posterior a la solicitud para este escenario.

Solicitud previa: establecer encabezados de autenticación

Inserta la clave API del proveedor desde la configuración del conector y aplica el Content-Type esperado:

var headers = {
  'Content-Type': 'application/json',
  'x-api-key': configuration['api_key']
};

done({
  request_vendor_headers: headers,
  request_vendor_body: request_body_map
});

Solicitud previa: insertar un mensaje del sistema

Establece los parámetros del modelo predeterminados y asegúrate de que haya un mensaje del sistema en cada conversación enviada al modelo:

var body = typeof request_body_map === 'string'
  ? JSON.parse(request_body_map)
  : request_body_map;

body.max_tokens = body.max_tokens || 1024;
body.temperature = 0.7;

var hasSystemMessage = body.messages.some(function(msg) {
  return msg.role === 'system';
});

if (!hasSystemMessage) {
  body.messages.unshift({
    role: 'system',
    content: 'You are a helpful assistant.'
  });
}

done({
  request_vendor_headers: { 'Content-Type': 'application/json' },
  request_vendor_body: JSON.stringify(body)
});

Posterior a la solicitud: procesar la matriz de opciones

Itera la matriz choices en la respuesta del proveedor y añade metadatos personalizados antes de volver al flujo de trabajo:

if (response_iserror) {
  done();
  return;
}

var body = typeof response_body === 'string'
  ? JSON.parse(response_body)
  : response_body;

if (body.choices && body.choices.length > 0) {
  body.choices.forEach(function(choice) {
    choice.processed_by = 'connector-post-script';
  });
}

body.custom_metadata = {
  processed: true,
  timestamp: new Date().toISOString()
};

done({ response_body: body });

Mejores prácticas

• Llamar siempre done() : un script que no llama a done() bloquea la solicitud.
• Copiar variables antes de mutar : el tiempo de ejecución utiliza el modo estricto. Asignar primero a una variable local: var headers = request_vendor_headers; y luego modificar headers.
• No escriba código después de done() : es inaccesible.
• Comprueba null o undefined : request_body y request_vendor_body son undefined para solicitudes GET y DELETE.
• Use continue: false to short-circuit — skip the vendor call and return your own response. Post-request scripts still run on that response.

Execution order

When a connector has both a global script and a resource script for the same phase, both scripts run, in this order:

1. Global pre-request script
2. Resource pre-request script
3. The request is sent to the provider
4. Global post-request script
5. Resource post-request script

Importante:

The post-request chain does not run in reverse. The global post-request script receives the raw provider response first, and can change or reject it before the resource post-request script runs.

Example: a global script and a resource script on one activity

Consider a connector with the following scripts:

• Global pre-request: adds an X-Acme-Tenant header from configuration.
• Global post-request: maps the provider's error envelope onto the matching HTTP status code.
• GET /contacts resource: a pre-request script that maps paging parameters, and a post-request script that reshapes the payload.

Orden	Script	Lo que ve
1	Global pre-request	The request as built from the activity input.
2	Resource pre-request	The request, including the tenant header added in step 1.
—	Provider call	—
3	Global post-request	The raw provider response.
4	Resource post-request	The response as left by step 3.

If both pre-request scripts set Authorization, the provider receives the value from the resource script, because it runs last. If the global post-request script sets response_error_message, the request ends with that error and step 4 does not run. Setting only an error response_status_code does not stop the chain.

When a pre-request script stops the request

If a global or resource pre-request script calls done() with continue: false, the request is not sent to the provider:

• Pre-request scripts that haven't run yet are skipped. For example, if the global pre-request script stops the request, the resource pre-request script does not run.
• Both post-request scripts still run, in the usual order, on the response returned by the script that stopped the request.
• If that script returned no response body, the post-request scripts receive an empty body: an empty array for a paginated resource, and an empty response otherwise.

To end the request with an error instead, set response_error_message. In a pre-request or post-request script, it ends the request immediately with that error, and no later script runs, including post-request scripts. The status code is the value of response_status_code, or 400 if it isn't set.