API endpoints can be setup to enable external systems to make calls to PhixFlow. API endpoints can be seen in the Repository for your application under 

API Endpoint Setup

API endpoints must be made using the specific option on the 

1. Create a new

   Insert excerpt
   _actionflow_api_endpoint _actionflow_api_endpoint name text nopanel true

    on the 

   Insert excerpt
   _actionflow _actionflow nopanel true

    homepage using the  option  
2. Set a unique name and provide a useful description
3. The API Endpoint 

   Insert excerpt
   _property_settings _property_settings nopanel true

    will open on the right
   1. In the Basic Settings section, enable Allow Anonymous Connections

      1. 
         

         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.

          Adding authorisation is covered on 3.12 API Authentication and Secret Keys.

   2. Copy the URL and save it locally, to be used later when calling the API

      1. Example URL: https://app.phixflow.com/phixflow/api/1/action/MyApp/My%20API/trigger

      2. 
         

         Expand
         title Url Structure
         The structure of the URL is as follows: https://<<Server Name>>/phixflow/api/1/action/<<Application Name>>/<<Actionflow Name>>/trigger 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. <<Actionflow Name>> The name of the actionflow set in Step 1. Note that if your actionflow has a space in the name this must be replaced with %20. For example "My API" becomes, "My%20API".  Note: In version 10, the URL structure differed, this old structure has been deprecated: https://<<Server Name>>/phixflow/api/1/action/<<Actionflow Name>>/trigger  Integrations using this old structure should be updated, however the URL structure will still work in version 11.

         
         

   3. Set the API Mode:
      1. Wait for result (Synchronous) (Default): The API waits for the results or the timeout to occur
         1. Note: If the timeout occurs the command is aborted
      2. Poll for result (Asynchronous): The API is called and a response is returned immediately including the process ID
         1. Subsequent API calls can be made using the process ID to fetch the status of the action
         2. The asynchronous mode can be thought of as “fire and forget”
   4. Set a Timeout (optional) (available in PhixFlow version 11.2+):

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

      2. 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

         1. 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

1. Insert excerpt
   _save _save nopanel true

    your changes
2. Configure the Actionflow to perform the required tasks, 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 and Output Attributes

API Status Check (Poll for Result)

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

Calling a PhixFlow API

HTTP Method

This is set on the 

1. To call a PhixFlow API use the HTTP Method GET or POST:
   1. GET simply calls the API with data passed in the body of the request
   2. 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

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

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

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

API Endpoint Results

To see the results of the API Endpoint processing in the 

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 

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.

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.

1. Create a new

   Insert excerpt
   _actionflow_api_endpoint _actionflow_api_endpoint name text nopanel true

    on the 

   Insert excerpt
   _actionflow _actionflow nopanel true

    homepage using the  option
   
   1. Name: API Company Data
   2. Click Create
2. The API Endpoint canvas will display, with the 

   Insert excerpt
   _property_settings _property_settings nopanel true

    open on the right
   1. In the Basic Settings section, enable Allow Anonymous Connections
   2. Copy the URL and save it locally, to be used later

   3. Insert excerpt
      _save _save nopanel true

       your changes

Construct JSON

1. Create a 

   Insert excerpt
   _action_calculate _action_calculate nopanel true

    action
   1. Name: GetDataAndConstructJSON
2. Connect the input to the Calculate action

3. From the 

   Insert excerpt
   _action_calculate _action_calculate nopanel true

    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 Outgoing Mappings: map across CompanyID, CompanyName and Industry

   
   

4. On the Calculate action, create an attribute where the JSON will be constructed
   1. Name: JSON
   2. Type: Structured Data

   3. Expression: 

      1. 
         

         Code Block
         theme Emacs
         toJson(getCo)

         
         

   4. Insert excerpt
      _finish _finish nopanel true

Configure the Output

1. Drag the 

   Insert excerpt
   _output _output nopanel true

    connection node onto the Calculate node

2. 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

1. On the API End Point, create a 

   Insert excerpt
   _action_json _action_json nopanel true

    action to receive the parameter
   1. 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
   2. Insert the  

      Insert excerpt
      _action_json _action_json nopanel true

       action between the 

      Insert excerpt
      _input _input nopanel true

       and 

      Insert excerpt
      _action_calculate _action_calculate nopanel true

       nodes
   3. On the Mappings between the 

      Insert excerpt
      _input _input nopanel true

       and 

      Insert excerpt
      _action_json _action_json nopanel true

       nodes, map across body, contentType, headers and url
   4. On the lookup connector, getCo, map the IndustryReceived attribute as an Incoming Mapping
   5. On the 

      Insert excerpt
      _action_view _action_view nopanel true

       action, add a filter:
      1. Name: ByIndustry
      2. Filter Details:  

Call API Actionflow Setup

1. On the screen, Company Call API, add an Actionflow to the Call API button
   1. If you have completed 2.13 HTTP Action Configuration and 2.14 JSON Action Configuration you will recognise the similar Actionflow setup
   2. On the input connection point, map in the Industry drop down field
   3. Create a 

      Insert excerpt
      _action_http _action_http nopanel true

       action:
      1. Name: Call API
   4. Connect the input to the HTTP action and map across the attribute, Industry
      1. HTTP Method: POST
      2. URL: the URL from the API End Point you copied earlier

      3. Body: 

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

         
         

      4. Log Traffic: 

         Insert excerpt
         _toggle_on _toggle_on nopanel true

         
         
         

         Expand
         title Checkpoint

         
         

   5. Create a 

      Insert excerpt
      _action_json _action_json nopanel true

       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
   6. Hover over the HTTP action and choose out, then connect it to the JSON action
   7. On the Mappings between the HTTP action and JSON action, map the attributes:
      1. body
      2. status
   8. Create an 

      Insert excerpt
      _output _output nopanel true

       connection point back to the screen
   9. Connect the JSON action to the output, and configure the following mappings:
      1.  
   10. Then map the following attributes back to the screen on the output connection point:
       1. 

Testing

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