Web Service API

Overview

 

Web Service is used to integrate various applications to facilitate sharing of data between them. The integration can be achieved with any third party application or web service that is capable of sending the data via http protocol. In case of request operations, it provides a convenient method to raise requests (other than the default e-mail or web form) directly into SapphireIMS ITSM without logging into the application. You can also design your own web form to raise a request using web service API's.

 

SapphireIMS provides a web service API for creating and changing the state of the ticket in service desk as explained in the following steps

 

 

Note: SapphireIMS web service API is based on Web Services Description Language (WSDL). The WSDL is a language written in XML for describing web services and how to access them. WSDL is often used in combination with SOAP and an XML Schema to provide Web services over the Internet. A client program connecting to a Web service can read the WSDL file to determine what operations are available on the server. Any special datatypes used are embedded in the WSDL file in the form of XML Schema. The client can then use SOAP to call one of the operations listed in the WSDL file

 

Creation of the Ticket

To create a ticket in service desk through web service API, ticket parameters like Project, Service, Title, Description and Additional Fields need to be provided along with the database schema.

 

Step 1: Defining Database Schema

 

Provide the database schema in which the ticket should get created. For Professional setup schema name is ‘ims’. For MSP setup schema name should be the customer schema.

 

String schema = "ims";

 

Step 2: Get the authentication key of the user who is going to create the ticket by providing user name and password

 

String strAuthKey = getAuthKey(encode("System"),encode("System"), schema);

 

This authentication key is used in other methods to validate the user.

 

Step 3: Create RemoteRequest object and set the ticket parameters for this object

 

RemoteRequest requestObj = new RemoteRequest();

 

 

Get category details based on service

 

· Get categories available for specific service

Set the service for which we want categories

 

int nServiceID=getServiceID(nProjectID, "Network and Security", strAuthKey,

schema);

 

Get the categories based on serviceid like below

 

  List<CategoryDetails> categoryList = getCategoryListBasedOnService(nServiceID,nProjectID, strAuthKey, schema);

System.out.println("Category details are as follows:");

System.out.println("");

for(int i=0;i<categoryList.size();i++){

System.out.println("Category ID"+categoryList.get(i).getNCategoryID());

System.out.println("Category Name : "+categoryList.get(i).getStrCategoryName());

System.out.println("Category Description : "+categoryList.get(i).getStrCategoryDescription());

System.out.println("");}

 

 

Steps for defining fixed data fields of the ticket

 

 

requestObj.setProjectID(nProjectID);

 

 

int nProjectID = getProjectID("Incident Management", strAuthKey, schema);

 

 

List<ProjectDetails> projectList = getProjectList(strAuthKey, schema);

for(int i=0;i<projectList.size();i++)

{

System.out.println("Project ID : "+projectList.get(i).getNProjectID());

System.out.println("Project Name : "+projectList.get(i).getStrProjectName());

System.out.println("Project Description : "+projectList.get(i).getStrProjectDescription());

}

 

 

requestObj.setServiceID(nServiceID);

 

 

int nServiceID = getServiceID(nProjectID, "Desktop Management", strAuthKey, schema);

 

 

List<ServiceDetails> serviceList = getServiceList(nProjectID,strAuthKey, schema);

