com.alarmpoint.integrationagent.script.api

## Interface ServiceAPI

-     public interface ServiceAPI

  This interface represents the Integration Service functions that are exposed to an Integration Service's script.

  NOTE: By convention, implementors of this interface must be thread-safe.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `NAME` This is the name of the global variable in each Integration Service's script that is assigned an instance of this interface.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `APXMLMessage` | `createAPXML()` Creates an new APXML message that the caller can populate.
    `IntegrationServiceRequest` | `createIntegrationServiceRequest()` Creates an object that can be used to make an Integration Service Request to either a local (i.e., hosted on the same Integration Agent), or external Integration Service.
    `java.lang.String` | `decrypt(java.lang.String encryptedString)` This method will decrypt the provided string.
    `GlobalService` | `getConfiguration()` Expose the service definition of this Integration Service.
    `org.apache.log4j.Logger` | `getLogger()` Gets a logger that will write to the APIA log file in the same log4j category and format as the Integration Service.
    `void` | `sendAPXML(APXMLMessage apxml)` Adds the specified APXML message to the end of the Integration Service's outbound queue.
    `void` | `sendAPXML(APXMLMessage apxml, java.lang.String domain, java.lang.String serviceName)` Adds the specified APXML message to the end of the specified service's inbound queue.

- - ### Field Detail

    - #### NAME

          static final java.lang.String NAME

      This is the name of the global variable in each Integration Service's script that is assigned an instance of this interface. In other words, this is the name of the variable through which scripts access this API.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getLogger

          org.apache.log4j.Logger getLogger()

      Gets a logger that will write to the APIA log file in the same log4j category and format as the Integration Service.

      For example, if the Integration Service is (default,sample), the logger will write to the category com.alarmpoint.integrationagents.services.default.sample).

      Returns:
        a non-null Logger

    - #### getConfiguration

          GlobalService getConfiguration()

      Expose the service definition of this Integration Service.
      Returns:
        configuration
      See Also:
        `GlobalService`

    - #### createAPXML

          APXMLMessage createAPXML()

      Creates an new APXML message that the caller can populate.
      Returns:
        a non-null APXMLMessage with a default transaction id=1, method "Add", and no subclass or tokens.

    - #### sendAPXML

          void sendAPXML(APXMLMessage apxml)
                  throws java.lang.Exception

      Adds the specified APXML message to the end of the Integration Service's outbound queue. The agent_client_id token is always set to the associated service's ID and the apia_priority token (if any) determines whether the message goes to the high or normal priority queue. If no apia_priority token is specified, or the value is unrecognized, the message is assumed to be normal priority.
      Parameters:
        `apxml` - - the outbound APXML message; must be non-null
      Throws:
        `java.lang.Exception` - if the message cannot be queued

    - #### sendAPXML

          void sendAPXML(APXMLMessage apxml,
                         java.lang.String domain,
                         java.lang.String serviceName)
                  throws java.lang.Exception

      Adds the specified APXML message to the end of the specified service's inbound queue. The agent_client_id token is always set to the associated service's ID and the apia_priority token (if any) determines whether the message goes to the high or normal priority queue. If no apia_priority token is specified, or the value is unrecognized, the message is assumed to be normal priority. Message is always sent to the local Integration Agent.

      Below is a sample usage of this method to send an APXML to the local ping|ping service.

           var apxml = ServiceAPI.createAPXML();
           apxml.setMethod("add");
           apxml.setSubclass("event");
           apxml.setToken("recipients","bsmith");
           apxml.setToken("situation","Redirected ping from sample.");
           apxml.setToken("device","localhost");
           apxml.setToken("incident_id","Redirected-localhost-ping-test");

           ServiceAPI.sendAPXML(apxml, "ping", "ping");

      Parameters:
        `apxml` - - the inbound APXML message; must be non-null
        `domain` - - the domain of the targeted service
        `serviceName` - - the service name to queue the message
      Throws:
        `java.lang.Exception` - if the message cannot be queued

    - #### createIntegrationServiceRequest

          IntegrationServiceRequest createIntegrationServiceRequest()

      Creates an object that can be used to make an Integration Service Request to either a local (i.e., hosted on the same Integration Agent), or external Integration Service.
      Returns:
        a non-null IntegrationServiceRequest

    - #### decrypt

          java.lang.String decrypt(java.lang.String encryptedString)
                            throws SymmetricCipherException

      This method will decrypt the provided string. If there are any issues when attempting to process the encrypted string (i.e., encrypted string has an invalid format) a SymmetricCipherException will be thrown.

      Below is a sample usage of this method to decrypt the "password" token passed in the apxml

           function handleRequest(apxml)
           {
              var encryptedPassword = apxml.getValue("password");
              var decryptedPassword = ServiceAPI.decrypt(encryptedPassword);

              // Log the decryptedPassword
              ServiceAPI.getLogger().debug("Decrypted Password is: " + decryptedPassword);
           }

      Parameters:
        `encryptedString` - - a string that has been encrypted. The encryptedString must not be null.
      Returns:
        a decrypted String
      Throws:
        `SymmetricCipherException` - if the encryptedString cannot be decrypted