ServiceGrid Article - HTTPS Post

From DocWiki

Jump to: navigation, search

Contents

Overview

The hypertext transfer protocol (HTTP), is a generic, stateless application-level protocol for distributed and collaborative used systems and is commonly used for data exchange between clients and server through the internet. HTTPS (hypertext transfer protocol with secure socket layer) combines the usability and advantages of HTTP with the security and reliability of SSL. The HTTPS Post method is used to send content to a website. This may enable an application to communicate data to another website instead of using interactive browser pages.

Parameters needed

A HTTP Post transaction consists of:

Request Parameters

  • Request header parameters - The request header contains the meta information for the request like Content-Length or Content-Type.
  • Request parameters - The request parameters contain data typically entered in HTML forms. This can be user, password, or the call data.
  • Request Stream - Instead of request parameters, call data can be sent using a stream.

Response Parameters

  • HTTP Status Code - The HTTP Status Code returns the success or failure of a HTTP Post transaction.
  • Response Stream -  The result data of the request.

There are 3 options when using HTTPS Post to connect to Cisco ServiceGrid:

Options
Actions
Description
push/push
SD push, Client push
  • Let ServiceGrid push new messages or updates to the client application
  • Client application pushes new messages or updates to ServiceGrid
push/pull
Client push, Client pull
  • Client application pushes new messages or updates to ServiceGrid
  • Client application pulls new messages or updates from ServiceGrid
pull/push
ServiceGrid pull, ServiceGrid push
  • Let ServiceGrid pushes new messages or updates to the client application
  • Let ServiceGrid pulls new messages or updates to the client application














The combination "pull/pull" is not supported. Attachments are not supported when using HTTPS POST.

Pushing messages to ServiceGrid through HTTPS Post using the method putCall

Parameters used

Parameter
Description
Example
URLs (main platform)

ServiceGrid HTTPS URL Production system

ServiceGrid HTTPS URL Staging system

https://ws.cisco.com/ws/distinct/HTTPDirectServlet

https://beta.cisco.com/pages/sdcall/HTTPDirectServlet

Request Parameters


Action
The action to push messages is putCall

Send as request header parameter: v

SDUser, SDPassword
Cisco provides the partner with a unique userID and password Sent as request header parameter: v
Sent as request parameter: v
Authentication
Instead of SDUser and SDPassword parameters, both can be sent as base64 encoded string (Basic Access Authentication) as described in http://en.wikipedia.org/wiki/Basic_access_authentication
Sent as request header parameter: v
Content-Type (optional)
Can be set by sender. Possible values are "text/xml" or "text/plain" or "application/x-sss-form-urlencoded"
Sent as request header parameter: v
Content-Length
Must be set by sender. Maximum length is 32000 characters
Sent as request header parameter: v
SDCallString
Must contain the call data in any format supported by ServiceGrid
Sent as request header parameter: v
Sent as request parameter: v
Sent as data stream: v
Response OK


HTTP Return Code

