Andar API Module

Andar API module allows data to be imported or exported remotely through a REST API. With this module, users will be able to run Andar Executive Plus operations remotely to retrieve Andar data and submit Andar Connector operations remotely to import data into Andar.

The API module allows remotely importing the same data as currently imported through the Andar Connector.The data format is the same as Andar Connector.

Server Setup

 You need to set up the server to allow for remote data import and export through the Andar API.

 To set up the server, go to System Preferences > System Preferences > General and find the External Data Import / Export section.

  • When the Process incoming data import / export option is checked, users can submit Andar Connector operations remotely to import data into Andar and run Andar Executive Plus operations remotely to retrieve Andar data. When this option is not checked, the system will not attempt to process any such requests, it will just send a message back to the requester indicating the system is not processing requests at the moment. 
  • The system must have a non-empty API Key before processing requests. This key has to be received with any external import / export data request or the request will not be processed and a message will be sent back to the requester indicating the the server setup is not complete. Once this key is set it must be sent to any system that will request external data import or export. It is your responsibility to maintain this key and to transmit it in a secure way to any entity that you will allow to import or export data remotely.

  

Data Import

The Andar API module allows data to be imported remotely. Users can submit Andar Connector operations remotely to import data into Andar. The URL is your Base Web Address followed by rest/cie (The base web address is set up in the System Preferences > e-Community > e-Community General > Base Web Address field).

 

Parameters

apiKey: for authentication with the server

header: (optional) data CSV header in Andar Connector Import CSV header format.

data: the data to import in Andar Connector Import CSV format.

parameters: (optional) import parameters as generated by the Andar Menu option: Import Parameters For Automation.

 

Optional Parameters

If the header parameter is not present the header of the columns must be included with the data.

The parameter "parameters" might not be necessary or it can be included with the data.

 

Data Content and Format

The data to be imported into Andar is the same data as imported through the Andar Connector. The data format is the same as Andar Connector. Therefore, all the headers, data, and parameters must follow the format of the Andar Connector Data Import.

 

Message Types and Status

Once the server receives a data import request it can generate 5 different types of replies depending on the step reached in processing the request:

  1. status 503 - service not available (server error)
  2. status 503 - service not active (server error)
  3. status 503 - server authentication not setup (server error)
  4. status 403 - client authentication failure (client error)
  5. status 406 - errors found during processing (client data error)
  6. status 200 - data correctly processed (all correct)

 

Message Format

The return message can be one, three or more lines.
Lines one, two and three are identified by a line type, lines four and beyond are error detail lines.
Line format is CSV (Comma separated value)
Line 1 ID: "status"
Line 2 ID: "ref"
Line 3 ID: "No Errors Found" or "Errors List"

The message format is:

  • If the server cannot process your request the return will have one line only: the status line ("status").
  • If the server was able to process your request and there were no errors found the return message will have three lines: the status line, the reference number line and the confirmation of records processed line ("status", "ref", "No Errors Found").
  • If the server was able to process your request and there were errors during processing the message will have at least 4 lines: the status line, the reference number line, the errors list line, followed be one error report per line ("status", "ref", "Error List", and a list of errors).

 

Error Format

The errors list will have one error per line. An import row can have more than one error.
Error code is intended for machine consumption. Error message is intended for human consumption.
Each error will have the following information in the the CSV string:

  1. (row) row number: row zero indicates the header row.
  2. (errorType) error type: for now all errors are of the type "error" (no warnings are issued).
  3. (errorCode) error code.
  4. (errorMessage) error message.
  5. (If available) import column that generated the error.

 

Testing the communication with your server

This simple form (ImportTest.html) will allow you to send a valid request to the server. Use this example to import phone numbers. You will have to change the URL for your server and the api_key value directly in the form before you can use it. Replace all the square brackets by angle brackets. Replace the URL with the correct URL.

<html>
<body>

sent:<br/>api_key=<font color="darkgreen">0062ecd0-9b6f-4704-98ab-c2cb99b47372</font>&header=individuals.accountNumber&data=42705&parameters=</font>


<form action="https://devtest.andar.local/rest/cie" method="post">

api_key: <input type="text" name="api_key" value="d2206558-2861-47eb-8c80-13feb883cbf2" style="position: absolute; left: 120px; width: 400px;"><br>
Header: <input type="text" name="header" value="Individuals.ACCOUNTNUMBER, Individuals.PhoneNumbers.PHONENUMBERTYPE, Individuals.PhoneNumbers.AREACODE, Individuals.PhoneNumbers.PHONENUMBER, Individuals.PhoneNumbers.EXTENSION" style="position: absolute; left: 120px; width: 400px;"><br>
Data: <textarea name="data" style="position: absolute; left: 120px; width: 400px; height: 160px;">1151871,WORK,647,1231234,320</textarea><br>
Parameters: <input type="text" name="parameters" value="" style="position: absolute; left: 120px; width: 400px;"><br>


