Webservices for use on CITSmart

This document is intended to provide guidance regarding the Web Services made available for integration with CTSmart ITSM Service Management.

Web Services have been created in CTSmart 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 contains 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 error.

Actions

Create a Ticket

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

Creating a Request /Incident

    {"Synchronize": true, 
    "sourceRequest": {"numberOrigin": "9999", 
    "type": "R", 
    "userID": " 61 84460708 ",
    " email ":" [email protected] ",
    " department ":" Department of the So-and-so ",
    " name ":" So-and-so "},
    " description ":" REST v3 ",
    " service ": {" name ":" SERVICE.TEST.1 ",
    " category ": {" name ":" Category 1 "}},
    " contractID ":" 1 ",
    " urgency " : "H", 
    "impact": "H"}
    }
    Assuming that the platform attribute in the login was informed by user and considering the synchronize attribute equal to true, the CITSmart will:
      - Check if there is an FROM-TO of contract 1 for the "user";
      - Include the applicant in the user registry, if it does not exist in the database;
      - Include the service in the service catalog of contract 1, if it does not exist in the database and register the service FROM-TO for the client;
      - Include request with source number 9999;
      - Register the DEPUT from the 9999 source request to the client.

Change ticket information (create)

Changing Information from Requests/Incidents

    {"Synchronize": true,
    "request": {"numberOrigin": "9999",
    "userID": "ciclano.de.tal",
    "contact": {"phoneNumber": "61 84460709",
    "email" "Cyclone",
    "name": "Cyclone of such"},
    "description": "Inclusion of request using REST v3 - Changed",
    "[email protected]",
    "department" "Service": {"name": "SERVICO.TESTE.2",
    "category": {"name": "Category 2"}}}}
   
    Assuming that the platform attribute in the login was informed by "user" and considering the synchronize attribute equal to true, the CITSmart will:
        Include the applicant in the user registry, if it does not exist in the database;
        Include the service in the service catalog of contract 1, if it does not exist in the database and register the service FROM-TO for the client;
        Change the requestor and service from the request with source number 9999.

Change ticket status (updateStatus)

Changing the Status of an Incidents/Requests

    Go to the WebService Operation screen and configure with the group authorized to execute this web service request_updateStatus
    Go to the WebService Operation screen and set the default justification ID parameter to change the situation, with the code for an activity suspension reason. The user can perform the command: 
    select * from justificativasolicitacao
    To get the code to be informed in the parameter described above.

Consult Requester's tickets (getByUser)

Inquire the applicant's Incidents and Requests

    {"userID": "john elliot ",
    "startDate": "2015-09-16T03:00:00.000Z",
    "endDate": "2015-09-19T03:00:00.000Z"}

Datails of ticket applicant

Details of The Request/Incident

    {"numberOrigin":"9999"}

Include occurrence in ticket

Include an occourrence on a Request

        {"requestNumberOrigin": "9999",
        "occurrence": {"description": "Occurrence test","category": {"code": "Workaround solution"},
        "date": "2015-08-20T03:00:00.000Z",
        "hour": "2219"}}

Query ticket occurences

Querying Information from Requests/Incidents

    {"requestNumberOrigin":"9999"}

Listing tickets to be attended

This webservice should be used to 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

	" id " – Response that returns the requester code found by the search;
	“name” - Response that returns the requester's name;
	"email" – Response that returns the requester's email address;
	“Unit” – Response that returns
    	Id: Unit code;
        Name: Unit name;
    “places” – Response that returns:
    	Id: Location code;
    	Name: Location name;
    “phone” – Response that returns the requester's phone number;
    •	"id" – Response that returns the ticket number;
    •	“tipo” - Response that returns the type of demand, that is, if it is a Request (R), Incident (I) or Procedure (P);
    •	"nomePrioridade" – Response that returns the Priority name given to the ticket;
    •	“solicitacao” – Response that returns the description of the requested activity;
    •	“tarefa” – Response that returns the task of the flow that is the ticket;
    •	“status” – Response that returns the status of the listed ticket task;
    •	“dataLimite” – Response that returns the service request closing date and time according to the SLA and calendar linked to the activityxcontract
    •	“statusFluxoNome” - Response that returns the status of the SLA, which can be: Normal, To be expired, Expired, Suspended.
    Example of valid response of the webservice
    "code": "200",
    "message": "Request processed successfully",
    "payload":{
    "initialNumber": 1,
    "lastPage": 1.0,
    "finalNumber": 20,
    "totalRequests": 168,
    "result":
    [
    "id": 1251,
    "tipo": "Incident",
    "nomePrioridade": "Medium",
    "solicitacao": "Incident",
    "tarefa": "Attend request",
    "status": "NORMAL",
    "dataLimite": "2020-06-09 09:18:00 AM UTC"
    ]
    }

