Serviço web SOAP AttachmentCreator

  • Versão de lançamento: Washingtondc
  • Atualizado 1 de fev. de 2024
  • 5 min. de leitura

    • Anexe documentos a registros na ServiceNow enviando uma mensagem SOAP direcionada à tabela ecc_queue.

    Importante:
    O serviço web SOAP AttachmentCreator não é recomendado. Em vez disso, use REST API de anexos para gerenciar anexos com serviços Web.
    Usando o serviço Web SOAP AttachmentCreator, você pode anexar um único documento a uma mensagem de no máximo 5 MB. Veja a seguir um exemplo de URL ou endpoint de destino: https://instance_name.service-now.com/ecc_queue.do?WSDL
    Tabela 1. Campos ecc_queue para criação de anexo
    Nome do campo Descrição valor
    agente O nome do agente que envia a solicitação. Pode ser qualquer valor, já que não é usado para processamento. AttachmentCreator
    tópico O tópico do registro da fila, este valor deve ser definido como "AttachmentCreator" para acionar a criação do anexo AttachmentCreator
    nome Este campo deve conter um valor delimitado por ":" do nome do arquivo e seu tipo de conteúdo file_name.xls:application/vnd.ms-excel
    origem Este campo deve conter um valor delimitado por ":" da tabela de destino e seu sys_id incidente: dd90c5d70a0a0b39000aac5aee704ae8
    carga Este campo deve conter a cadeia de caracteres codificada em Base 64 que representa o objeto a ser anexado a cadeia de caracteres codificada em base 64

    O envio dos valores descritos na tabela acima anexará um arquivo do Excel à tabela de incidentes para o registro localizado pelo sys_id dd90c5d70a0a0b39000aac5aee704ae8

    Segurança

    Como todos os outros serviços Web baseados em HTTP disponíveis na plataforma, o serviço Web SOAP AttachmentCreator deve ser autenticado usando a autenticação básica por padrão. O ID do usuário usado para autenticação estará sujeito ao controle de acesso da mesma forma que um usuário interativo.

    Para criar anexos, o usuário SOAP deve ter as funções necessárias para criar registros de Anexo [sys_attachment], bem como a função soap_create e todas as funções necessárias para ler e gravar registros na tabela de destino, como a função itil para adicionar anexos a registros de incidentes. Por padrão, não há uma função única que permita adicionar anexos. Você pode criar uma função para permitir explicitamente a adição de anexos e atribuir essa função ao usuário SOAP.

    Segurança de tipo de arquivo

    Você pode controlar quais tipos de arquivo os usuários podem anexar definindo as propriedades glide.attachment.extensions e glide.security.file.mime_type.validation.

    Para que essas propriedades se apliquem ao serviço Web AttachmentCreator, a propriedade glide.attachment.enforce_security_validation deve ser definida como verdadeiro. Essa propriedade será definida como verdadeira por padrão.

    Exemplo de Mensagem SOAP

    A seguir está um exemplo de uma mensagem SOAP que usaria um arquivo de texto "john1.txt" do tipo mime: text/plain e o anexaria a um incidente com um GUID de: e6eed6950a0a3c59006f32c8e3ff3cf9. Observe que a carga útil é a codificação base64 do próprio arquivo.
    <?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecc="http://www.service-now.com/ecc_queue">
    <soapenv:Header />
    <soapenv:Body>
        <ecc:insert>
            <agent>AttachmentCreator</agent>
            <topic>AttachmentCreator</topic>
            <name>john1.txt:text/plain</name>
            <source>incident:e6eed6950a0a3c59006f32c8e3ff3cf9</source>
            <payload>SSB3b25kZXIgaWYgc2hlIGtub3ducyB3aGF0IHNoZSdzIGRvaW5nIG5vdy4K</payload>
        </ecc:insert>
    </soapenv:Body>
</soapenv:Envelope>

    Exemplo de script Node.js

    O exemplo de script Node.js a seguir adiciona um anexo a um registro de incidente. Execute este script em um computador cliente, não em uma instância.
    /**
 * 
 * Node.js to ServiceNow attachment upload via SOAP
 * 
 * Andrew Venables andrew.venables@servicenow.com
 * July 2014
 * 
 * Version 1.0
 * 
 */

var soap = require('soap'), // https://github.com/vpulim/node-soap
	mime = require('mime'), // https://github.com/broofa/node-mime
	fs = require("fs");

var WSDL_FILENAME = 'ecc_queue.xml'; // Goto https://instancename.service-now.com/ecc_queue.do?WSDL and save a copy of the WSDL locally for simplicity
var DIRECTORY_CONTAINING_FILES = '/Users/andrew.venables/Documents/Uploads'; // Local path to the directory containing all the files we want to upload
var USERNAME = 'andy.venables'; // An admin user account on the instance
var PASSWORD = 'MY_PASSWORD'; // Password for above account
var TARGET_TABLE = 'incident'; // Target table to attach the files to
var TARGET_SYS_ID = '9d385017c611228701d22104cc95c371'; // Target record / sys_id to attach the files to. OOTB INC0000002