<input type="submit" value="Submit">

</form>
</body>
</html>

 

Examples of communication between the client and the server

1. status 503 (example)
sent:
(any data if the server is not available)
received:
status, 503, Service not available
details:
a return code 503 means the server is not ready to receive your data.
the message "Service not available" means this server cannot provide this service. You might want to use this information when contacting the server's maintainers.

2. status 503 (example)
sent:
(any data if the server is not active)
received:
status, 503, External Data Import / Export not allowed at this moment
details:
a return code 503 means the server is not ready to receive your data.
the message "External Data Import not allowed at this moment" means any import is disallowed by the server. You might want to use this information when contacting the server's maintainers.

3. status 503 (example)
sent:
(any data if the server authentication is not setup)
received:
status, 503, Server authentication not setup
details:
a return code 503 means the server is not ready to receive your data.
the message "Server authentication not setup" means the server setup was not completed. You might want to use this information when contacting the server's maintainers.

4. status 403 (example)
sent:
api_key=d__wrong_value_in_keyf2&header=individuals.accountNumber&data=5113592&parameters  
received:
status, 403, Invalid API Key authentication
details:
a return code 403 means your authentication key doesn't match the server's authentication key. You will need to request the correct authentication key from the server's maintainers.


5. status 406 (example)
Error in the data headers (row 0 indicates header row)
sent:
api_key=d2206558-2861-47eb-8c80-13feb883cbf2&header=individuals.account_Number&data=5113592&parameters  
received:
status, 406, errors found
ref, 671
Errors List
0,Error,Connector.inMap.noMapDtl,Mapping not found for INDIVIDUALS.ACCOUNT_NUMBER(column header = individuals.account_Number : column number = 1 : column letter = A)
details:
a return code 406 means your data was accepted but there were errors during the processing.
the error list line starts with the import record number, so in this example we have:
record 0 (record 0 means the header record) contains a column header that was not recognized ("INDIVIDUALS.ACCOUNT_NUMBER")
when an error is found in the header record the data will not be processed.

Error in the data
sent:
api_key=d2206558-2861-47eb-8c80-13feb883cbf2&header=individuals.accountNumber&data+style%3D=7112%0D%0A42705a%0D%0A1234%0D%0A42549%0D%0A-2%0D%0A5538%0D%0A1966&parameters
received:
status, 406, errors found
ref, 669
Errors List
1,OK
2,Error,Connector.Individuals.duplicate,Potential duplicate with import record # 1
2,Error,Formatter.WholeNumber.Invalid,Invalid whole number format (42705a) on field "ACCOUNTNUMBER" ("Account Number"),Individuals[1].ACCOUNTNUMBER
3,Error,Connector.Individuals.accountInvalid,Individual account 1234 is invalid,Individuals[1].accountNumber
4,OK
5,OK
6,OK
details:
a return code 406 means your data was accepted but there were errors during the processing.
the error list line starts with the import record number, so in this example we have:
record 1 was fully processed.
record 2 had two errors because the account number passed in is not a numeric value.
record 3 had one error: the account number supplied is not a valid account number.
records 4,5,6 were fully processed.

6. status 200 (example)
sent:
api_key=d2206558-2861-47eb-8c80-13feb883cbf2&header=individuals.accountNumber&data=42705&parameters
received:
status, 200
ref, 650
No Errors Found, 1, records processed
details:
a return code 200 means that your data was accepted, fully processed and imported by the server without any errors.
You might want the record the Andar import reference number for future reference.

Data Export

The Andar API module allows Andar data to be retrieved remotely. The URL is your Base Web Address followed by /rest/retrieve (The base web address is set up in the System Preferences > e-Community > e-Community General > Base Web Address field). Data will be retrieved through an Andar Executive Plus operation. 

Setting up the Executive Plus to retrieve the data

Create Executive Plus components using the API type. Only Executive Plus operations of the API type can be invoked remotely.

The Executive Plus components of the API type can be formatted with a style sheet. Returning binary data (images, PDF) is not supported at the moment.

Here is an example of an API component to retrieve Main addresses updated yesterday: 

select accountnumber, addressline1, addressline2, addressline3, city, stateorprov, zippostalcode, countrycode

from <@Schema>.addresses

where addresstype = 'Main'

and lastchgdate = CONVERT(varchar(8), DATEADD(day, -1, convert(date, GETDATE())), 112)

API_example.jpg

 

Client Usage

 

Parameters

apiKey: for authentication with the server.

name: the name of the Andar Internal Executive Plus that will retrieve the data.

parameters: (optional) a Comma Separate Values (CSV) string with name/value pairs to be passed as parameters to the Andar Executive Plus.

 

Optional Parameters

The parameter "parameters" might not be necessary.

 

