Service Web SOAP AttachmentCreator

  • Rversion finale: Washingtondc
  • Mis à jour 1 févr. 2024
  • 5 minutes de lecture

    • Joignez des documents aux enregistrements dans ServiceNow en envoyant un message SOAP ciblant la table ecc_queue.

    Important :
    Le service Web SOAP AttachmentCreator n’est pas recommandé. Utilisez plutôt REST API de pièce jointe pour gérer les pièces jointes avec des services Web.
    À l’aide du service Web SOAP AttachmentCreator, vous pouvez joindre un seul document à un message d’une taille maximale de 5 Mo. Voici un exemple d’URL ou de point de terminaison cible : https ://instance_name.service-now.com/ecc_queue.do ? WSDL
    Tableau 1. ecc_queue champs pour la création de pièces jointes
    Nom de champ Description Valeur
    agent Nom de l’agent qui envoie la demande. Il peut être n’importe quelle valeur, car il n’est pas utilisé pour le traitement. Créateur d’attachement
    sujet Rubrique de l’enregistrement de file d’attente, cette valeur doit être définie sur « AttachmentCreator » pour déclencher la création de pièce jointe Créateur d’attachement
    nom Ce champ doit contenir une valeur du nom de fichier délimitée par « : » et son type de contenu file_name.xls :application/vnd.ms-excel
    source Ce champ doit contenir une valeur délimitée par « : » de la table cible et de ses sys_id Incident :DD90C5D70A0A0B39000AAC5AEE704AE8
    payload Ce champ doit contenir la chaîne codée en base 64 représentant l’objet à attacher la chaîne codée en base 64

    L’envoi des valeurs décrites dans la table ci-dessus joint un fichier Excel à la table d’incidents pour l’enregistrement localisé par le sys_id dd90c5d70a0a0b39000aac5aee704ae8

    Sécurité

    Comme tous les autres services Web basés sur HTTP disponibles sur la plateforme, le service Web SOAP AttachementCreator est requis pour s’authentifier à l’aide de l’authentification de base par défaut. L’ID utilisateur utilisé pour l’authentification sera soumis au contrôle d’accès de la même manière qu’un utilisateur interactif.

    Pour créer des pièces jointes, l’utilisateur SOAP doit disposer de tous les rôles nécessaires pour créer des enregistrements de pièce jointe [sys_attachment], ainsi que du rôle soap_create et de tous les rôles requis pour lire et écrire des enregistrements sur la table cible, tels que le rôle itil pour ajouter des pièces jointes aux enregistrements d’incidents. Par défaut, il n’existe aucun rôle unique vous permettant d’ajouter des pièces jointes. Vous pouvez créer un rôle pour autoriser explicitement l’ajout de pièces jointes, puis affecter ce rôle à l’utilisateur SOAP.

    Sécurité du type de fichier

    Vous pouvez contrôler les types de fichiers que les utilisateurs peuvent joindre en définissant les glide.attachment.extensions propriétés and glide.security.file.mime_type.validation .

    Pour que ces propriétés s’appliquent au service Web AttachmentCreator, la propriété glide.attachment.enforce_security_validation doit être définie sur vrai. Cette propriété est par défaut définie sur true.

    Exemple de message SOAP

    Voici un exemple de message SOAP qui prendrait un fichier texte « john1.txt » de type mime : text/plain et le joindrait à un incident avec un GUID de : e6eed6950a0a3c59006f32c8e3ff3cf9. Notez que la charge utile est l’encodage base64 du fichier lui-même.
    <?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>

    Exemple Node.js script

    L’exemple Node.js script suivant ajoute une pièce jointe à un enregistrement d’incident. Exécutez ce script à partir d’un ordinateur client, et non d’une instance.
    /**
 * 
 * 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);
		});
	});
}

    Exemple de script Perl

    L’exemple de script Perl suivant créera une pièce jointe à un enregistrement d’incident.
    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';
}