Email Endpoints are available in PhixFlow version 11.3+

What is an

Email Endpoint?

How does an Email Endpoint work?

1. An Email Account must be set up in your application to receive incoming emails. See Email Account Integrationfor an example.
   1. The email account setup must include:
      1. Type: choose Inbound
      2. On Email Received: choose Trigger an email endpoint actionflow
      3. Email Endpoint Action: choose your

         Insert excerpt
         _

1. 1. 1. email_

1. 1. 1. endpoint _

1. 1. 1. email_

1. 1. 1. endpoint

1. 1. 1. nopanel true

2. To save the emails, a

   Insert excerpt
   _tables _tables nopanel true

1. must be created with appropriate attributes for the headers on the incoming emails, e.g. id, from, to, cc, subject, body, folderId
2. To allow PhixFlow to save attachments, a

   Insert excerpt
   _

1. tableFile _

1. tableFile nopanel true

1. must be created
2. The above Table and File Table must have a relation on an ERD, see Relationship
3. Upon receiving an email, the

   Insert excerpt
   _

1. email_endpoint _

1. email_endpoint nopanel true

Creating an API Endpoint

1. will run and perform the action(s) as specified within the Email Endpoint Actionflow, such as saving each incoming email as a record in a table 
   1. If saving to a table, each received email saves as a separate record

Creating an Email Endpoint

Email endpoints must be made using the specific option on the 

ensure the set of predefined input parameters are configured on the 

1. Create a new

   Insert excerpt
   _

1. email_

1. endpoint _

1. email_endpoint

1. nopanel true

    on the 

   Insert excerpt
   _actionflow _actionflow nopanel true

1. homepage using the 

Image Removed

1. Image Added option
   Image Removed  
   1. 1. Image Added
   2. Set a unique name and provide a useful description
   If you have made your API Endpoint via
   1. Additional attributes can be added to the 

      Insert excerpt
      _

   repository

   1. input _

   repositorynopaneltrue, right-click on the API Endpoint name and choose Insert excerpt_actionflow_icon_actionflow_

   1. input name icon nopanel true

   DisplayThe API Endpoint  Insert excerpt_property_settings_property_settingsnopaneltrue will open on the right - for the full Properties list, see API Endpoint PropertiesConfigure the API
   1. connection point which will obtain the value from a header with the same name on the incoming email(s) 
      1. Note: Any '-' characters are removed from the name and the names are case insensitive 
   2. Configure the endpoint to perform the required tasks on receiving of incoming emails, for example
   return all company data , or pass in a date and return all companies onboarded after this date
   1. See Worked Example below for an example setup

   Input Parameters

   1. , save all records to a 

      Insert excerpt
      _

   actionflow_api_endpoint

   1. tables _

   actionflow_api_endpointnametext

   1. tables nopanel true

   s have fixed parameters set on the input node (body, headers, contentType and url), and the output node (body, headers, contentType and statusCode) which can be mapped to.

   Image Removed

   On the Input Connection Point, additional Input Parameters can be created to facilitate query string parameters being passed into the API via the URL.

   Click on the
   1. , see Save Action Configuration
      1. If saving any of the attributes with a Type of Structured Data, a 

         Insert excerpt
         _

   input

   1. 1. action_

   inputnopaneltrue nodeThe Insert excerpt_property_settings_property_settings

   1. 1. calculate _action_calculate nopanel true

   will open on the right and in the Input Parameters section, click the 
   1. 1. action can be used between the

         Insert excerpt
         _

   add_icon

   1. 1. input _

   add_icon

   1. 1. input nopanel true

   icon to create a new attribute
2. Enter a Name and Default Value (optional)
The Name set on the
1. 1. and 

      Insert excerpt
      _action_

input

1. 1. save _

input

1. 1. action_save nopanel true

must match the parameter name in the URL, e.g. if an Input Parameter, "field" is created, and the request URL is https://server/phixflow/api/1/ then the value "abc" will be used as a parameter. When calling APIs using query string parameters in the URL, care should be taken to ensure that the values are appropriately URL encoded to prevent unexpected behaviour. See HTTP Action Configuration.

If a parameter is missing then it will be marked as unavailable, unless a Default Value has been configured. 

Note
If a “timeout” parameter is sent via the URL, a corresponding Input Parameter is not required on the API Endpoint. See Timeout below.

URL & URL Alias