Saving ticket in progress

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

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

    {
    	"status": "SUCCESS", 
	"code": "200", 
	"message": "Request processed successfully", 
	"payload": {
		"idGrupoAtual": 171, 
		"idTarefa": 8809, 
		"idStatus": 1, 
		"status": "In Progress", 
		"dataHoraInicio": "2020-09-10 11:58:28 AM BRT", 
		"dataHoraInicioSLA": "2020-09-10 11:58:29 AM BRT", 
		"dataHoraLimite": "2020-09-10 17:08:00 PM BRT", 
		"dataHoraSolicitacao": "2020-09-10 11:58:28 AM BRT", 
		"descricao": "<div>test</div>", 
		"idCategoriaSolucao": 13, 
		"idCausaIncidente": 7, 
		"idContrato": 52, 
		"idServico": 670, 
		"idSolicitacaoServico": 5712, 
		"idSolicitante": 456, 
		"idUnidade": 2, 
		"impacto": "A", 
		"resposta": "Recording test via webservice", 
		"siglaGrupo": "LEVEL1", 
		"tarefa": "Answer Ticket", 
		"urgencia": "A", 
		"idUsuarioResponsavelAtual": 254,
		"nomeGrupoAtual": "Level 1", 
		"solicitanteVip": false
	}  
    }

Receive Units

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

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

Receive Units

    •	id:  Returns the unit code;
    •	name: Returns the unit description;
    Example of webservice output
    {
        "status": "SUCCESS",
        "code": "200",
        "message": "Request processed successfully",
        "payload": [
            {
                "id": 52,
                "name": "---Human Resourcer"
            }
        ]
    }

Receive justification for suspension

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

Preconditions: The user who is passed on the webservice 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 webservice must be used to return the options allowed in the flow in a given group.

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

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

List tickets to be attended

    •	"id" – Response that returns the ticket number;
    •	“type” - Response that returns the type of demand, that is, if it's a Request (R), Incident (I) or Procedure (P);
    •	"namePriority" – Response that returns the Priority name given to the ticket;
    •	“request” – Response that returns the description of the requested activity;
    •	“task” – Response that returns the task of the flow that is the ticket;
    •	“status” – Response that returns the status of the listed ticket task;
    •	“dataLimite” – Response that returns the service request closing date and time according to the SLA and calendar linked to the activityxcontract
    •	“statusFlowName” - Response that returns the status of the SLA, which can be: Normal, To Be Expired, Expired, Suspended.
    Example of a valid webservice response
    "code": "200",
    "message": "Request processed successfully",
    "payload":{
    "initialNumber": 1,
    "lastPage": 1.0,
    "finalNumber": 20,
    "totalRequests": 168,
    "result":
    [
    "id": 1251,
    "type": "Incident",
    "namePriority": "Medium",
    "request": "Service of Incident",
    "task": "Attend request",
    "status": "NORMAL",
    "dataLimite": "2020-06-09 09:18:00 AM UTC"
    ]
    }

Receive user actions on a ticket

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

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

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

Receive user actions on a ticket

    •	"id:  Flow action code registered in the flow design;
    •	Name: Flow action name;
    •	Description: Description of the flow action;
    •	requiresReason: Inform whether the reason is mandatory, there are two responses to this attribute:
        o	True: When the reason is mandatory;
        o	False: When the reason is not mandatory;
    •	approvalActionId: Returns the approval response code;
    •	ticketStatusId: Returns the ticket status code;
    {
        "status": "SUCCESS",
        "code": "200",
        "message": "Request processed successfully",
        "payload": [
            {
                "id": 1302,
                "name": "ApproveTicket",
                "description": "Approve Ticket",
                "requiresReason": false,
                "approvalActionId": 1,
                "ticketStatusId": 1
            },
            {
                "id": 1304,
                "name": "DenyTicket",
                "description": "Deny Ticket",
                "requiresReason": false,
                "approvalActionId": 2,
                "ticketStatusId": 3
            }
        ]
    }

