SOAP Web Service „AttachmentCreator“

Hängen Sie Dokumente an Datensätze in ServiceNow an, indem Sie eine SOAP-Nachricht für die Tabelle „ecc_queue“ senden.

Wichtig:

Der SOAP Web Service AttachmentCreator wird nicht empfohlen. Verwenden Sie stattdessen den REST-Anhang-API, um Anhänge mit Webservices zu verwalten.

Mit dem SOAP Web Service „AttachmentCreator“ können Sie ein einzelnes Dokument an eine maximal 5 MB große Nachricht anhängen. Das folgende Beispiel zeigt eine URL oder einen Zielendpunkt: https://instance_name.service-now.com/ecc_queue.do?WSDL

Tabelle : 1. ecc_queue-Felder für die Erstellung von Anhängen

Feldname	Beschreibung	Wert
Agent	Der Name des Agenten, der die Anforderung sendet. Kann ein beliebiger Wert sein, da er nicht zur Verarbeitung verwendet wird.	AttachmentCreator
Thema	Das Thema des Warteschlangendatensatzes. Dieser Wert muss auf „AttachmentCreator“ festgelegt werden, um die Erstellung des Anhangs auszulösen	AttachmentCreator
Name	Dieses Feld muss einen durch „:“ getrennten Wert des Dateinamens und seinen Content Typ enthalten	file_name.xls:application/vnd.ms-excel
Quelle	Dieses Feld muss einen durch „:“ getrennten Wert der Zieltabelle und dessen sys_id enthalten	incident:dd90c5d70a0a0b39000aac5aee704ae8
Payload	Dieses Feld muss die Base 64-codierte Zeichenfolge enthalten, die das anzuhängende Objekt darstellt	die Base 64-codierte Zeichenfolge

Beim Senden der in der Tabelle oben beschriebenen Werte wird eine Excel-Datei an die Incident-Tabelle für den Datensatz angehängt, der sich in der sys_id dd90c5d70a0a0b39000aac5aee704ae8 befindet.

Sicherheit

Wie alle anderen HTTP-basierten Webservices, die auf der Plattform verfügbar sind, ist der SOAP Web Service von AttachementCreator erforderlich, um die Basic Authentication standardmäßig zu verwenden. Die für die Authentifizierung verwendete Benutzer-ID wird wie ein interaktiver Benutzer der Zugriffskontrolle unterzogen.

Zum Erstellen von Anhängen muss der SOAP-Benutzer über alle erforderlichen Rollen zum Erstellen von Anhang-Datensätzen [sys_attachment] sowie über die Rolle „soap_create“ und über alle zum Lesen und Schreiben von Datensätzen in der Zieltabelle erforderlichen Rollen verfügen, z. B. über die Rolle „itil“, um Anhänge den Incident-Datensätzen hinzuzufügen. Standardmäßig gibt es keine Einzelrolle, mit der Sie Anhänge hinzufügen können. Sie können eine Rolle erstellen, um das Hinzufügen von Anhängen explizit zuzulassen, und diese Rolle dann dem SOAP-Benutzer zuweisen.

Dateityp-Sicherheit

Sie können steuern, welche Dateitypen Anwender anhängen können, indem Sie festlegen glide.attachment.extensionsUnd glide.security.file.mime_type.validationEigenschaften.

Damit diese Eigenschaften auf den AttachmentCreator-Webservice angewendet werden, die Eigenschaft glide.attachment.enforce_security_validationMuss auf „wahr“ festgelegt werden. Diese Eigenschaft ist standardmäßig „true“.

Beispiel einer SOAP-Nachricht

Im Folgenden finden Sie ein Beispiel für eine SOAP-Nachricht, die eine Textdatei „john1.txt“ mit dem MIME-Typ „Nur-Text“ verwenden und an einen Incident mit der GUID „e6eed6950a0a3c59006f32c8e3ff3cf9“ anfügen würde. Beachten Sie, dass die Payload die base64-Kodierung der eigentlichen Datei ist.

<?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>

Beispiel Node.js-Skript

Das folgende Beispielskript „Node.js“ fügt einem Incident-Datensatz einen Anhang hinzu. Führen Sie dieses Skript von einem Clientcomputer und nicht von einer Instanz aus.

/**
 * 
 * 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);
		});
	});
}

Beispiel für ein Perl-Skript

Das folgende Beispiel-Perl-Skript erstellt einen Anhang zu einem Incident-Datensatz.

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