Webservices for use on CITSmart

32 min

This document is intended to guide the Web Services made available for integration with CITSmart ITSM Service Management.

Web Services have been created in CITSmart for inclusion, updating, consultation, and cancellation of service requests (incidents and requisitions).

Before getting started

Before any CITSmart REST operation is used, the user must be authenticated.

Authentication is done through the REST login operation in the URL /services/login, which receives a CtLogin object containing the username, password, and platform attributes.

The login operation returns an alphanumeric value in the SessionID attribute. This same SessionID must be used in the other REST calls. The returned object contains the code and description of the error in case of problems in executing the login operation.

The authenticated user composes the key for data synchronization when the synchronize attribute is set to true.

Request inclusion and update services rely on the synchronize attribute. When this attribute is true, the user registration and catalog services are automatically created or updated in CITSmart from the information sent in the Web Service request.

✅ Rule:

All REST services created in CITSmart receive an input object and return an object. In case of error, the return object contains the code and description of the error. When there is no error, in addition to the attributes defined for each service, the return object has the date and time of execution and the id of the operation. CITSmart ensures that every request is recorded in its database and an operation ID is returned to the requester, even in case of an error.

Actions

Create a Ticket

Pre-conditions: configure the contracts, groups, flows, and permissions.

Creating a Request /Incident

    /services/request/create

Change ticket information (create)

Changing Information from Requests/Incidents

    /services/request/create

Change ticket status (updateStatus)

Changing the Status of an Incidents/Requests

    /services/request/updateStatus

Consult Requester's tickets (getByUser)

Inquire about the applicant's Incidents and Requests

    /services/request/getByUser

Details of ticket applicant

Details of The Request/Incident

    /services/request/getById

Include occurrence in ticket

Include an occurrence on a Request

    /services/request/createOccurrence

Query ticket occurrences

Querying Information from Requests/Incidents

    /services/request/listOccurrences

Listing tickets to be attended

This web service should list the users who can be requesters when opening a ticket.

Prerequisites: The requester must be linked to a group that is allowed to create in a workflow.

Listing requests/incidents to be attended

    /services/request/createOccurrence 
    /webmvc/servicerequestincident/searchTickets

Saving ticket in progress

This web service should be used to return tickets to the attended by the analysts.

Prerequisites: Have access to the system and permission of execution in the workflow.

    To only save the ticket: webmvc/servicerequestincident/save  
    To save and advance the ticket: webmvc/servicerequestincident/next

Receive Units

This web service must be used to return the existing active units in the system for selection when creating a ticket.

Preconditions: This web service changes results if parameter 61 - Link contracts to the unit (Eg.: Y or N) is active.

Receive Units

    webmvc/ v1/unit
    Method: GET
    Possible return codes
    200 – Successful request
    401 - Invalid authentication token or user without access to the resource
    404 – Justification not found

Receive justification for suspension

This web service must be used to return the justification for suspension registered and active in the system.

Preconditions: The user who is passed on the web service must have permission to suspend in the workflow.

Receive justification for suspension

    webmvc/v1/ticket/justification
    Method: GET
    Possible return codes
    200 – Successful request
    401 - Invalid authentication token or user without access to the resource
    404 – Justification not found

List tickets to be attended

This web service must be used to return the options allowed in the flow in a given group.

Preconditions: The user who is passed on the web service must have access to the system.

The user who is passed on the web service must have permission in the workflow.

List tickets to be attended

    /webmvc/v1/ticket/{ticketId}/permissions
    Method: GET
    Possible return codes
    200 – Successful request
    401 - Invalid authentication token or user without access to the resource
    404 – Ticket not found

Receive user actions on a ticket

This web service must be used to return user actions designed in a workflow.

Preconditions: The user who is passed on the web service must have access to the system.

The user who is passed on the web service must have permission to run in the workflow.

