Introduction to ITSM functions 

Chatbot functions allow chatbots to create and edit ESM data, and also allow more complex logic with customized configuration.

Functions are used by the chatbots of Efecte Chat to create tickets and chat session data cards in ESM, as well as update them. Functions can have values that are always the same depending on the ESM configuration, for example you can set for which template are data cards created with. However, it is also possibilities to set values for ESM data cards “on the fly”, when calling for the function. This allows the same function to be used in different ways, for example to create incidents with one category in one scenario, and using a different category in another scenario.

Functions in existing environments are not automatically updated when changes or new functions are introduced. Introducing any changes to functions in already existing environments requires involving professional services.

Efecte Chat for Service Management contains at the moment following functions:

1. CreateTicket

Description

The main purpose of this function is to create a ticket on the ESM side. You can use this function at any time in the scenario, it's up to you whether you want to create a ticket at the beginning of the user's conversation with the chatbot [1] or only at the end. To add this function to a scenario, add a new block in the scenario editor, select Function Block, and then select the appropriate one from the list. An additional menu will be displayed on the right side [2], there you must enter the subject of the ticket that is sent to ESM and the id of the next block to which the function is to go after the task is completed. More information on creating scenarios can be found in the guide.

Function Settings

For the function to work properly, go to the Functions tab, then select the appropriate one from the list and click the Edit button. The most important settings are in the Config object [1] field, where you should modify the variables in accordance with the ESM settings.

"API_URL" - adjust the URL with following details

• environment URL, e.g. “https://newenvironment.efectecloud.com”  - do NOT replace full URL with only the environment URL!
• correct ESM folder code, e.g. “incident_management”
• the full setting of API_URL should always look like this:  
• "API_URL": "https://newenvironment.efectecloud.com/api/itsm/dataCardImport.ws?folderCode=incident_management&createEmptyReferences=true&includeIDs=true",
   

"resHistoryPath" - this is the path to the history of conversations, do not make any changes in this field!

"ticketURL" - here you should also set the correct address of your environment from ESM, as above in API_URL, without changing rest of the URL

"auth" - authorization code, created on the basis of login data. It will be provided by our Support, in case of any changes of login details, please contact support to update the code.

2. UpdateTicket

Description:

The main task of the function is to apply changes to an existing ticket. We can use this function at the end of the scenario to modify the status of a given request, e.g. if the user, after going through the scenario, solves his problem, we are able to automatically change the status of such a request from "new" to "solved" or another depending on business requirements.

We can also modify the status of the created ticket after a failed attempt to connect to the agent.

Please note that the UpdateTicket function only works in conjunction with the CreateTicket function.

With the help of this function, you can change an existing ticket status or cancel a previously created ticket.

The scenario of using the UpdateTicket function can look like following:

1. CreateTicket function - here, at the very beginning of the scenario, we automatically create a ticket in ESM, together with the title (as indicated in the CreateTicket description)
2. Problem solving path - we can add several branches depending on how the problem is solved and its complexity. At the end of the scenario, we want to know what the result is, so it is necessary to prepare a summary question. The result will be used to determine the next step.
3. Scenario after selecting “No, I still have issues” - if the problem still exists, we can display further steps, e.g. cancel the ticket or connect with the agent.
4. Cancel this ticket - to cancel the ticket, you should embed the "UpdateTicket" function here and add attribute settings: type and address of the next block to which the function will go after the task is completed.
5. Update the ticket - we can also add additional information to an existing ticket, e.g. if there are no agents available at the moment, and we want to describe our problem, we can also use the UpdateTicket function to send information with a description of our problem.

{
  "type": "Cancel",
  "nextChild": "statement-c4678291"
}

6. In case the problem has been solved and our user selects “yes”, using the same “UpdateTicket” function we can automatically change the status of our ticket to “resolved”. In this case, in the settings, you only need to enter the address of the next block to which you want to go.

In order for the function to work properly, the following parameters must be entered in the function settings:

Function Settings:

Similarly to the settings of the "CreateTicket" function described above in the first point, here you also need to provide the API_URL of your ESM environment and authorization. This data should be the same as in the "CreateTicket" function. The only change is in the “mainScriptId” attribute, here you should enter the ID of our Main Menu block (you will find it in the URL by editing the story ♻️ Main Menu)

