AttachmentCreator SOAP Web Service

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 o 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 com no máximo 5 MB. A seguir está um exemplo de um 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 ":" da tabela de destino e seu sys_id	incidente:dd90c5d70a0a0b39000aac5aee704ae8
carga	Este campo deve conter a cadeia de caracteres codificada de Base 64 que representa o objeto a ser anexado	a cadeia de caracteres codificada de base 64

Enviar os 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 AttachementCreator é necessário para autenticar usando autenticação básica por padrão. O ID do usuário usado para autenticação será submetido ao controle de acesso da mesma forma que um usuário interativo.

Para criar anexos, o usuário SOAP deve ter todas 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 do tipo de arquivo

Você pode controlar quais tipos de arquivo os usuários podem anexar definindo glide.attachment.extensionse. glide.security.file.mime_type.validationpropriedades.

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

Exemplo de mensagem SOAP

Um exemplo de uma mensagem SOAP que pega um arquivo de texto "john1.txt" de mime-type: Text/plain e o anexa a um Incidente com um GUID de: E6eed6950a0a3c59006f32c8e3ff3cf9. Observe que a carga é 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>

Script Node.js de exemplo

O script Node.js de exemplo a seguir adiciona um anexo a um registro de incidente. Execute este script a partir de um computador cliente, não de uma instância.

/**
 * 
 * Node.js to ServiceNow attachment upload via SOAP
 * 
 * Andrew Venables [e-mail]
 * 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);
		});
	});
}

Script Perl de exemplo

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';
}