{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":1287,"path":"api-reference/web-services/r_AttachmentCreatorSOAPWebService.md","title":"AttachmentCreator SOAP web service","bundle":null,"doc_type":null,"release":"australia","body":"\n# AttachmentCreator SOAP web service\n\nAttach documents to records in ServiceNow by sending a SOAP message targeting the ecc\\_queue table.\n\n**Important:** The AttachmentCreator SOAP web service is not recommended. Instead, use the REST [Attachment API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/c_AttachmentAPI.md) to manage attachments with web services.\n\nUsing the AttachmentCreator SOAP web service, you can attach a single document to a message that is a maximum of 5 MB. The following is an example of a URL or target end point: `https://instance_name.service-now.com/ecc_queue.do?WSDL`\n\n|Field Name|Description|Value|\n|----------|-----------|-----|\n|agent|The name of the agent sending in the request, this can be any value since it is not used for processing.|AttachmentCreator|\n|topic|The topic of the queue record, this value must be set to \"AttachmentCreator\" to trigger the attachment creation|AttachmentCreator|\n|name|This field must contain a \":\" delimited value of the file name, and its content-type|file\\_name.xls:application/vnd.ms-excel|\n|source|This field must contain a \":\" delimited value of the target table and its sys\\_id|incident:dd90c5d70a0a0b39000aac5aee704ae8|\n|payload|This field must contain the Base 64 encoded string representing the object to be attached|the base 64 encoded string|\n\nSending in the values described in the table above will attach an Excel file to the incident table for the record located by the sys\\_id `dd90c5d70a0a0b39000aac5aee704ae8`\n\n## Security\n\nLike all other HTTP based web services available on the platform, the AttachementCreator SOAP web service is required to authenticate using basic authentication by default. The user ID that is used for authentication will be subjected to access control in the same way as an interactive user.\n\nTo create attachments, the SOAP user must have any roles required to create Attachment \\[sys\\_attachment\\] records, as well as the soap\\_create role, and any roles required to read and write records on the target table, such as the itil role to add attachments to incident records. By default there is no single role allowing you to add attachments. You can create a role to explicitly allow adding attachments, then assign this role to the SOAP user.\n\n## File type security\n\nYou can control what file types users can attach by setting the **glide.attachment.extensions** and **glide.security.file.mime\\_type.validation** properties.\n\nFor these properties to apply to the AttachmentCreator web service, the property **glide.attachment.enforce\\_security\\_validation** must be set to true. This property is true by default.\n\n## Example SOAP Message\n\nThe following is an example of a SOAP message that would take a text file \"john1.txt\" of mime-type: text/plain and attach it to an Incident with a GUID of: e6eed6950a0a3c59006f32c8e3ff3cf9. Note the payload is the base64 encoding of the file itself.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\" xmlns:ecc=\"http://www.service-now.com/ecc_queue\">\n    <soapenv:Header />\n    <soapenv:Body>\n        <ecc:insert>\n            <agent>AttachmentCreator</agent>\n            <topic>AttachmentCreator</topic>\n            <name>john1.txt:text/plain</name>\n            <source>incident:e6eed6950a0a3c59006f32c8e3ff3cf9</source>\n            <payload>SSB3b25kZXIgaWYgc2hlIGtub3ducyB3aGF0IHNoZSdzIGRvaW5nIG5vdy4K</payload>\n        </ecc:insert>\n    </soapenv:Body>\n</soapenv:Envelope>\n```\n\n## Example Node.js Script\n\nThe following example Node.js script adds an attachment to an incident record. Run this script from a client computer, not an instance.\n\n```\n/**\n * \n * Node.js to ServiceNow attachment upload via SOAP\n * \n * Andrew Venables andrew.venables@servicenow.com\n * July 2014\n * \n * Version 1.0\n * \n */\n\nvar soap = require('soap'), // https://github.com/vpulim/node-soap\n\tmime = require('mime'), // https://github.com/broofa/node-mime\n\tfs = require(\"fs\");\n\nvar 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\nvar DIRECTORY_CONTAINING_FILES = '/Users/andrew.venables/Documents/Uploads'; // Local path to the directory containing all the files we want to upload\nvar USERNAME = 'andy.venables'; // An admin user account on the instance\nvar PASSWORD = 'MY_PASSWORD'; // Password for above account\nvar TARGET_TABLE = 'incident'; // Target table to attach the files to\nvar TARGET_SYS_ID = '9d385017c611228701d22104cc95c371'; // Target record / sys_id to attach the files to. OOTB INC0000002\n\nvar files_to_upload; // Global that will contain our list of files to be uploaded\nvar pos = 0; // Global pointer for our position in the files_to_upload list\n\n// Create a SOAP client to use to post to the instance\nsoap.createClient(WSDL_FILENAME, function(err, client) { // Node uses callbacks\n\tif (err) console.error(err);\n\t\n\t// Set the username and password\n\tclient.setSecurity(new soap.BasicAuthSecurity(USERNAME, PASSWORD));\n\t\n\t// Read all the files in our source directory, will include . and ..\n\tfiles_to_upload = fs.readdirSync(DIRECTORY_CONTAINING_FILES);\n\t\n\tconsole.log('Files to upload: ' + files_to_upload.length + '\\n');\n\t\n\t// Start iterating through the list of files to upload\n\tnext(client);\n\t\t\n});\n\n// Process the next file in the files_to_upload array\n// This is a neat way of dealing with Node and its expectation of callbacks\nfunction next(client) {\n\t\n\t// Check we haven't reached the end\n\tif (pos >= files_to_upload.length) return;\n\t\n\t// Get the next file to upload\n\tvar file_name = files_to_upload[pos];\n\t\n\t// Increment the pointer to the next file\n\tpos++;\n\t\n\tconsole.log(pos + '/'+ files_to_upload.length+ ' - Uploading file: ' + file_name);\n\n\t// A blank file is the end of the list\n\tif (file_name == '') return;\n\t\n\t// Skip to the next file as this one is invalid\n\tif (file_name == '.' || file_name == '..' || file_name.indexOf('.') == 0) \n\t\tnext(client);\n\t\n\t// Get the file type using an module called mime\n\tvar file_type = mime.lookup(file_name);\n\tconsole.log('   of type: ' + file_type);\n\t\n\tvar file_payload;\n\t// Load the file into a buffer\n\tfs.readFile(DIRECTORY_CONTAINING_FILES + '/' + file_name, function(err, the_data) {\n\t\tif (err) console.error(err);\n\t\t\n\t\t// Encode the buffer to base64\n\t\tfile_payload = new Buffer(the_data, 'binary').toString('base64');\n\t\t\n\t\t// Set the parameters before we call the Web Service\n\t\tvar parameters = {\n\t\t\t'agent': \t'AttachmentCreator',\n\t        'topic': \t'AttachmentCreator',\n\t        'name': \tfile_name+':'+file_type,\n\t        'source': \tTARGET_TABLE+':'+TARGET_SYS_ID,\n\t        'payload': \tfile_payload\n\t\t};\n\t\t\n\t\tconsole.log('      sending...')\n\t\t// Make the Web Service call, remember node likes callbacks\n\t\tclient.insert(parameters, function(err, result) {\n\t\t\tif (err) console.error(err);\n\t\t\t\n\t\t\tconsole.log(result);\n\t\t\t\n\t\t\t// This file is done, next!\n\t\t\tnext(client);\n\t\t});\n\t});\n}\n```\n\n## Example Perl Script\n\nThe following example Perl script will create an attachment to an incident record.\n\n```\nuse MIME::Base64;\nuse strict;\nuse SOAP::Lite;\n \n# the ServiceNow instance\nmy $SNC_HOST = \"https://instance_name.service-now.com\";\nmy $base64;\nmy $buf;\n \n# upload and attach a file on the local disk, base 64 encode it into a string first\nopen(FILE, \"/Users/davidloo/Desktop/test_files/number_test.xls\") or die \"$!\";\nbinmode FILE; #preserves file formatting on Windows\nwhile (read(FILE, $buf, 60*57)) {\n  $base64 .= encode_base64($buf);\n}\n \n# call the sub routine to attach\nattach_incident();\n \nsub attach_incident {\n  # target the ecc_queue table\n  my $soap = SOAP::Lite->proxy(\"$SNC_HOST/ecc_queue.do?SOAP\");\n  $soap->{_transport}->{_proxy}->{ssl_opts}->{verify_hostname} = 0;\n  my $method = SOAP::Data->name('insert')->attr({xmlns => 'http://www.service-now.com/'});\n \n  # set the ecc_queue parameters\n  my @params = (SOAP::Data->name(agent => 'AttachmentCreator'));\n  push(@params, SOAP::Data->name(topic => 'AttachmentCreator') );\n \n  # identify the file name and its mime type\n  push(@params, SOAP::Data->name(name => 'number_test.xls:application/vnd.ms-excel') );\n \n  # attach to the incident, specifying its sys_id\n  push(@params, SOAP::Data->name(source => 'incident:dd90c5d70a0a0b39000aac5aee704ae8') );\n \n  # set the payload to be the base 64 encoded string representation of the file\n  push(@params, SOAP::Data->name(payload => $base64) );\n \n  # invoke the web service\n  my $result = $soap->call($method => @params);\n \n  print_fault($result);\n \n  print_result($result);\n}\n \nsub print_result {\n  my ($result) = @_;\n \n  if ($result->body && $result->body->{'insertResponse'}) {\n    my %keyHash = %{ $result->body->{'insertResponse'} };\n    foreach my $k (keys %keyHash) {\n        print \"name=$k   value=$keyHash{$k}\\n\";\n    }\n  }\n}\n \nsub print_fault {\n  my ($result) = @_;\n \n  if ($result->fault) {\n    print \"faultcode=\" . $result->fault->{'faultcode'} . \"\\n\";\n    print \"faultstring=\" . $result->fault->{'faultstring'} . \"\\n\";\n    print \"detail=\" . $result->fault->{'detail'} . \"\\n\";\n  }\n}\n \n# use the itil user for basic auth credentials\nsub SOAP::Transport::HTTP::Client::get_basic_credentials {\n   return 'itil' => 'itil';\n}\n```\n\n**Parent Topic:**[SOAP web service](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/c_SOAPWebService.md)\n\n"}}