URL and URL Alias can be found on the API Endpoint
1. 1. action
/App/Api/trigger?field=abc
1. 1. to convert these incoming values into a format that can be saved by PhixFlow
      1. For each attribute, use the listToString function

The default structure of the URL (i.e. with no URL Alias set) is as follows:

https://<<Server Name>>/phixflow/api/1/action/<<Application Name>>/<<Actionflow Name>>/trigger

3. Use URL Alias to modify the URL for the API
   • When set, instead of the URL being constructed using the API Endpoint name and application name, it will use the alias instead
   • Any special characters will be translated, such as, spaces to their URL encoded form (%20)

URL Alias Example

If the API URL is, https://server.phixflow.com/phixflow/api/1/action/My%20App/My%20API%20Endpoint/trigger and a URL Alias of Company Data is set, then the API URL will change to, https://server.phixflow.com/phixflow/api/2/Company%20Data

API Mode

API Mode can be found on the API Endpoint

_property_settings actions, output connection points, lookups or phases.

Note
Email Endpoints cannot contain  Insert excerpt _propertyaction_settingsscreen _propertyaction_settingsscreen nopanel true . Copy the URL and save it locally, to be used later when calling the API
Expand
title Url Structure
Parameter	Description
<<Server Name>>	URL of the server e.g. app.phixflow.com
phixflow	the name of the instance, typically this is phixflow
<<Application Name>>	The name of the application where the Actionflow resides.
<<API Name>>	The name of the API. Note: If the API Name contains a space, this is replaced with %20. For example "My API" becomes, "My%20API".
Insert excerpt
_property_settings

Saving Attachments

Attachments can be saved in a separate 

Insert excerpt
_tableFile _tableFile nopanel true

.

Choose an API Mode:

• Wait for result (Synchronous) (Default): The API waits for the results or the timeout to occur
  • Note: If the timeout occurs the command is aborted
• Poll for result (Asynchronous): The API is called and a response is returned immediately including the process ID
  • Subsequent API calls can be made using the process ID to fetch the status of the action
  • The asynchronous mode can be thought of as “fire and forget”

Authorisation

Allow Anonymous Connections can be found on the API Endpoint
1. On the Email Endpoint, click

   Insert excerpt
   _property_settings _property_settings nopanel true

.

If Allow Anonymous Connections is enabled:

Excerpt
name AllowAnonymousConnections
This allows anyone with the URL for the API to call it. The audit trail records the system as running performing the API call.

Note: Adding authorisation is covered on API Authentication and Secret Keys.

Timeout

Timeout can be found on the API Endpoint Insert excerpt_property_settings_property_settingsnopaneltrue.

Set a Timeout (optional):

• Specify a maximum time in milliseconds that the API will wait for before the command is aborted

• When a Timeout value is set, it overrides the default timeout, which is 60 seconds where API Mode is Synchronous and 500 milliseconds where API Mode is Asynchronous

  • However, if a timeout parameter has been provided in the URL calling this API, that will override both this Timeout value and the default value

API Status Check (Poll for Result)

• If calling a PhixFlow Asynchronous API only, a result will be immediately returned which includes a Process ID for that run
• The Process ID is returned on the path:
  • $.processId
  • This can be accessed in an Output attribute using, _result.value
• The Process ID can be used to call the following URL which will return the current state of the run:
  • https://<<Server Name>>/phixflow/api/1/action/<<Application Name>>/<<Actionflow Name>>/poll/<<processID>>

Calling a PhixFlow API

HTTP Method

This is set on the  Insert excerpt_action_http_action_httpnopaneltrue action on the Actionflow calling the API.
• To call a PhixFlow API use the HTTP Method GET or POST:
  • GET simply calls the API with data passed in the body of the request
  • POST calls the URL and sends data in the body of the request. The body data is passed into the body attribute of the API as an Input Connection point

See HTTP Action Configuration.

Returned Data JSON Path

If your API has been configured to return data the path will be in the format:

$.data.<<Output Name>> 

Where <<Output Name>> is the Output connection point.

Server Console Responses

The item calling the API endpoint will receive the Response from the API endpoint stating whether it has run successfully (Success) or not (Fail). Responses can be customised to return specific messages.

The response recorded in the Insert excerpt_console_consolenopaneltrue:

If you are making the call using PhixFlow the Responses can be access as follows:

1. Click the Actionflow entry
   1. Image Removed
2. In the Messages section which is opened below, double-click the lines that begin Response
   1. Image Removed