Message Types and Status

Once the server receives a data export request it can generate 5 different types of replies depending on the step reached during processing the request:

  1. status 503 - service not available (server error)
  2. status 503 - service not active (server error)
  3. status 503 - server authentication not setup (server error)
  4. status 403 - client authentication failure (client error)
  5. status 406 - errors found during processing (client data error)
  6. status 200 - data correctly processed (all correct)

 

Message Format

 The return message can be one, two or more lines.

  • Line one is identified by a line type.
  • Line two (if present) can be the metadata header line or the first line of data (*).
  • Lines three and beyond (if present) will contain data.

Line format is CSV (Comma separated value).

Line 1 ID: "status" (*) as the output data could have been formatted with a style sheet at the server the header metadata line could have been suppressed.

 

The message format is:

  • If the server cannot process your request the return will have one line only: the status line ("status").
  • If the server was able to process your request and there were no errors found the return message will have two or more lines: the status line, the metadata header line and as many lines as necessary with the retrieved data.

 

Error Format

If the returned status line is an error line after the status number it will contain a brief message identifying the error. This message can be an SQL abbreviated error message.
Error code is intended for machine consumption. Error message is intended for human consumption.

Receiving the detailed message from Andar. Your system might not be passing the Andar fully-detailed error message to the remote system. If this is the case, please create a tag within a "web.config" configuration file located in the root directory of the current web application to enable the details of this specific error message to be viewable on remote machines. This tag should then have its "mode" attribute set to "Off".

Solution: Edit the web.config file for the ISS web site. Add the following under </System.webservers> and above </configuration>:

<system.web>
                   <customErrors mode="Off"/>
</system.web>

This will allow a more detailed message to be passed through to the browser.

 

Testing the communication with your server

This simple form (postExportTest.html) will allow you to send a valid request to the server:

  • The following example will import phone numbers. You will have to change the URL for your server and the api_key value directly in the form before you can use it. Replace all the square brackets by angle brackets. Replace the URL with the correct URL.

<html>
<body>


<form action="https://devtest.andar.local/rest/retrieve" method="post">

api_key: <input type="text" name="api_key" value="0062ecd0-9b6f-4704-98ab-c2cb99b47372" style="position: absolute; left: 120px; width: 400px;"><br>
name: <input type="text" name="name" value="GetMeAPIData1" style="position: absolute; left: 120px; width: 400px;"><br>
parameters: <input type="text" name="parameters" value="accountNumber,5113592" style="position: absolute; left: 120px; width: 400px;"><br>

<input type="submit" value="Submit">

</form>
</body>
</html>

  • Click on GetMeAPIData1.xep to download the Executive Plus code that will be invoked by the postExportTest.html. You need to import the GetMeAPIData1.xep file into Andar Executive Plus.

 

Examples of communication between the client and the server

 

1. status 503 (example)
sent:
(any data if the server is not available)
received:
status, 503, Service not available
details:
a return code 503 means the server is not ready to receive your data.
the message "Service not available" means this server cannot provide this service. You might want to use this information when contacting the server's maintainers.

2. status 503 (example)
sent:
(any data if the server is not active)
received:
status, 503, External Data Import / Export not allowed at this moment
details:
a return code 503 means the server is not ready to receive your data.
the message "External Data Import not allowed at this moment" means any import is disallowed by the server. You might want to use this information when contacting the server's maintainers.

3. status 503 (example)
sent:
(any data if the server authentication is not setup)
received:
status, 503, Server authentication not setup
details:
a return code 503 means the server is not ready to receive your data.
the message "Server authentication not setup" means the server setup was not completed. You might want to use this information when contacting the server's maintainers.

4. status 403 (example)
sent:
api_key=d__wrong_value_in_keyf2&header=individuals.accountNumber&data=5113592&parameters
received:
status, 403, Invalid API Key authentication
details:
a return code 403 means your authentication key doesn't match the server's authentication key. You will need to request the correct authentication key from the server's maintainers.


5. status 406 (example)
sent:
api_key=a valid key&name= GetMeAPIData1
status, 406, API function not found (GetMeAPIData1)
Details: the function GetMeAPIData1 is not defined at the server.

5. status 200 (examples)

sent:
name=individuals data=5113592&#182&parameters=monteiro
status, 200
FIRSTNAME,LASTNAME
"Antonio","Monteiro"
Details: Assuming the requested API function 'Individuals Data' was set up to return all individuals names where the last name is a specific name that was passed in through the parameter “parameters”.


sent:
name= API Functions
status, 200
API Functions Use 'API Functions' to get a list of valid Functions.
Individual Data
OrganizationData
Details: Assuming the requested 'API Functions' was set up to retrieve a list of available API functions.
This shows data retrieved that was formatted with a style sheet.
Note there is no header metadata line and the output is color-coded.