for(int i=0;i<serviceList.size();i++){

System.out.println("Service ID : "+serviceList.get(i).getNServiceID());

System.out.println("Service Name : "+serviceList.get(i).getStrServiceName());

System.out.println("Service Description : +serviceList.get(i).getStrServiceDescription());

}

request.setSubmitter(nUserID);

 int nUserID = getUserID("Administrator", strAuthKey, schema);

int nUserIDOne = getUserIDByLoginID("admin", strAuthKey, schema);

 int nUserIDTwo = getUserIDByColumn("EmailAddress",   "sanjeev.b@sapphireims.com", strAuthKey, schema);

int nUserIDThree = getUserIDByColumn("EmployeeID", "094", strAuthKey, schema);

int nUserIDFour = getUserIDByColumn("Cell_No", "9916012345", strAuthKey, schema);

 

 

requestObj.setTitle("Test Ticket");

 

 

requestObj.setDescription("Test Ticket");

 

requestObj.setCategoryID(nCategoryID);

 

 

int nCategoryID = getCategoryID(nProjectID, "Hardware", strAuthKey, schema);

 

 

List<CategoryDetails> categoryList = getCategoryList(nProjectID, strAuthKey, schema);

for(int i=0;i<categoryList.size();i++){

System.out.println("Category ID : "+categoryList.get(i).getNCategoryID());

System.out.println("Category Name : "+categoryList.get(i).getStrCategoryName());

System.out.println("Category Description : "

+categoryList.get(i).getStrCategoryDescription());}

 

 

requestObj.setSubCategoryID(nSubCategoryID);

 

 

int nSubCategoryID = getSubCategoryID(nProjectID, nCategoryID, "Laptop Battery Issue", strAuthKey, schema);

 

 

List<SubCategoryDetails> subCategoryList  = getSubCategoryList(nProjectID, nCategoryID, strAuthKey, schema);

for(int i=0;i<subCategoryList.size();i++){

System.out.println("Category ID : "+subCategoryList.get(i).getNCategoryID());

System.out.println("Category Name : "+subCategoryList.get(i).getStrCategoryName());

System.out.println("Sub Category ID : "+subCategoryList.get(i).getNSubCategoryID());

System.out.println("Sub Category Name : "+subCategoryList.get(i).getStrCategoryName());}

 

 

requestObj.setDerivedField1ID(nDerivedField1ID);

 

 

int nDerivedField1ID = getDerivedField1ID(nProjectID, "DF1", strAuthKey, schema);

 

 

List<DerivedFieldDetails> derivedField1List = getDerivedField1List(nProjectID, strAuthKey, schema);

for(int i=0;i<derivedField1List.size();i++){

System.out.println("Derived Field1 ID : "+derivedField1List.get(i).getNDerivedFieldID());

System.out.println("Derived Field1 Name : "+derivedField1List.get(i).getStrDerivedFieldName());}

 

 

List<DerivedFieldDetails> derivedField1ListSubCategory = getDerivedField1ListSubCategory(nProjectID, nSubCategoryID, strAuthKey, schema);

for(int i=0;i<derivedField1ListSubCategory.size();i++){

System.out.println("Derived Field1 ID : "+derivedField1ListSubCategory.get(i).getNDerivedFieldID());

System.out.println("Derived Field1 Name : "+derivedField1ListSubCategory.get(i).getStrDerivedFieldName());}

 

 

requestObj.setDerivedField2ID(nDerivedField2ID);

 

 

int nDerivedField2ID = getDerivedField2ID(nProjectID, "DF2", strAuthKey, schema);

 

 

List<DerivedFieldDetails> derivedField2List = getDerivedField2List(nProjectID, strAuthKey, schema);

for(int i=0;i<derivedField2List.size();i++){

System.out.println("Derived Field2 ID : "+derivedField2List.get(i).getNDerivedFieldID());

System.out.println("Derived Field2 Name : "+derivedField2List.get(i).getStrDerivedFieldName());}

 

 

List<DerivedFieldDetails> derivedField2ListSubCategory = getDerivedField2ListSubCategory(nProjectID, nSubCategoryID,nDerivedField1ID,strAuthKey, schema);

for(int i=0;i<derivedField2ListSubCategory.size();i++){

System.out.println("Derived Field2 ID : "+derivedField2ListSubCategory.get(i).getNDerivedFieldID());

System.out.println("Derived Field2 Name : "+derivedField2ListSubCategory.get(i).getStrDerivedFieldName());}

 

 

requestObj.setDerivedField3ID(nDerivedField3ID);

 

 

int nDerivedField3ID = getDerivedField3ID(nProjectID, "DF3", strAuthKey, schema);

 

 

List<DerivedFieldDetails> derivedFied3List = getDerivedField3List(nProjectID, strAuthKey, schema);

for(int i=0;i<derivedFied3List.size();i++){

System.out.println("Derived Field3 ID : "+derivedFied3List.get(i).getNDerivedFieldID());

System.out.println("Derived Field3 Name : "+derivedFied3List.get(i).getStrDerivedFieldName());}

 

 

List<DerivedFieldDetails> derivedField3ListSubCategory = getDerivedField3ListSubCategory(nProjectID, nSubCategoryID,nDerivedField1ID,nDerivedField2ID, strAuthKey, schema);

for(int i=0;i<derivedField3ListSubCategory.size();i++){

System.out.println("Derived Field3 ID : "+derivedField3ListSubCategory.get(i).getNDerivedFieldID());

System.out.println("Derived Field3 Name : "+derivedField3ListSubCategory.get(i).getStrDerivedFieldName());}

 

 

requestObj.setAssetID(nAssetID);

 

 

int nAssetID = getAssetID("DEV-TKD-005",strAuthKey,schema);

 

 

List<AssetDetails> assetList = getAssetList(strAuthKey, schema);

for(int i=0;i<assetList.size();i++){

System.out.println("Asset ID : "+assetList.get(i).getNAssetID());

System.out.println("Asset Number :    "+assetList.get(i).getStrAssetNumber());

System.out.println("Asset Type : "+assetList.get(i).getStrAssetType());}

 

 

List<AssetDetails> assetListByType = getAssetListByType("Laptop Assets",strAuthKey, schema);

 for(int i=0;i<assetListByType.size();i++){

System.out.println("Asset ID : "+assetListByType.get(i).getNAssetID());

System.out.println("Asset Number : "+assetListByType.get(i).getStrAssetNumber());

System.out.println("Asset Type : "+assetListByType.get(i).getStrAssetType());}

 

 

List<AssetDetails> assetListForUser = getAllocatedAssetList(nUserID,strAuthKey, schema);

  for(int i=0;i<assetListForUser.size();i++){

System.out.println("Asset ID : "+assetListForUser.get(i).getNAssetID());

System.out.println("Asset Number : "+assetListForUser.get(i).getStrAssetNumber());

System.out.println("Asset Type : "+assetListForUser.get(i).getStrAssetType());}

 

 

List<AssetDetails> assetListForUserByType = getAllocatedAssetListByType(nUserID,"Laptop Assets",strAuthKey, schema);

for(int i=0;i<assetListForUserByType.size();i++){

System.out.println("Asset ID "+assetListForUserByType.get(i).getNAssetID());

System.out.println("Asset Number : "+assetListForUserByType.get(i).getStrAssetNumber());

  System.out.println("Asset Type : "+assetListForUserByType.get(i).getStrAssetType());}

 

 

requestObj.setRecordTypeID(nRecordTypeID);

 

  

int nRecordTypeID = getRecordTypeID(nProjectID, "Major Incident",  strAuthKey, schema);

 

 

List<RecordTypeDetails> recordTypeList = getRecordTypeList(nProjectID, strAuthKey, schema);

for(int i=0;i<recordTypeList.size();i++){

System.out.println("Record Type ID : "+recordTypeList.get(i).getNRecordTypeID());

System.out.println("Record Type Name : "+recordTypeList.get(i).getStrRecordTypeName());}

 

 

requestObj.setUrgencyID(nUrgencyID);

 

 

 int nUrgencyID = getUrgencyID(nProjectID, "High", strAuthKey, schema);

 

 

List<UrgencyDetails> urgencyList = getUrgencyList(nProjectID, nServiceID, strAuthKey, schema);

for(int i=0;i<urgencyList.size();i++){

System.out.println("Urgency ID : "+urgencyList.get(i).getNUrgencyID());

System.out.println("Urgency Name : "+urgencyList.get(i).getStrUrgencyName());

System.out.println("Urgency Description : "+urgencyList.get(i).getStrUrgencyDescription());}

 

 

requestObj.setImpactID(nImpactID);

 

 

int nImpactID = getImpactID(nProjectID, "Medium", strAuthKey, schema);

 

 

List<ImpactDetails> impactList = getImpactList(nProjectID, nServiceID, strAuthKey, schema);

for(int i=0;i<impactList.size();i++){

System.out.println("Impact ID : "+impactList.get(i).getNImpactID());

System.out.println("Impact Name : "+impactList.get(i).getStrImpactName());

System.out.println("Impact Description : "+impactList.get(i).getStrImpactDescription());}

 

 

requestObj.setPriorityID(nPriorityID);

 

 

int nPriorityID = getPriorityID(nProjectID, "P1", strAuthKey, schema);

 

 

List<PriorityDetails> priorityList = getPriorityList(nProjectID, nServiceID, strAuthKey, schema);

for(int i=0;i<priorityList.size();i++){

System.out.println("Priority ID : "+priorityList.get(i).getNPriorityID());

System.out.println("Priority Name : "+priorityList.get(i).getStrProrityName());

System.out.println("Priority Description : "+priorityList.get(i).getStrPriorityDescription());}

 

 

 requestObj.setLocationID(nLocationID);

 

 

int nLocationID = getLocationID("India", strAuthKey, schema);

 

 

List<LocationDetails> locationList = getLocationList(strAuthKey, schema);

for(int i=0;i<locationList.size();i++){

System.out.println("Location ID : "+locationList.get(i).getNLocationID());

System.out.println("Location Name : "+locationList.get(i).getStrLocationName());}

 

 

requestObj.setDepartmentID(nDepartmentID);

 

 

int nDepartmentID = getDepartmentID("Engineering", strAuthKey, schema);

 

 

List<DepartmentDetails> departmentList = getDepartmentList(strAuthKey, schema);

for(int i=0;i<departmentList.size();i++){

System.out.println("Department ID : "+departmentList.get(i).getNDepartmentID());

System.out.println("Department Name : "+departmentList.get(i).getStrDepartmentName());}

 

 

requestObj.setSourceID(nSourceID);

 

 

int nSourceID = getSourceID(nProjectID, "E-mail", strAuthKey, schema);

 

 

List<SourceDetails> sourceList = getSourceList(nProjectID, strAuthKey, schema);

for(int i=0;i<sourceList.size();i++){

System.out.println("Source ID : "+sourceList.get(i).getNSourceID());

System.out.println("Source Name : "+sourceList.get(i).getStrSourceName());

System.out.println("Source Description : "+sourceList.get(i).getStrSourceDescription());}

 

 

requestObj.setWorkGroupID(nWorkGroupID);

 

 

int nWorkGroupID = getWorkGroupID(nProjectID, "Desktop Group",strAuthKey, schema);

 

 

List<WorkGroupDetails> workGroupList = getWorkGroupList(nProjectID, strAuthKey, schema);

for(int i=0;i<workGroupList.size();i++){

System.out.println("Work Group ID : "+workGroupList.get(i).getNWorkGroupID());

System.out.println("Work Group Name : "+workGroupList.get(i).getStrWorkGroupName());

System.out.println("Work Group Description : "+workGroupList.get(i).getStrWorkGroupDescription()); }

 

Steps for defining additional fields for the ticket

 

Get the custom field list based on project or service or category or sub category or state.

 

List<CustomFieldDetails> customFieldList = getCustomFieldsList(nProjectID, strAuthKey, schema);

for(int i=0;i<customFieldList.size();i++){

System.out.println("Custom Field ID : "+customFieldList.get(i).getNCustomFieldID());

System.out.println("Custom Field Name : "+customFieldList.get(i).getStrCustomFieldDisplayName());}

 

 

List<CustomFieldDetails> customFieldListService = getCustomFieldsListService(nProjectID,nServiceID, strAuthKey, schema);

for(int i=0;i<customFieldListService.size();i++){

System.out.println("Custom Field ID : "+customFieldListService.get(i).getNCustomFieldID());

System.out.println("Custom Field Name : "+customFieldListService.get(i).getStrCustomFieldDisplayName());}

 

 

List<CustomFieldDetails> customFieldListCategory = getCustomFieldsListCategory(nProjectID,nServiceID,nCategoryID,nSubCategoryID, strAuthKey, schema);

for(int i=0;i<customFieldListCategory.size();i++){

System.out.println("Custom Field ID : "+customFieldListCategory.get(i).getNCustomFieldID());

System.out.println("Custom Field Name : "+customFieldListCategory.get(i).getStrCustomFieldDisplayName());}

 

 

List<CustomFieldDetails> customFieldListState = getCustomFieldsListState(nProjectID, nServiceID, nCategoryID, nSubCategoryID, nStateID, strAuthKey, schema);

for(int i=0;i<customFieldListState.size();i++){

System.out.println("Custom Field ID : "+customFieldListState.get(i).getNCustomFieldID());

System.out.println("Custom Field Name : "+customFieldListState.get(i).getStrCustomFieldDisplayName());}

 

 

int nAdditionalFieldID = getAdditionalFieldID(nProjectID, "Error Code", strAuthKey, schema);

int nAdditionalFieldID1 = getAdditionalFieldID(nProjectID, "Symptoms", strAuthKey, schema);

 

 

List customFieldListData = new ArrayList<CustomFieldData>();

 

 

 

CustomFieldData customFieldsData = new CustomFieldData();

customFieldsData.setNCustomFieldID(nAdditionalFieldID);

customFieldsData.setStrCustomFieldData("93");

 

// Adding the additional field data object into the list

 

customFieldListData.add(customFieldsData);

 

 

 

customFieldsData.setNCustomFieldID(nAdditionalFieldID1);

customFieldsData.setStrCustomFieldData("Laptop battery is not getting charged.");

 

//Adding the object into the list.

 

customFieldListData.add(customFieldsData);

 

customFieldsData list contains data of the additional fields of this ticket

 

To define additional fields for this ticket, the above list of data should be converted into string format.

The below method is provided to convert the list of additional fields into string format.

 

 

String strCustomFieldData = getCustomFieldData(customFieldListData, strAuthKey, schema);

 

 

requestObj.setAdditionalParams(strCustomFieldData);

 

Defining the ticket parameters is done and now the ticket needs to be created. Ticket can be created by calling ‘createRequest’ method which takes input as RemoteRequest object which contains all the ticket parameter’s data.

 

 

RemoteRequest returnedRequest = createRequest(request, strAuthKey, schema);

 

Calling ‘RemoteRequest’ method, returns ‘RemoteRequest' object which contains the information: created ticket’s problem ID , request ID and error message.

 

if(returnedRequest!= null){

      //Get problem id of the generated ticket.

int nReturnedProblemID = returnedRequest.getProblemID();

//Get request id of the generated ticket.

String strReturnedRequestID = returnedRequest.getRequestID();

if(nReturnedProblemID == 0){

      //Print error occurred if the ticket creation is failed

System.out.println("Ticket submission failed with following error message :: "+ returnedRequest.getErrorMessage());

}else{

System.out.println("Ticket submitted successfully. RequestID :: "+strReturnedRequestID);

}

}else{

System.out.println("Ticket Submission got failed");

}

Attach a file to the ticket

Step1: Define Database Schema

Refer Step 1

 

Step 2: Get the authentication key of the user who is going to create the ticket by providing user name and password

Refer Step 2

 

Step3: Set the filename and file path to upload like below:

  

String filePath="C:\\Users\\tkdadmin\\Desktop\\usefull.txt";

String fileName="usefull.txt";

 

where file Path is the path of the file which we want to upload and filename is the name of the file.

 

Step4: Get ID of the project based on project name

 

int nProjectID = getProjectID("Incident Management", strAuthKey, schema);

 

Step5: Get problemID based on RequestID and ProjectID

 

int nProblemID = getProblemID(nProjectID, "INC-00287", strAuthKey, schema);

 

   Step6: Set the accessType for attachment (0-public 1-private)

      

int aceessType=1;

 

step7: Set the comment for an attachment

      

String comment="write comment here";

 

Step8: Get the current state of the ticket

 

StateDetails stateName=getCurrentStatus(nProblemID, strAuthKey, schema);

String strCurrentStateName=stateName.getStrStateName();

int nstateID=getStateID(nProjectID,strCurrentStateName,strAuthKey, schema);

 

Step9: Get the logged-in userID using username

         

int nUserID = getUserIDByLoginID("System ", strAuthKey, schema);

 

Step10: To Upload in web service, use ReceiveFileServlet in web service

      

UPLOAD_URL="http://<ServerIPAddress>/ITSMWS/ReceiveFileServlet ";

   BUFFER_SIZE = 4096;

 

// creates a HTTP connection

         URL url = new URL(UPLOAD_URL);

HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();

     httpConn.setUseCaches(false);
     httpConn.setDoOutput(true);
     httpConn.setRequestMethod("POST");
  

// sets file name as a HTTP header

     httpConn.setRequestProperty("fileName", uploadFile.getName());
     httpConn.setRequestProperty("strAuthKey",strAuthKey);
     httpConn.setRequestProperty("schema",schema);

 httpConn.setRequestProperty("problemID",String.valueOf(nProblemID ));

     httpConn.setRequestProperty("filePath",filePath);
     httpConn.setRequestProperty("stateID",String.valueOf(nstateID ));
     httpConn.setRequestProperty("userID",String.valueOf(nUserID ));
     httpConn.setRequestProperty("comment",comment);
     httpConn.setRequestProperty("access",String.valueOf(aceessType));

       

 // opens output stream of the HTTP connection for writing data

        OutputStream outputStream = httpConn.getOutputStream();

  

// Opens input stream of the file for reading data

        FileInputStream inputStream = new FileInputStream(uploadFile);
    byte[] buffer = new byte[BUFFER_SIZE];
    int bytesRead = -1;
    while ((bytesRead = inputStream.read(buffer)) != -1) {
    outputStream.write(buffer, 0, bytesRead);
    }
    outputStream.close();
    inputStream.close();

     

  // always check HTTP response code from server

        int responseCode = httpConn.getResponseCode();
    if (responseCode == HttpURLConnection.HTTP_OK) {

     

   // reads server's response

          BufferedReader reader = new BufferedReader(new InputStreamReader(
     httpConn.getInputStream()));
     String response = reader.readLine();
     System.out.println("Server's response: " + response);
     } else {
     System.out.println("Server returned non-OK code: " + responseCode);
     }

If file upload is done successfully then you will get the UPLOAD DONE message.

 

Note: Attachment should be done after creating the ticket

Delegation Configuration

Step1: Define Database Schema

Refer Step 1

 

Step 2: Get the authentication key of the user who is going to create the ticket by providing user name and password

Refer Step 2

 

  Step3: Get ID of the project based on project name

    intnProjectID = getProjectID("Incident Management", strAuthKey, schema);

 

Step4: Set the type of delegation, i.e. whether you want to delegate to Technician or Approval manager. Here 1-Technician 2-Approval manager.

intnType=2;

 

Step5: Just to understand whether we are listing technicians or approval managers

 

String strType="";

if(nType==1){

strType="Technicians";

}else{

strType="Approval Mangers";

}

 

Step 6: Set the "delegated from"

 

String loggedUser="System";

 

Note: Here we are setting the login name and not the full name.

 

Step7: List the technicians or approval managers present in the particular project

 

String techniciansORApprovalManagers=listTechniciansORApprovalManagers

(nProjectID ,nType ,strAuthKey,  schema);

String[] array=techniciansORApprovalManagers.split(",");

System.out.println("List of "+strType+" are as follows:");

System.out.println("");

for(String str:array){

System.out.println(str);

}

Step8: Set the particular technician or approval managers you want to delegate

 

String strName="Administrator";

 

Step9: Get userID from full name

 

 intnUserID = getUserID(strName, strAuthKey, schema);

 

Step10: Set the start time for delegation in the format yyyy-mm-ddhh:mm:ss

Example: 2015-09-22 17:33:00

String startTime="2015-09-23 18:00:00";

 

Step11: Set the end time for delegation in the format yyyy-mm-ddhh:mm:ss

Example: 2015-09-23 17:17:00

 

Step12: Call delegation configuration method from webservice which returns the message

 

String message=delegationConfiguration(nUserID, startTime, endTime,nProjectID,nType, loggedUser,strAuthKey,  schema);

System.out.println(message);

 

Note: If delegation is configured then you will get the message "Delegation is configured Successfully..."

otherwise you will get the message with reason for the failure