3. Click the Message Details tab to see the response

API Endpoint Results

To see the results of the API Endpoint processing in the  Insert excerpt_console_consolenopaneltrue:
1. Click the Actionflow entry for the API Endpoint
2. In the Messages section which is opened below, double-click any of the Messages to see more details
3. If you are using a debug() statement these will appear here

Failures

An API Endpoint will fail if the logic in the Actionflow fails or if the error() function is used to force a failure.

If records are passed to the API Endpoint individually a failure will only impact the specific record being processed.

Error Codes

200

• Occurs if the output of an API Endpoint is not connected

• Occurs if the output is connected and a record is returned 

400

• Occurs if the output is connected but no record is returned 

Worked Example

Here's a worked example using the Company Data (available from the Learning Centre).

In this example, we are using:  

• A Company Call API screen containing a fixed drop down list of industries, a string fields for the API Status and a multi-line string field for the Results - this screen was created using the Tile with Buttons template

Tip
If you are completing this chapter as part of the Actionflow course and using a training instance, the screens have already been pre-loaded into the Actionflow Advanced Application. For this example, we'll be working on the Company Call API screen.

Image Removed

Excerpt

name	example

Example 1: Passing Out Data

In this example, we'll configure an API Endpoint that passes out Company ID, Company Name and Industry data from our Companies data.

Create API Endpoint

In this example, we'll set up an API Endpoint to pass out company data.

Create a new Insert excerpt_actionflow_api_endpoint_actionflow_api_endpointnametextnopaneltrue on the  Insert excerpt_actionflow_actionflownopaneltrue homepage using the Image Removed option

1. Name: API Company Data
2. Click Create
The API Endpoint canvas will display, with the  Insert excerpt_property_settings_property_settingsnopaneltrue open on the right
4. In the Basic Settings section, enable Allow Anonymous Connections
5. Copy the URL and save it locally, to be used later
Insert excerpt_save_savenopaneltrue your changes

Expand
title Checkpoint
Image Removed

Construct JSON

Create a  Insert excerpt_action_calculate_action_calculatenopaneltrue action
1. Name: GetDataAndConstructJSON
6. Connect the input to the Calculate action
From the  Insert excerpt_action_calculate_action_calculatenopaneltrue action, create a lookup to the Companies data


Expand
title How?
Hover over the Calculate action and select Add lookup Name: getCo On the Create View window: Name: CompanyData Table: Companies Output Attributes Selection: drag CompanyID, CompanyName and Industry into the Output Attributes section of the View Action properties Return (Outgoing) Mappings: map across CompanyID, CompanyName and Industry

On the Calculate action, create an attribute where the JSON will be constructed
7. Name: JSON
8. Type: Structured Data

Expression: 

Code Block
theme Emacs
toJson(getCo)

Insert excerpt_finish_finishnopaneltrue

Expand
title Checkpoint
Image Removed

Configure the Output

Drag the  Insert excerpt_output_outputnopaneltrue connection node onto the Calculate node

Map the JSON attribute from the Calculate action to the body attribute 

Example 2: Passing in Parameters

In this example, we'll retrieve data from our Companies API and pass in an industry parameter (e.g. "Telecoms") to filter the results to just companies in that industry.

API End Point Setup

On the API End Point, create a  Insert excerpt_action_json_action_jsonnopaneltrue action to receive the parameter
9. Name: GetIndustry
   1. Input Expression: in.body
   2. Path: $
   3. Create an Output Attribute on the JSON action
      1. Name: IndustryReceived
      2. Type: String
      3. Expression: _result.Industry
Insert the   Insert excerpt_action_json_action_jsonnopaneltrue action between the  Insert excerpt_input_inputnopaneltrue and  Insert excerpt_action_calculate_action_calculatenopaneltrue nodesOn the Mappings between the  Insert excerpt_input_inputnopaneltrue and  Insert excerpt_action_json_action_jsonnopaneltrue nodes, map across body, contentType, headers and url
10. On the lookup connector, getCo, map the IndustryReceived attribute as an Incoming Mapping
On the  Insert excerpt_action_view_action_viewnopaneltrue action, add a filter:
1. Name: ByIndustry
2. Filter Details: Image Removed 

Call API Actionflow Setup

