# Complemento de acción externa

En este documento se tratan los siguientes temas:

- [Acerca del complemento de acción externa](#acerca-del-complemento-de-acción-externa)
- [Integración con aplicaciones de terceros](#integración-con-aplicaciones-de-terceros)
- [Configuración de su integración](#configuración-del-complemento)
- [Operaciones de solicitud compatibles de forma predeterminada](#operaciones-de-solicitud-compatibles-de-forma-predeterminada)
- [Integración predeterminada (integración con JIRA)](#integración-predeterminada-integración-con-jira)

## Propósito de este documento

Este documento proporciona información procedimental para que los desarrolladores creen un complemento y establezcan la integración entre ServiceDesk Plus y varias otras aplicaciones de terceros.

## Acerca del complemento de acción externa

Un flujo de trabajo completo de una solicitud requiere que el equipo de soporte realice distintas tareas. Ocasionalmente, el equipo de soporte puede involucrar aplicaciones de terceros para llevar a cabo ciertas tareas accediendo a las aplicaciones correspondientes, lo que puede exceder el límite de la aplicación.

Por lo tanto, para superar el tedioso proceso de incorporar aplicaciones de terceros para realizar tareas, como la integración con rastreadores de incidencias, la creación de cuentas de Active Directory y la creación de nuevas cuentas de correo, puede aprovechar la opción de complemento de acción externa en ServiceDesk Plus. Esta opción ayuda al equipo de soporte a realizar varias operaciones relacionadas con terceros directamente desde la página de **Solicitudes** con solo hacer clic en el menú **Acciones**.

**Escenario:**

Considere una organización que usa ServiceDesk Plus para su soporte al cliente y JIRA para el seguimiento de errores. Aquí es donde entra en juego el marco del complemento de acción externa, con el cual pueden crear una integración entre ServiceDesk Plus y JIRA. Como resultado, pueden crear incidencias en JIRA desde el menú **Acciones** de la página de **Solicitudes**.

![Complemento de acción externa](https://www.manageengine.com/images/x_plugin.jpg)

Habilidades necesarias para desarrollar el complemento de acción externa:

- Lenguaje de marcado extensible (XML)
- Notación de objetos de JavaScript (JSON)
- Java (específicamente los conceptos de interfaz e implementación)

## Configuración del complemento

El complemento está diseñado para tener una clase de implementación y puede invocarse a través de un menú. El menú se puede configurar en el módulo **Administración** de ServiceDesk Plus.

- Clase de implementación
- Configuración del menú

### Clase de implementación

La clase Java debe extender `DefaultActionInterface` y proporcionar la implementación mediante el método `execute`. Las clases de importación necesarias están disponibles en `AdventNetHelpDesk.jar` y `AdventNetServiceDeskCommon.jar` que se encuentran en:

`[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();

        // Puede colocar aquí su implementación
        // El tipo de retorno debe ser JSON
    }
}
```

**El método Execute:**

La implementación se definirá en el método `execute` con el parámetro objeto `ExecutorData`:

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

**Datos del ejecutor:**

El objeto `ExecutorData` es un parámetro del método `Execute`. Con esto, podemos obtener los detalles sobre el menú que se invoca mediante el método `getActionMenuData()`. Esto devuelve un objeto llamado `ActionMenuData`.

i) **ActionMenuData** – Proporciona información sobre el menú desde el cual se invoca la acción.

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

A continuación se muestran los métodos disponibles para extraer valores y sus respectivos tipos de datos:

| Parámetro | Valor devuelto |
|---|---|
| **getMenuName**<br><br>Devuelve el nombre del menú de acción que se invoca. | String |
| **getDisplayText**<br><br>Devuelve el nombre para mostrar del menú que se invoca. | String |
| **getExecutorClass**<br><br>Devuelve el nombre de la clase de ejecución de Java especificada para este menú. | String |
| **getAllowedRoles**<br><br>Devuelve la lista de roles que tienen permitido usar este menú. | ArrayList |
| **getAllowedTemplates**<br><br>Devuelve la lista de plantillas en las que este menú estará disponible. | ArrayList |

ii) **Datos JSON** – Los detalles de la solicitud desde la cual se activó el menú se pueden obtener invocando el método `getDataJSON` en `ExecutorData`. Esto devolverá los detalles como un objeto JSON:

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

Un ejemplo de datos se vería como el siguiente:

```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": ""
}
```

## Operaciones de solicitud compatibles de forma predeterminada

Con esta información, los clientes pueden escribir su propio código de implementación para realizar la operación necesaria. Ahora, existen dos formas de actualizar un ticket:

1. Usar la compatibilidad con la API REST disponible en SDP y actualizar la solicitud o realizar operaciones como agregar un worklog, notas, resolución, etc.
2. Usar la **funcionalidad de retorno predeterminada compatible con el marco del complemento de acción**.

El método `execute` devuelve un objeto JSON. De forma predeterminada, se admite **agregar notas** y **actualizar una solicitud** si el JSON devuelto cumple con el formato compatible.

### a. Agregar notas a una solicitud

```json
{
  "message":"Solicitud agregada correctamente",
  "result":"success",
  "operation":[
    {
      "INPUT_DATA": [
        {
          "notes": {
            "notestext":"El ticket se ha creado en JIRA y la información se ha completado en SDP"
          }
        }
      ],
      "OPERATIONNAME":"ADD_NOTE"
    }
  ]
}
```

### b. Actualizar una solicitud

```json
{
  "message":"Solicitud agregada correctamente",
  "result":"success",
  "operation":[
    {
      "INPUT_DATA": [
        {
          "Jira ID":"35",
          "Jira Key":"SDP-3",
          "self":"http://jira-server/rest/api/2/issue/35"
        }
      ],
      "OPERATIONNAME":"UPDATE_REQUEST"
    }
  ]
}
```

## Integración predeterminada (integración con JIRA)

**Para configurar el menú Acciones de solicitud**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<menus>
  <menu name="JiraIntegration" refresh="true">
    <displaytext>Integración de SCP con Jira</displaytext>
    <roles>
      <role>ModifyRequests</role>
    </roles>
    <template>
      <template>Plantilla definida por el sistema</template>
    </templates>
    <invoke>
      <class>com.manageengine.supportcenter.integrations.jira.action.JiraActionImplementation</class>
    </invoke>
  </menu>

  <menu name="SDP Integration" refresh="true">
    <displaytext>Integración de SCP con SDP</displaytext>
    <roles>
      <role>ModifyRequests</role>
    </roles>
    <templates>
      <template>Plantilla definida por el sistema</template>
      <template>testing</template>
    </templates>
    <invoke>
      <class>com.manageengine.supportcenter.integrations.jira.action.SDPActionImplementation</class>
    </invoke>
  </menu>
</menus>
```

**Para la integración con JIRA**

**Nota:** Se proporciona una **implementación predeterminada para JIRA**. Para esto, los clientes deben definir **otro XML** que tendrá las **implementaciones específicas de JIRA**.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<menus>
  <!-- El nombre del menú debe coincidir con el especificado en el xml de ActionMenu -->
  <menu name="JiraIntegration">
    <!-- Especifica los parámetros de entrada que deben pasarse a JIRA -->
    <request>
      <!-- Credenciales necesarias para iniciar sesión en JIRA -->
      <username>administrator</username>
      <password>administrator</password>

      <!-- URL que se invocará para realizar la operación -->
      <url>http://localhost:8080/rest/api/2/issue/</url>

      <!-- Parámetros que se pasarán a la URL -->
      <param>
        <name>project</name>
        <type>projectpicker</type>
        <value>SCP</value>
      </param>

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

      <!-- Los parámetros dinámicos pueden especificarse con el prefijo $. -->
      <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>Integración con Jira realizada correctamente y el id de Jira es: $id</success>
    <failure>No se pudo integrar con jira</failure>

    <!-- Especifica los campos que deben actualizarse después de que se ejecute la acción -->
    <response>
      <param>
        <!-- name indica el atributo en el objeto JSON de retorno recibido desde la API de JIRA -->
        <name>JIRA_ISSUE_ID</name>
        <!-- value indica el campo de SDP que debe actualizarse con el valor de JIRA -->
        <value>$id</value>
      </param>

      <param>
        <name>JIRA_ISSUE_URL</name>
        <value>$self</value>
      </param>

      <!-- Si es necesario agregar alguna nota al final de la operación -->
      <notes>
        <note>El ticket se creó en jira con la clave: $key y con Id: $id</note>
        <note>El ticket se creó en jira con issueID: $id</note>
      </notes>
    </response>
  </menu>
</menus>
```