{
  "API_URL": "https://example.env.from.esm.com/api/itsm/dataCardImport.ws?folderCode=incident_management&updateDataCards=true&createDataCards=false",
 "auth": "Basic XXXXXXXXaaaa1122233bbbcccdddeeefffXXXXXXXX",
 "mainScriptId": 45177
}

Supported parameters:
{
"type": "Cancel",
"type": "Description"
}

3. CreateTicketFromForm

Description:
 

CreateTicketFromForm function is used to create a ticket in ESM based on a form filled in by the user. To facilitate the process of sending tickets, we have created a form in our Chatbot containing two fields “Subject” and “Description”. Based on this data and your information, we can create a ticket in ESM. Tickets created in this way cannot be edited from the Chatbot level, but if the user connects to the agent on Live Chat, all his current tickets created using the Chatbot will be visible in the agent.widget window.

1. To be able to use this function, we need to define our form in the first step. By default, two attributes "Subject" and "Description" are set, such variables will be sent to ESM (it is possible to extend this function with new variables, for this purpose contact PS Team InteliWISE)
2. Form cancellation script. Responsible for displaying the form cancellation message and possible next steps, in this case the "Back to menu" button
3. “CreateTicketFromForm” function - based on the data from the form and user data, a ticket will be created automatically. After successfully creating a ticket, the user will automatically receive a message with the incident number. This function does not require defining any additional parameters.

Function Settings:

Similarly to the settings of the previous functions, here you should also provide the appropriate API_URL, ticket_URL, auth and enter the ID of the “MainMenu” script

{
 "API_URL": "https://example.env.from.esm.com/api/itsm/dataCardImport.ws?folderCode=incident_management&createEmptyReferences=true&includeIDs=true",
 "resHistoryPath": "https://rail-webfront.app.inteliwi.se/channels/history?channelUid=",
 "ticketURL": "https://example.url.from.esm.com/itsm/EfecteFrameset.do#/workspace/datacard/view/",
 "auth": "Basic XXXXXXXXaaaa1122233bbbcccdddeeefffXXXXXXXX",
 "mainScriptId": 45177
}

4. CreateChatSession

Description:

The main task of this function is to create a data_card responsible for collecting information about the user's conversation history with Chatbot and agents. Based on the information sent by this function, the agent can check the history of conversations with a given user. We can also use the collected data for various types of analyzes and preparation of reports on the use of a given functionality. The block with the function should be inserted into the Live chat scenario as indicated in the graphic below

1. “CreateChatSession” function script
2. Opening a connection with the Agent

Function Settings:

Similarly to the other functions, in the "Config object" field, you should enter the appropriate values API_URL and auth.

{
 "API_URL": "https://example.env.from.esm.com/api/itsm/dataCardImport.ws?folderCode=chat_sessions",
 "resHistoryPath": "https://rail-webfront.app.inteliwi.se/channels/history?channelUid=",
 "auth": "Basic XXXXXXXXaaa111222333dddfffggXXXXXXXX"
}

ITAM functions (QR-code):

1. RequestEsmData

Based on the functions of the Efecte platform, delivered in R1_23, we can send various variables in the URL. Using this functionality of the platform, we can easily add the attribute of our choice to the address of the client's environment (link to ESS). Then, using all data from custom_data, we are able to prepare a request to the ESM platform to send detailed information related to the user or any attribute stored on the data card on ESM.

2. CreateIncident

The function is detailed in ITSM functions.

An example httpBody variable from the createIncident function containing selected attributes:

const httpBody = `<entityset>
<entity>
<template code="\${efecteChat.integration.deviceIncident.templateCode}"/>
<group code="\${efecteChat.integration.ticket.folderCode}"/>
<attribute code="\${efecteChat.integration.deviceIncident.subject.attributeCode}">
<value>${subject}</value>
</attribute>
<attribute code="\${efecteChat.integration.deviceIncident.description.attributeCode}">
<value>${description}</value>
</attribute>
<attribute code="\${efecteChat.integration.deviceIncident.customer.attributeCode}">
<value>${customData.clientData.externalId}</value>
</attribute>
<attribute code="\${efecteChat.integration.deviceIncident.contactType.attributeCode}">
<value code="\${efecteChat.integration.deviceIncident.contactType.chatbot.valueCode}">ignored</value>
</attribute>
<attribute code="\${efecteChat.integration.deviceIncident.affectedDevice.attributeCode}">
<value>${vars.efecteID}</value>
</attribute>
</entity>

3. CreateRequest

Using the function, we can create various requests from standard incidents, service requests to our own custom requests. The createRequest function is such an example. By modifying only the httpBody variable inside the function, we can send a given type of request.

An example httpBody variable from the crateRequest function containing selected attributes:

const httpBody = `<entityset>
<entity>
<template code="\${efecteChat.integration.ticket.templateCode}"/>
<group code="\${efecteChat.integration.ticket.folderCode}"/>
<attribute code="\${efecteChat.integration.ticket.customer.attributeCode}">
<value>${customData.clientData.externalId}</value>
</attribute>
<attribute code="\${efecteChat.integration.ticket.contactType.attributeCode}">
<value code="\${efecteChat.integration.ticket.contactType.chatbot.valueCode}">ignored</value>
</attribute>
<attribute code="\${efecteChat.integration.ticket.chatSessionId.attributeCode}">
<value>${request.body.sessionId}</value>
</attribute>
<attribute code="\${efecteChat.integration.ticket.subject.attributeCode}">
<value>${params.scriptNode.functionParams.subject}</value>
</attribute>
</entity>

4. SendEsmDataMessage

Using the data collected by the requestEsmData function, we can dynamically generate a message containing data from the ESM (information about the user, a given device or other data downloaded from data_card). We can also generate buttons in the Chatbot that can link to any place (articles in the ESM knowledge base, data downloaded from the User Guide or external links).

Remember that all functions described here must be configured in accordance with the instructions described in the section ITSM functions -> createTicket

The applications of the above functions are very wide, for ease of use, we have described one of the projects using the described functions.

An example of using this function is a project prepared for one of our clients to recognize a device using a QR code placed on a given device. After scanning the QR code, the user logs in to ESS. The user is automatically redirected to the Chatbot, where they can find all the necessary information about the device. In the next step, the user can report an incident or send a service request related to the recognized device. All necessary data, such as user and affected device, are automatically added as ticket attributes. The agent who handles the ticket has all the necessary information at once.

Effie AI Chat

GPT_RequestEsmData:

Description:

The Effie AI chat integration with ChatGPT involves passing additional data from the ESM person_data_card along with the conversation history. The data we want to send must be included in the function as attributes. Then, the model analyzes the presented question and based on the context of the conversation and the data sent, it is able to provide an accurate answer. This integration extends the model's capabilities. The function also allows for sending only the end-user's question and generating an answer based on it, without any additional data. Such an approach limits the model's capabilities, but in this case, no ESM data is transmitted.

What include:

1. declaration of a function that creates a class with methods parsing xml to json and assigning it to the XMLParser variable
2. declaration of a function parsing the data received from the ESM to a user object - parseUserData(data)
3. declaration of a function parsing the data received from the ESM to an array of the user's 5 most recent incidents
4. declaration of enum types: MessageButtonType and PostbackType
5. creation of variables: preparedAnswer (extracted from request.body.params), parser (an instance of the XMLParser class with an attribute {ignoreAttributes: false}), externalID
6. extraction of the object where the 'type' key has the value 'CUSTOM_DATA' by sending a request to the address "https://rail-webfront.app.inteliwi.se/channels/history?channelUid=" + uid (params.channelUid). When we receive the above object, the value of the 'externalId' key (customData.clientData.externalId) is extracted from it and assigned to the externalID variable, if it does not find such a key, it returns information about not recognizing it and displays the 'Back' button
7. extraction of user data from the ESM by sending a request to the address ".../api/itsm/search.ws?query=SELECT DISTINCT $first_name$,$workstations:workstation_model$, $mobile_devices:mobile_device_model$ FROM entity WHERE entity.template.code = 'person' AND $email$ =" + externalID, then we parse the received xml data with the function parseUserData
8. extraction of data about the user's incidents by sending a request to the address ".../api/itsm/search.ws?query=SELECT $subject$, $status$, $description$, $created$, $updated$ FROM entity WHERE entity.template.code = 'incident' AND $customer_email$ ="," + externalID + 'ORDER BY $updated$ DESC', then we parse the received xml data with the function parseUserIncidents
9. in the success object, we send a customData object with the value { user } and run the next block in the scenario.