Review (BA-36527)

Overview

Cloud function is https endpoint, which is provided to Addon-Mart by the Communication Service Provider (as a Vendor of the service). Provided function is invoked by Porta Billing (internal part SMS Dispatcher) and is used for SMS notifications.

Supported cloud functions

Supported cloud functions are: Oracle Cloud Functions, AWS Lambdas, Azure Functions, Google Cloud Functions

SMS Function interface

Function (https endpoint) shall accept input in the POST HTTP request in JSON format and return output in JSON format.

Interface Open API description

yaml format:

api.yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: Test function API
  description: Test function API

servers:
  - url: https://oracleclouddomain/deploymentpath

paths:
  /function_endpoint:
    post:
      description: Invoke function
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object 
              required:
                - dst_phone
                - src_phone
                - auth_info
                - message
              properties:
                dst_phone:
                  type: string
                  description: The phone number of the SMS reciever.
                src_phone:
                  type: string
                  description: 'The representation of the source number on the vendor side. Note: for the SMS provider Twilio, this phone is provided in the Account Info section.'
                message:
                  type: string
                  description: The text of the message to send.
                auth_info:
                  type: object
                  description: The credentials required for the SMS provider authorization.
                  required:
                    - token
                    - login
                    - password
                  properties:
                    token:
                      type: string
                      description: 'The token required for the SMS provider authorization. Note: for the SMS provider Twilio, this token is provided in the Account Info section.'
                    login:
                      type: string
                      description: 'The login required for the SMS provider authorization. Note: for the SMS provider Twilio, this is the Account SID value, provided in the Account Info section.'
                    password:
                      type: string
                      description: 'The password required for the SMS provider authorization. Note: for the SMS provider Twilio, the password is not required.'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                properties:   
                  success:
                    type: boolean
                    description: True for success, false in case of failure
        '400':
          description: Client error response
          content:
            application/json:
              schema:
                type: object
                properties:   
                  success:
                    type: boolean
                    description: True for success, false in case of failure.
                  error:
                    type: string
                    description: Contains the error message in case of client error.
        '500':
          description: Server error response
          content:
            application/json:
              schema:
                type: object
                properties:   
                  success:
                    type: boolean
                    description: True for success, false in case of failure.
                  error:
                    type: string
                    description: Contains the error message in case of server error.

Request body

Function shall accept the following parameters as input in JSON format:

NameTypeDescription
dst_phonestringThe phone number of the SMS reciever.
src_phonestringThe representation of the source number on the vendor side. Note: for the SMS provider Twilio, this phone is provided in the Account Info section.
messagestringThe text of the message to send.
auth_infoobjectThe credentials required for the SMS provider authorization.
auth_info.tokenstringThe token required for the SMS provider authorization. Note: for the SMS provider Twilio, this token is provided in the Account Info section.
auth_info.passwordstringThe password required for the SMS provider authorization. Note: for the SMS provider Twilio, the password is not required.
auth_info.loginstring

The login required for the SMS provider authorization. Note: for the SMS provider Twilio, this is the Account SID value, provided in the Account Info section.


Request example:

curl -k -X POST <functions endpoint> -H "Content-Type: application/json" -d'{
        "dst_phone": "+38NNN555NNNN",
        "src_phone": "+1NNN555NNNN",
        "message": "Test message",
        "auth_info": {
            "token": "bbaabe325689e3578ec10d047a7d08728",
            "login": "ACf2700aaaa18e2191334b3594807fffff",
            "password": "fwoejgforeghureh1233"
        }
}'

Response body

Function should return the following output parameters in JSON format:

NameTypeDescription
successbooleanTrue for success, false in case of failure.
errorstringContains the error message in case of error.

Response shall have standard HTTP codes: 200 code in case of success, 400 code in case of client error, 500 code in case of server error.

In the example function the following HTTP codes are used: 200 (OK), 400 (BAD_REQUEST), 401 (UNAUTHORIZED), 500 (INTERNAL_SERVER_ERROR).

Response BODY error example (json)

Response body with error
{
    "error": "The login is missing. The login should be equal to the Twilio account SID.",
    "success": false
}

Response BODY success example (json)

Response body success
{
    "success": true
}

Oracle cloud function example

Oracle cloud function specific example

Google cloud function example

Google cloud function specific example

How to deal with different cloud providers (AWS, Google, Microsoft)

AWS Lambdas, Azure Functions, Google Cloud Functions - developed according to its own documentation on any supported language. Oracle function for Twilio provided as example.

Provided function should implement SMS Function interface in order to be deployed in Addon-Mart.

How to deploy publicly accessible cloud function to Addon-Mart

Cloud function is deployed into Communication Service Providers cloud infrastructure.

Communication Service Provider provides publicly accessible https endpoint to PortaOne Devops team.

Communication Service Provider allows access to the IP address of the function caller (PortaOne iPaaS SMS Dispatcher, Frankfurt: 129.159.206.65, South Africa: 129.151.179.170). Access to the functions endpoint from all other IPs shall be prohibited.

How to deploy cloud function requiring cloud provider authentication to Addon-Mart

Cloud function can be called by using signed https request to its direct endpoint.

Cloud function is deployed into Communication Service Providers cloud infrastructure.

Function have to be available for call from PortaOne iPaaS SMS dispatcher (Frankfurt: 129.159.206.65, South Africa: 129.151.179.170).

Communication Service Provider provides https endpoint to PortaOne Devops team.

Communication Service Provider provides cloud provider credentials.

For each supported by PortaOne SMS dispatcher cloud providers different set of credentials must be provided.

Oracle specific credentials
NameDescription
tenancyOCIDTenancy's OCID
userOCIDUser's OCID
keyFingerprintThe fingerprint of the key that was added to Oracle
regionThe region
privateKeyRSA private key (minimum 2048 bits)
privateKeyPassphraseRSA private key passphrase
Google specific credentials
NameDescription
identityTokenGcloud auth identity token
Microsoft Azure specific credentials
NameDescription
accessKeyFunction access key (API access key).
Amazon Web Services specific credentials
NameDescription
idAWS access key ID
secretAWS secret access key
tokenAWS session token to sign requests with
regionThe region
serviceAWS lambda service
It is possible to deploy new Cloud Functions into PortaOne's infrastructure. Though this isn't a preferred way. Customer needs Sales or PMD approval. After that sources of its Cloud Function have to be provided to our Devops team.