# Plug-in de ação externa

Os seguintes tópicos são discutidos neste documento:

- [Sobre o Plug-in de Ação Externa](https://www.manageengine.com/br/service-desk/help/adminguide/api/external-action-plugin.html#ext%20act%20plug-in)
- [Integração com aplicativos de terceiros](https://www.manageengine.com/br/service-desk/help/adminguide/api/external-action-plugin.html#integ)
- [Configurando sua integração](https://www.manageengine.com/br/service-desk/help/adminguide/api/external-action-plugin.html#implement)
- [Operações de solicitação suportadas por padrão](https://www.manageengine.com/br/service-desk/help/adminguide/api/external-action-plugin.html#default%20req)
- [Integração padrão (integração com o JIRA)](https://www.manageengine.com/br/service-desk/help/adminguide/api/external-action-plugin.html#jira)

## Objetivo deste documento

Este documento fornece informações processuais para que desenvolvedores criem um plug-in e estabeleçam integração entre o ServiceDesk Plus e vários outros aplicativos de terceiros.

## Sobre o Plug-in de Ação Externa

Um fluxo de trabalho completo de solicitação exige que diferentes tarefas sejam executadas pela equipe de suporte. Ocasionalmente, a equipe de suporte pode envolver aplicativos de terceiros para realizar determinadas tarefas acessando os aplicativos em questão, o que pode exceder o limite do aplicativo.

Assim, para superar o processo trabalhoso de trazer aplicativos de terceiros para executar tarefas, como integração com rastreador de problemas, criação de conta no Active Directory e criação de nova conta de e-mail, você pode utilizar a opção Plug-in de Ação Externa no ServiceDesk Plus. Essa opção ajuda a equipe de suporte a realizar várias operações relacionadas a terceiros diretamente da página **Solicitações**, apenas clicando no menu **Ações**.

**Cenário:**

Considere uma organização que usa o ServiceDesk Plus para o suporte ao cliente e o JIRA para rastreamento de bugs. É aqui que a estrutura de plug-in de ação externa entra em ação, por meio da qual eles podem criar integração entre o ServiceDesk Plus e o JIRA. Como resultado, eles podem criar problemas no JIRA a partir do menu **Ações** da página **Solicitações**.

![ ](https://www.manageengine.com/images/x_plugin.jpg)

Habilidades necessárias para desenvolver o Plug-in de Ação Externa

É necessário conhecimento nas seguintes áreas para trabalhar no plug-in:

- Extensible Markup Language (XML)
- JavaScript Object Notation (JSON)
- Java (especificamente conceitos de Interface e Implementação)

## Configurando o Plug-in

O plug-in foi projetado para ter uma classe de implementação e pode ser invocado por meio de um menu. O menu pode ser configurado no módulo **Admin** do ServiceDesk Plus.

- Classe de implementação
- Configuração de menu

### Classe de implementação

A classe Java deve estender `DefaultActionInterface` e fornecer a implementação por meio do método `execute`. As classes de importação necessárias estão disponíveis em `AdventNetHelpDesk.jar` e `AdventNetServiceDeskCommon.jar`, encontrados em:

```
"[SCP_HOME]\applications\extracted\AdventNetSupportCenter.eear\AdventNetHelpDesk.ear\"
```

```java
package com.manageengine.servicedesk.actionplugin.sample;

import com.manageengine.servicedesk.actionplugin.executor.ActionInterface
import com.manageengine.servicedesk.actionplugin.executor.ExecutorData

public class SampleActionImplementation extends DefaultActionInterface
{
    public JSONObject execute(ExecutorData executorData) throws Exception
    {
        ExecutorData data = executorData;

        ActionMenuData menuData = data.getActionMenuData();
        String menuName = (String) menuData.getMenuName();
        JSONObject scpValuesObj  = data.getDataJSON();

        //Você pode colocar sua implementação aqui

        //O tipo de retorno deve ser JSON
    }
}
```

**O método Execute:**

A implementação será definida no método `execute` com o parâmetro objeto `ExecutorData`:

- Método: `Execute (ExecutorData)`
- Retorna: `JSONObject`

**Dados do Executor:**

O objeto `ExecutorData` é um parâmetro para o método Execute. Usando-o, podemos obter os detalhes do menu que é invocado por meio do método `getActionMenuData()`. Isso retornará um objeto chamado `ActionMenuData`.

i) **ActionMenuData** - Fornece informações sobre o menu a partir do qual a ação é invocada.

- Método: `getActionMenuData()`
- Retorna: `ActionMenuData`

Abaixo estão os métodos disponíveis para extrair valores e seus respectivos tipos de dados:

| Parâmetro | Valor de retorno |
|---|---|
| **getMenuName**<br><br>Retorna o nome do menu de ação que é invocado. | String |
| **getDisplayText**<br><br>Retorna o nome de exibição do menu que é invocado. | String |
| **getExecutorClass**<br><br>Retorna o nome da classe de execução Java especificada para este menu. | String |
| **getAllowedRoles**<br><br>Retorna a lista de funções que têm permissão para usar este menu. | ArrayList |
| **getAllowedTemplates**<br><br>Retorna a lista de modelos nos quais este menu estará disponível. | ArrayList |

ii) **Dados JSON** - Os detalhes da solicitação a partir da qual o menu foi acionado podem ser obtidos invocando o método `getDataJSON` em `ExecutorData`. Isso retornará os detalhes como um objeto JSON:

- Método: `getDataJSON()`
- Retorna: `JSONObject`

Um exemplo de dados seria como abaixo:

```json
{
   "WORKORDERID": "1",
   "REQUESTER": "Guest",
   "CREATEDBY": "administrator",
   "CREATEDTIME": "1469685688321",
   "DUEBYTIME": "1469692888321",
   "RESPONSEDUEBYTIME": "-1",
   "FR_DUETIME": "-1",
   "RESPONDEDTIME": "0",
   "RESOLVEDTIME": "0",
   "COMPLETEDTIME": "0",
   "SHORTDESCRIPTION": "",
   "TIMESPENTONREQ": "0hrs 0min",
   "SUBJECT": "Testing for Bulk SMS",
   "REQUESTTEMPLATE": "Default Request",
   "MODE": "E-Mail",
   "SLA": "Medium SLA",
   "ASSET": "",
   "DEPARTMENT": " HR  Department",
   "EDITORID": "null",
   "EDITING_STATUS": "0",
   "IS_CATALOG_TEMPLATE": "false",
   "SITE": "Singapore Support",
   "ISVIPUSER": "No",
   "SERVICE": "",
   "CATEGORY": "Software",
   "SUBCATEGORY": "MS Office",
   "ITEM": "Install",
   "TECHNICIAN": "Heather Graham",
   "TECHNICIAN_LOGINNAME": "Heather",
   "STATUS": "Open",
   "PRIORITY": "Medium",
   "LEVEL": "Tier 2",
   "IMPACT": "",
   "URGENCY": "High",
   "IMPACTDETAILS": "-",
   "REQUESTTYPE": "Incident",
   "APPROVAL_STATUS": "",
   "CLOSURECODE": "",
   "CLOSURECOMMENTS": "",
   "FCR": "false",
   "YETTOREPLYCOUNT": "",
   "GROUP": "Hardware Problems",
   "DESCRIPTION": "",
   "Test": ""
}
```

## Operações de solicitação suportadas por padrão

Com essas informações, os clientes podem escrever seu próprio código de implementação para executar a operação necessária. Agora, existem duas maneiras de atualizar um ticket. A primeira opção é usar o suporte à API REST disponível no SDP e atualizar a solicitação ou executar operações como adicionar um registro de trabalho, notas, resolução etc. A segunda é usar a **funcionalidade de retorno padrão suportada pela estrutura do plug-in de ação**.

O método `execute` retorna um objeto JSON. Por padrão, **a adição de notas** e **a atualização de uma solicitação** são suportadas se o JSON retornado estiver em conformidade com o formato suportado.

### a. Adicionando notas a uma solicitação

```json
{
  "message":"Solicitação adicionada com sucesso",
  "result":"success",
  "operation":[
    {
      "INPUT_DATA":[
        {
          "notes":{
            "notestext":"O ticket foi criado no JIRA e as informações foram preenchidas no SDP"
          }
        }
      ],
      "OPERATIONNAME":"ADD_NOTE"
    }
  ]
}
```

### b. Atualizando uma solicitação

```json
{
  "message":"Solicitação adicionada com sucesso",
  "result":"success",
  "operation":[
    {
      "INPUT_DATA":[
        {
          "Jira ID":"35",
          "Jira Key":"SDP-3",
          "self":"http://jira-server/rest/api/2/issue/35"
        }
      ],
      "OPERATIONNAME":"UPDATE_REQUEST"
    }
  ]
}
```

## Integração padrão (integração com o JIRA)

**Para configurar o menu Ações da Solicitação**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<menus>
  <menu name="JiraIntegration" refresh="true">
    <displaytext>Integração SCP para Jira</displaytext>
    <roles>
      <role>ModifyRequests</role>
    </roles>
    <template>
      <template>Modelo definido pelo sistema</template>
    </templates>
    <invoke>
      <class>com.manageengine.supportcenter.integrations.jira.action.JiraActionImplementation</class>
    </invoke>
  </menu>

  <menu name="SDP Integration" refresh="true">
    <displaytext>Integração SCP para SDP</displaytext>
    <roles>
      <role>ModifyRequests</role>
    </roles>
    <templates>
      <template>Modelo definido pelo sistema</template>
      <template>testing</template>
    </templates>
    <invoke>
      <class>com.manageengine.supportcenter.integrations.jira.action.SDPActionImplementation</class>
    </invoke>
  </menu>
</menus>
```

**Para integração com o JIRA**

**Observação:** Forneceremos uma **implementação padrão para o JIRA**. Para isso, os clientes precisam definir **outro xml** que terá as **implementações específicas do JIRA**.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<menus>
  <!-- O nome do menu deve corresponder ao especificado no xml ActionMenu -->
  <menu name="JiraIntegration">
    <!-- Especifica os parâmetros de entrada que devem ser passados para o JIRA -->
    <request>
      <!-- Credenciais necessárias para fazer login no JIRA -->
      <username>administrator</username>
      <password>administrator</password>

      <!-- URL a ser invocada para executar a operação -->
      <url>http://localhost:8080/rest/api/2/issue/</url>

      <!-- Parâmetros a serem passados para a URL -->
      <param>
        <name>project</name>
        <type>projectpicker</type>
        <value>SCP</value>
      </param>

      <param>
        <name>Issuetype</name>
        <type>select</type>
        <value>Bug</value>
      </param>

      <!-- Parâmetros dinâmicos podem ser especificados por um prefixo $. Neste caso, o valor da variável será obtido do SDP e passado. -->

      <param>
        <name>summary</name>
        <type>textfield</type>
        <value>$subject</value>
      </param>

      <param>
        <name>priority</name>
        <type>select</type>
        <value>$priority</value>
      </param>

      <param>
        <name>description</name>
        <type>textarea</type>
        <value>$description</value>
      </param>

      <param>
        <name>labels</name>
        <type>labels</type>
        <value>$JIRA_ISSUE_ID</value>
      </param>

      <param>
        <name>environment</name>
        <type>textarea</type>
        <value>$description</value>
      </param>

      <param>
        <name>duedate</name>
        <type>datepicker</type>
        <value>$dueByTime</value>
      </param>

      <param>
        <name>customfield_10002</name>
        <type>url</type>
        <value>$Company Website</value>
      </param>

      <param>
        <name>customfield_10100</name>
        <type>url</type>
        <value>$JIRA_SelectList</value>
      </param>

      <param>
        <name>customfield_10200</name>
        <type>float</type>
        <value>$Jira Numeric Field</value>
      </param>

      <param>
        <name>customfield_10300</name>
        <type>textfield</type>
        <value>$Jira_Text Field</value>
      </param>

      <param>
        <name>customfield_10301</name>
        <type>datetime</type>
        <value>$Jira_Date Time</value>
      </param>

      <param>
        <name>customfield_10302</name>
        <type>datepicker</type>
        <value>$Jira_Date Picker</value>
      </param>

      <param>
        <name>customfield_10303</name>
        <type>userpicker</type>
        <value>$Jira_User Picker</value>
      </param>

      <param>
        <name>customfield_10304</name>
        <type>grouppicker</type>
        <value>$Jira_Group Picker</value>
      </param>

      <param>
        <name>customfield_10306</name>
        <type>textarea</type>
        <value>$Jira_Free Text Field</value>
      </param>
    </request>

    <success>Integrado com sucesso ao Jira e o ID do Jira é: $id</success>
    <failure>Falha ao integrar com o jira</failure>

    <!-- Especifica os campos que devem ser atualizados após a execução da ação -->
    <response>
      <param>
        <!-- name indica o atributo no objeto JSON de retorno recebido da API do JIRA -->
        <name>JIRA_ISSUE_ID</name>
        <!-- value indica o campo do SDP que deve ser atualizado com o valor do JIRA -->
        <value>$id</value>
      </param>

      <param>
        <!-- name indica o atributo no objeto JSON de retorno recebido da API do JIRA -->
        <name>JIRA_ISSUE_URL</name>
        <!-- value indica o campo do SDP que deve ser atualizado com o valor do JIRA -->
        <value>$self</value>
      </param>

      <!-- Se alguma nota precisar ser adicionada ao final da operação, ela deve ser especificada aqui. $message obterá o valor do objeto json retornado pelo JIRA. Mensagens fixas também podem ser usadas -->
      <notes>
        <note>O ticket foi criado no jira com a chave: $key e com o ID: $id</note>
        <note>O ticket foi criado no jira com o issueID: $id</note>
      </notes>
    </response>
  </menu>
</menus>
```