Receive user actions on a ticket

    webmvc/v1/ticket/{ticketId}/flow-actions
    Method: GET
    Possible return codes
    200 – Successful request
    401 - Invalid authentication token or user without access to the resource
    404 – Ticket not found
    Post condition:
    
To send the selected response in the user action, use the Save and Advance webservice (webmvc/servicerequestincident/next)
    Attributes:
    "flowAction": 
    "reasonFlowAction":

List ticket attachments

This web service must be used to return the list of ticket attachments to be assisted by the analysts.

Preconditions: The user who is passed on the web service must have access to the system.

Note: This document contains all the necessary web services for an attachment that includes:

List attachments of a ticket;
Download the attachment;
Attach documents to the ticket (upload);
Delete attachment of a ticket

List tickets attachment

    /webmvc/servicerequestincident/{serviceRequestIncidentId}/attachments
    Method type: GET
    Possible return codes
    200 – Successful request
    401 - Invalid authentication token or user without access to the resource
    404 - Ticket not found

Download ticket attachments

    webmvc/servicerequestincident/{serviceRequestIncidentId}/attachments/{documentId} 
    Method type: GET
    Possible return codes
    200 – Successful request
    401 - Invalid authentication token or user without access to the resource
    404 - Document or ticket not found

Upload ticket attachments

    /services/request/addAttachments 
    Method type: POST
    Preconditions:
    1.	Check the parameters:
    2.	44 - Upload directory repository path (Eg.: Windows - C:/temp)
    3.	278 - Maximum file size, in bytes, to upload. Default[1073741824] = 1GB
    4.	318 - List of file extensions that cannot be attached (For more than one extension, separate with a semicolon)
    5.	446 - Send attachments in the Ticket notification email? (Eg.: Y or N - Default: 'N')
    Possible return codes
    200 – Successful request
    500 – Mandatory fields not informed

Delete ticket attachments

    /webmvc/v1/ticket/{ticketId}/attachments/{documentId}
    Methode type: DELETE
    Possible return codes
    200 – Successful request
    401 - Invalid authentication token or user without access to the resource
    404 - Ticket not found

Filtrer knowledge

Delete ticket attachments

    /webmvc/v1/knowledge-base/indexed
    Type of method: Get
    Technical documentation: Link of swagger: /webmvc/swagger-ui.html#/Knowledge%20Base/searchUsingGET
    The presented webservice allows you to filter knowledge by title.
    Possible return codes:
    1.	200 Success
    2.	401 Invalid authentication
    3.	404 Ticket not found

Detail Knowledge, List Attachments, and View the amount of like and dislike in the knowledge

Delete the ticket attachments

    /webmvc/v1/knowledgebase/{knowledgeBaseId}
    Type of method: Get
    Technical documentation: /webmvc/swagger-ui.html#/Knowledge%20Base/findUsingGET
    The webservice presented allows you to view a knowledge, list its attachments and see the amount of likes and dislikes on its content.
    Possible return codes:
    1.	200 Success
    2.	401 Invalid authentication
    3.	404 Ticket not found

Attachments download

Delete the tickets attachments

        /webmvc/v1/knowledgebase/{knowledgeBaseId}/attachments/{documentId}
        Type of method: Get
        Technical documentation: Link of swagger: /webmvc/swagger-ui.html#/Knowledge%20Base/downloadAttachmentsUsingGET
        The presented webservice allows to download attachments listed in a knowledge.
        Possible return codes:
	        200 Success
	        401 Invalid authentication
	        404 Ticket not found

Sending likes and Dislikes

Delete the tickets attachments

        /webmvc/v1/knowledgebase/{knowledgeBaseId}/vote/{type}
        Type of method: Post
        Technical documentation: Link of swagger: /webmvc/swagger-ui.html#/Knowledge Base/voteUsingPOST
        The presented webservice allows to like and dislike a content of the knowledge portal
        Possible return codes:
	        200 Success
	        401 Invalid authentication
	        404 Ticket not found