var files_to_upload; // Global that will contain our list of files to be uploaded
var pos = 0; // Global pointer for our position in the files_to_upload list

// Create a SOAP client to use to post to the instance
soap.createClient(WSDL_FILENAME, function(err, client) { // Node uses callbacks
	if (err) console.error(err);
	
	// Set the username and password
	client.setSecurity(new soap.BasicAuthSecurity(USERNAME, PASSWORD));
	
	// Read all the files in our source directory, will include . and ..
	files_to_upload = fs.readdirSync(DIRECTORY_CONTAINING_FILES);
	
	console.log('Files to upload: ' + files_to_upload.length + '\n');
	
	// Start iterating through the list of files to upload
	next(client);
		
});

// Process the next file in the files_to_upload array
// This is a neat way of dealing with Node and its expectation of callbacks
function next(client) {
	
	// Check we haven't reached the end
	if (pos >= files_to_upload.length) return;
	
	// Get the next file to upload
	var file_name = files_to_upload[pos];
	
	// Increment the pointer to the next file
	pos++;
	
	console.log(pos + '/'+ files_to_upload.length+ ' - Uploading file: ' + file_name);

	// A blank file is the end of the list
	if (file_name == '') return;
	
	// Skip to the next file as this one is invalid
	if (file_name == '.' || file_name == '..' || file_name.indexOf('.') == 0) 
		next(client);
	
	// Get the file type using an module called mime
	var file_type = mime.lookup(file_name);
	console.log('   of type: ' + file_type);
	
	var file_payload;
	// Load the file into a buffer
	fs.readFile(DIRECTORY_CONTAINING_FILES + '/' + file_name, function(err, the_data) {
		if (err) console.error(err);
		
		// Encode the buffer to base64
		file_payload = new Buffer(the_data, 'binary').toString('base64');
		
		// Set the parameters before we call the Web Service
		var parameters = {
			'agent': 	'AttachmentCreator',
	        'topic': 	'AttachmentCreator',
	        'name': 	file_name+':'+file_type,
	        'source': 	TARGET_TABLE+':'+TARGET_SYS_ID,
	        'payload': 	file_payload
		};
		
		console.log('      sending...')
		// Make the Web Service call, remember node likes callbacks
		client.insert(parameters, function(err, result) {
			if (err) console.error(err);
			
			console.log(result);
			
			// This file is done, next!
			next(client);
		});
	});
}

    Exemplo de Script Perl

    O script Perl de exemplo a seguir criará um anexo para um registro de incidente.
    use MIME::Base64;
use strict;
use SOAP::Lite;
 
# the ServiceNow instance
my $SNC_HOST = "https://instance_name.service-now.com";
my $base64;
my $buf;
 
# upload and attach a file on the local disk, base 64 encode it into a string first
open(FILE, "/Users/davidloo/Desktop/test_files/number_test.xls") or die "$!";
binmode FILE; #preserves file formatting on Windows
while (read(FILE, $buf, 60*57)) {
  $base64 .= encode_base64($buf);
}
 
# call the sub routine to attach
attach_incident();
 
sub attach_incident {
  # target the ecc_queue table
  my $soap = SOAP::Lite->proxy("$SNC_HOST/ecc_queue.do?SOAP");
  $soap->{_transport}->{_proxy}->{ssl_opts}->{verify_hostname} = 0;
  my $method = SOAP::Data->name('insert')->attr({xmlns => 'http://www.service-now.com/'});
 
  # set the ecc_queue parameters
  my @params = (SOAP::Data->name(agent => 'AttachmentCreator'));
  push(@params, SOAP::Data->name(topic => 'AttachmentCreator') );
 
  # identify the file name and its mime type
  push(@params, SOAP::Data->name(name => 'number_test.xls:application/vnd.ms-excel') );
 
  # attach to the incident, specifying its sys_id
  push(@params, SOAP::Data->name(source => 'incident:dd90c5d70a0a0b39000aac5aee704ae8') );
 
  # set the payload to be the base 64 encoded string representation of the file
  push(@params, SOAP::Data->name(payload => $base64) );
 
  # invoke the web service
  my $result = $soap->call($method => @params);
 
  print_fault($result);
 
  print_result($result);
}
 
sub print_result {
  my ($result) = @_;
 
  if ($result->body && $result->body->{'insertResponse'}) {
    my %keyHash = %{ $result->body->{'insertResponse'} };
    foreach my $k (keys %keyHash) {
        print "name=$k   value=$keyHash{$k}\n";
    }
  }
}
 
sub print_fault {
  my ($result) = @_;
 
  if ($result->fault) {
    print "faultcode=" . $result->fault->{'faultcode'} . "\n";
    print "faultstring=" . $result->fault->{'faultstring'} . "\n";
    print "detail=" . $result->fault->{'detail'} . "\n";
  }
}
 
# use the itil user for basic auth credentials
sub SOAP::Transport::HTTP::Client::get_basic_credentials {
   return 'itil' => 'itil';
}