On the screen, Company Call API, add an Actionflow to the Call API button
11. If you have completed 2.13 HTTP Action Configuration and 2.14 JSON Action Configuration you will recognise the similar Actionflow setup
12. On the input connection point, map in the Industry drop down field
Create a  Insert excerpt_action_http_action_httpnopaneltrue action:
1. Name: Call API
Connect the input to the HTTP action and map across the attribute, Industry
13. HTTP Method: POST
14. URL: the URL from the API End Point you copied earlier

Body: 

Code Block
theme Emacs
[{ "Industry": "${in.Industry}" }]

Log Traffic:  Insert excerpt_toggle_on_toggle_onnopaneltrue

Expand
title Checkpoint
Image Removed

Create a  Insert excerpt_action_json_action_jsonnopaneltrue action 

1. Name: ReturnedCompanies

2. Input Expression: in.body

3. Path: $.getCo

4. Create 2 Output Attributes on the JSON action

   1. Name: CoName
      1. Type: String 
      2. Expression: _result.1.CompanyName
   2. Name: CompanyID
      1. Type: Integer 
      2. Expression: _result.1.CompanyID
15. Hover over the HTTP action and choose out, then connect it to the JSON action
16. On the Mappings between the HTTP action and JSON action, map the attributes:
    1. body
    2. status
Create an  Insert excerpt_output_outputnopaneltrue connection point back to the screen
17. Connect the JSON action to the output, and configure the following mappings:
    1. Image Removed 
18. Then map the following attributes back to the screen on the output connection point:
    1. Image Removed

Expand
title Checkpoint
Image Removed

Testing

1. On the screen, Company Call API, click the Call API button to see the results of the Actionflow
Excerpt

name	LogTraffic

System Console Response

On the HTTP action, Call API, the option to Log Traffic was enabled allowing the API response to be seen in the  Insert excerpt_console_consolenopaneltrue.The results of the API call can also be seen in the  Insert excerpt_console_consolenopaneltrue via the  Insert excerpt_administration_administrationnopaneltrue option
19. Navigate to the Completed Tasks tab
20. Find the Actionflow calling the API and click on it
21. In the Messages tab in the bottom half of the screen, double-click the message, Response from URL
Click on the Message Detail tab in the Log Message window to see the API output
1. in the toolbar to open the settings on the right
   1. For the full Properties list, see Email Endpoint Properties

2. In the Basic Settings, in the Save Attachments to field, set the File Table that incoming email attachments should be saved to

   1. A new

      Insert excerpt
      _tableFile _tableFile nopanel true

      can be created by clicking the

      Insert excerpt
      _add_icon _add_icon nopanel true

       icon or choose an existing table using the

      Insert excerpt
      _tableFile _tableFile name icon nopanel true

      icon or selecting from the drop down list.
      1. When creating a File Table to save attachments to, a folderId attribute is automatically created

Note
If the Email Endpoint fails, any incoming attachments will still be saved to the specified Insert excerpt _tableFile _tableFile nopanel true . If no location is specified in the Save Attachments to field, attachments will not be saved.

Linking Emails and Attachments

The folderId attribute that is automatically created on new

Insert excerpt
_tableFile _tableFile nopanel true

s is used to link an email to its attachments.
• After receiving an incoming email with attachments:
  • A value will generate for the folderId attribute on the

    Insert excerpt
    _tables _tables nopanel true

     where the email records are saved for each email received
  • A value will generate for the folderId attribute on the

    Insert excerpt
    _tableFile _tableFile nopanel true

     where the email attachments are saved for each email received

Displaying Emails

HTML Comment
hidden true
A grid view is created backed by the correspondence table. This includes the summary, date and a count of the records in myFiles by using the collectionId relationship. Double clicking on the grid opens a view screen. The body of the email is shown in an html editor A view backed by the correspondence record adds columns from myFiles via the relationship, this includes the name, size and preview image A gallery is included in edit mode. It is backed by the correspondence.collectionId. Dropping new files on the gallery will upload the files and create a new myFiles entry using the same collectionId. Deleting entries in the gallery will remove the colllectionId value from the filetable record. If all the files are removed the corrsespondence.collectionId value is cleared when the record is saved.

Emails can be displayed using a

Insert excerpt
_grid _grid nopanel true

view.  

Worked Example

Coming Soon.

If you require further support on this topic, please contact PhixFlow Support via the 

Insert excerpt
_chat_bot _chat_bot nopanel true

 ChatBot, available in Image Added Design Mode from the system controls in the top right of PhixFlow.