Hello Everyone,
I have been administering and developing in SNOW since 2014 and recently I was tasked to integrate ServiceNow with Ultimate Software's UltiPro. I have had experience with SOAP and REST integrations but this one perplexed me at first especially since there is zero content for an integration with UltiPro.
I would estimate the initial project took about 2 months which only consisted of creating new hire contractors in our UltiPro environment and getting the employee number assigned in UltiPro to update the RITM.
Since the project has ended I have done much more with the integration and I want to share the knowledge I have gained to the community. I have received a wealth of knowledge from the community and I need to give back. I hope this article helps anyone looking to do the same integrations or even helps general SOAP & REST actions between ServiceNow and other SAAS solutions.
Things you will need for this integration.
- Basic knowledge of REST and SOAP API's
- Postman I cannot recommend this app enough you will be using it for the entire integration and it is indispensable.
- ServiceNow Advanced admin training or comparable experience.
Things you will need from your UltiPro Administrator
- An Ultipro Web-Service Account
-
Client Access Key
- User Access Key
- Access to the API Service.
You will need to determine the API Service the web-service account needs to access. A list of the API's are found here Ultimate Software API Documentation.
Your Ultipro Admin should be able to provide you for the first 3 easily. With number 4 it will depend on your integration. When you select an API the documentation to the right will tell you the web-service access you need.
This is always found in the Prerequisite section.
In this article we will be getting a license token. I will follow up with another article on creating a new employee using the Employee New Hire Service API from UltiPro. One token can be used through the entire workflow.
To get the UltiPro token you will need to create an Outbound Web Service. Filter on SOAP, under Outbound choose SOAP Message and click New from the List
Give the Outbound SOAP message for login token a name and provide the URL endpoint.
Your URL may by different but it should be something like https://service101.ultipro.com/services/LoginService the 101 would be your instance that can get from ultipro or your admin. If you look at the attached Getting Started guide on page 7 you will see more examples of the endpoints you might use.
Save the record and click the "Generate sample SOAP messages" link under Related Links. You should now see an "Authenticate" record under "SOAP Message Functions". Click the related Authenticate record to edit it.
I had no success using the ServiceNow generated envelope to get my authorization token but using the attached document WebServiceAPIGuide_LoginService.doc or my sample xml below you can replace the generated message and get a login token. Replace the ${variables} with the information provided by your UltiPro Admin.
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://www.w3.org/2005/08/addressing">
<s:Header>
<a:Action s:mustUnderstand="1">http://www.ultipro.com/services/loginservice/ILoginService/Authenticate</a:Action>
<h:ClientAccessKey xmlns:h="http://www.ultipro.com/services/loginservice">${YOUR CLIENT ACCESS KEY}</h:ClientAccessKey>
<h:UserAccessKey xmlns:h="http://www.ultipro.com/services/loginservice">${YOUR USER ACCESS KEY}</h:UserAccessKey>
<h:Password xmlns:h="http://www.ultipro.com/services/loginservice">${YOUR WEB SERVICE ACCOUNT PASSSWORD}</h:Password>
<h:UserName xmlns:h="http://www.ultipro.com/services/loginservice">${YOUR WEB SERVICE ACCOUNT USERNAME}</h:UserName>
</s:Header>
<s:Body>
<TokenRequest xmlns="http://www.ultipro.com/contracts" />
</s:Body>
</s:Envelope>Once you have updated the XML with your authentication keys and user name and password you should be able to use this outbound message to get a token in a business rule or a script action in workflow.
Clicking the TEST under Related Links will not work, You will get the error "Method failed: (/services/LoginService) with code: 415" you will need to specify the content-type in your business rule or Script action in your Workflow to get your token.
This is not only for getting a token but you will need to specify a content-type for all outbound SOAP messages to UltiPro.
To test this use Postman and you will need to add a Content-Type header with the value of "application/soap+xml". There will be a default Content-Type but the one you add will override the default.
Click the Body tab in Postman and paste your XML from your SOAP message function created earlier, click Send and you should get a result with your token.
Once you have a successful result you are ready to use your outbound SOAP Message for workflow or business rules. For almost all Ultipro integrations you will need this authentication token.
Getting the token in workflow.
Add a Run Script action to your workflow. This is where you execute your outbound SOAP message and will need to set the Content-Type header as well as using the workflow.scratchpad for your token.
Your script should look something like this (you may have named your outbound SOAP message something other than 'Ultipro Login Token')
var s = new sn_ws.SOAPMessageV2('UltiPro Login Token', 'Authenticate');
s.setRequestHeader('Content-Type', 'application/soap+xml');
var response = s.execute();
var responseBody = response.getBody();
var status = response.getStatusCode();
var xmlDoc = new XMLDocument2();
xmlDoc.parseXML(responseBody);
var token = xmlDoc.getNode("//Token").getTextContent();
workflow.scratchpad.token = token;Now you can use workflow.scratchpad.token for other run script actions in your workflow for your integration for the other available API's. Here is how I am using it in a workflow to create a new contractor or employee.
To use this in a business rule you can set a variable or a field on your form with the token. You only need to change the last line of the script.
This is my fist article published for the community and I hope you you find it useful. I will be following up this article with the 'Create New Contractor In Ultipro' run script action along with other ways to POST or GET data from UltiPro.
Let me know if you have any questions in the comments below.
Thank you,
David Whaley
