SPARROW Echo Data Exchange - Tutorial

Contents

Overview

Payload Formats

Reference

Version Compatibility

Echo Data Exchange Instructions

Data Schemas

XML

CSV

TXT

Custom

External Systems

PGP Encrypted Payload

Test Text Payload

Test PGP Encrypted Payload

Events

Subscribed Events

History

Overview

The Sparrow Gateway has ability to delivery Echo events to the external web systems. This document provides details how such invocations are performed.

Payload Formats

The Sparrow Gateway uploads Echo events to external web systems in a form of HTTP POST requests. The payload is passed in the request’s body.  The format of the payload is dictated by the selected data scheme: plain text, CVS, and XML. Additionally, there are two special payload formats supported: pgp-encrypted payload and test payload (that is used for “Test Connection” procedure).

Below these formats are described in details. For following terms are used in the examples:

Term

Description

<WEB-SERVICE-URL>

The address specified in the Echo External System (with “Connection Type = Web”).

<FILENAME>

The virtual filename for upload data. It is based on the filename specified in the Data Scheme.

<GATEWAY-VERSION>

The current version of the gateway in the format X.Y.Z (e.g. 2.9.7)

Reference

User Guide is available at the following URL:

https://sparrow.zendesk.com/hc/en-us/articles/207994686

Version Compatibility

Echo Data Exchange Current Version

Version:  Release 3.1

Echo Data Exchange Instructions

Data Schemas

The first step would be to active a Hub transaction that is configured to put the data files out of the system.  Schemas can either be created, imported, edited, copied and deleted.  If a Schema is assigned to a system data interchange (SDI) event, it cannot be deleted.  The system will notify the user of this condition when the Delete button is pressed. 

  1. Go to the Administration > Echo Data Exchange > Data Schemas tabs
  2. Select the Add Data Schema link (bottom left of the page)
  3. The New Data Schema popup page will appear to enter the following information:
    • Name – User friendly name for the data file as a unique identifier
    • Format (Output of how the format will be received as):

XML

XML Payload

The XML payload is used with data schemes with Format=XML for external systems without encryption enabled (Use Encryption = None).

Here is an example of a HTTP request with such payload:

CSV

CSV Payload

The CSV payload is used with data schemes with Format=CSV for external systems without encryption enabled (Use Encryption = None).

Here is an example of a HTTP request with such payload:

TXT

Text Payload

The text payload is used with data schemes with Format=TXT for external systems without encryption enabled (Use Encryption = None).

Here is an example of a HTTP request with such payload:

Custom

Custom Rules can be created in the FBI Tools system, as a rule with the Action = Event.   Please see the FAQ Article about how to create an Custom Rule: https://sparrow.zendesk.com/hc/en-us/articles/206607426

  • File Name – The name will be automatically generated by the system by combining the Schema Name and using the proper formatted extension. The user may edit the name.
  • Description – Free form description of schema/data file
  • Data Set – Lists all of the available API fields from all system interfaces. Responses includes the response fields that would be sent for each event.
  • Available Fields – List of all fields in the chosen API Data Set.
  • Data Output File – List of all the selected fields for the current schema.
  1. Press the Save button
  2. Press the Exit button

External Systems

The next step for the user is the declaration and setup of the external systems.  The table lists the previously setup systems and includes the following fields:

  • Name – Name of the External System
  • Description – Description of the External System
  • Destination – The path of where it will be routed too
  • Creation Time – Timestamp of when it was created
  • Modification Time – Timestamp of when it was modified
  • Edit, Copy and Delete – Editable links 

Configuring an External System
1. Select the Add External System link (bottom left of the page)
2. System Name – User friendly name for the data file as a unique identifier
3. Description – Free form to fill out the description of the system
4. Use Encryption –
None: None needed
PGP: The file sent to FTP can be encrypted using PGP encryption:

PGP Encrypted Payload

The PGP encrypted payload is used with any data schemes for external systems with PGP encryption enabled (Use Encryption = PGP).

Here is an example of a HTTP request with such payload:

5. Connection Type – The following choices are available of how to transfer the files through the system:
• FTP
• FTPS (Implicit Mode)
• SFTP
• Web Service
6. URL - Destination allows for the entry of the URL that is associated with the transfer
7. Port – When applicable
8. Username – When applicable
9. Password – When applicable
10. Press the Test Connection to ensure your settings are correct

Test Text Payload

When a user clicks on “Test Connection” button for an external system with “Use Encryption = None” the following request is sent:

Test PGP Encrypted Payload

When a user clicks on “Test Connection” button for an external system with “Use Encryption = PGP” the following request is sent:

11. Press the Save button
12. Press the Exit button

Events

Each data file movement that is triggered is an “Event.”  Events can be either the time of day, rules or an actual system transaction.  The system populates a grid with rows that is expanded.  Each event can be selected by a checkbox and will be available for an assignment once it has been triggered.

This page has two functions:

  1. Assign Events to the list box by marking the checkbox.
  2. Provide a list of all the possible Events with the description for each item.
    • Custom Rules – This can be created in the FBI Tools system, as a rule with the Action = Event.
      Please see the FAQ Article about how to create an Custom Rule: https://sparrow.zendesk.com/hc/en-us/articles/206607426
    • Transaction API – Services API
    • Data Vault API – Data Vault API
    • Mobile API – Mobile API
    • Batch API
    • Billing API – Services API
    • Reply – Users can modify the system default response fields by choosing Reply as the Event trigger. Doing so will use the newly created response in place of the system default response thereby customizing the response to the calling system.  To revert back to the original system that is a defined response file, the user should delete the Assignment and/or Schema.

Subscribed Events

This page provides the list of all the created Events.  Schemas can be assigned to systems in one or many fashion. 

  1. Select the Add Subscribed Event link (bottom left of the page)
  2. Select the Event Type – EX: A notification will be trigged once that type of event is triggered.
  3. Email – You can place multiple emails to send the triggered notification.
  4. System – Select your System that you would like to utilize
  5. Schema – From the drop down option, select the schema that you would like to assign to generate the event.
  6. Time of Day – If this checkbox is not selected, then the file would be created in the external system immediately after processing the transaction. If this checkbox is selected, then the file would be created on the time of day and it would contain several transactions that have been processed since the last "Time of Day” file creation.

    Please note:  In the version 3.2 release -
    * End of Day at Time [ 01:00 ]

* Every [ 1 v ] hours
             2   

            3

           4

 

History

The system provides a running log and a transaction movement table as shown below. 

Table data fields:

  • Schema – The schema that was created for the event
  • Destination – Where the files got sent too
  • Create Date – Date the Event was created
  • Exchange Date – Date that the Event got exchanged
  • Response – Response or status of the transaction
  • Details – Shows the XML, CSV, TXT formats

To view the Echo Data Exchange History:

  1. Exchange Date: From - Select the From date range
  2. Exchange Date: To - Select the To data range
  3. Exchange Date: View History - Select the View History to view on the landing page
  4. Exchange Date: View Log - Select the View Log as an executable file
  5. Details link (bottom left of the page), displays the following formats:
    • XML
    • CSV
    • TXT format (according to the data schema’s format)

 

 

Have more questions? Submit a request

Comments

Powered by Zendesk