Soap API: Outbound Integration
SOAP (Simple Object Access Protocol) is an XML-based messaging protocol used for exchanging information between two applications. It includes a WSDL file, which contains the necessary information about what the web service does and the location of the web service.
WSDL, also known as Web Service Definition Language, is the format in which data can be represented. All tables and import sets dynamically generate a WSDL XML document that describes the table schema and available operations.
You can obtain a table’s WSDL by using a URL call to your instance that contains the name of the target table and the WSDL parameter (e.g.,
https://myinstance.servicenow.com/incident.do?WSDL).
To get started with SOAP, you need a source instance and a target instance (the target instance could be another third-party application or another ServiceNow instance).
Use case: Whenever an incident record is created in the source instance, that same record should get inserted/populated in the target instance/application.
We are going to create an inbound integration on the target instance, essentially an import set that will synchronously transform the incoming data (SOAP message + Basic AUTH) based on associated transform maps.
Web Services > Inbound
•Label - Name of Import : Incident demo
•Name - Value of name of Import: u_incidentdemo
•Checkmark <u>Copy fields from target table</u>, because we need all the fields that are in the table
•Target Table - Name of table you’re deriving data from: Incident
Click Create
•Then Click “Automapping Assist” to pull out all the fields from the target table, creating an import set.
What Is The Purpose:
To generate the WSDL URL data of the table. If you type the label name, it’ll come up as a module. Click on it and copy the WSDL URL.
On to the Source Instance:
On the source instance, search for SOAP API - SOAP Message. Keep in mind that our source instance is performing the outbound integration because a record is being ‘thrown out’ of the system.
On SOAP Message:
Click New
1•Name: Name of Soap Message: IncidentDemo
(Naming conventions doesn’t matter)
2•WSDL: Date copied from target instance
3•Authentication Type: Basic
4•Basic Auth Profile: Serves as credentials to authenticate the client( target instance ) by verifying the username and password against its authentication system before processing soap requests.
To get the Basic Auth profile, go to the target instance to get your system administrator username and password. Make sure it’s set or reset it if need be. (Sys_user.LIST to access the admin account.)
•Once username and password has been reset,
go back to source instance and add it on Basic AUTH profile field, then save form.
5•Once you save it, you will see a “Generate Sample Soap Messages” related link. —-this is a no code approach to simply insert requested data without any need for a customization(scripting).
6•Click on the link, and it'll download the WSDL of the target instance target table from the URL, generating the Soap methods.
•Update - to update records.
•getRecords - to get multiple records.
•deleteRecord - to delete a record.
•Insert - to insert a record.
•deleteMultiple - deletes multiple records.
•get- to get a record.
Click on the Insert Method, because we’re going to be inserting a new record on the target instance.
1• Select authentication as Basic and choose the Basic Auth we created.
2•On the envelope field, we see all the fields that make up incident record in an XML file, you can remove fields that aren’t required/ part of requirement.
3•Once done, Save the form.
4•Go to the “Autogenerate Variables” related link on form, which generates variable substitution for all template variables on the envelope/ XML data.
5•Once generated, we are given the option to test,
by providing these variables with test values to validate integration success, before implementing business rule to customize the integration.
6• After given it test values, click on the Test related link, upon testing review the HTTP status to ensure it states: 200,
meaning testing was successful and integration worked.
How do we check if the incident record was created/inserted in the target instance?
Go to the target instance, navigate to the target table (Incident), and check if the test record has been inserted.
Our test record got inserted—great job! You successfully performed SOAP integration. 😊
However, our set priority is of a different value because the priority field value is dependent on two other fields (impact and urgency). To properly set the priority field value, you have to set values for the impact and urgency fields.
Other than that, you successfully performed a SOAP integration that inserted a new record into another application!
Check YouTube video here:
[https://youtu.be/mAOIWpEiTF8?si=AYIke1KphsITk1CP]
To watch the implementation on how to create an after-business rule to always insert a new incident record into the target instance whenever an incident record is created in the source instance.
PS: Do not ever use the **“Before”** business rule during integration because you don’t want the record to get stored in the target system before the source system.
Key things to keep in mind when watching the YouTube video:
We are going to be creating an “After” business rule with the “Insert” operation.
For the advanced field, to set up the code, go back to the SOAP message insert function and click on the “Preview Script Usage” related link, copy the code, preview, and paste it into the business rule advanced field.
What is the code doing?
The code is calling the SOAP message we created ‘IncidentDemo’ and the method ‘Insert’ that was used in the SOAP message.
Then it’s setting parameters; the values in our parameters are from our testing, so we will need to replace them with current values.
Once that’s done, save your business rule, and again, by creating a new incident on the source instance, go to your target instance to make sure that it got populated there as well.
PS: It’s very important to keep in mind that only the field values that are being set in the parameter would show up in the target instance.
Thank you for reading and watching! I hope this lesson broke down SOAP integrations properly. To learn more about SOAP, check out these product documentations:
•https://docs.servicenow.com/bundle/tokyo-application-development/page/integrate/inbound-soap/concept/c_SOAPWebService.html
Top comments (2)
Very Educative
Thank you