200 (=ok), (see HTTP Return Codes in wikipedia..http://en.wikipedia.org/wiki/List_of_HTTP_status_codes).
Response Stream

Text: "....successfully handled request"
Response Stream: Option

customizable response message
Response Error


HTTP Return Code

a return code >= 400 means, that an error occurred (see HTTP Return Codes in wikipedia..http://en.wikipedia.org)en.wikipedia.org
Response Stream

Text: error message...
 !

All data must be UTF-8 encoded! Any other encoding may result in wrong characters.
The content length must not exceed 32000 bytes! The request cannot be handled and will result in a HTTP Response Code <> 200.


































Sample request:


A putCall request with call data in stream:

POST /ws/distinct/HTTPDirectServlet?action=putCall HTTP/1.1
Content-Type: text/xml
SDUser: myuser
SDPassword: mypassword
User-Agent: Java/1.4.2_05
Host: ws.solvedirect.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Content-Length: 233
<CALL>
<CALLS.ID>435245032</CALLS.ID>
<CALLS.REMARKS>Callupdate per HTTP</CALLS.REMARKS>
<CALLSTATES.SHORTNAME>C02</CALLSTATES.SHORTNAME>
<CALLS.NOTES type="T2">This is a note of type T2....</CALLS.NOTES>
</CALL> 

Checklist

  • Make sure that the URLS are accessible through your firewalls.
  • Try to access the URLs. Result: HTML: GET not supported.
  • Request SDUser and SDPassword from your ServiceGrid administrator interface, and login from sdcall.cisco.com or beta.cisco.com.
  • Send a request including all header parameters and call data. You should receive the HTTP response code 200.
  • A call insert or call update is performed on the ServiceGrid platform or an error message is sent.


HTML Forms to invoke HTTPDirectServlet

You can also use very simple HTML forms to invoke the HTTPDirectServlet. Paste the following HTML Code into a HTML file and open the file with your browser. You do not need a webserver. You can open the HTML file with file://PATH-TO-THE-HTML-FILE

Form for putCall

<FORM method="POST" action="https://ws.cisco.com/ws/distinct/HTTPDirectServlet?action=putCall">
Username: <INPUT type="text" name=SDUser>
<BR>Password: <INPUT type="text" name=SDPassword>
<BR>SDCallString: 
<BR><TEXTAREA name=SDCallString style="HEIGHT: 400px; WIDTH: 400px;"></TEXTAREA><BR><INPUT type=submit value="Submit Query"></FORM>

For building the inbound message trigger, see SD.Message Rules.


Pulling new messages or updates from Cisco ServiceGrid via HTTPS Post using the method getCalls

Parameters used

Parameter
Description
Example
URLs (main platform)

ServiceGrid HTTPS URL Production system

ServiceGrid HTTPS URL Staging system

https://ws.cisco.com/ws/distinct/HTTPDirectServlet

https://beta.cisco.com/pages/sdcall/HTTPDirectServlet

Request Parameters


Action
The action to pull messages is getCalls

Send as request header parameter: v

SDUser, SDPassword
Cisco will provide the partner with a unique userID and password Sent as request header parameter: v
Sent as request parameter: v
Authentication
Instead of SDUser and SDPassword parameters, both can be sent as base64 encoded string (Basic Access Authentication) as described in http://en.wikipedia.org/wiki/Basic_access_authentication
Sent as request header parameter: v
Response OK


HTTP Return Code

200 (=ok), (see HTTP Return Codes in wikipedia..http://en.wikipedia.org/wiki/List_of_HTTP_status_codes).
Response Stream

  • contains the call data as xml
  • zero, 1 or many calls, if zero the response stream is a valid XML with an empty tag
Response Error


HTTP Return Code

a return code >= 400 means, that an error occurred (see HTTP Return Codes in wikipedia..http://en.wikipedia.org)en.wikipedia.org
Response Stream

Text: error message...
 !

All data must be UTF-8 encoded! Any other encoding may result in wrong characters.
The content length must not exceed 32000 bytes! The request cannot be handled and will result in a HTTP Response Code <> 200.


























Sample request:

A getCalls request with SDUser and SDPassword as POST parameters:

POST /ws/distinct/HTTPDirectServlet?action=getCalls HTTP/1.0
User-Agent: Wget/1.11.4
Accept: */*
Host: ws.solvedirect.com
Connection: Keep-Alive
Content-Type: application/x-www-form-urlencoded
Content-Length: 26
---request end---
[POST data: SDUser=XYZT&SDPassword=xyz]

Checklist

  • Make sure that the URLS are accessible through your firewalls.
  • Try to access the URLs, Result: HTML: GET not supported.
  • Request SDUser and SDPassword from ServiceGrid, and login from sdcall.cisco.com or beta.cisco.com
  • Send a request including all header parameters. Make sure that valid calls or updates are available for processing on SD side.

HTML Forms to invoke HTTPDirectServlet

You can also use very simple HTML forms to invoke the HTTPDirectServlet. Paste following HTML Code into a HTML file and open the file with your browser. You do not need a webserver. You can open the HTML file with file://PATH-TO-THE-HTML-FILE.

'Form for getCalls'

<FORM method=post action=https://ws.solvedirect.com/ws/distinct/HTTPDirectServlet?action=getCalls> 
Username: <INPUT name=SDUser>
<br>Password: <INPUT name=SDPassword>
<br><INPUT type=submit value="Submit Query">
</FORM>

For building the outbound message trigger, see SD.Message Rules.

Letting ServiceGrid to push new messages or updates to the client system

To let Cisco ServiceGrid push a message through HTTPS Post, the following parameters need to be known by ServiceGrid:

  • URL (Ex. https://mydomain.com/myservice)
  • Content-Type (For example, text/xml)
  • Authorization method (For example, Basic Access Authentification as request header parameter) and authorization data
  • Additional needed request header parameters root tag of the XML document
  • Are attachments used?

Example property file for a HTTPS Post push communication:

URL = https://mydomain.com/services
CONTENT_TYPE = text/xml
HEADER_Authorization = Basic Y2NpDmwOm3lWW50dXNlcjEK
CHECK_FOR_ATTACHMENTS = false
ROOT_TAG = CALL 

Letting ServiceGrid to pull new messages or updates from the client system

To let Cisco ServiceGrid pull a message through HTTPS Post, the following parameters need to be known by the ServiceGrid:

  • URL (For example, https://mydomain.com/myservice)
  • Content-Type (For example,  text/xml)
  • Authorization method (Ex. Basic Access Authentification as request header parameter) and authorization data
  • Additional needed request header parameters

Example property file for a HTTPS Post push communication:

URL = https://mydomain.com/services
CONTENT_TYPE = text/xml
HEADER_Authorization = Basic Y2NpDmwOm3lWW50dXNlcjEK


HTTPS Post Security

To transport messages through HTTPS POST, the port 443 (HTTPS) must be enabled. The Cisco ServiceGrid supports only Post via HTTPS. So the communication is always encrypted. An additional VPN encryption through IPSEC can be used as option. For more information about IPsec, refer to SD bridge Network Layer.


For a complete list of Cisco ServiceGrid Articles, go to the List of Articles page.


Rating: 0.0/5 (0 votes cast)

Personal tools