Webservices for use on 4biz
This document is intended to provide guidance regarding the Web Services made available for integration with 4biz Service Management.
Web Services have been created in 4biz for inclusion, updating, consultation and cancellation of service requests (incidents and requisitions).
Before getting started
Before any 4biz 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 platform attribute must contain the ID of the site that is requesting the service.
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 4biz from the information sent in the Web Service request.
✅ Rule: All REST services created in 4biz receive an input object and return an object. In case of an 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.
4biz ensures that every request is recorded in its database and an operation ID is returned to the requester, even in case of error.
Actions
Criar um ticket (/servicerequestincident/create)
- Pré-condições: configurar os contratos, grupos, fluxos e permissões.
🖊 Nota: Para visualizar o título, o parâmetro 301 – Exibir título na solicitação serviço deverá estar habilitado.
O webservice apresentado abaixo cria um ticket para um usuário que possua cadastro no sistema.
Criando uma Requisição/Incidente:
{
"idGrupoAtual": 2,
"idTarefa": 4358,
"idStatus": 1,
"status": "Em Andamento",
"localidade": "Distrito Federal",
"dataHoraInicio": "2020-02-10 12:53:46 PM BRST",
"dataHoraInicioSLA": "2020-02-10 12:53:46 PM BRST",
"dataHoraLimite": "2020-02-12 12:53:00 PM BRST",
"dataHoraSolicitacao": "2020-02-10 12:53:46 PM BRST",
"descricao": "Teste de Criação de soiclitacao de serviço, via Webservice.",
"emailcontato": "[email protected]",
"idContrato": 1,
"idLocalidade": 1,
"idServico": 29,
"idSolicitacaoServico": 3604,
"idSolicitante": 3,
"idUnidade": 1,
"impacto": "B",
"nomecontato": "Consultor",
"nomeServico": "A navegação na internet está lenta",
"nomeTipoDemandaServico": "I",
"nomeUnidadeSolicitante": "Cidade Satelite",
"siglaGrupo": "SDNIVEL1",
"tarefa": "Aprovar",
"telefonecontato": "3242-4433",
"urgencia": "B",
"sla": "24:00",
"nomeGrupoAtual": "1º Nível"
}Change ticket information
Changing Information from Requests/Incidents
/services/request/createChange ticket status
Changing the Status of an Incidents/Requests
/services/request/updateStatusINQUIRE THE APPLICANT's INCIDENTS AND REQUESTS
Inquire the applicant's Incidents and Requests
/services/request/getByUserDetails of ticket applicant
Details of The Request/Incident:
/services/request/getByIdInclude occurrence in ticket
Include an occourrence on a Request:
/services/request/createOccurrenceQuery ticket occurences
Querying Information from Requests/Incidents:
/services/request/listOccurrencesListing tickets to be attended
This webservice should be used to list the users who can be requesters when opening a ticket.
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/searchTicketsSaving ticket in progress
This webservice should be used to return tickets to the be attended by the analysts.
It is necessary to 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/nextReceive Units
This webservice must be used to return the existing active units in the system for selection when creating a ticket.
This webservice 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 foundReceive justification for suspension
This webservice must be used to return the justification for suspension registered and active in the system.
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 foundList tickets to be attended
This webservice must be used to return the options allowed in the flow in a given group.
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
/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 foundReceive user actions on a ticket
This webservice must be used to return user actions designed in a workflow.
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
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 webservice must be used to return the list of attachments of a ticket to be assisted by the analysts.
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:
/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 foundDownload ticket attachments
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 foundUpload ticket attachments
Upload ticket attachments
/webmvc/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 informedDelete ticket attachments
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