List ticket attachments

This webservice must be used to return the list of attachments of a ticket to be assisted by the analysts.

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

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

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

List tickets attachment

    •	authentication-token: Attribute that receives the application access token:
        o	The token must be put in the header;
    •	serviceRequestIncidentId: Mandatory attribute that receives the ticket number;
        o	The ticket number must be passed in the path, next to the URL;
    Example of webservice input
    {
        Not applicable, note that the input attributes are in the header and in the Path of the url.
    }

Download ticket attachments

    The attachment itself
    Example of a valid webservice response
    {
        Not applicable   
    }

Upload ticket attachments

    •	dateTime: Mandatory attribute indicating date and time of execution;
    •	dateTimeMilliseconds: Hour in milliseconds;
    •	operationID: Number of the operation that was performed;
    •	error: Mandatory attribute that indicates if there was an error while running the webservice;
    Example of a valid webservice response
    {
        "dateTime": "2020-05-19 14:56:00",
        "dateTimeMilliseconds": 1589910960717,
        "operationID": 603,
        "error": null
    }

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

    •	" status " – Response that returns service status;
    •	“code” - Response with the return code;
    •	" message " – Response that displays the return code message;
    •	“payload” – Answer that presents: idBaseKnowledge and title;

    Example of a valid webservice response
    {
    "status": "SUCCESS",
    "code": "200",
    "message": "Request processed successfully",
    "payload": [
        {
            "idBaseConhecimento": 555,
            "titulo": "Applications instalation"
        }

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

Delet ticket attachments

    •	" status " – Response that returns service status;
    •	“code” - Response with the return code;
    •	" message " – Response that displays the return code message;
    “payload” – Response which presents: título, contente, version, totalLike, totalUnlike, liked, unliked, userCreated, lastPublicationDate, userUpdated, attachments
    Example of a valid webservice response
    {
        "status": "SUCCESS",
        "code": "200",
        "message": "Request processed successfully",
        "payload": {
            "title": "Applications instalation",
            "content": "<p>Applications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalationApplications instalation</p>\n",
            "version": "1.0",
            "totalLike": 1,
            "totalUnlike": 0,
            "liked": false,
            "unliked": false,
            "userCreated": "Consultant",
            "lastPublicationDate": "2020-04-01 06:22:14 AM BRT",
            "userUpdated": "Vinny Gravito",
            "attachments": [
                {
                    "id": 606,
                    "name": "App instalation.pdf",
                    "extension": "pdf"
                }
            ]
        }
    }

Attachments download

Delet tickets attachments

        •	authentication-token: Mandatory attribute that receives the login authentication code
        •	knowledgeBaseId: Attribute that receives the ticket number
        Example of webservice entry
            {
	        " authentication-token: ": " eyJhbGciOiJIUzUxMiJ9.eyJleHAiOjE2MDgxNDk2MjcsIm5hbWUiOiJDbGllbnRPbmUiLCJjb250cm9sIjoiN2IyMjY5NzAyMjNhMjIzMTM4MzkyZTM2MmUzMzM1MmUzMjMwMzIyMjJjMjI2ODZmNzM3NDIyM2EyMjMxMzgzOTJlMzYyZTMzMzUyZTMyMzAzMjIyN2QiLCJpc3N1ZWRBdCI6MTYwODE0NjAyNzIzNCwibG9jYWxlIjoiZW4iLCJjbGllbnRfaWQiOiJ1bmtub3duIiwidGltZW91dCI6MzYwMCwidXNlcm5hbWUiOiJjbGllbnQwMSJ9.zEfN_lP00Hgtp5ojWtMuIiqinxxnKs9VZY28tEPQskGUbYdIb9GXH33sjPYxrD-v9BRocDuDZoi7M6uMleGefQ",
            }

Sending likes and Dislikes

Delet 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